Il diagramma di Contesto di Sistema è il livello 1 del modello C4 -- il singolo diagramma di architettura più importante che il tuo team possa creare. Questa guida spiega cosa deve contenere un diagramma di contesto c4, illustra un esempio completo di diagramma di contesto e mostra come crearne uno manualmente o generarlo dal tuo codice.

Diagramma di Contesto di Sistema C4: guida completa con esempi

Se devi disegnare un solo diagramma di architettura nella tua vita, scegli il diagramma di Contesto di Sistema. È il punto di ingresso del modello C4, il diagramma che ogni stakeholder può leggere senza formazione e il modo più rapido per far emergere disaccordi su ciò che il tuo sistema fa realmente.

Eppure la maggior parte dei team lo sbaglia. Ci stipano dentro database, microservizi e cluster Kubernetes finché il diagramma di "contesto" diventa una mappa illeggibile dell'infrastruttura. Oppure lo saltano del tutto e passano direttamente a un diagramma di container, lasciando gli stakeholder non tecnici senza nulla che possano comprendere.

Questa guida è un approfondimento sul livello 1 del modello C4: cos'è un diagramma di contesto di sistema, cosa esattamente deve contenere (e cosa no), un esempio completo svolto, gli errori che rovinano la maggior parte dei diagrammi di contesto e un processo passo dopo passo per crearne uno -- a mano o generato dal tuo codice. Se sei nuovo al modello C4 in sé, inizia dalla nostra guida completa al modello C4 e poi torna qui.

Che cos'è un diagramma di Contesto di Sistema?

Un diagramma di Contesto di Sistema è il primo diagramma e quello di livello più alto nel modello C4. Mostra un singolo sistema software come un'unica scatola e risponde a una sola domanda: come si inserisce questo sistema nel suo ambiente?

Come recita la definizione del glossario, il diagramma di Contesto di Sistema si concentra sulle persone e sui sistemi esterni che interagiscono con il sistema descritto, omettendo deliberatamente la struttura interna. Il suo obiettivo è stabilire il perimetro: chi usa il sistema, da quali sistemi dipende e quali sistemi dipendono da esso.

Tre tipi di elementi compaiono in un diagramma di contesto, e soltanto tre:

Il tuo sistema software -- una scatola, al centro. Non i suoi servizi, non i suoi database. Una scatola.
Persone -- gli utenti, i ruoli o le personas che interagiscono con il sistema. Un "Cliente", un "Amministratore", un "Agente di supporto".
Sistemi software esterni -- i sistemi con cui il tuo dialoga ma che il tuo team non possiede: un gateway di pagamento, un provider di email, un ERP legacy, un identity provider.

A collegarli ci sono le relazioni: frecce etichettate che descrivono chi fa cosa. "Effettua ordini tramite", "Invia richieste di pagamento a", "Riceve aggiornamenti di spedizione da".

Questo è l'intero vocabolario. Scatole per il sistema, le persone e i sistemi esterni; frecce per le relazioni. La disciplina del diagramma deriva da ciò che lasci fuori.

Chi è il pubblico?

Il diagramma di Contesto di Sistema è unico tra i quattro livelli C4 perché è progettato per tutti -- comprese le persone che non leggeranno mai una riga di codice:

Stakeholder non tecnici. Un product manager, un CEO o un responsabile della compliance possono guardare un diagramma di contesto e comprendere lo scopo del sistema, i suoi utenti e le sue dipendenze da terze parti in meno di un minuto.
Nuovi membri del team. Prima che un nuovo ingegnere impari la struttura delle cartelle, dovrebbe imparare il perimetro del sistema. Il diagramma di contesto è la diapositiva numero uno dell'onboarding.
Architetti e revisori di sicurezza. Ogni freccia che attraversa il perimetro del sistema è un punto di integrazione, un flusso di dati e una potenziale superficie di attacco. Le revisioni di sicurezza e compliance spesso partono da qui.
Altri team. Quando un altro team chiede "il vostro sistema chiama direttamente l'API di fatturazione?", il diagramma di contesto risponde senza bisogno di una riunione.

Per questo le scelte tecnologiche non hanno posto qui. Nel momento in cui scrivi "PostgreSQL" o "Kafka" in un diagramma di contesto, hai ristretto il pubblico agli ingegneri -- e per quello hai il diagramma di container.

Cosa deve contenere un diagramma di contesto (e cosa no)

Includere

Il sistema in oggetto -- esattamente una scatola, chiaramente denominata.
Ogni categoria di utente -- non le singole persone, ma i ruoli o le personas. Se i clienti e il personale di magazzino usano il sistema in modo diverso, sono due scatole-persona distinte.
Ogni dipendenza da sistemi esterni -- comprese quelle che dai per scontate: il servizio email, l'identity provider, la piattaforma di analytics, lo stack di monitoraggio se è architetturalmente rilevante.
I sistemi che dipendono da te -- se il sistema di un partner consuma la tua API, va inserito nel diagramma con la freccia che punta verso di te.
Relazioni etichettate -- ogni freccia ha bisogno di una locuzione verbale. Una freccia senza etichetta è un punto interrogativo.

Escludere

Container -- niente web app, niente servizi API, niente database, niente code di messaggi. Quelli sono il livello 2.
Scelte tecnologiche -- niente "React", niente "Go", niente "PostgreSQL". Un diagramma di contesto dovrebbe sopravvivere a una riscrittura completa del tuo stack senza cambiare.
Struttura interna dei sistemi esterni -- Stripe è una scatola, non un diagramma dell'architettura di Stripe.
Dettagli di infrastruttura e deployment -- niente regioni, niente cluster, niente load balancer.
Singole funzionalità -- il diagramma mostra relazioni, non un elenco di funzionalità.

Un test semplice: se rimuovere un elemento non cambierebbe chi interagisce con il sistema o quali sistemi esterni esso tocca, allora quell'elemento non ha posto al livello 1.

Un esempio completo di diagramma di contesto: piattaforma di pagamenti online

Lavoriamo su un esempio realistico. Immagina di documentare PayFlow, una piattaforma di pagamenti online che permette ai merchant di accettare pagamenti con carta sui loro siti web.

Passo 1: dai un nome al sistema

Una scatola al centro: PayFlow Payment Platform. Aggiungi una descrizione in una riga: "Permette ai merchant di accettare e gestire pagamenti online con carta."

Passo 2: identifica le persone

Chi interagisce con PayFlow, e in quale ruolo?

Merchant -- un titolare d'azienda che configura le pagine di pagamento, visualizza le transazioni e avvia i rimborsi.
Cliente finale -- un acquirente che paga un acquisto tramite un checkout PayFlow.
Agente di supporto -- personale interno che indaga sulle transazioni contestate.

Passo 3: identifica i sistemi esterni

Da cosa dipende PayFlow, e cosa dipende da PayFlow?

Circuiti di carte / Banca acquirer -- autorizza e regola le transazioni con carta.
Servizio di rilevamento frodi -- assegna un punteggio di rischio di frode alle transazioni.
Servizio email -- invia ricevute e notifiche.
Identity Provider -- gestisce il single sign-on dei merchant.
Sito e-commerce del merchant -- il sito web del merchant stesso, che incorpora il checkout PayFlow e consuma l'API PayFlow.
Piattaforma di contabilità -- riceve i report di regolamento per la contabilità del merchant.

Passo 4: disegna le relazioni

L'elenco completo di elementi e relazioni si presenta così:

People:
  [Merchant]          --> [PayFlow] : Configures payments, views transactions, issues refunds
  [End Customer]      --> [PayFlow] : Pays for purchases via hosted checkout
  [Support Agent]     --> [PayFlow] : Investigates and resolves disputes

External systems:
  [Merchant E-Commerce Site] --> [PayFlow] : Initiates payments via API, embeds checkout
  [PayFlow] --> [Card Networks / Acquiring Bank] : Authorizes and settles card transactions
  [PayFlow] --> [Fraud Detection Service] : Requests risk scores for transactions
  [PayFlow] --> [Email Service] : Sends receipts and payment notifications
  [PayFlow] --> [Identity Provider] : Delegates merchant authentication
  [PayFlow] --> [Accounting Platform] : Exports settlement reports

Dieci elementi in totale: un sistema, tre persone, sei sistemi esterni. Ogni freccia ha una locuzione verbale. Non c'è alcun riferimento a servizi, database, code o linguaggi -- eppure chiunque legga questo diagramma capisce cos'è PayFlow, chi lo usa e da cosa dipende.

Nota cosa rende immediatamente visibile questo diagramma:

Superficie di compliance. I circuiti di carte e il rilevamento frodi nel diagramma indicano a un revisore di sicurezza esattamente dove scorrono i dati rilevanti per il PCI.
Rischio fornitori. Sei dipendenze esterne, ciascuna un potenziale punto di guasto o oggetto di trattativa contrattuale.
Perimetro bidirezionale. Il sito e-commerce del merchant chiama verso PayFlow -- il sistema non è solo un consumatore di altri servizi, è anche una dipendenza per qualcun altro.

È esattamente il tipo di conversazione che un diagramma di contesto è fatto per avviare.

Errori comuni nei diagrammi di Contesto di Sistema

Errore 1: troppo dettaglio

Il fallimento più comune. Il diagramma parte pulito, poi qualcuno aggiunge "solo il database principale", poi l'API gateway, poi i tre microservizi core, e nel giro di un mese è un diagramma di container travestito da diagramma di contesto. La soluzione è spietata: il tuo sistema è una scatola. Se senti l'impulso di mostrare gli interni, è il segnale per creare un diagramma di container come vista separata e collegata -- non per sovraccaricare questo.

Errore 2: dipendenze esterne mancanti

I team dimenticano puntualmente le dipendenze che considerano noiose: il provider di email, il gateway SMS, l'identity provider, la CDN, il servizio di feature flag. Ma le dipendenze "noiose" causano disservizi reali e un reale lock-in con i fornitori. Scorri i tuoi file di configurazione e le variabili d'ambiente -- ogni chiave API di solito corrisponde a un sistema esterno che ha posto nel diagramma.

Errore 3: mescolare livelli di astrazione

Un diagramma che mostra "Cliente → Web App → API Ordini → PostgreSQL → Stripe" mescola una persona, due container, un database e un sistema esterno in un'unica vista piatta. I lettori non riescono a capire dove sia il perimetro del tuo sistema. Ogni diagramma C4 dovrebbe vivere esattamente a un livello di zoom; il senso stesso della gerarchia del modello C4 è che si zooma tra i diagrammi, mai dentro uno.

Errore 4: relazioni senza etichetta o vaghe

"Usa" non è un'etichetta di relazione -- tutto "usa" tutto. Scrivi cosa succede davvero: "Invia ordini tramite", "Riceve eventi webhook da", "Si autentica su". Le etichette sono dove risiede la maggior parte delle informazioni del diagramma.

Errore 5: disegnarlo una volta e non aggiornarlo mai

Un diagramma di contesto del 2023 che mostra ancora il CRM legacy da cui hai migrato l'anno scorso è attivamente fuorviante. I diagrammi di contesto cambiano meno spesso di quelli di livello inferiore, ma cambiano comunque -- ogni nuova integrazione con un fornitore, ogni API di partner dismessa. Tratta il diagramma come documentazione viva, non come un artefatto di kickoff.

Come creare un diagramma di Contesto di Sistema: passo dopo passo

L'approccio manuale

Dai un nome e descrivi il sistema. Una frase: cosa fa, e per chi?
Elenca i ruoli utente. Fai brainstorming di ogni persona distinta che interagisce con il sistema. Unisci i ruoli che interagiscono in modo identico; separa quelli che no.
Elenca i sistemi esterni. Passa in rassegna integrazioni, chiavi API, webhook, export pianificati. Includi i sistemi che chiamano te, non solo quelli che chiami tu.
Disegna le relazioni. Una freccia per ogni interazione significativa, ciascuna etichettata con una locuzione verbale. La direzione segue l'iniziativa: chi avvia l'interazione?
Rivedi con il team. Questo è il passo a maggior valore. Una revisione di 30 minuti fa emergere puntualmente i disaccordi: "aspetta, chiamiamo ancora quel servizio?", "da quando i partner colpiscono direttamente la nostra API?". Quei dibattiti sono il risultato.
Pubblicalo dove la gente lo troverà -- non sepolto in una pagina wiki che nessuno visita.

Qualsiasi strumento va bene per il disegno in sé: una lavagna, diagrams.net, Structurizr, PlantUML con le estensioni C4. Il collo di bottiglia non è mai stato il disegno -- sono i passi 2, 3 e 5, e mantenere accurato il risultato nel tempo.

L'approccio automatizzato: generare diagrammi di contesto con Archyl

È qui che Archyl prende una strada diversa dagli strumenti di disegno. Invece di partire da una tela bianca, colleghi i tuoi repository ed esegui la AI discovery: Archyl analizza la struttura del codice, i file di configurazione e i grafi delle dipendenze, poi propone una bozza di modello C4 -- sistemi, dipendenze esterne, container, componenti e le relazioni tra di essi. Tu rivedi ogni suggerimento, lo accetti o lo modifichi, e la vista di Contesto di Sistema viene generata automaticamente dal modello.

Poiché il diagramma è generato da un modello anziché disegnato a mano, ne conseguono due cose:

I livelli restano collegati. La scatola del sistema nel tuo diagramma di contesto è la stessa entità in cui scendi per la vista dei container. Nessuno scostamento da copia-incolla tra i diagrammi.
L'obsolescenza diventa misurabile. La drift detection di Archyl confronta di continuo la tua architettura documentata con ciò che esiste realmente nel codice, così quando un'integrazione viene rimossa o un servizio rinominato, lo scopri da un punteggio di drift invece che da un nuovo assunto confuso.

Se preferisci una documentazione che vive nel version control, Archyl supporta anche un workflow di Architecture as Code: definisci il tuo modello C4 in YAML, lo committi insieme al codice e lasci che i diagrammi vengano generati da quella definizione.

Dal contesto ai container

Il diagramma di Contesto di Sistema stabilisce il perimetro; il livello successivo apre la scatola. Una volta che il tuo diagramma di contesto è stabile, il passo naturale successivo è il diagramma di container -- la vista di livello 2 che mostra le unità deployabili (web app, API, database, broker) all'interno del tuo sistema e come comunicano. Lo trattiamo in dettaglio nella nostra guida al diagramma di Container C4.

La progressione conta. I team che saltano il diagramma di contesto e partono dal livello 2 tendono a produrre diagrammi di container con perimetri sfocati -- sistemi esterni mescolati ai servizi interni, perché nessuno ha mai concordato dove finisce il sistema.

FAQ

Qual è la differenza tra un diagramma di Contesto di Sistema e un diagramma di Container?

Il diagramma di contesto (livello 1) mostra il tuo sistema come un'unica scatola e si concentra sul suo ambiente: utenti e sistemi esterni. Il diagramma di container (livello 2) zooma dentro quella scatola per mostrare le unità deployabili -- web app, servizi, database -- e le loro scelte tecnologiche. Il contesto risponde a "con cosa interagisce questo sistema?"; i container rispondono a "di cosa è fatto questo sistema?".

Quanti elementi dovrebbe avere un diagramma di contesto?

Non esiste una regola rigida, ma la maggior parte dei diagrammi di contesto sani ha un sistema, da due a cinque ruoli utente e da tre a dieci sistemi esterni. Se superi i quindici o venti elementi, o il perimetro del tuo sistema è troppo ampio, oppure stai documentando un panorama enterprise -- nel qual caso il diagramma di System Landscape C4 (più sistemi in un'unica vista) è la scelta migliore.

I database dovrebbero comparire in un diagramma di Contesto di Sistema?

No -- finché il database appartiene al tuo sistema, è un dettaglio interno e compare al livello dei container. L'eccezione è un database gestito da un altro team o fornitore da cui il tuo sistema legge direttamente; quello è di fatto un sistema esterno e può comparire come tale.

Un diagramma di contesto C4 è la stessa cosa di un diagramma di contesto UML o data-flow?

Concettualmente sono cugini -- l'idea di un "diagramma di contesto" (un sistema, il suo ambiente) precede C4 ed esiste nell'analisi strutturata e nella pratica UML. La versione C4 si distingue per la sua collocazione in una gerarchia: ogni elemento al suo interno può essere scomposto nel livello inferiore, dandoti una mappa navigabile invece di un'immagine isolata.

Pronto a creare il tuo diagramma di Contesto di Sistema? Prova Archyl gratis e genera un modello C4 direttamente dai tuoi repository. Oppure continua a leggere: Cos'è il modello C4? Una guida completa | Guida al diagramma di Container C4 | Diagramma di Contesto di Sistema nel glossario.

Diagramma di Contesto di Sistema C4: guida completa con esempi - Archyl Blog