Template di documentazione dell'architettura software (gratis)

Il modo in cui di solito nasce un documento di architettura: arriva un nuovo ingegnere, chiede come si incastrano i pezzi del sistema, e qualcuno promette di "metterlo per iscritto come si deve". Cerca un template di documentazione dell'architettura software, trova un file Word di quaranta pagine del 2012 o un PDF universitario, ne compila metà e non lo riapre più. Un anno dopo il nuovo assunto successivo lo trova, si fida e sbaglia.

Il problema raramente è la mancanza di un template. Sono i template che chiedono tutto, così non si finisce niente, e i documenti senza owner, così non si aggiorna niente. Il template qui sotto è volutamente snello: un unico file markdown, nove sezioni, ognuna presente perché chi lo leggerà ne avrà bisogno. Copialo nel tuo repository, senza registrazione, senza download. Poi leggi le note sezione per sezione su cosa mettere in ogni parte e su come evitare che diventi obsoleto.

A cosa serve un documento di architettura (e chi lo legge)

Un documento di architettura risponde alle domande a cui il codice non risponde in fretta: a cosa serve il sistema, con cosa dialoga, come è suddiviso, perché è suddiviso così e cosa si sa essere fragile. Non è la specifica di design di una singola funzionalità, e non è un riferimento delle API.

Ha cinque tipi di lettore, e aiuta scrivere pensando a loro per nome:

Lettore	Cosa gli serve	Sezioni che leggerà
Un nuovo ingegnere, prima settimana	Dove stanno le cose e come scorre una richiesta	Contesto, container, flussi principali, glossario
Chi revisiona una modifica di design	Cosa tocca la modifica e cosa è già stato deciso	Container, decisioni, obiettivi di qualità
L'ingegnere di reperibilità alle 3 di notte	Cosa dipende da cosa, e cosa si sa che si rompe	Container, flussi principali, rischi
Un auditor o una security review	Confini, flussi di dati, parti esterne	Contesto, vincoli, decisioni
Tu, fra un anno	Perché l'hai fatto così	Decisioni, rischi

Se una sezione del tuo documento non serve a nessuno di loro, cancellala. Questa regola fa per la qualità della documentazione più di qualsiasi template.

Una nota sui nomi: "documento di architettura", "system design document" (SDD) e "software architecture document" (SAD) si usano per indicare più o meno la stessa cosa. I template SDD tendono a essere scritti per progetto o per funzionalità e includono il design di dettaglio; un documento di architettura descrive il sistema così com'è e cambia insieme a esso. Il template qui è del secondo tipo.

Il template (un unico blocco markdown)

Copialo in docs/architecture.md (oppure in ARCHITECTURE.md nella root) e compilalo. Tutto ciò che è tra parentesi angolari è un segnaposto. Cancella le sezioni che non si applicano invece di lasciarle vuote.

# <Nome del sistema>: architettura

| | |
|---|---|
| Owner | <team o persona responsabile di mantenerlo veritiero> |
| Ultima revisione | <AAAA-MM-GG> |
| Prossima revisione | <AAAA-MM-GG, oppure "a ogni modifica delle sezioni 3-5"> |
| Stato | <bozza / attuale / in sostituzione con X> |

## 1. Contesto e ambito

<Due o tre frasi: cosa fa il sistema, per chi e perché esiste.>

**Utenti**
- <Ruolo>: <cosa fanno con il sistema>

**Sistemi esterni**
- <Sistema>: <cosa inviamo o riceviamo, protocollo>

**Fuori ambito**
- <Cose che si dà per scontato che il sistema faccia, ma non fa>

**Diagramma di contesto di sistema (C4 livello 1)**
<Link o embed. Il sistema come un unico box, ogni tipo di utente, ogni sistema esterno.>

## 2. Obiettivi di qualità

Le tre-cinque qualità che prevalgono quando entrano in conflitto tra loro, in ordine di priorità.

| Priorità | Qualità | Scenario concreto |
|---|---|---|
| 1 | <es. Disponibilità> | <es. Il checkout continua a funzionare quando il servizio di raccomandazioni è giù> |
| 2 | <es. Latenza> | <es. checkout p95 sotto i 2 s a 500 ordini/minuto> |
| 3 | <es. Modificabilità> | <es. Un nuovo metodo di pagamento va in produzione senza toccare l'order service> |

## 3. Vincoli

Cose che non abbiamo scelto ma con cui dobbiamo convivere.
- <es. Gira sulla piattaforma Kubernetes aziendale>
- <es. I dati dei clienti restano nell'UE>
- <es. Servizi backend solo in Go o Java>

## 4. Architettura

**Diagramma dei container (C4 livello 2)**
<Link o embed. Ogni unità deployabile e ogni archivio di dati, con tecnologia e protocolli.>

| Container | Tecnologia | Responsabilità | Owner |
|---|---|---|---|
| <Web app> | <SPA React> | <Cosa fa> | <Team> |
| <API> | <Go> | <Cosa fa> | <Team> |
| <Database> | <PostgreSQL> | <Cosa memorizza> | <Team> |

**Diagrammi dei componenti (C4 livello 3)**
<Solo per l'uno o i due container con cui un nuovo arrivato farebbe fatica. Link o embed.>

**Flussi principali**
<I due o tre scenari più importanti, come passi numerati o come diagramma dinamico C4.>

1. <Attore> -> <Container>: <cosa succede>
2. <Container> -> <Container>: <cosa succede, protocollo, sincrono o asincrono>

## 5. Decisioni chiave

I record completi si trovano in <docs/adr/>. Questo è l'indice.

| ADR | Decisione | Stato | Data |
|---|---|---|---|
| [ADR-001](adr/001-<slug>.md) | <es. Un database per servizio> | Accettato | <AAAA-MM-GG> |
| [ADR-002](adr/002-<slug>.md) | <es. Kafka per gli eventi degli ordini> | Accettato | <AAAA-MM-GG> |

## 6. Aspetti trasversali

Come l'intero sistema gestisce le cose che ogni container tocca. Una o due righe ciascuno, con un link al dettaglio.
- **Autenticazione e autorizzazione:** <dove avviene, quale token>
- **Osservabilità:** <log, metriche, trace, dove guardare>
- **Gestione degli errori e retry:** <convenzioni, idempotenza>
- **Dati e privacy:** <dove si trovano i dati personali, conservazione>

## 7. Deployment e operations

- **Ambienti:** <produzione, staging, ...> e in cosa differiscono
- **Dove gira:** <cloud, regione, cluster>
- **Runbook:** <link>
- **Dashboard e alert:** <link>

## 8. Rischi e debito tecnico

| Rischio o debito | Impatto se si manifesta | Piano | Owner |
|---|---|---|---|
| <es. Scorte riservate prima del pagamento, nessuna compensazione> | <Prenotazioni fantasma dopo pagamenti falliti> | <Aggiungere il rilascio in caso di errore, Q4> | <Team> |

## 9. Glossario

| Termine | Significato qui |
|---|---|
| <Ordine> | <Definizione così come la usa il business> |

Questo è tutto il template. Compilato per un sistema con una decina di container, di solito occupa qualche pagina. Se il tuo è molto più lungo, probabilmente qualcosa al suo interno appartiene a un documento collegato piuttosto che a questo.

Sezione per sezione

Intestazione: owner e data di revisione

Le quattro righe in alto contano più di qualsiasi sezione sottostante. Owner dice chi corregge il documento quando è sbagliato. Ultima revisione dice al lettore quanto fidarsi. Un documento che dice "ultima revisione quattordici mesi fa" è onesto; uno che non dice nulla sembra attuale quando non lo è.

1. Contesto e ambito

Parti da qui, perché ogni altra sezione dipende dal confine. Elenca ogni tipo di utente e ogni sistema esterno, compresi quelli che dai per scontati (identity provider, servizio email, gateway di pagamento). La lista fuori ambito fa risparmiare più riunioni di qualsiasi altra parte del documento: è dove scrivi che questo sistema non gestisce i rimborsi, anche se tutti pensano di sì.

Il diagramma è un diagramma di contesto di sistema C4: il tuo sistema come un unico box, utenti e sistemi esterni intorno, frecce etichettate. La guida al diagramma di contesto di sistema spiega cosa ci va dentro.

2. Obiettivi di qualità

La maggior parte dei documenti di architettura salta questa sezione, ed è quella che spiega tutto il resto. "Disponibilità prima della consistenza" o "modificabilità prima delle prestazioni pure" dice al lettore perché i container hanno quell'aspetto. Limitati a tre-cinque obiettivi, ordinali per priorità e dai a ciascuno uno scenario abbastanza concreto da poterlo testare: un numero, un carico, un guasto.

3. Vincoli

I vincoli sono le decisioni prese da qualcun altro: il platform team, l'ufficio legale, la policy aziendale sui linguaggi. Metterli per iscritto chiude la conversazione "perché non hai usato semplicemente X?" e dice a un lettore futuro quali scelte si possono rimettere in discussione e quali no.

4. Architettura: i diagrammi C4

È la sezione che la maggior parte delle persone considera "l'architettura". Usa il modello C4, perché dà a ogni diagramma un solo compito:

Diagramma dei container (livello 2), sempre. Ogni unità deployabile e ogni archivio di dati, ciascuno con la sua tecnologia, ogni freccia con un protocollo. Se disegni un solo diagramma, disegna questo. La guida al diagramma dei container ha un esempio svolto.
Diagrammi dei componenti (livello 3), in modo selettivo. Solo per i container con cui un nuovo arrivato farebbe fatica.
Flussi principali. Due o tre scenari come passi numerati. Un diagramma statico mostra che due container si parlano; un flusso mostra in quale ordine, e quali passi l'utente aspetta. La guida al diagramma dinamico C4 mostra come scriverne uno.

La tabella dei container con una colonna Owner c'è di proposito. Un container che non ha un owner è un container che nessuno aggiornerà nemmeno in questo documento.

Se il C4 è nuovo per te, cos'è il modello C4 spiega i quattro livelli. Per esempi di questi diagrammi applicati a sistemi reali e grandi, vedi i nostri esempi di modello C4.

5. Decisioni chiave (ADR)

Non scrivere le decisioni nel testo. Tieni ciascuna come architecture decision record in un file a sé (contesto, decisione, alternative considerate, conseguenze) e qui conserva solo l'indice. Gli ADR si scrivono una volta e si sostituiscono anziché modificarli, così il documento resta breve e la cronologia resta intatta. La guida completa agli architecture decision record spiega il formato e quando una decisione ne merita uno.

Un buon test per l'indice: un nuovo ingegnere dovrebbe poter indicare qualsiasi box sorprendente della sezione 4 e trovare l'ADR che lo spiega.

6. Aspetti trasversali

Alcune cose non vivono in un solo container: autenticazione, logging, gestione degli errori, dove si trovano i dati personali. Una o due righe ciascuna bastano, con un link al dettaglio. È la sezione su cui un auditor passa la maggior parte del tempo, quindi rendigliela facile.

7. Deployment e operations

Tienila breve e rimanda altrove. Gli ambienti e in cosa differiscono, dove gira il sistema, e i link a runbook e dashboard. Il dettaglio appartiene al tuo codice infrastrutturale e ai tuoi runbook, che cambiano più spesso di quanto dovrebbe cambiare questo documento.

8. Rischi e debito tecnico

La sezione onesta. Scrivi ciò che si sa essere fragile, con un owner e un piano, anche se il piano è "accettato, da rivedere nel Q3". Un rischio messo per iscritto è un rischio a cui qualcuno può dare priorità. Un rischio che vive nella testa di un solo ingegnere se ne va con lui.

9. Glossario

Ogni sistema ha parole che qui significano qualcosa di specifico: "ordine" vs "carrello", "account" vs "tenant", "evasione". Definiscile una volta sola. I nuovi ingegneri leggono questa sezione più di quanto immagini.

Il rapporto con arc42

Se questo template ti sembra familiare, è perché è una versione snella delle stesse idee di arc42, il template gratuito e open source per la documentazione dell'architettura creato da Peter Hruschka e Gernot Starke. arc42 ha dodici sezioni e consiglia esso stesso di documentare "solo ciò di cui i tuoi stakeholder hanno bisogno" (FAQ di arc42, B-1). La corrispondenza:

Questo template	Sezione arc42
1. Contesto e ambito	1 Introduzione e obiettivi (scopo), 3 Contesto e ambito
2. Obiettivi di qualità	1 Introduzione e obiettivi (obiettivi di qualità), 10 Requisiti di qualità
3. Vincoli	2 Vincoli
4. Architettura	4 Strategia della soluzione (in breve), 5 Vista dei building block, 6 Vista di runtime
5. Decisioni chiave	9 Decisioni architetturali
6. Aspetti trasversali	8 Concetti trasversali
7. Deployment e operations	7 Vista di deployment
8. Rischi e debito tecnico	11 Rischi e debito tecnico
9. Glossario	12 Glossario

Scegli arc42 quando ti serve la sua struttura completa: ambienti regolamentati, sistemi grandi con più architetti, o un'organizzazione che lo ha già adottato come standard. Scegli qualcosa di queste dimensioni quando l'alternativa è non avere alcun documento. Per un confronto dettagliato, incluso quale diagramma C4 va in quale sezione di arc42, vedi arc42 vs C4.

Evitare che diventi obsoleto

Ogni documento di architettura è accurato il giorno in cui viene fatto il merge. Che lo sia ancora tra sei mesi dipende da poche abitudini, la maggior parte delle quali riguarda i diagrammi, perché le sezioni 4 e 5 sono quelle dove la realtà cambia più in fretta.

Tienilo nel repository. docs/architecture.md accanto al codice significa che una pull request che divide un servizio può aggiornare la tabella dei container nella stessa review. Una pagina wiki non può far parte di una code review.

Collega i diagrammi, non incollare screenshot. Uno screenshot del diagramma dei container è obsoleto nel momento in cui un container viene rinominato. Un diagramma generato da un modello (Structurizr DSL, un modello YAML o uno strumento che ne contiene uno) è obsoleto solo quanto il modello.

Fai lavorare la data di revisione. Aggiungi il documento a qualsiasi checklist che scatta quando un container viene aggiunto o rimosso: il template delle pull request, la review di architettura, la pianificazione trimestrale. "Prossima revisione: a ogni modifica delle sezioni da 3 a 5" è una voce valida.

Scrivi le decisioni in avanti. Non modificare mai un ADR accettato. Sostituiscilo. L'indice nella sezione 5 mostra così la cronologia, che è la parte di cui le persone hanno più bisogno.

Verifica automaticamente le parti strutturali. Le sezioni 1 e 4 descrivono cose che esistono nel codice: servizi, archivi di dati, dipendenze. Si possono confrontare con il repository. Le sezioni 2, 6 e 8 no, e hanno bisogno di una persona a cadenza regolare. La guida al rilevamento del drift architetturale spiega i metodi per il primo tipo e cosa ciascuno riesce e non riesce a vedere.

È il problema per cui è costruito archyl, per la metà del documento fatta di diagrammi. Collega un repository e la scoperta tramite IA propone il modello C4 (sistemi, container, componenti e relazioni) da rivedere e approvare invece di disegnarlo. ADR, documentazione e flussi si collegano agli elementi che descrivono. Un drift score verifica poi se gli elementi documentati esistono ancora nel codice, in modo deterministico e senza IA nel percorso, così una sezione 4 obsoleta si presenta come un numero anziché come una sorpresa. Non verifica i tuoi obiettivi di qualità né la tua lista dei rischi; per quelli serve ancora la data di revisione. Per le pratiche che mantengono aggiornata la documentazione, con o senza uno strumento, vedi documentazione architetturale vivente.

FAQ

Cosa dovrebbe includere un documento di architettura software?

Come minimo: il contesto e l'ambito del sistema (utenti e sistemi esterni), un diagramma a livello di container con le tecnologie, le decisioni architetturali chiave con le loro motivazioni, i rischi noti e un owner con una data di revisione. Il template qui sopra aggiunge obiettivi di qualità, vincoli, aspetti trasversali, note di deployment e un glossario, tutti brevi.

Questo template è davvero gratuito?

Sì. È il blocco markdown qui sopra. Copialo e adattalo al tuo sistema. Nessuna registrazione, nessun download, nessuna email.

Dove dovrebbe stare il documento di architettura?

Nel repository, come docs/architecture.md o ARCHITECTURE.md, accanto agli ADR in docs/adr/. In questo modo le modifiche all'architettura e le modifiche al documento passano dalla stessa pull request.

Quanto dovrebbe essere lungo un documento di architettura?

Il più breve possibile, pur rispondendo alle domande dei suoi lettori. Per un sistema con una decina di container, qualche pagina è normale. Se cresce molto oltre, sposta il dettaglio in documenti collegati (runbook, ADR, riferimenti delle API) e tieni questo come mappa.

Qual è la differenza tra questo e un system design document?

Un system design document di solito si scrive per un progetto o una funzionalità, prima di costruirla, e include il design di dettaglio. Un documento di architettura descrive l'intero sistema così com'è ora e cambia insieme a esso. Spesso i team hanno un documento di architettura per sistema e molti design document nel corso della sua vita, e le decisioni durature dei design document finiscono come ADR.

Dovrei usare arc42?

Se ti serve la sua struttura completa o la tua organizzazione lo usa già, sì. Questo template corrisponde alle sezioni di arc42 (vedi la tabella sopra), quindi puoi partire da qui e passare ad arc42 in seguito senza riscrivere nulla.

Vuoi che i diagrammi della sezione 4 vengano dal tuo codice invece che dalla memoria? Prova archyl gratis con il piano Developer, senza carta di credito. Continua a leggere: arc42 vs C4 | Architecture Decision Records: la guida completa | Cos'è il modello C4? | Documentazione architetturale vivente | Rilevamento del drift architetturale.