habits.andr33v.ru/GEMINI/ARCHITECTURE.md

Architecture

1. High-Level Architecture

The application follows a fullstack SPA architecture:

• Nuxt 3 frontend
• Nitro backend (Node.js)
• REST API
• MySQL database
• Prisma ORM

Frontend and backend live in a single repository.

---

2. Architectural Principles

• Clear separation of concerns:
  • UI
  • State
  • Domain logic
  • Persistence
• Backend is the source of truth
• Frontend does not calculate time-based progression
• No real-time connections (WebSockets not required)

---

3. Frontend Structure

• Pages:
  • Habits
  • Quests
  • Village
  • Leaderboard
• Components:
  • HabitCard
  • QuestItem
  • VillageGrid
  • VillageObject
  • BuildModeOverlay
• State:
  • userStore
  • habitsStore
  • questsStore
  • villageStore
  • leaderboardStore

---

4. Backend Structure

• API routes grouped by domain:
  • /auth
  • /user
  • /habits
  • /quests
  • /village
  • /leaderboard
• Domain services:
  • HabitService
  • QuestService
  • VillageService
  • CropGrowthService
• All time-based logic is calculated on request

---

5. Village Logic

• Village grid is logical (cell-based)
• Isometric view is purely visual
• Build mode:
  • shows grid overlay
  • allows placing, moving and removing objects
• View mode:
  • allows planting and harvesting
• Obstacles must be cleared before building

---

6. Time & Progression

• Server calculates:
  • whether a quest is available today
  • whether a crop is grown
  • streak progression
• Time is based on user local date stored on server
• No background jobs required for MVP

---

7. Data Flow

1. Frontend requests current state
2. Backend recalculates progression if needed
3. Backend returns updated state
4. Frontend updates Pinia stores
5. UI reflects the new state

---

8. Non-Goals

• No SSR optimization
• No WebSocket connections
• No offline mode
• No push notifications