Files

T

davideandClaude Opus 5 e1e8dd5415 Reorganize documentation and unify the AI assistant rules

Documentation:
- Add docs/README.md, the documentation index that AGENTS.md pointed to as the
  first file to read but which did not exist.
- One home per piece of information: the feature list stays in ROADMAP.md,
  CHANGELOG.md records only when something shipped, TODO.md only ongoing work.
  Reconcile the entries that had drifted (CSI was both done and pending;
  pagelle, badge social and serie were missing from the roadmap).
- Rewrite DATABASE.md as tables: add giocatori_squadra (already created by a
  migration) and profili_giocatore (planned in DD-016), fix the wrong heading
  levels, drop the duplicated roadmap.
- DESIGN_DECISIONS.md: move the index to the top and sort it, extract the
  template into _template-dd.md.
- ARCHITECTURE.md becomes the technical reference; CLAUDE.md no longer
  duplicates it.
- Add docs/EFFICIENZA_CLOUD.md with the rules previously kept in mem/,
  separating what the code enforces from the goals not yet implemented.
- Fix statements the code contradicted: mutations use setQueryData rather than
  invalidateQueries, and scout_sessioni and giocatori_squadra are not read by
  the code yet.
- Track the v1.0 modules with no spec in docs/modules/ from TODO.md.

AI assistants:
- AGENTS.md is the single source of the rules, now including the technical
  constraints only Claude Code knew about (generated files, Vite plugins, data
  access) and an end-of-work checklist that applies to every assistant.
- CLAUDE.md and .cursor/rules/crapp.mdc point to AGENTS.md instead of
  restating it.
- Remove the five .cursor/*.md files, which Cursor never loaded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-30 16:26:14 +02:00

4.4 KiB

Raw Blame History

Architettura del progetto

Come è fatta CrAPP: stack, organizzazione del codice, flusso di sviluppo. È il documento di riferimento tecnico — CLAUDE.md non ripete questi contenuti, li richiama.

Stack

Livello	Tecnologie
Frontend	React 19, TypeScript, TanStack Start (SSR), Vite 8, Tailwind CSS 4, Radix UI / shadcn
Backend	Supabase (PostgreSQL, Auth, Storage)
Hosting	Vercel
Versionamento	Git, GitHub

Le dipendenze sono installate con bun (bun.lock, bunfig.toml). bunfig.toml impone minimumReleaseAge = 24h come guardia supply-chain: aggiungere un pacchetto a minimumReleaseAgeExcludes richiede conferma esplicita.

Struttura del progetto

src/
  components/   componenti condivisi (crapp/, ui/, motion/)
  routes/       routing file-based
  lib/          logica di dominio, un file per modulo
  integrations/ client Supabase e integrazioni esterne
  hooks/
  assets/
supabase/       migration SQL
test/           suite di test (unit, integration, end-to-end)
docs/           documentazione ufficiale

Punti fermi

Routing: file-based in src/routes/. src/routeTree.gen.ts è generato, non si modifica a mano.
Configurazione Vite: vite.config.ts usa @lovable.dev/vite-tanstack-config, che include già devtools, tanstackStart, viteReact, tailwind, tsconfig-paths, nitro e l'alias @ → src/. Non ri-aggiungere questi plugin: l'app si rompe.
Entry point server: src/server.ts avvolge l'entry di TanStack Start per intercettare gli errori SSR che h3 trasformerebbe in un 500 JSON silenzioso, e renderizza renderErrorPage(). src/start.ts registra i middleware globali (error handler, CSRF sui server functions, attachSupabaseAuth).
Supabase: src/integrations/supabase/client.ts (browser/SSR, chiave publishable — file generato) e client.server.ts (supabaseAdmin, solo server). types.ts è generato dallo schema.

Livello dati

Tutta la logica di dominio sta in src/lib/, un file per modulo (presenze, eventi, pagelle, mvp-voti, palloni, cacche, badges, scout-*, infortuni, …). Il pattern ricorrente:

ogni modulo esporta hook TanStack Query (useX); i default globali stanno in src/router.tsx (staleTime 5 min, gcTime 30 min, refetchOnWindowFocus/Mount/Reconnect disattivati, retry: 1);
dopo una mutazione la cache si aggiorna con setQueryData, non con invalidateQueries: invalidare provoca una rilettura e costa una query in più (unica eccezione oggi: scout-live.ts);
le funzioni pure di calcolo sono separate dagli hook (es. palloni-core.ts vs palloni.ts, mediePagelle() vs usePagelle());
src/lib/rosa.ts è l'aggregatore: compone tutti gli hook e restituisce la rosa completa con le statistiche derivate, senza query aggiuntive rispetto a quelle già in cache. Le route consumano useRosa(), non i singoli moduli.

Nessun accesso al database dai componenti: solo attraverso i moduli in src/lib/, così il backend resta sostituibile in un solo punto (DD-013, PORTABILITA.md).

Vincoli di efficienza cloud — niente polling, cache lunga, setQueryData invece di invalidateQueries — in EFFICIENZA_CLOUD.md.

Badge e statistiche sono calcolati a runtime dai dati, non persistiti (DD-007). La gamification deve restare equa tra ruoli (DD-008).

La rosa è tuttora hardcoded in src/lib/crapp-data.ts (rosaCSI); la migrazione verso la tabella giocatori_squadra è in corso — vedi DD-015 e DD-016.

UI

Componenti condivisi in src/components/crapp/ (ui-bits.tsx per PageHeader, Section, StatTile), primitive shadcn in src/components/ui/, animazioni in src/components/motion/. Mobile-first (DD-005): poche schermate, pochi click.

Comandi

npm run dev       # vite dev su http://localhost:8080
npm run build     # build di produzione (nitro)
npm run lint      # eslint (include prettier come regola)
npm run format    # prettier --write .
npm run test      # test unit (veloci, senza rete né database)
npm run test:integration  # route server vere
npm run test:e2e          # percorsi sull'app servita
npm run test:all          # tutto

Branch e flusso di sviluppo

main → produzione, deploy automatico su Vercel.
develop → sviluppo; si lavora qui, mai direttamente su main (DD-003).

develop → test → merge su main → deploy automatico su Vercel

4.4 KiB Raw Blame History