250 lines
4.3 KiB
Markdown
250 lines
4.3 KiB
Markdown
# 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. 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.
|
|
|
|
---
|
|
|
|
## 5. 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
|
|
|
|
---
|
|
|
|
## 6. Development
|
|
|
|
Install dependencies:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
Generate Prisma client:
|
|
|
|
```bash
|
|
npx prisma generate
|
|
```
|
|
|
|
Run dev server:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## 7. API Example
|
|
|
|
Health check:
|
|
|
|
```
|
|
GET /api/health
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"usersCount": 0
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 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.
|
|
|
|
---
|
|
|
|
## 9. Deployment Notes
|
|
|
|
- Use Node 20 on hosting
|
|
- Run Prisma migrations during deployment
|
|
- SQLite is acceptable for MVP
|
|
- Database file: `dev.db`
|
|
|
|
---
|
|
|
|
## 10. 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
|
|
|
|
---
|
|
|
|
## 11. 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.
|