Architettura del software

Dal codice che funziona al codice che si mantiene

Questo percorso parte da un programma volutamente fragile e lo trasforma, passo dopo passo, in una piccola applicazione organizzata. Il progetto è sempre lo stesso: un Registro del laboratorio scolastico per gestire strumenti, prestiti, guasti e salvataggio dei dati.

L’obiettivo non è studiare architettura in astratto. L’obiettivo è capire una cosa molto concreta: quando una regola deve stare nel dominio, quando una funzione diventa un caso d’uso, quando il salvataggio dei dati è solo un dettaglio tecnico e quando la UI sta facendo troppo.

Inizia qui

Lo studente non deve scegliere tra tre corsi. Deve seguire un solo percorso e fermarsi al checkpoint adatto al tempo disponibile.

I 24 elementi del percorso sono moduli, non per forza 24 lezioni singole. Un modulo è una tappa didattica da 2-4 ore: può contenere una lezione lunga, due lezioni brevi, un laboratorio guidato o una revisione in classe.

Nell’indice del percorso ogni modulo mostra sempre le lezioni previste. Una lezione con link è già pubblicata; una lezione senza link è pianificata e verrà sviluppata dopo.

1. Parti dal modulo 1. Prepara repository, cartella progetto e README iniziale.
2. Costruisci prima una versione fragile. Nei moduli 1-2 il codice può essere disordinato: serve a vedere il problema.
3. Arriva al checkpoint 20 ore. Qui devi avere dominio minimo, casi d’uso principali e persistenza in memoria.
4. Continua con i moduli 9-16. Aggiungi interfacce, adapter, localStorage o JSON, test più strutturati e documentazione.
5. Chiudi con i moduli 17-24. Inserisci variante database o API, sicurezza di base, logging, revisione con Codex e presentazione finale.

Il primo obiettivo reale è quindi semplice: avviare il registro e far emergere il disordine iniziale. L’architettura viene introdotta dopo, quando serve davvero.

Apri la prima lezione: Preparazione del laboratorio

Struttura reale del corso

Il filo resta sempre lo stesso: stesso progetto, stesso dominio, più responsabilità separate a ogni fase.

A chi è rivolto

• Studenti con basi di programmazione.
• Classi di scuola superiore che hanno già scritto script, pagine web o piccole applicazioni.
• Docenti che vogliono proporre un laboratorio di progettazione software concreto.
• Principianti che sanno far funzionare un programma, ma iniziano a sentire il bisogno di organizzarlo meglio.
• Studenti intermedi che vogliono capire test, refactoring e separazione tra regole e interfaccia senza entrare in architetture pesanti.

Prerequisiti

Prima di iniziare è utile conoscere:

• variabili;
• funzioni;
• condizioni;
• cicli;
• array o liste;
• oggetti o dizionari;
• file separati o moduli;
• basi di HTML e JavaScript se si lavora nel browser;
• basi minime di Git, consigliate ma non obbligatorie.

Lo stack didattico principale usa JavaScript modulare o TypeScript leggero, browser e localStorage. Non servono framework complessi: l’obiettivo è vedere le responsabilità del codice, non nasconderle dentro strumenti troppo grandi.

Competenze in uscita

Alla fine del percorso lo studente deve saper:

• separare interfaccia, casi d’uso, dominio e infrastruttura;
• riconoscere responsabilità troppo grandi in una funzione, in un file o in un servizio;
• modellare stati e regole del problema;
• scrivere casi d’uso indipendenti dalla UI;
• sostituire una persistenza in memoria con localStorage o JSON;
• scrivere test sulle regole principali;
• documentare la struttura del progetto;
• spiegare una scelta architetturale con parole semplici.

Progetto guida: Registro del laboratorio scolastico

Il registro rappresenta strumenti o dispositivi usati in un laboratorio scolastico: notebook, sensori, kit Arduino, alimentatori, tablet, microscopi, cavi, adattatori o qualunque materiale prestabile.

Il progetto cresce per tappe. All’inizio basta un registro in memoria, con pochi dati e comandi essenziali. Poi si separano regole e casi d’uso. Più avanti si aggiungono persistenza, errori più chiari, test, documentazione e una variante infrastrutturale.

Le funzionalità progressive sono:

• registrare strumenti o dispositivi;
• cercare strumenti per nome, categoria o stato;
• segnare strumenti come disponibili, in prestito, guasti o in manutenzione;
• registrare prestiti;
• chiudere prestiti;
• aprire segnalazioni di guasto;
• salvare dati prima in memoria, poi in localStorage o JSON, poi eventualmente in database o API nei moduli finali;
• mostrare messaggi comprensibili all’utente;
• testare regole e casi d’uso.

Esempio di stati:

const StatoStrumento = {
  DISPONIBILE: "disponibile",
  IN_PRESTITO: "in_prestito",
  GUASTO: "guasto",
  IN_MANUTENZIONE: "in_manutenzione",
};

Esempio di regola di dominio:

function puoEsserePrestato(strumento) {
  return strumento.stato === StatoStrumento.DISPONIBILE;
}

Questa regola non deve stare nel pulsante “Presta” della UI. Deve stare nel dominio, perché vale sempre: da una pagina web, da una CLI, da un test o da una futura API.

Architettura minima

Il laboratorio usa quattro livelli. Sono nomi tecnici, ma l’idea è semplice: ogni livello ha un lavoro preciso.

Un esempio di flusso:

1. La UI riceve il nome dello studente e l’id dello strumento.
2. La UI chiama il caso d’uso RegistraPrestito.
3. Il caso d’uso legge lo strumento dall’archivio.
4. Il dominio verifica se lo strumento può essere prestato.
5. L’infrastruttura salva il nuovo stato e il prestito.
6. La UI mostra un messaggio comprensibile.

Il dominio non deve sapere se i dati stanno in memoria, in localStorage, in un file JSON o in un database. Questo confine è il cuore del percorso.

Come leggere il programma dettagliato

La tabella sotto serve a docenti e studenti per pianificare le lezioni. Non va letta come un elenco di argomenti teorici: ogni modulo produce un pezzo del progetto o una verifica concreta.

• I moduli 1-8 portano al checkpoint 20 ore.
• I moduli 9-16 consolidano il progetto.
• I moduli 17-24 chiudono il laboratorio con revisione e presentazione.

La regola pratica è: non anticipare complessità. Prima si fa funzionare il registro, poi si separa meglio, poi si sostituisce l’infrastruttura.

Piano dettagliato per docenti

Questa parte non è la navigazione principale del corso. Serve a pianificare ore, attività e output. La sequenza da seguire resta quella del Percorso del corso sopra: modulo 1, poi modulo 2, poi modulo 3, fino ai checkpoint.

Ore 0-20: moduli 1-8

Checkpoint 20 ore

Alla fine del modulo 8 deve essere pronto:

• progetto avviato;
• dominio minimo;
• casi d’uso principali;
• separazione base dei livelli;
• persistenza in memoria;
• almeno alcuni test sulle regole;
• README iniziale.

Non è ancora richiesto:

• database;
• API;
• sicurezza avanzata;
• diagrammi dettagliati;
• architetture complesse.

La domanda guida del checkpoint è: se cambio la UI, le regole principali restano valide e testabili?

Ore 21-40: moduli 9-16

Checkpoint 40 ore

Alla fine del modulo 16 deve essere pronto:

• dominio stabile;
• casi d’uso principali;
• UI o CLI funzionante;
• persistenza localStorage o JSON;
• test su regole e casi d’uso;
• errori gestiti;
• README;
• diagramma architetturale minimo;
• presentazione finale.

La domanda guida del checkpoint è: se cambio il modo in cui salvo i dati, posso mantenere dominio e casi d’uso quasi intatti?

Ore 41-60: moduli 17-24

Checkpoint 60 ore

Alla fine del modulo 24 deve essere pronto:

• progetto completo;
• variante infrastrutturale;
• test più maturi;
• gestione errori chiara;
• documentazione tecnica;
• revisione con Codex;
• riflessione sulle scelte architetturali;
• presentazione finale.

La domanda guida del checkpoint è: so spiegare perché il progetto è organizzato così e quali scelte cambierei in una versione reale?

Micro-sfide

Trova la responsabilità nascosta

• Obiettivo: riconoscere una funzione che fa più lavori.
• Attività: scegli una funzione lunga del registro e sottolinea tutte le responsabilità presenti: lettura input, validazione, regola, salvataggio, messaggio.
• Vincolo: non riscrivere subito il codice.
• Risultato atteso: elenco delle responsabilità e prima proposta di separazione.

Sposta una regola fuori dalla UI

• Obiettivo: impedire che un pulsante contenga logica importante.
• Attività: trova una regola scritta dentro un event listener e spostala nel dominio.
• Vincolo: la UI deve solo chiamare un caso d’uso o una funzione di dominio.
• Risultato atteso: stessa funzionalità, regola testabile senza browser.

Impedisci il prestito di uno strumento guasto

• Obiettivo: modellare un’invariante di dominio.
• Attività: implementa la regola per cui uno strumento guasto non può essere prestato.
• Vincolo: la regola deve valere anche se il prestito viene richiesto da test o CLI.
• Risultato atteso: caso d’uso rifiutato con errore di dominio comprensibile.

Cambia archivio senza modificare il caso d’uso

• Obiettivo: capire interfacce e inversione delle dipendenze.
• Attività: sostituisci ArchivioStrumentiInMemoria con ArchivioStrumentiLocalStorage.
• Vincolo: il file del caso d’uso non deve cambiare.
• Risultato atteso: stesso caso d’uso, persistenza diversa.

Trasforma un errore tecnico in messaggio utente

• Obiettivo: distinguere errore interno e comunicazione all’utente.
• Attività: intercetta un errore come “Cannot read properties of undefined” e trasformalo in “Strumento non trovato”.
• Vincolo: non mostrare stack trace o dettagli tecnici nella UI.
• Risultato atteso: messaggio chiaro per l’utente e dettaglio tecnico disponibile nei log.

Scrivi un test prima del refactoring

• Obiettivo: proteggere il comportamento prima di cambiare struttura.
• Attività: scegli una regola già funzionante e scrivi un test prima di spostare codice.
• Vincolo: il refactoring non deve cambiare il risultato del test.
• Risultato atteso: test verde prima e dopo la modifica.

Separa DTO e modello di dominio

• Obiettivo: evitare che il formato salvato decida il modello interno.
• Attività: crea un DTO per i dati in localStorage e una funzione di mapping verso Strumento.
• Vincolo: il dominio non deve leggere direttamente il formato JSON salvato.
• Risultato atteso: mapping esplicito tra dato esterno e modello interno.

Aggiungi un nuovo stato “in manutenzione”

• Obiettivo: verificare quanto il modello è modificabile.
• Attività: aggiungi lo stato in_manutenzione e aggiorna ricerche, prestiti e messaggi.
• Vincolo: evita condizioni duplicate sparse in molti file.
• Risultato atteso: nuovo stato gestito senza rompere gli stati esistenti.

Documenta una decisione tecnica

• Obiettivo: spiegare una scelta architetturale.
• Attività: scrivi nel README perché il dominio non usa direttamente localStorage.
• Vincolo: massimo 10 righe, linguaggio comprensibile a un compagno.
• Risultato atteso: decisione tecnica breve, motivata e leggibile.

Usa Codex per fare una revisione architetturale

• Obiettivo: usare l’AI come revisore.
• Attività: chiedi a Codex di controllare confini tra Presentation, Application, Domain e Infrastructure.
• Vincolo: Codex non deve riscrivere il progetto al posto tuo.
• Risultato atteso: report con problemi, rischi e prossimi refactoring.

Crea un archivio finto per i test

• Obiettivo: testare un caso d’uso senza dipendere da localStorage.
• Attività: implementa un fake repository in memoria usato solo dai test.
• Vincolo: il fake deve rispettare la stessa interfaccia dell’archivio reale.
• Risultato atteso: test più veloci e indipendenti dal browser.

Disegna il flusso di un caso d’uso

• Obiettivo: rendere visibile il passaggio tra livelli.
• Attività: disegna il flusso di RegistraPrestito con frecce e nomi dei livelli.
• Vincolo: niente UML complesso; bastano caselle e frecce.
• Risultato atteso: diagramma leggibile da uno studente esterno.

Uso di Codex nel laboratorio

Codex può essere utile quando aiuta a ragionare sul codice. In questo percorso va usato come revisore, compagno di analisi e generatore di alternative controllate, non come scorciatoia per produrre tutto senza capire.

Codex può essere usato per:

• revisionare codice;
• generare liste di test;
• suggerire refactoring;
• individuare violazioni architetturali;
• spiegare codice esistente;
• aiutare nella documentazione.

Codex non deve essere usato per:

• generare tutto il progetto senza comprensione;
• scegliere l’architettura al posto dello studente;
• introdurre framework non richiesti;
• nascondere errori dietro codice apparentemente corretto.

Prompt pronti per studenti e docenti:

1. “Analizza questo file e indica se contiene troppe responsabilità. Non riscrivere il codice. Restituisci solo: responsabilità individuate, punti di accoppiamento, suggerimenti di separazione.”
2. “Queste sono le regole di dominio del Registro del laboratorio. Genera una lista di test, non il codice dei test. Per ogni test indica nome, scenario, input e risultato atteso.”
3. “Controlla se questo caso d’uso dipende dalla UI o dalla persistenza. Segnala solo le violazioni architetturali.”
4. “Proponi un refactoring in massimo 5 passi. Ogni passo deve mantenere il programma funzionante. Non introdurre nuove librerie.”
5. “Analizza questa struttura di cartelle e dimmi se i confini tra Presentation, Application, Domain e Infrastructure sono chiari.”
6. “Leggi questo README e dimmi se uno studente esterno riuscirebbe a capire come è organizzato il progetto.”
7. “Osserva questi test e dimmi quali regole importanti non sono ancora coperte. Non scrivere codice.”
8. “Confronta queste due soluzioni di persistenza e indica pro, contro e rischi per un progetto didattico.”

Regola pratica: prima si prova a spiegare il problema con parole proprie, poi si chiede a Codex di controllare, criticare o proporre alternative.

Rubrica di valutazione

Condizioni minime di sufficienza: il progetto non è sufficiente se:

• le regole principali sono nella UI;
• il salvataggio dati è mescolato ai casi d’uso;
• non esiste nessun test sulle regole;
• il README non spiega la struttura.

Checklist finale per studenti

• Ho separato i livelli.
• Le regole stanno nel dominio.
• I casi d’uso non leggono direttamente dalla UI.
• La persistenza è sostituibile.
• Ho scritto test sulle regole importanti.
• Gli errori utente sono comprensibili.
• Il README spiega il progetto.
• So spiegare almeno una scelta architetturale.
• So indicare un limite del progetto attuale.
• So dire cosa cambierei in una versione più grande.

Checklist per docenti

• Prerequisiti verificati.
• Progetto iniziale predisposto.
• Micro-sfide assegnate.
• Checkpoint a 20, 40 e 60 ore.
• Criteri di valutazione condivisi.
• Uso controllato di Codex.
• Revisione finale dei progetti.
• Tempo riservato a demo e retrospettiva.

Glossario essenziale

• Architettura software: insieme di confini, responsabilità e decisioni che rendono un programma comprensibile e modificabile.
• Responsabilità: compito preciso assegnato a una funzione, classe, modulo o livello.
• Coesione: misura di quanto gli elementi di un modulo lavorano per lo stesso scopo.
• Accoppiamento: dipendenza tra parti del sistema; se è alto, cambiare una parte rompe facilmente le altre.
• Dominio: parte del codice che rappresenta il problema reale: strumenti, prestiti, stati, regole.
• Invariante: regola che deve restare sempre vera, per esempio “uno strumento guasto non può essere prestato”.
• Caso d’uso: operazione applicativa che coordina una richiesta, per esempio registrare un prestito.
• Interfaccia: contratto che dice quali operazioni sono disponibili senza fissare come sono implementate.
• Adapter: componente che collega il sistema a un dettaglio esterno, come localStorage, file, database o API.
• DTO: oggetto usato per trasferire dati in un formato esterno o salvato.
• Mapping: trasformazione tra DTO e modello di dominio.
• Persistenza: modo in cui i dati vengono salvati e recuperati.
• Refactoring: miglioramento della struttura del codice senza cambiare il comportamento osservabile.
• Test: verifica ripetibile che controlla se una regola o un comportamento funziona come previsto.
• Fake: implementazione semplificata usata nei test, per esempio un archivio in memoria.
• Stub: oggetto o funzione che restituisce risposte predefinite durante un test.
• Requisito non funzionale: vincolo di qualità, come sicurezza, prestazioni, leggibilità o manutenibilità.

Principi da ricordare

• Prima capire il problema, poi scrivere codice.
• La UI non deve contenere le regole importanti.
• Il dominio non deve conoscere localStorage, database o API.
• Un caso d’uso coordina, non mostra messaggi.
• L’infrastruttura è un dettaglio sostituibile.
• I test proteggono il refactoring.
• L’architettura serve a cambiare il programma senza romperlo.
• Codex aiuta a ragionare, ma lo studente deve verificare.

Conclusione

Questo percorso non serve a imparare una formula da copiare. Serve a costruire un modello mentale: quando il codice cresce, bisogna capire quali parti parlano con quali altre, dove vivono le regole, che cosa può cambiare e che cosa deve restare stabile.

Alla fine, il Registro del laboratorio scolastico non è importante solo perché funziona. È importante perché lo studente può leggerlo, modificarlo, testarlo e spiegarlo. Questo è il salto dal codice che parte al codice che si mantiene.