Il modello C4 e Structurizr

Il modello C4 e Structurizr: dalla complessità alla chiarezza nell’architettura software

Introduzione
L’architettura software è uno degli aspetti più critici e allo stesso tempo più trascurati nello sviluppo di sistemi complessi. Da un lato, è il cuore pulsante di ogni progetto: definisce i confini, le interazioni e le regole del gioco tra i diversi componenti. Dall’altro, è spesso percepita come un argomento “per addetti ai lavori”, complicata da schemi troppo dettagliati, diagrammi confusionari o documentazione poco leggibile.

In questo contesto si inserisce il modello C4, ideato da Simon Brown, che ha l’obiettivo di rendere l’architettura comprensibile, comunicabile e mantenibile. Non solo: grazie a strumenti come Structurizr, oggi è possibile integrare la modellazione architetturale direttamente nei processi di sviluppo, rendendola un asset vivo e aggiornato nel tempo.

Perché parlare di architettura software oggi
Le architetture moderne sono sempre più complesse: microservizi, container, cloud ibridi, API distribuite. In questo scenario:

• La comunicazione è fondamentale: non basta scrivere codice, serve spiegare come il sistema è fatto e come cresce.

• La documentazione deve essere agile: un PDF statico non basta più; serve qualcosa che possa vivere insieme al codice.

• Gli stakeholder sono eterogenei: sviluppatori, manager, utenti finali, fornitori. Tutti devono poter capire il sistema, ma a livelli di dettaglio diversi.

È proprio da queste esigenze che nasce il modello C4.

Il modello C4: i quattro livelli di astrazione
Il nome C4 deriva dai quattro livelli che compongono il modello: Context, Container, Component e Code. Ognuno fornisce un diverso grado di dettaglio.

1. Context Diagram
   Il livello più alto. Rappresenta il sistema come una scatola nera, mostrando chi sono gli utenti (attori), quali altri sistemi interagiscono con il nostro e come avvengono le interazioni.
   Esempio: immagina un sistema di prenotazione online. Nel diagramma di contesto vedremo gli utenti (cliente, operatore), i sistemi esterni (gateway di pagamento, sistema CRM) e le relazioni con il nostro sistema centrale.

2. Container Diagram
   Il secondo livello scende dentro la “scatola” e descrive i principali contenitori logici del sistema: applicazioni web o mobile, API, database, servizi di backend, microservizi.
   Esempio: nel sistema di prenotazione, il container diagram mostrerà il frontend web, l’app mobile, l’API REST, il database PostgreSQL e magari un servizio di notifiche via email/SMS.

3. Component Diagram
   Il terzo livello analizza i singoli contenitori, mostrando i componenti interni che li compongono: moduli, librerie, servizi interni, controller.
   Esempio: nel backend del sistema di prenotazione, potremmo avere un componente “Gestione Pagamenti”, uno “Gestione Prenotazioni”, uno “Gestione Utenti”, ciascuno con le proprie responsabilità.

4. Code Diagram
   Infine, il quarto livello scende fino al dettaglio del codice, rappresentando classi, interfacce e metodi. Non sempre è necessario arrivare a questo livello, ma è utile per documentare parti critiche del sistema, fare formazione a nuovi sviluppatori e rendere più chiare le code review

I vantaggi del modello C4
Rispetto ai tradizionali UML o ai diagrammi “home made” con strumenti di disegno, il modello C4 porta con sé diversi benefici:

1. Semplicità – Ogni diagramma ha uno scopo chiaro e non si rischia di sovraccaricare di dettagli chi non ne ha bisogno.

2. Comunicazione efficace – Un manager può fermarsi al livello Context, mentre uno sviluppatore può arrivare fino al dettaglio del codice.

3. Scalabilità – Perfetto per sistemi complessi basati su microservizi o architetture cloud.

4. Flessibilità – Non impone uno standard rigido: puoi arricchirlo con simboli, icone e convenzioni adatte al tuo contesto.

Structurizr: lo strumento per dare vita al C4
Avere un buon modello è utile, ma serve anche uno strumento che ne faciliti l’adozione. Qui entra in gioco Structurizr, sviluppato dallo stesso Simon Brown.

Caratteristiche principali:

• DSL e API: puoi descrivere la tua architettura con un linguaggio testuale o tramite codice (Java, .NET, ecc.).

• Versionamento: i diagrammi diventano parte del repository Git, aggiornabili e condivisibili come il codice.

• Collaborazione: è uno strumento web-based, quindi i team possono lavorare sugli stessi diagrammi in tempo reale.

• Integrazione: si può collegare con wiki, pipeline CI/CD, documentazione automatica.

Esempio pratico: migrazione di un sistema legacy
Immaginiamo una pubblica amministrazione che voglia migrare da un gestionale monolitico a un sistema a microservizi:

• Con il Context Diagram, mostriamo agli stakeholder il sistema centrale e i sistemi esterni (pagamenti, anagrafe, servizi interni).

• Con il Container Diagram, spieghiamo come il nuovo sistema è diviso in microservizi (gestione utenti, gestione pratiche, notifiche).

• Con il Component Diagram, dettagliamo ogni microservizio per il team di sviluppo.

• Con Structurizr, versioniamo i diagrammi e li aggiorniamo man mano che la migrazione procede.

Il risultato? Tutti gli stakeholder, dal dirigente al programmatore, hanno una visione chiara e aggiornata del progetto.

Best practice per introdurre C4 e Structurizr

1. Parti dal contesto: non scendere subito nel dettaglio, ma costruisci progressivamente i livelli.

2. Mantieni i diagrammi semplici: ogni diagramma deve rispondere a una domanda precisa.

3. Usa Structurizr DSL: la scrittura testuale ti obbliga a essere chiaro e mantiene i diagrammi aggiornati.

4. Integra nel flusso DevOps: collega la generazione dei diagrammi alle pipeline di build e release.

5. Coinvolgi il business: mostra i diagrammi di contesto e container anche a chi non è tecnico.

Conclusioni
Il modello C4 non è “l’ennesima notazione”, ma un modo nuovo di pensare la documentazione architetturale: chiara, multilivello e adatta a diversi pubblici.

Con strumenti come Structurizr, l’architettura non è più un disegno statico su PowerPoint, ma un asset vivo, integrato nel codice e aggiornato nel tempo.

Per aziende e pubbliche amministrazioni, adottare C4 e Structurizr significa migliorare la governance dei progetti, ridurre i rischi e aumentare la collaborazione tra team.

Full-Stack Group supporta i clienti in questo percorso con consulenza, formazione e progetti pilota, aiutando i team a introdurre queste pratiche in modo efficace e sostenibile.