habits.andr33v.ru/GEMINI.md

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:

   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).

   npx prisma migrate dev
   

Development

To run the development server with hot-reloading:

npm run dev

Никогда НЕ запускай npm run dev сам. Скажи пользователю, что бы сделал это сам.

Building for Production

To build the application for production:

npm run build

Не запускай 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.

Data Conventions

• daysOfWeek Field: This array represents the days a habit is active. The week starts on Monday.
  • Monday: 0
  • Tuesday: 1
  • Wednesday: 2
  • Thursday: 3
  • Friday: 4
  • Saturday: 5
  • Sunday: 6
• Daily Streak: The dailyStreak field on the User model is an integer representing the user's consecutive daily visits. Its primary function is to act as a multiplier for rewards (coins and EXP) earned from completing habits and village activities.
  • The multiplier is typically capped (e.g., at 3x).
  • It is updated by the calculateDailyStreak function located in server/utils/streak.ts. This function determines if a visit extends the streak, maintains it, or resets it.

4. Date and Time Handling (Game Day Concept)

To ensure consistent and timezone-agnostic handling of daily game mechanics, the project employs a "Game Day" concept. This approach prioritizes the user's local calendar day for relevant actions and uses a standardized string format for persistence.

Key Principles:

1. "Game Day" Format: All dates representing a calendar day (e.g., when a habit was completed, a daily visit occurred, or a village event was processed) are stored and primarily handled as a String in "YYYY-MM-DD" format. This includes fields like DailyVisit.date, HabitCompletion.date, VillageObject.lastExpDay, VillageTile.clearingStartedDay, and Village.lastTickDay.

2. Client as Source of Truth for User's Day:

   • For user-initiated actions (e.g., completing a habit, triggering a daily visit), the frontend (client-side) determines the current "Game Day" based on the user's local timezone.
   • This "YYYY-MM-DD" string is then sent to the backend with the API request. This prevents timezone conflicts where the server's day might differ from the user's local perception of "today."

3. Server-Side Consistency with UTC:

   • On the backend, when parsing these "YYYY-MM-DD" strings into Date objects for calculations (e.g., to determine the day of the week or calculate daysSince), they are explicitly parsed as UTC dates (e.g., new Date(\${gameDay}T00:00:00Z`)`). This ensures that date arithmetic (like finding the previous day) is consistent and avoids shifts due to the server's local timezone.

4. Day-of-Week Convention: The application adheres to a specific convention for days of the week:

   • Monday: 0
   • Tuesday: 1
   • Wednesday: 2
   • Thursday: 3
   • Friday: 4
   • Saturday: 5
   • Sunday: 6

Example Usage:

• DailyVisit.date: Stores the "Game Day" on which a user's visit was recorded.
• HabitCompletion.date: Stores the "Game Day" on which a habit was marked as complete.
• Village.lastTickDay: Stores the "Game Day" (server-side determined) when the village's background progression was last processed, preventing redundant calculations within the same server day.
• VillageObject.lastExpDay: Stores the "Game Day" when an object (e.g., a field) last generated experience.
• VillageTile.clearingStartedDay: Stores the "Game Day" when a tile's clearing process began.

This consistent use of "Game Day" strings and client-provided dates (for user actions) combined with server-side UTC parsing (for calculations) provides a robust solution to managing time-based game mechanics across different timezones.

5. 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.