habits.andr33v.ru/README.md

Smurf Habits

Habit tracker with a light game layer (village, quests, EXP). Mobile-first web application.

---

1. Tech Stack

• Node.js 20 LTS (required)
• Nuxt 4.x
• Vue 3
• Prisma 6.x (⚠️ NOT 7)
• SQLite (development & MVP)
• TypeScript

---

2. Environment Requirements

Node.js

Required:

Node >= 20.x (LTS)

❌ Node 22 / 24 are NOT supported
❌ Do not use experimental Node versions

Check:

node -v

---

3. Project Structure

/
├─ app/              # UI (pages, components, layouts)
├─ server/           # Backend (API, utils, Prisma)
│  ├─ api/
│  └─ utils/
├─ prisma/
│  ├─ schema.prisma
│  └─ migrations/
├─ public/
├─ .env
├─ nuxt.config.ts
└─ README.md

Important rules

• app/ — UI only
• server/ — backend only
• server/ MUST be in project root (not inside app/)
• Do NOT change this structure

---

4. Date and Time Handling

To ensure consistent and timezone-agnostic management of daily game mechanics (like habit completion, streaks, and village progression), the project uses a "Game Day" concept. Dates are primarily stored as String in "YYYY-MM-DD" format. The client provides its local "Game Day" for user actions, and the server processes dates consistently using UTC.

For a detailed explanation of the "Game Day" concept and its implementation, please refer to the GEMINI.md file.

---

5. Prisma Setup (IMPORTANT)

Prisma version

This project intentionally uses Prisma 6.

❌ Do NOT upgrade to Prisma 7
❌ Do NOT use Prisma adapters
❌ Do NOT remove DATABASE_URL

Reason:

• Prisma 7 has unstable adapter-based API
• Prisma 6 is stable and well-supported by Nuxt and tooling

---

Prisma schema

prisma/schema.prisma uses classic datasource config:

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

---

Environment variables

.env:

DATABASE_URL="file:./dev.db"

---

Prisma workflow

Whenever you change schema.prisma:

npx prisma migrate dev

Never forget migrations.

---

6. Prisma Client Usage

Prisma client is initialized here:

server/utils/prisma.ts

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

export default prisma

Rules

• Do NOT initialize PrismaClient elsewhere
• Do NOT use dynamic imports
• Do NOT change this file without a good reason

---

7. Development

Install dependencies:

npm install

Generate Prisma client:

npx prisma generate

Run dev server:

npm run dev

---

8. API Example

Health check:

GET /api/health

Expected response:

{
  "ok": true,
  "usersCount": 0
}

---

9. Scheduled Cleanup Task

To manage anonymous user data, a cleanup task can be triggered via a protected API endpoint. This task deletes anonymous users who were created more than 24 hours ago and have not registered.

Environment Variable

The cleanup endpoint is protected by a secret key. Ensure the following environment variable is set in your .env file (and in production environments):

CLEANUP_SECRET="your_strong_secret_key_here"

Replace "your_strong_secret_key_here" with a strong, unique secret.

Manual Trigger (for Development/Testing)

You can manually trigger the cleanup task using curl (or Postman, Insomnia, etc.):

curl -X POST \
     -H "Content-Type: application/json" \
     -H "x-cleanup-secret: your_strong_secret_key_here" \
     http://localhost:3000/api/admin/cleanup

Important:

• Replace http://localhost:3000 with your application's actual URL if not running locally.
• Replace your_strong_secret_key_here with the value set in your CLEANUP_SECRET environment variable.

Production Setup

In a production environment, this endpoint should be called by an external scheduler (e.g., a cron job service provided by your hosting platform, GitHub Actions, etc.) on a regular basis (e.g., daily). This ensures reliable, automatic cleanup without impacting user experience.

---

10. Deployment Notes

• Use Node 20 on hosting
• Run Prisma migrations during deployment
• SQLite is acceptable for MVP
• Database file: dev.db

---

11. AI / Gemini Rules (IMPORTANT)

When using Gemini / AI tools:

DO NOT ALLOW:

• changing Node version
• upgrading Prisma
• changing Prisma configuration
• modifying project structure

ALLOWED:

• adding models to schema.prisma
• generating API endpoints
• implementing business logic

---

12. Why these constraints exist

This setup was intentionally chosen to:

• avoid unstable Prisma 7 API
• keep development predictable
• ensure compatibility with Nuxt and Node
• prevent tooling-related regressions

Breaking these rules will likely break the project.