# 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:
```bash
node -v
```

---

## 3. Project Structure

```text
/
├─ 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:

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

---

### Environment variables

`.env`:

```env
DATABASE_URL="file:./dev.db"
```

---

### Prisma workflow

Whenever you change `schema.prisma`:

```bash
npx prisma migrate dev
```

Never forget migrations.

---

## 6. Prisma Client Usage

Prisma client is initialized here:

```ts
server/utils/prisma.ts
```

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

```bash
npm install
```

Generate Prisma client:

```bash
npx prisma generate
```

Run dev server:

```bash
npm run dev
```

---

## 8. API Example

Health check:

```
GET /api/health
```

Expected response:

```json
{
  "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):

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

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