# 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