# GEMINI Project Context: SmurfHabits

This document provides a comprehensive overview of the SmurfHabits project for AI-assisted development.

## 1. Project Overview

SmurfHabits is a mobile-first web application for habit tracking with a light gamification layer. The core user loop involves completing daily habits and quests to earn rewards, which are then used to build and develop a virtual village. This progression grants Experience Points (EXP) that are tracked on a global leaderboard.

The project is a full-stack SPA (Single Page Application) built with Nuxt 3, using Vue 3 for the frontend and a Node.js backend powered by Nuxt Nitro. It uses SQLite as its database with Prisma ORM for data access.

### Key Architectural Principles:
- **Monorepo:** Frontend and backend coexist in a single codebase.
- **Backend as Source of Truth:** All progression, time-based calculations, and rewards are handled by the server-side API to ensure consistency.
- **Clear Separation of Concerns:** A strict distinction is maintained between UI (in `app/`), backend logic (in `server/`), and data persistence (in `prisma/`).

## 2. Building and Running

The project uses `npm` for dependency management and running scripts.

### First-Time Setup
1.  **Install Node.js:** Ensure you are using a Node.js version in the 20.x LTS range.
2.  **Install Dependencies:**
    ```bash
    npm install
    ```
3.  **Setup Database:** Create the initial database and apply migrations. The `.env` file is pre-configured to use a local SQLite file (`dev.db`).
    ```bash
    npx prisma migrate dev
    ```

### Development
To run the development server with hot-reloading:
```bash
npm run dev
```

### Building for Production
To build the application for production:
```bash
npm run build
```

## 3. Development Conventions

Adhering to these conventions is critical for maintaining project stability.

### Project Structure
- `app/`: Contains all frontend UI code (pages, components, layouts).
- `server/`: Contains all backend API code and utilities.
- `prisma/`: Contains the database schema (`schema.prisma`) and migration files.
- `public/`: Contains static assets.

### Database and Prisma
- The project is intentionally locked to **Prisma v6.x**. Do **NOT** upgrade to v7 or introduce Prisma adapters.
- All changes to the database schema in `prisma/schema.prisma` **must** be followed by a migration command:
  ```bash
  npx prisma migrate dev
  ```
- The primary Prisma client instance is exported from `server/utils/prisma.ts`. Do not initialize the client elsewhere.

### State Management
- **Frontend:** Pinia is used for client-side state management.
- **Backend:** The backend API is the authoritative source for all user progression, rewards, and time-sensitive data. The frontend should not implement its own logic for these calculations.

### API Development
- API routes are located in `server/api/`.
- Group API endpoints by domain (e.g., `/api/habits`, `/api/village`).
- All business logic should reside in the backend.

### AI / Gemini Usage Rules
- **DO NOT** allow the AI to change the Node.js version, upgrade Prisma, alter the Prisma configuration, or modify the core project structure.
- **ALLOWED:** The AI can be used to add or modify Prisma schema models, generate new API endpoints, and implement business logic within the existing architectural framework.