215 lines
3.0 KiB
Markdown
215 lines
3.0 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. 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.
|