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

---

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

---

6. Development

Install dependencies:

npm install

Generate Prisma client:

npx prisma generate

Run dev server:

npm run dev

---

7. API Example

Health check:

GET /api/health

Expected response:

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

---

8. Deployment Notes

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

---

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

---

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