# CrAPP — Technical case study **Autore:** Davide Grilli · davide.grilli@outlook.com **Progetto:** applicazione web per la gestione di una squadra di pallavolo, in produzione con utenti reali. **Ruolo:** sviluppo full-stack (interfaccia, database, notifiche), insieme a Ivan Cacciari. **Codice:** > **In una frase:** un'applicazione full-stack completa (accesso con Google, database con permessi per ruolo, notifiche push ed email, valutazione delle partite in diretta), messa in produzione, testata e documentata. **In sintesi:** sezioni 1–3 per una visione d'insieme; la sezione 5 entra nelle scelte tecniche, ciascuna con problema, soluzione e motivo; il glossario (sezione 8) spiega i termini specialistici. --- ## 1. In breve | Cosa | Dato | | -------------- | -------------------------------------------------------------------------------------------------- | | Stato | In produzione, usata da una squadra reale (~17 utenti), versione 1.6.3 | | Periodo | Primi commit 6 agosto 2026, versione 1.0.0 il 24 settembre, ultimo aggiornamento 22 novembre | | Team | Due persone: 295 commit su 344 sono miei, il resto di Ivan Cacciari | | Frontend | React 19, TypeScript, TanStack Start (rendering lato server), Vite, Tailwind CSS 4 | | Backend | Supabase (PostgreSQL, autenticazione, archivio file); hosting su Vercel | | Dimensioni | 109 file TypeScript (~17.700 righe), 50 migration SQL (~3.600 righe), oltre 60 policy di sicurezza | | Qualità | 77 file di test su tre livelli, 54 decisioni di progetto scritte, 16 schede di modulo | | Servizio extra | Un worker per le email, in un container Docker su un Raspberry Pi | ## 2. Cosa dimostra | Competenza | Dove si vede | | ------------------------------ | ----------------------------------------------------------------------------------------------- | | Sviluppo full-stack end to end | Dal database con RLS alla PWA, fino al worker in container e al job pianificato | | Sicurezza applicativa | RLS per ruolo, test dei permessi con utenti veri, chiusura delle route aperte (DD-024) | | Modellazione dati | 50 migration additive, vincoli a database, trigger di pulizia a cascata | | Testing | 77 file di test su tre livelli, con test che rifiutano di toccare la produzione | | Attenzione ai costi cloud | Regole di efficienza imposte per costruzione, eccezioni motivate | | Affidabilità e casi limite | Sessioni con scadenza, fusi orari, timestamp non validi | | Documentazione e comunicazione | 54 decisioni, 16 schede di modulo, indice e regole di manutenzione | | Lavoro in team e con AI | Due sviluppatori, flusso di branch, regole scritte per gli assistenti | | Operatività | Stack locale per le prove distruttive, migration verificate prima del push, backup e ripristino | ## 3. Il problema e il risultato Una squadra di pallavolo gestisce tutto con chat, fogli di calcolo e carta: presenze rincorse su WhatsApp, scout delle partite su carta, certificati medici che scadono senza che nessuno se ne accorga, nessun promemoria per chi deve portare i palloni. La soluzione è **una sola app sul telefono di tutti**, installabile dalla schermata Home senza passare dagli store. Due vincoli hanno guidato quasi ogni scelta tecnica: - **facile da usare:** mobile-first, poche schermate e pochi tocchi (DD-005); - **costo quasi nullo:** piano cloud minimo, nessun server da amministrare, per una squadra di ~17 persone. Tre ruoli vedono cose diverse, e a farlo rispettare è il database: | Ruolo | Cosa fa | | ---------- | -------------------------------------------------------------------- | | Giocatore | Risponde alle presenze, vede badge e statistiche, vota pagelle e MVP | | Allenatore | Crea eventi e convoca, sollecita chi non risponde | | Admin | Dashboard, certificati medici, profili, export CSV | Come appare sul telefono:
Presenze
Presenze
Risposta in un tocco, chi c'è e chi no
Sollecito
Sollecito
Un tocco per sollecitare chi non ha risposto
Scout live
Scout live
Valutazione − / + per fondamentale, in diretta
Dashboard admin
Dashboard admin
Certificati medici mancanti e profili
### Il risultato, in numeri Dati del database di produzione al 22 novembre 2026. Sono solo conteggi aggregati, senza dati personali, e includono le prove effettuate in produzione. | Cosa | Numero | | ------------------------------- | ---------------------------------------------------------------------------------- | | In uso da | 2 settembre 2026 (primo evento in calendario), 12 settimane | | Eventi già svolti | 26: 20 allenamenti, 4 partite, 2 altri eventi | | Eventi in calendario | 78 in tutto, fino al 31 maggio 2027 | | Risposte di presenza registrate | 426 sugli eventi già svolti: 353 presente, 66 assente, 4 infortunato, 3 in ritardo | | Voti dei giocatori | 26 voti MVP e 67 pagelle | | Partite valutate con lo scout | 4, archiviate | | Dispositivi con le push attive | 20 | | Notifiche in-app inviate | 303 | | Rilasci | 17, dalla 1.0.0 (24 settembre) alla 1.6.3 (16 novembre): meno di otto settimane | Ogni correzione e ogni novità, rilascio per rilascio, è nel [CHANGELOG](../docs/CHANGELOG.md). **Da dove nasce.** Il progetto è partito come prototipo su Lovable, un generatore di app. Per scelta (DD-001) è stato spostato su un repository indipendente, con Vercel e Supabase gestiti direttamente. Resta una traccia, un preset di build, censita nel piano di portabilità. ## 4. Architettura ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart TB T["Telefono
app installabile (PWA)
React 19 + cache lunga"] subgraph V["Vercel"] SSR["TanStack Start
pagine renderizzate lato server"] API["Route API
notifiche, campionato CSI, cron di keepalive"] MW["Middleware
gestione errori, protezione CSRF,
token di sessione"] end subgraph S["Supabase"] DB[("PostgreSQL
permessi RLS per ruolo")] AU["Autenticazione
login con Google"] ST["Archivio file
foto e documenti"] end W["Worker email
container Docker su Raspberry Pi"] EXT["Portale CSI
risultati del campionato"] OUT["SMTP e servizi push dei browser"] T -- "pagine" --> SSR T -- "azioni e notifiche" --> API SSR --> MW API --> MW MW -- "query con l'identità dell'utente" --> DB MW -- "verifica la sessione" --> AU T -- "carica foto e documenti" --> ST API -- "legge i risultati" --> EXT DB -- "coda di notifiche" --> W W --> OUT OUT --> T classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class MW hl ``` Figura 1 — Il telefono parla con Vercel; ogni richiesta passa da un middleware prima di toccare Supabase. Le notifiche escono da una coda, non dall'app. **La regola centrale:** i componenti dell'interfaccia non parlano mai direttamente con il database. Ogni area funzionale ha un modulo in `src/lib/` (presenze, eventi, pagelle, scout…) che contiene due cose separate: gli _hook_ che leggono e scrivono i dati, e le _funzioni pure_ che fanno i calcoli. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart LR C["Componente
schermata"] -- "chiede i dati" --> H["Hook del modulo
es. usePresenze"] H -- "legge e scrive" --> Q["Cache locale
TanStack Query"] Q -- "solo se la cache è scaduta" --> DB[("Database")] H -- "delega i calcoli" --> P["Funzioni pure
calcoli senza rete"] P -- "provate da" --> TU["Test unit veloci"] classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class Q hl ``` Figura 2 — Le schermate leggono dalla cache; il database si interroga solo quando serve. **Perché conta:** se domani cambia il fornitore del database, si riscrive un solo livello e le schermate restano com'erano; e i calcoli (percentuali, badge, classifiche) si provano in millisecondi senza avviare nulla. --- ## 5. Le scelte tecniche, spiegate ### 5.1 La sicurezza sta nel database, non nell'interfaccia **Il problema.** Nascondere un pulsante non protegge niente: chi chiama l'API a mano salta l'interfaccia. **La scelta.** I permessi sono regole di PostgreSQL chiamate **Row Level Security** (RLS): il database stesso decide, riga per riga, cosa può leggere o scrivere l'utente che sta facendo la richiesta. L'app ne usa più di 60. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart LR R["Richiesta
dall'app o fatta a mano"] --> JWT["Identità verificata
token di sessione"] JWT --> RLS{"Policy RLS
cosa può fare
questo utente?"} RLS -- "consentito" --> OK["Dati restituiti
o modifica salvata"] RLS -- "non consentito" --> NO["Nessuna riga,
modifica rifiutata"] classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class RLS hl ``` Figura 3 — Il database decide per ogni richiesta, anche se non arriva dall'app. **Come l'ho verificato.** Un test di integrazione (`permessi.test.ts`) **crea utenti veri su un database locale e interroga come loro**, controllando uno per uno i permessi della tabella di progetto. Rifiuta di girare contro la produzione: legge le credenziali dallo stack locale, non dal file `.env`, così non può puntare al database vero per sbaglio. **Perché conta.** Un permesso scritto solo nel codice si verifica leggendolo; uno scritto nel database e provato con utenti reali si verifica eseguendolo. ### 5.2 Una vulnerabilità trovata, valutata e chiusa per iscritto **Il problema.** Le route in `src/routes/api/public/` usano una chiave di servizio che salta la RLS. Una revisione ha mostrato che nessuna controllava chi la chiamava: chiunque conoscesse l'URL poteva far suonare i telefoni di tutta la squadra. La difesa apparente («serve un id evento valido») non lo era, perché l'id è prevedibile e visibile a qualsiasi utente loggato. **La scelta (DD-024).** Le route che inviano notifiche verificano prima le credenziali, e lo fanno _prima ancora_ di validare l'input, così la risposta non rivela nemmeno se un evento esiste. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart TD REQ["Chiamata alla route"] --> TK{"Token di sessione
valido?"} TK -- "no" --> E401["401 non autenticato"] TK -- "sì" --> RL{"Ruolo admin
in user_roles?"} RL -- "no" --> E403["403 non autorizzato"] RL -- "sì" --> VAL["Validazione dell'input"] VAL --> ACT["Invio delle notifiche"] classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class TK,RL hl ``` Figura 4 — Le credenziali si controllano prima di tutto, anche prima dell'input. **Perché conta.** Il danno possibile era molestia e consumo della quota push, non furto di dati; la decisione lo dichiara esplicitamente. Valutare il rischio in modo proporzionato e comunque chiudere la porta è il comportamento che si cerca in chi lavora su sistemi reali. ### 5.3 Costi bassi per costruzione, non per ottimizzazione **Il problema.** Su un piano cloud minimo ogni query ha un costo, e un'app che ricarica i dati di continuo lo fa pagare. **La scelta.** Regole imposte dall'inizio: niente polling, cache lunga (5 minuti) e passiva, e dopo una modifica la cache si aggiorna a mano con `setQueryData` invece di invalidarla, perché invalidare costerebbe una nuova lettura. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart LR subgraph NO["Approccio comune"] direction LR M1["Modifica"] --> I["Invalida la cache"] --> R1["Rilegge dal database
1 query in più"] end subgraph SI["Approccio di CrAPP"] direction LR M2["Modifica"] --> S["Aggiorna la cache
con il valore già noto"] --> R2["Nessuna query in più"] end classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class S,R2 hl ``` Figura 5 — Dopo una modifica la cache si aggiorna con il valore già noto: una query in meno. Un aggregatore (`useRosa()`) compone tutto ciò che è già in cache e calcola statistiche e badge a runtime **senza query aggiuntive**. L'eccezione è documentata: nello scout live un altro dispositivo può aver preso il controllo, quindi lì si rilegge davvero. **Perché conta.** L'efficienza è una regola del progetto con eccezioni motivate, non un'ottimizzazione tardiva. ### 5.4 Concorrenza e fusi orari: i bug che i test felici non trovano **Scout live a più dispositivi.** Più persone possono aprire lo scout della stessa partita, ma ne scrive una sola alla volta. La sessione scade dopo 5 minuti di inattività, così se il telefono del referente si spegne nessuno resta bloccato; un timestamp illeggibile libera la sessione invece di bloccarla per sempre. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% stateDiagram-v2 [*] --> Libera Libera --> InUso: un giocatore apre lo scout InUso --> InUso: ogni tocco aggiorna l'orario InUso --> Libera: nessun tocco per 5 minuti InUso --> Libera: fine partita, salvata in archivio ``` Figura 6 — Una sessione scout ferma da più di 5 minuti si considera libera: chi arriva dopo può riprenderla. **Mezzanotte italiana.** La data di «oggi» si calcola con il fuso `Europe/Rome` tramite `Intl`, non con i metodi locali di `Date`. Il motivo: sul server il fuso è spesso UTC, e `toISOString()` lo è sempre. Un errore qui sposta la mezzanotte, e nelle prime ore del giorno una partita già giocata risulterebbe «di domani». **Perché conta.** Sono errori che compaiono solo in orari e situazioni particolari. Averli previsti e scritti nel codice con la spiegazione è ciò che distingue un prototipo da un'app usata davvero. ### 5.5 L'integrità dei dati la garantiscono i vincoli **Il problema.** Il voto MVP deve essere definitivo: se si potesse cambiare, la classifica di una partita potrebbe ribaltarsi dopo che la squadra l'ha già vista. **La scelta (DD-051).** Non basta togliere il pulsante «Cambia voto». Il vincolo `UNIQUE (match_id, votante_id)` fa rifiutare il secondo voto dal database, e al giocatore resta solo il permesso di inserimento: modifica e cancellazione sono riservate agli admin, che possono correggere un errore. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart LR V1["Primo voto
del giocatore"] --> INS["INSERT consentito"] --> SAL[("Voto salvato")] V2["Secondo voto
stessa partita"] --> UQ{"Vincolo UNIQUE
match_id, votante_id"} UQ -- "violato" --> RIF["Rifiutato dal database"] ADM["Admin"] --> COR["UPDATE / DELETE
per correggere un errore"] --> SAL classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class UQ hl ``` Figura 7 — Il secondo voto lo rifiuta il database, non l'interfaccia. Lo stesso principio vale per le migration (le modifiche allo schema): sono solo additive, non si riscrivono mai una volta applicate, e prima di ogni push in produzione salvo lo schema. **Perché conta.** L'interfaccia è un comfort; la regola vera sta nel dato, dove nessun bug dell'interfaccia può aggirarla. ### 5.6 Notifiche su tre canali, senza dipendenze proprietarie **Il problema.** Chi non risponde alla convocazione va sollecitato, ma senza martellare la squadra e senza legarsi a un servizio esterno a pagamento. **La scelta.** Le notifiche nascono dentro il database, da un job pianificato, e finiscono in code. Un worker separato le consegna. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontSize":"20px"},"flowchart":{"wrappingWidth":340,"padding":14}}}%% flowchart TB A["1 · Il database
24 ore prima dell'evento controlla
chi non ha risposto o ha risposto «forse»"] B["2 · La coda
per ognuno scrive una notifica:
in-app, push ed email"] C["3 · Il worker
un piccolo programma in Docker
legge la coda e consegna"] T["Push
sul telefono,
anche ad app chiusa"] M["Email
nella casella
di posta"] IA["Avviso in-app
nel centro
notifiche"] R["Il giocatore risponde
con un tocco"] A --> B B --> C B -- "subito" --> IA C --> T C --> M T --> R IA --> R M --> R classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class B hl ``` Figura 8 — Dal controllo nel database alla risposta del giocatore: la coda separa chi decide da chi consegna. Dettagli che contano: - **Push senza librerie di terzi:** il protocollo Web Push con firma VAPID è implementato con **Web Crypto**, disponibile in Node 18+. - **Worker isolato:** parla solo con Supabase, con un server SMTP a scelta e con i servizi push dei browser. È in un container con controllo di salute, su un Raspberry Pi; nessuna porta in entrata, nessun IP pubblico. - **Ognuno decide:** push, in-app ed email hanno ciascuna un interruttore personale. - **Niente rumore:** il sollecito automatico parte una sola volta, a 24 ore dall'evento, e solo per chi non ha ancora risposto. **Perché conta.** Tre canali con un'infrastruttura minima, tutta sostituibile. ### 5.7 Un modello dati pensato per i permessi Le tabelle principali, dall'alto in basso: chi è l'utente, a quale evento si riferisce, quali dati produce. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontSize":"20px","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart TB U["Account Google"] R["user_roles
chi è admin"] G["giocatori_squadra
lo slot del giocatore"] E["eventi_app
allenamenti e partite"] PR["risposte_presenze
chi c'è"] VO["voti
MVP, pagelle, badge"] SC["scout
la partita in numeri"] U -- "ha un ruolo" --> R U -- "si collega a" --> G G -- "è convocato a" --> E E -- "genera" --> PR E -- "genera" --> VO E -- "genera" --> SC classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF class E hl ``` Figura 9 — Al centro l'evento: presenze, voti e scout nascono da lui e spariscono con lui. Sono mostrate le tabelle principali. Due regole di dominio che il modello codifica e che hanno richiesto una decisione scritta ciascuna: - `convocati` **vuoto significa tutta la rosa**, non nessuno (DD-027); - **cancellare un evento** pulisce a cascata, con un trigger, tutte le tabelle collegate: presenze, voti, turni, scout (DD-029). --- ## 6. Come lavoro: documentazione prima, codice dopo Il progetto è **document-first** (DD-002): ogni funzione nasce come scheda in `docs/modules/` (obiettivo, dati, permessi), poi si scrive il codice. La scelta è deliberata: serve a lavorare bene in più persone e con assistenti AI, cioè con collaboratori che non ricordano nulla delle sessioni precedenti. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%% flowchart LR A["Scheda del modulo
e riga in ROADMAP"] --> B["Decisione scritta
se la scelta non è ovvia"] B --> C["Schema: documentazione,
nuova migration, policy, test permessi"] C --> D["Logica pura con test unit,
poi hook e interfaccia"] D --> E["CHANGELOG e checklist
di fine lavoro"] ``` Figura 10 — Dalla scheda del modulo al rilascio: la documentazione viene prima del codice. - **54 decisioni di progetto** (`docs/decisions/`), ognuna con contesto, scelta, alternative scartate e quando riaprire la questione. Chi arriva dopo capisce non solo cosa c'è, ma perché. - **Una sola casa per ogni informazione**, per evitare che le copie divergano: funzioni in `ROADMAP`, schema in `DATABASE`, rilasci in `CHANGELOG`. - **Portabilità dichiarata:** PostgreSQL standard, API HTTP standard, nessuna funzione proprietaria. Esiste un piano scritto per spostare tutto su un normale server Node + PostgreSQL, con script di backup e procedura di ripristino. - **Guardia sulla catena di fornitura:** i pacchetti nuovi devono avere almeno 24 ore di vita, per ridurre il rischio di pacchetti compromessi appena pubblicati. ### Un metodo pensato per usare l'IA meglio Un assistente AI ricomincia da zero a ogni sessione: non sa cosa si è deciso la settimana scorsa e non conosce le abitudini del progetto. Se la conoscenza vive nelle teste o nelle chat, l'assistente deve indovinarla; se vive nel repository, la legge. Per questo la documentazione è la **memoria condivisa** di persone e assistenti (la regola 4 di `AGENTS.md` lo dice: la fonte di verità è il repository, non la cronologia della conversazione). Il risultato è un'IA più _efficiente_, perché legge meno, e più _efficace_, perché sbaglia meno. | Cosa c'è nel progetto | Cosa evita all'assistente | Vantaggio | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------ | | Indice con ordine di lettura e una sola casa per ogni informazione | Esplorare tutto il codice a tappeto o trovare due versioni diverse dello stesso dato | Efficienza | | Grafo del repository interrogabile (graphify) | Cercare file a tentativi per capire chi chiama cosa | Efficienza | | Decisioni (DD) lette una per una, solo quelle richiamate dal modulo | Caricare tutta la storia del progetto per fare una modifica piccola | Efficienza | | Scheda del modulo scritta prima del codice | Inventare funzioni o comportamenti non voluti (era il rischio che motivò DD-002) | Efficacia | | Decisioni con le alternative già scartate | Riproporre ogni volta una soluzione già valutata e rifiutata | Efficacia | | «Trappole note» in `ARCHITECTURE.md` | Ripetere errori già visti, come invalidare la cache o accedere al database dai componenti | Efficacia | | Un solo file di regole, `AGENTS.md`, che Claude Code, Codex e Cursor leggono | Comportamenti diversi a seconda dello strumento usato | Coerenza | | Test obbligatori e checklist di fine lavoro (lint, tipi, test, documentazione) | Dichiarare finito un lavoro che non lo è: la verifica la fa la macchina, non la fiducia | Affidabilità | Funziona anche per le persone: chi entra nel progetto, come un nuovo collega, parte dagli stessi documenti. Il metodo non sostituisce il giudizio di chi revisiona, ma gli dà qualcosa di verificabile: ogni modifica dell'assistente si confronta con una scheda, una decisione e un test. ### Test su tre livelli | Livello | File | Cosa prova | | ----------- | ---- | ----------------------------------------------------------------- | | Unit | 43 | Calcoli puri: veloci, senza rete né database | | Integration | 33 | Route server vere e permessi per ruolo, su un database locale | | End-to-end | 1 | Percorsi completi sull'app servita (da estendere, vedi sezione 7) | ### Uso dell'intelligenza artificiale Sviluppo con assistenti AI (Claude Code e Cursor). Per governarli esiste un file di regole di progetto (`AGENTS.md`) con la procedura obbligatoria prima di dichiarare finito un lavoro: documentazione aggiornata, lint, controllo dei tipi, test. L'AI accelera la scrittura; decisioni, controllo dei permessi e verifica restano un lavoro di revisione, ed è ciò che questo repository documenta. --- ## 7. Limiti e prossimi passi Cosa migliorerei, in ordine di priorità. | Limite | Cosa farei | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Sviluppo e produzione condividono lo stesso Supabase | Separare gli ambienti; intanto le prove distruttive girano solo sullo stack locale | | Il backup non è automatizzato per intero | Automatizzare anche l'export delle variabili d'ambiente di Vercel | | Un solo test end-to-end | Aggiungere i percorsi principali sull'app servita | | I dati del campionato si leggono dal portale a ogni richiesta | Sincronizzarli periodicamente in una tabella locale (obiettivo già scritto) | | Statistiche calcolate a runtime (DD-007) | Rivalutare se i dati crescessero di molto | ## 8. Glossario | Termine | Significato | | --------------------------- | ------------------------------------------------------------------------------------------------------------- | | PWA | App web che si installa dalla schermata Home del telefono, senza passare dagli store | | SSR | Le pagine vengono preparate dal server prima di arrivare al telefono, quindi si aprono più in fretta | | RLS (Row Level Security) | Regole del database che decidono, riga per riga, cosa può leggere o scrivere ogni utente | | CSRF | Attacco in cui un sito esterno fa compiere azioni a un utente loggato a sua insaputa; il middleware lo blocca | | Migration | File SQL che modifica lo schema del database in modo ordinato e ripetibile | | Vincolo `UNIQUE` | Regola del database che impedisce di salvare due righe uguali su certi campi | | Cache (TanStack Query) | Copia locale dei dati già scaricati, per non rileggerli dal database a ogni schermata | | Hook / funzione pura | Hook: codice che legge o scrive dati. Funzione pura: calcolo che dà sempre lo stesso risultato, senza effetti | | Job pianificato (`pg_cron`) | Attività che il database esegue da solo a orari stabiliti | | Web Push / VAPID | Standard delle notifiche sul telefono, anche ad app chiusa; VAPID identifica chi le invia | | Container (Docker) | Programma impacchettato con tutto ciò che serve, che gira uguale su qualsiasi computer |