Disegnare l’architettura prima di farla generare

Un diagramma di 10 minuti su carta o lavagna virtuale evita giorni di refactor. L’AI è ottima a implementare un’architettura definita; è pessima a inventarla coerentemente. Il diagramma non deve essere bello: deve essere corretto, leggibile e completo abbastanza da guidare la generazione.

Perché questa lezione conta

Senza disegno preliminare, il modello inventa pezzi che non si parlano: stato qui, fonte di verità là, integrazione con servizio esterno fatta diversamente in due punti. Il risultato sembra funzionare alla demo e cade alla prima feature aggiuntiva. Con disegno preliminare, ogni file generato si infila in un sistema coerente.

Obiettivo operativo

Alla fine devi saper:

1. produrre diagramma leggero (caselle, frecce, etichette) di un sistema piccolo;
2. identificare contratti principali (componenti, API, eventi) e confini di fiducia;
3. tradurre il diagramma in prompt strutturati per generazione.

Nucleo della lezione

1. Diagrammi leggeri, non UML completo

Non serve UML. Serve chiarezza. Quattro elementi sufficienti:

• Caselle: cose che esistono (componenti UI, servizi backend, database, servizi esterni).
• Frecce: chi parla con chi, in che direzione (request/response, eventi, sottoscrizioni).
• Confini di fiducia: linee che separano aree (client/server, dentro/fuori organizzazione, pubblico/privato).
• Etichette: cosa scorre lungo le frecce (dati, autenticazione, formato).

Strumenti: carta, Excalidraw (gratuito, web), Mermaid (testuale, versionabile in repo), tldraw, Figma. Per progetti piccoli, anche un blocco di testo strutturato basta.

Esempio testuale:

[Browser]
   ↕ HTTPS, cookie sessione
[Vercel Edge — Astro pages]
   ↕ HTTPS interno
[API Routes — Node.js]
   ↕ TLS, query SQL
[Supabase Postgres]

[Browser] → [Resend API] (solo per send transactional email, da server)
[API Routes] ⇆ [Stripe API] (webhook in entrata, charge in uscita)

Confine di fiducia: tra Browser e API

Brutale ma corretto. Risponde alle domande più importanti.

2. Contratti principali

Il diagramma rivela i punti dove serve definire un contratto:

• Componenti: nome, props ricevute, callback emesse, stato interno.
• Moduli: funzioni esportate, tipi pubblici, dipendenze.
• API endpoint: metodo, URL, request body, response body, errori.
• Storage: tabelle, vincoli, indici, accesso.
• Eventi: nome, payload, chi pubblica, chi sottoscrive.
• Errori: dove possono originarsi, come si propagano, come si comunica all’utente.
• Punti di estensione: dove prevedi che il sistema crescerà (plugin, hook, configurazione esterna).

Definire contratti prima della generazione = il modello ha confini espliciti, non inventa.

3. Dal diagramma al prompt

Sequenza:

1. Diagramma (testuale o visuale) salvato come file in repo (docs/architettura.md).
2. Tabella contratti principali (API, eventi, componenti chiave).
3. Prompt iniziale che allega/cita il diagramma e indica quale parte verrà costruita ora.
4. Modello genera codice all’interno della parte indicata, rispettando contratti.
5. Verifica diff vs diagramma: il codice ha rispettato i confini? Le frecce sono ancora valide?

Ogni nuova feature: aggiorna diagramma se cambia, poi prompt. Mai prompt senza diagramma aggiornato.

Caso guidato

Scenario: vuoi generare una piccola app “inventario libri” per catalogare libri, cercarli e segnare prestiti. Prima di chiedere codice, disegna l’architettura minima:

[Browser]
  - BookList
  - BookForm
  - SearchBox
  - LoanPanel

[Application logic]
  - addBook(input)
  - searchBooks(query)
  - openLoan(bookId, person)
  - closeLoan(loanId)

[Storage]
  - LocalStorage adapter per MVP
  - interfaccia BookRepository

[External services]
  - nessuno nella prima versione

Poi aggiungi i confini:

• la UI non decide se un libro può essere prestato;
• la regola “un libro già prestato non può essere prestato di nuovo” vive nella logica applicativa;
• localStorage è dettaglio sostituibile, non compare nei componenti;
• i dati salvati hanno formato stabile: books[], loans[].

Prompt migliore:

Genera solo il primo passo dell'app inventario libri seguendo questa architettura. Implementa tipi, repository in memoria e funzioni applicative. Non creare UI ancora. Non usare localStorage nel dominio. Aggiungi esempi di chiamata e casi errore.

Noti la differenza: l’AI non deve inventare dove mettere le regole. Tu hai già deciso il disegno, il modello genera dentro quel perimetro.

Procedura pratica

Sequenza iniziale di un nuovo progetto:

1. Mappa 4 strati (lezione 23): frontend, backend, dati, esterni.
2. Disegna diagramma: caselle + frecce + confini.
3. Lista contratti principali: API endpoint, componenti chiave, eventi.
4. Scrivi docs/architettura.md con: diagramma + tabella contratti + decision log breve.
5. Includi nel AGENTS.md un puntatore a docs/architettura.md come fonte di verità per scelte architetturali.
6. Prompt iniziale di generazione cita architettura e parte da implementare.

Laboratorio guidato

Disegna architettura per “app capstone” personale (anche se non l’hai ancora scelto, immagina una semplice). Esempio: lettore RSS local-first.

Diagramma:

[Browser PWA]
   ↑↓  IndexedDB locale (feed cache, articoli letti)
   ↕   Service Worker (offline, sync background)
   ↕   HTTPS
[Vercel Edge]
   ↕   server-side fetch (CORS workaround)
[Feed RSS esterni]

Nessun backend persistente. Nessun account utente.
Confine: Browser è il sistema completo. Vercel solo proxy.

Contratti:

• Componente <FeedList>: prop feeds: FeedSource[], emette onSelectFeed(id).
• Funzione fetchAndParse(url): Promise<ParsedFeed>: chiama Vercel proxy, ritorna feed.
• Schema IndexedDB: store feeds (id, url, title, lastSync), store articles (id, feedId, url, title, content, readAt).
• Endpoint /api/proxy?url=...: GET, ritorna XML/RSS bypassando CORS, rate-limited.

Decision log breve:

• Local-first: scelto per privacy + offline. Costo: niente sync multi-dispositivo (out of scope).
• Vercel: scelto come proxy CORS, gratuito. Alternativa: client-side CORS proxy (rischio di down).

Questo documento, allegato al primo prompt, dà al modello tutto ciò che serve per non inventare.

Output atteso

File docs/architettura.md con: diagramma testuale, tabella 5-10 contratti, decision log iniziale (3-5 voci), domande aperte. Diventa fonte di verità del progetto.

Controllo qualità del disegno

Un buon disegno architetturale per vibe coding non deve essere bello: deve impedire fraintendimenti. Fallisce se contiene solo nomi generici come “frontend”, “backend”, “database” senza dire quali responsabilità vivono in ciascun blocco. Funziona quando una persona esterna riesce a rispondere a tre domande: dove nasce il dato, dove viene validato, dove viene salvato.

Prima di usarlo in un prompt, leggilo cercando verbi: “valida”, “salva”, “calcola”, “mostra”, “sincronizza”. Se un blocco non ha verbi, è decorazione. Se due blocchi hanno lo stesso verbo, forse hai duplicazione di responsabilità.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: preparare una descrizione visuale e testuale del sistema prima di lasciare che l’AI crei file e dipendenze. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Diagrammi leggeri: blocchi, frecce, dati, confini di fiducia, servizi esterni.
• Contratti principali: componenti, moduli, API, storage, eventi, errori e punti di estensione.
• Come tradurre il diagramma in prompt: prima struttura, poi implementazione, poi test.

3. Applicazione: svolgi il laboratorio: disegnare l’architettura di un’app capstone in forma testuale e visuale. L’output da ottenere è: un documento di architettura di una pagina da riusare nei moduli di contesto, generazione e verifica.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• ho un diagramma scritto/disegnato per ogni progetto significativo;
• conosco i contratti principali del mio sistema;
• il file architettura è linkato dal AGENTS.md ed è citato nei prompt iniziali;
• aggiorno il diagramma quando l’architettura cambia, non solo all’inizio.

Errori comuni

Diagramma fatto e dimenticato. Architettura cambia, diagramma no. Diagramma stale = peggio di nessun diagramma.

Diagramma elaborato 100x meno utile di brutto. UML completo per progetto da 1 weekend = procrastinazione travestita. Cinque caselle e cinque frecce bastano.

Niente confini di fiducia. Senza separazione client/server/esterno, gli errori di sicurezza sono incorporati nel design.

Contratti impliciti. “Il modello capirà”. No: il modello inventa. Contratti scritti.

Diagramma solo visuale, mai testuale. Versionabile = testuale. Mermaid + git è meglio di file PNG.

Saltare diagramma su progetti “piccoli”. I progetti piccoli sono dove i diagrammi rendono di più (poco da disegnare, molto da chiarire).

Prompt di lavoro

Sto progettando architettura per: [descrizione progetto in 5 righe]

Aiutami a costruirla in 4 fasi (rispondi una alla volta, aspetta mio OK):

Fase 1 — strati: identifica frontend, backend, dati, servizi esterni rilevanti per il mio caso. Per ognuno, lista cosa contiene.

Fase 2 — diagramma testuale: disegna caselle + frecce + confini di fiducia. Stile compatto, leggibile. Etichette su frecce.

Fase 3 — contratti principali: API endpoint, componenti chiave, eventi, schema dati. Tabella con: nome, input, output, errori.

Fase 4 — decision log: 3-5 decisioni iniziali con motivazione + alternative scartate + classificazione reversibile/irreversibile (vedi lezione 27).

Concludi con domande aperte e raccomandazione di cosa prototipare per primo (passo più rischioso).

Non scrivere codice. Voglio l'architettura prima.

Esercizio finale

Apri il README.md di un tuo progetto recente. Quanto del diagramma architetturale è scritto lì? Probabilmente niente. Aggiungi una sezione “Architettura” di 200 parole con il diagramma testuale e i contratti principali. Poi, tra una settimana, riapri il file: è ancora valido o l’architettura è cambiata? Quel ciclo (scrivi, aggiorna, mantieni vivo) è ciò che separa un progetto navigabile da uno labirinto.