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

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

Development

To run the development server with hot-reloading:

npm run dev

Building for Production

To build the application for production:

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:
```
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.

3.3 KiB Raw Blame History