arc42 vs modello C4: differenze e come combinarli

Qualcuno nel tuo team propone arc42 per la documentazione dell'architettura. Qualcun altro dice che il team usa già il C4. La discussione che segue di solito dà per scontato che bisogna sceglierne uno, ed è la prima ipotesi da abbandonare.

Confrontare arc42 e C4 è un po' come confrontare la scaletta di un report con i grafici che ci vanno dentro. arc42 è un template: dodici sezioni che ti dicono cosa documentare di un'architettura, dagli obiettivi di qualità ai rischi. Il C4 è un modello e una notazione: quattro livelli di diagrammi che ti dicono come disegnare la struttura di un sistema software. Si sovrappongono in alcuni punti e si combinano bene. Questa guida spiega cosa copre ciascuno, cosa chiede arc42 che il C4 non disegna, cosa aggiunge il C4 ad arc42, e una mappatura sezione per sezione di quale diagramma C4 va dove.

La risposta in una riga

arc42 è un template per la documentazione dell'architettura. Il modello C4 è un modo di disegnare diagrammi di architettura software. La maggior parte dei team che li usa entrambi mette i diagrammi C4 dentro le sezioni di arc42.

La FAQ di arc42 descrive così il rapporto tra i due. Alla domanda "E arc42 e C4?", risponde che il modello C4 "ha molte somiglianze con alcune sezioni di arc42, ma ne omette certe parti (ad es. requisiti di qualità, concetti trasversali, rischi e poche altre)" (FAQ di arc42, B-17). La stessa FAQ elenca il modello C4 di Simon Brown tra le alternative ad arc42 (A-6), il che è vero se ti servono solo i diagrammi, e fuorviante se ti serve tutto il resto che un documento contiene.

Le dodici sezioni di arc42

Prima di mappare qualsiasi cosa, conviene avere davanti le sezioni con i loro numeri esatti. Provengono dalla documentazione di arc42, versione del template 9.0 (luglio 2025, secondo la pagina di download):

C'è un'altra cosa su cui arc42 è esplicito: non devi compilare tutto. Alla domanda "quali parti sono essenziali?" la FAQ risponde "Per favore non compilare tutto. Documenta solo ciò di cui i tuoi stakeholder hanno bisogno", perché tutto ciò che scrivi "potrà richiedere lavoro di manutenzione in futuro" (B-1). Questo consiglio conta per la combinazione descritta più sotto. Un documento arc42 snello con buoni diagrammi C4 in tre sezioni batte un documento completo che nessuno aggiorna.

Cosa copre arc42 che il C4 non copre

Il C4 riguarda la struttura e, tramite i suoi diagrammi supplementari, il runtime e il deployment. Non dice nulla delle parti di un'architettura che non sono box. In termini di arc42, queste sezioni non hanno alcuna controparte C4:

• Sezione 1, Introduzione e obiettivi. Perché il sistema esiste, a chi importa e i tre-cinque obiettivi di qualità che orientano ogni decisione successiva. Un diagramma di contesto C4 mostra chi usa il sistema. Non può dire che "un checkout deve completarsi in meno di due secondi" conta più di "la UI di amministrazione è bella".
• Sezione 2, Vincoli. "Deve girare sulla piattaforma Kubernetes aziendale", "deve essere scritto in Java", "i dati non possono uscire dall'UE". I vincoli spiegano scelte che un diagramma si limita a mostrare.
• Sezione 4, Strategia della soluzione. La manciata di scelte fondamentali (prima il monolite, event sourcing per il ledger, comprare il motore di ricerca) riassunte in un unico punto.
• Sezione 8, Concetti trasversali. Autenticazione, gestione degli errori, logging, pattern di persistenza, internazionalizzazione. Attraversano ogni box, quindi nessun box da solo può mostrarli.
• Sezione 10, Requisiti di qualità. Scenari di qualità concreti: stimolo, risposta, misura.
• Sezione 11, Rischi e debito tecnico. Ciò che sai essere fragile e ciò che hai rimandato.
• Sezione 12, Glossario. Le parole che usa il business, definite una volta sola.

Sono esattamente le sezioni che la FAQ di arc42 nomina quando dice che il C4 "ne omette certe parti". Se la tua documentazione di architettura è fatta solo di diagrammi C4, queste sono le domande che un nuovo architetto o un auditor avrà ancora dopo averla letta.

Cosa aggiunge il C4 ad arc42

arc42 non prescrive volutamente alcuna notazione. La sezione 5 chiede una "collezione gerarchica di black box e white box", la sezione 3 suggerisce "ogni tipo di diagramma che mostri il sistema come una black box", e la sezione 6 accetta di tutto, da un elenco numerato di passi ai diagrammi di sequenza, al BPMN o alle macchine a stati (sezione 5, sezione 3, sezione 6). Questa flessibilità è un punto di forza del template, ed è anche il punto in cui i documenti arc42 variano di più: ogni autore disegna a modo suo.

Il C4 colma questa lacuna con due cose:

1. Uno zoom coerente. La vista dei building block di arc42 ha già dei livelli: il Livello 1 è "la descrizione white box del sistema complessivo insieme alle descrizioni black box di tutti i building block contenuti", e il Livello 2 "zooma su alcuni building block del livello 1" (sezione 5). I livelli del C4 danno a quei passi di zoom un significato fisso (sistema, container, componente, codice), così un lettore che conosce il C4 sa cosa sta guardando prima ancora di leggere le etichette.
2. Un piccolo vocabolario condiviso. Persona, software system, container, componente, relazione, ciascuno con un nome, una descrizione e di solito una tecnologia. È una notazione sufficiente a rendere confrontabili i diagrammi tra team diversi, e abbastanza ridotta da non richiedere formazione a nessuno.

C'è anche un vantaggio pratico. Se i diagrammi C4 provengono da un modello anziché da uno strumento di disegno, lo stesso elemento compare con lo stesso nome nelle sezioni 3, 5, 6 e 7. arc42 non si esprime su come ottenerlo, ma è ciò che mette d'accordo le sezioni tra loro.

Tabella di mappatura: quale diagramma C4 va in quale sezione di arc42

Questa mappatura è nostra, ricavata dalle definizioni delle sezioni di arc42 e da quelle dei diagrammi C4. La FAQ di arc42 rimanda a esempi della community che usano la combinazione (per esempio il repository di esempio arc42 + C4 di bitsmuggler) anziché prescriverne una, e i team variano nei dettagli indicati nell'ultima colonna.

Le sezioni che non compaiono in tabella (1, 2, 4, 8, 10, 11, 12) sono testo e tabelle, non diagrammi C4. Non è una lacuna di nessuno dei due metodi; è la divisione del lavoro.

Esempio svolto

Ecco come appare la combinazione per il sistema e-commerce della nostra guida completa al modello C4: una single-page app React, un API gateway, servizi Go per ordini, prodotti e utenti, database PostgreSQL, Kafka e un notification service. È uno scheletro arc42 snello con i diagrammi C4 al loro posto, non un documento completo.

1. Introduzione e obiettivi
   - Scopo: i clienti sfogliano e ordinano prodotti; il personale di magazzino gestisce le scorte
   - Obiettivi di qualità: (1) il checkout si completa in meno di 2 s al p95
                           (2) nessun ordine viene confermato senza un'autorizzazione di pagamento riuscita
                           (3) si può aggiungere un nuovo servizio senza modificare quelli esistenti

2. Vincoli
   - Gira sulla piattaforma Kubernetes aziendale; Go per i servizi backend

3. Contesto e ambito
   - Contesto di business: diagramma C4 System Context
     [Customer], [Warehouse Staff] -> [E-Commerce Platform]
     -> [Stripe], [FedEx API], [SendGrid]
   - Contesto tecnico: tabella interlocutore / protocollo / dati scambiati

4. Strategia della soluzione
   - Un database per servizio; notifiche asincrone tramite Kafka

5. Vista dei building block
   - Livello 1: diagramma C4 Container (SPA, API Gateway, servizi Order/Product/User,
     tre database PostgreSQL, Kafka, Notification Service)
   - Livello 2: diagramma C4 Component del solo Order Service
     (Order Handler, Order Service, Order Repository, Payment Client,
     Inventory Client)

6. Vista di runtime
   - "Il cliente effettua un ordine": diagramma dinamico C4, 10 passi numerati

7. Vista di deployment
   - Produzione: diagramma di deployment C4
   - Staging: solo le differenze rispetto alla produzione

8. Concetti trasversali
   - Autenticazione sul gateway; chiavi di idempotenza su POST /orders;
     logging strutturato con un request ID

9. Decisioni architetturali
   - ADR-001 Un database per servizio
   - ADR-002 Kafka per gli eventi degli ordini invece di chiamate sincrone
   - ADR-003 Autorizzare il pagamento prima di scrivere l'ordine

10. Requisiti di qualità
   - Scenario: 500 checkout al minuto durante una promozione, p95 sotto i 2 s

11. Rischi e debito tecnico
   - Le scorte vengono riservate prima del pagamento; ancora nessuna compensazione se il pagamento fallisce

12. Glossario
   - Ordine, Prenotazione, Autorizzazione, Evasione

Nota dove stanno i diagrammi: sezioni 3, 5, 6 e 7. Tutto il resto sono poche righe di testo. Nota anche come il rischio nella sezione 11 e l'ADR-003 nella sezione 9 si riferiscano alla stessa cosa che mostra il diagramma dinamico nella sezione 6. È in questi rimandi incrociati che un documento arc42 e C4 combinato dimostra il suo valore: il diagramma mostra l'ordine dei passi, l'ADR dice perché, e il rischio dice cosa non va ancora.

Per il diagramma dinamico in sé, la guida al diagramma dinamico C4 ripercorre passo per passo proprio questo scenario. Per la sezione 9, la guida completa agli architecture decision record spiega il formato che arc42 raccomanda e come tenere un indice.

Se le dodici sezioni di arc42 ti sembrano più di quanto serva al tuo team, il nostro template di documentazione dell'architettura software è una scaletta markdown più breve costruita sulle stesse idee, con una sezione che spiega come si ricollega ad arc42.

Tenerli entrambi aggiornati

arc42 e C4 condividono lo stesso punto debole: entrambi sono eccellenti il giorno in cui vengono scritti. La FAQ stessa di arc42 avverte che ogni sezione che compili è manutenzione che ti sei impegnato a fare (B-1). Alcune abitudini che reggono nel tempo:

• Tieni i diagrammi fuori dal corpo del documento quando puoi. Rimanda a diagrammi generati da un modello, o incorporali, invece di incollare screenshot. Lo screenshot di un diagramma dei container diventa obsoleto il giorno in cui un container viene rinominato. Un diagramma generato dal modello è obsoleto solo quanto il modello.
• Metti le sezioni che cambiano in fretta accanto al codice. Le sezioni 5, 6 e 9 cambiano con il codice. Le sezioni 1, 2 e 10 cambiano con il business. Conservare il primo gruppo nel repository (arc42 fornisce template Markdown e AsciiDoc proprio per questo) significa che le pull request possono aggiornarle.
• Scrivi gli ADR in avanti, non modificarli mai. Una decisione superata riceve un nuovo ADR. La sezione 9 diventa una storia invece di un racconto riscritto.
• Dai a ogni sezione un owner e una data di revisione. Un documento senza owner è un documento che nessuno aggiorna.
• Verifica le sezioni strutturali rispetto al codice. Le sezioni 3 e 5 descrivono cose che esistono nel codice, quindi si possono verificare automaticamente. Le sezioni 1, 8 e 10 no; hanno bisogno di una revisione umana, a cadenza regolare.

Quest'ultimo punto è dove entra in gioco archyl, e solo per una parte del problema. archyl contiene il modello C4, non un documento arc42. La sua scoperta tramite IA propone sistemi, container, componenti e relazioni a partire da un repository, da approvare, gli ADR si collegano agli elementi C4 che riguardano, e un drift score verifica se gli elementi documentati esistono ancora nel codice. Questo copre le sezioni ricche di diagrammi (3, 5, 6, 9). Non scrive i tuoi obiettivi di qualità, i tuoi concetti trasversali né la tua lista dei rischi, e non c'è un export arc42; le sezioni testuali restano nel tuo documento arc42, con link al modello.

FAQ

arc42 è meglio del C4?

Nessuno dei due è migliore, perché non fanno lo stesso lavoro. arc42 è un template di documentazione che copre obiettivi, vincoli, struttura, runtime, deployment, decisioni, qualità e rischi. Il C4 è un modo di disegnare la struttura in modo coerente. Se ti serve un documento di architettura completo, usa arc42 (o qualcosa con una forma simile). Se ti servono diagrammi coerenti, usa il C4. La maggior parte dei team che ha bisogno di entrambi usa i diagrammi C4 dentro arc42.

Si possono usare arc42 e C4 insieme?

Sì, ed è comune. arc42 non prescrive una notazione, quindi i diagrammi C4 si inseriscono direttamente nelle sue sezioni: il diagramma di contesto nella sezione 3, i diagrammi dei container e dei componenti nella sezione 5, i diagrammi dinamici nella sezione 6 e i diagrammi di deployment nella sezione 7.

Dove va il diagramma dei container C4 in arc42?

Nella sezione 5, Vista dei building block, al Livello 1: la vista white box dell'intero sistema. I diagrammi dei componenti vanno al Livello 2 per i container che ne hanno bisogno. Se il tuo sistema è un monolite modulare, i building block del Livello 1 potrebbero essere moduli anziché container, e la corrispondenza è meno precisa.

arc42 richiede UML?

No. arc42 suggerisce notazioni in diverse sezioni (la sezione 3, per esempio, cita un diagramma di deployment UML per il contesto tecnico) ma lascia a te la scelta. Con arc42 si usano C4, UML e semplici box e frecce.

Dove vanno gli ADR in arc42?

Nella sezione 9, Decisioni architetturali. arc42 stesso raccomanda un ADR per ogni decisione importante, nella struttura di Michael Nygard, e permette di documentare una decisione localmente nel building block che riguarda, se così si legge meglio.

arc42 è gratuito?

Sì. Il template è gratuito e open source, con licenza CC BY-SA 4.0, ed è disponibile in dodici lingue e in diversi formati, tra cui AsciiDoc, Markdown, Word e Confluence (pagina di download).

Vuoi che la metà C4 del tuo documento arc42 resti fedele al codice? Prova archyl gratis e genera il modello dal tuo repository. Continua a leggere: Cos'è il modello C4? Una guida completa | Architecture Decision Records: la guida completa | Guida al diagramma dinamico C4 | Template di documentazione dell'architettura software.