lucianoandClaude Opus 4.7
87ca5af765
Setup pnpm workspaces with apps/{web,api} placeholders and shared
packages: tsconfig, eslint-config, shared, ui, db. Includes Prettier,
ESLint, Husky pre-commit, lint-staged, EditorConfig, VSCode settings.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
209 lines
8.8 KiB
Markdown
209 lines
8.8 KiB
Markdown
# KetoPath
|
||
|
||
> Web app responsive multi-utente per la gestione personalizzata di chetogenica e digiuno intermittente, con piani alimentari adattivi, tracking peso/progressi, gestione del digiuno e lista della spesa automatica.
|
||
|
||
Questo file viene letto automaticamente da Claude Code a ogni sessione. Tienilo aggiornato con le decisioni architetturali e di prodotto.
|
||
|
||
---
|
||
|
||
## Vision
|
||
|
||
Trasformare la chetogenica e il digiuno intermittente da diete temporanee a stili di vita strutturati, accompagnando ogni utente dalla prima settimana di adattamento al mantenimento per la vita.
|
||
|
||
Il documento di prodotto completo è in `docs/PRD_KetoPath.docx`. Quando devi prendere decisioni di prodotto non banali, leggilo prima di proporre soluzioni.
|
||
|
||
---
|
||
|
||
## Tech stack
|
||
|
||
**Frontend**
|
||
- Next.js 14 (App Router) + TypeScript strict mode
|
||
- Tailwind CSS + shadcn/ui per i componenti
|
||
- TanStack Query per data fetching client-side
|
||
- Zustand per stato globale leggero
|
||
- Zod per validazione form e tipi runtime
|
||
|
||
**Backend**
|
||
- Node.js + Fastify + TypeScript
|
||
- Prisma come ORM
|
||
- Auth gestita via Clerk (no roll-your-own)
|
||
|
||
**Database & infrastruttura**
|
||
- PostgreSQL 15+ come DB principale
|
||
- Redis per cache, sessioni e queue di job
|
||
- Cloudflare R2 per storage foto progress
|
||
- SendGrid per email transazionali
|
||
- Firebase Cloud Messaging per push web
|
||
|
||
**Hosting & DevOps**
|
||
- Vercel per il frontend Next.js
|
||
- Render o Fly.io per il backend Fastify
|
||
- GitHub Actions per CI/CD
|
||
- PostHog (self-hosted) per analytics
|
||
- Sentry per error tracking
|
||
|
||
---
|
||
|
||
## Repository structure
|
||
|
||
```
|
||
ketopath/
|
||
├── apps/
|
||
│ ├── web/ # Next.js frontend (App Router)
|
||
│ └── api/ # Fastify backend
|
||
├── packages/
|
||
│ ├── db/ # Prisma schema, client, migrations
|
||
│ ├── shared/ # Tipi TS, utility e logica di dominio condivisa
|
||
│ └── ui/ # Componenti UI riusabili (estensione shadcn/ui)
|
||
├── docs/
|
||
│ ├── PRD_KetoPath.docx
|
||
│ └── decisions/ # ADR (Architecture Decision Records)
|
||
├── .github/workflows/
|
||
└── CLAUDE.md # questo file
|
||
```
|
||
|
||
Usa un monorepo con pnpm workspaces o Turborepo. Tutto in TypeScript.
|
||
|
||
---
|
||
|
||
## Convenzioni di codice
|
||
|
||
- **TypeScript strict mode** sempre. Mai `any` senza commento `// eslint-disable-next-line` motivato.
|
||
- **File**: `kebab-case.tsx` per i moduli, `PascalCase.tsx` per i componenti React esposti.
|
||
- **Componenti React**: function components + hooks, no class components.
|
||
- **Naming**:
|
||
- Variabili e funzioni: `camelCase`
|
||
- Componenti, tipi e interfacce: `PascalCase`
|
||
- Costanti globali: `SCREAMING_SNAKE_CASE`
|
||
- **Commit message**: Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, ecc.).
|
||
- **Linting**: ESLint + Prettier, formattazione automatica al pre-commit con husky + lint-staged.
|
||
- **Test**: Vitest per unit test, Playwright per E2E. Coverage minima 70% sui moduli di dominio (calcoli BMR, macros, fasi).
|
||
|
||
---
|
||
|
||
## Pattern di codice da preferire
|
||
|
||
- **Server Components** di default in Next.js; `"use client"` solo dove serve interattività.
|
||
- **Server Actions** per mutazioni semplici di form, API routes per logica più complessa.
|
||
- **Suspense + Error Boundary** per ogni feature.
|
||
- **Form**: React Hook Form + Zod resolver. Mai validazione manuale.
|
||
- **Date**: usa `date-fns`. Mai `Date.parse` o stringhe ad-hoc.
|
||
- **DB queries**: Prisma client. Niente raw SQL se non strettamente necessario, e in quel caso commenta perché.
|
||
- **Optimistic updates** per le azioni utente frequenti (segnare un pasto come consumato, spuntare un articolo della lista spesa).
|
||
|
||
---
|
||
|
||
## Conoscenza di dominio
|
||
|
||
Il dominio dell'app ha alcuni concetti chiave che devi conoscere prima di scrivere codice:
|
||
|
||
- **3 Fasi del percorso utente**:
|
||
- `INTENSIVE` (giorni 1-30/45) — deficit calorico aggressivo, IF stretto
|
||
- `TRANSITION` (giorni 31-90) — reverse dieting, calorie in salita
|
||
- `MAINTENANCE` (per sempre) — 14:10, regola 80/20, soglia di allarme
|
||
- **Calcolo calorie** con formula Mifflin-St Jeor:
|
||
- Uomini: `BMR = 10 × peso(kg) + 6.25 × altezza(cm) − 5 × età + 5`
|
||
- Donne: `BMR = 10 × peso(kg) + 6.25 × altezza(cm) − 5 × età − 161`
|
||
- TDEE = BMR × fattore attività (1.2 / 1.375 / 1.55 / 1.725)
|
||
- **Macros target per fase**:
|
||
- Carboidrati netti: 5-10% in Phase 1, sale in Phase 2-3
|
||
- Proteine: 1.5-1.8 g/kg di peso ideale
|
||
- Grassi: il resto
|
||
- **Protocolli di digiuno**: enum `FASTING_PROTOCOL = 14_10 | 16_8 | 18_6 | 20_4 | ESE_24 | FIVE_TWO`
|
||
- **Esclusioni alimentari**: ogni `Ingredient` ha `exclusion_groups` (es. `lactose`, `fish`, `nuts`); ogni `Recipe` eredita le esclusioni dai suoi ingredienti
|
||
|
||
Quando implementi una nuova funzionalità, mappa sempre prima a quale fase appartiene e quali macros/vincoli rispetta.
|
||
|
||
---
|
||
|
||
## Comandi comuni
|
||
|
||
```bash
|
||
# Sviluppo
|
||
pnpm dev # Avvia frontend + backend in parallelo
|
||
pnpm dev:web # Solo Next.js
|
||
pnpm dev:api # Solo Fastify
|
||
|
||
# Build & deploy
|
||
pnpm build # Build di tutti i package
|
||
pnpm start # Avvia in production mode
|
||
|
||
# Database
|
||
pnpm db:migrate # prisma migrate dev
|
||
pnpm db:studio # Apre Prisma Studio
|
||
pnpm db:seed # Popola DB con dati di test
|
||
|
||
# Quality
|
||
pnpm lint # ESLint
|
||
pnpm format # Prettier
|
||
pnpm typecheck # tsc --noEmit
|
||
pnpm test # Vitest
|
||
pnpm test:e2e # Playwright
|
||
```
|
||
|
||
---
|
||
|
||
## Vincoli non negoziabili
|
||
|
||
- **Lingua UI di default: italiano**. Tutti i testi user-facing in italiano. Predisporre i18n con `next-intl` per l'eventuale internazionalizzazione futura.
|
||
- **Mobile-first responsive**: ogni pagina deve essere progettata e testata prima a 375px di larghezza.
|
||
- **GDPR by design**: i dati di salute (peso, misure, foto, sintomi) rientrano nell'art. 9 GDPR. Crittografia at-rest sul DB, niente log dei dati sanitari, consenso esplicito.
|
||
- **Disclaimer medico** sempre visibile in onboarding, nelle pagine di calcolo calorico e nelle pagine di tracking. Testo da concordare con un medico advisor.
|
||
- **Privacy first**: niente tracking di terze parti senza consenso, no Google Analytics di default. Se proprio servono analytics, usa PostHog self-hosted con cookie-less mode.
|
||
- **Accessibilità WCAG 2.1 AA**: tutto il contenuto navigabile da tastiera, contrasto colori sufficiente, alt text sulle immagini, semantica HTML corretta.
|
||
|
||
---
|
||
|
||
## Cosa NON fare mai
|
||
|
||
- Salvare password in chiaro (Clerk gestisce auth, non implementarla a mano).
|
||
- Loggare dati di salute fuori dal DB cifrato.
|
||
- Usare `eval()` o `new Function()` con input utente.
|
||
- Disabilitare feature di sicurezza (CSP, CORS, rate limiting) per "comodità di sviluppo".
|
||
- Fare claim medici sui prodotti o suggerire farmaci/integratori specifici.
|
||
- Esportare dati utente in chiaro senza autenticazione e log dell'export.
|
||
- Fare commit di file `.env`, chiavi API, dump di database.
|
||
- Usare librerie deprecate o senza manutenzione attiva (controlla l'ultimo commit prima di aggiungere una dipendenza).
|
||
|
||
---
|
||
|
||
## Workflow consigliato per Claude Code
|
||
|
||
Quando ti chiedo una nuova funzionalità, segui questo flusso:
|
||
|
||
1. **Domanda di chiarimento** se il task non è completamente specificato.
|
||
2. **Lettura preventiva**: leggi i file pertinenti prima di proporre modifiche, non scrivere codice "alla cieca".
|
||
3. **Plan mode** per task non banali: presentami un piano in 5-10 punti prima di toccare il codice.
|
||
4. **Implementazione progressiva**: feature piccole, commit frequenti, ogni commit verde (lint + test passano).
|
||
5. **Diff esplicito**: mostrami sempre i diff prima di applicare modifiche a file critici (`prisma/schema.prisma`, `package.json`, file di config).
|
||
6. **Test**: per ogni nuova logica di dominio (calcoli macros, fasi, vincoli) scrivi anche unit test.
|
||
7. **Documentazione**: aggiorna il README e questo CLAUDE.md quando introduci pattern nuovi o cambi decisioni architetturali.
|
||
|
||
---
|
||
|
||
## Decisioni architetturali aperte (da prendere insieme)
|
||
|
||
Queste decisioni non sono ancora finalizzate. Se le tocchi, aprire un ADR in `docs/decisions/`.
|
||
|
||
- [ ] Stripe vs Lemon Squeezy per il payment provider
|
||
- [ ] PostHog self-hosted vs Mixpanel per analytics di prodotto
|
||
- [ ] Render vs Fly.io vs AWS ECS per l'hosting backend
|
||
- [ ] Strategia di seeding del database ricette (manuale vs scraping autorizzato vs LLM-assisted)
|
||
- [ ] Localizzazione: i18n da subito o solo italiano per MVP?
|
||
- [ ] App mobile nativa post-MVP: React Native o Expo?
|
||
|
||
---
|
||
|
||
## Riferimenti
|
||
|
||
- PRD completo: `docs/PRD_KetoPath.docx`
|
||
- Documentazione Next.js: https://nextjs.org/docs
|
||
- Documentazione Prisma: https://www.prisma.io/docs
|
||
- Documentazione Clerk: https://clerk.com/docs
|
||
- shadcn/ui: https://ui.shadcn.com
|
||
- GDPR e dati sanitari: https://www.garanteprivacy.it/
|
||
|
||
---
|
||
|
||
*Ultimo aggiornamento: aprile 2026. Modifica questo file ogni volta che cambia una decisione architetturale o un pattern di codice.*
|