Das C4-Modell an einem realistischen Beispiel erklärt

Das C4-Modell ist schnell erklärt und genauso schnell falsch angewendet. Viele Teams landen bei einem riesigen Diagramm, das Nutzer, Microservices, Java-Klassen und Cloud-Kästen vermischt – genau das, was C4 verhindern soll. Dieser Guide geht ein vollständiges C4-Modell-Diagramm-Beispiel durch: ein erfundenes System, gezeichnet auf den Ebenen 1, 2 und 3. So siehst du, was auf welches Diagramm gehört, wer es liest und wo sich die typischen Fehler einschleichen.

Das C4-Modell in einer Minute

Das C4-Modell von Simon Brown beschreibt Softwarearchitektur als eine Reihe zoombarer Diagramme. Jede Ebene beantwortet eine andere Frage für ein anderes Publikum.

Ein „Container“ ist in C4 alles, was eigenständig läuft oder Daten speichert: eine Web-App, eine API, ein Worker, eine Datenbank, eine Message Queue oder ein Topic. Gemeint ist nicht speziell ein Docker-Container. C4 definiert Abstraktionen, keine Formen oder Farben – die Notation liegt bei dir. Die offizielle Referenz findest du unter c4model.com.

Das Beispielsystem: Folio, ein Online-Buchhandel

Damit es konkret bleibt, nutzen wir ein erfundenes System. Folio ist ein fiktiver Online-Buchhandel – kein echtes Unternehmen –, der gedruckte Bücher und E-Books verkauft.

• Kund:innen durchsuchen den Katalog, kaufen Bücher und laden E-Books herunter.
• Das Backoffice pflegt Katalog, Lagerbestand und Preise.
• Folio hängt von drei externen Systemen ab: einem Payment-Provider, einem E-Mail-Versanddienst und dem Fulfilment-System eines Lagerpartners.

Ebene 1: System-Context-Diagramm

Das Context-Diagramm zeigt Folio als einen einzigen Kasten und alles drumherum. Keinerlei interne Details.

• Customer (Person): stöbert und kauft Bücher.
• Back-office Staff (Person): pflegt Katalog, Bestand und Preise.
• Folio (Software System, im Scope): ermöglicht den Kauf gedruckter Bücher und E-Books.
• Payment Provider (Software System, extern): autorisiert und bucht Kartenzahlungen.
• Email Service (Software System, extern): verschickt Bestell- und Versand-E-Mails.
• Fulfilment System (Software System, extern, gehört dem Lagerpartner): kommissioniert, verpackt und versendet Printbestellungen.

Jede Beziehung bekommt ein Label, das die Absicht nennt:

• Customer → Folio: „Stöbert und kauft Bücher über“
• Back-office Staff → Folio: „Pflegt Katalog und Bestand über“
• Folio → Payment Provider: „Wickelt Kartenzahlungen ab über“
• Folio → Email Service: „Verschickt Bestell-E-Mails über“
• Folio → Fulfilment System: „Sendet Printbestellungen an“

Für wen: Produktmanager:innen, neue Teammitglieder, Security-Reviewer, andere Teams. Wenn jemand mehr als einen kurzen Blick braucht, ist das Diagramm zu voll. Protokolle und Technologien bleiben auf dieser Ebene meist weg.

Ebene 2: Container-Diagramm

Zoom in Folio hinein. Personen und externe Systeme bleiben; Folio wird zu einer Boundary um seine Container.

Beziehungen tragen jetzt Absicht plus Protokoll:

• Web Storefront → API Application: „Liest Katalog, gibt Bestellungen auf [JSON/HTTPS]“
• API Application → Main Database: „Liest und schreibt [SQL/TCP]“
• API Application → Payment Provider: „Erstellt und bucht Zahlungen [HTTPS]“
• API Application → Order Events Queue: „Publiziert OrderPaid-Events [AMQP]“
• Order Worker → Order Events Queue: „Konsumiert OrderPaid-Events [AMQP]“
• API Application → E-book Store: „Signiert Download-Links für E-Book-Dateien [HTTPS]“
• Order Worker → Fulfilment System: „Übermittelt Printbestellungen [JSON/HTTPS]“
• Order Worker → Email Service: „Verschickt Bestätigungs-E-Mails [HTTPS]“

Für wen: Engineers, Architekt:innen und SREs. Im Alltag ist das meist das nützlichste C4-Diagramm: das, was du im Design-Review zeigst oder neuen Teammitgliedern gibst. Achte darauf, was fehlt: Pods, VPCs, Load Balancer. Die gehören auf ein Deployment-Diagramm.

Ebene 3: Component-Diagramm

Zoom in einen Container, die API Application. Nicht jeder Container braucht ein Component-Diagramm; zeichne es dort, wo das Innenleben eine Erklärung verdient.

• Catalogue Controller (Spring MVC REST Controller): Such- und Buchdetail-Endpoints.
• Checkout Controller (Spring MVC REST Controller): Warenkorb- und Checkout-Endpoints.
• Order Service (Spring Service): validiert Warenkörbe, legt Bestellungen an, publiziert Events.
• Payment Gateway Client (Spring Component): kapselt die API des Payment-Providers.
• Order Repository (Spring Data JPA): persistiert Bestellungen.
• Catalogue Repository (Spring Data JPA): liest Bücher, Preise und Bestand.

Die Beziehungen folgen derselben Regel wie auf Ebene 2, zum Beispiel Order Service → Payment Gateway Client „Fordert Zahlungsbuchung an“ und Order Repository → Main Database „[SQL/TCP]“.

Für wen: die Entwickler:innen, denen dieser Container gehört. Component-Diagramme veralten am schnellsten.

Ebene 4, Code: nicht von Hand zeichnen. Klassendiagramme bei Bedarf aus der IDE generieren.

Notationstipps für lesbare C4-Diagramme

• Jeder Kasten hat vier Dinge: Name, Elementtyp, Technologie und eine einzeilige Verantwortung.

API Application
[Container: Java, Spring Boot]
Provides catalogue, ordering and account functionality via a JSON/HTTPS API.

• Beschrifte jede Beziehung mit der Absicht und ab Ebene 2 mit dem Protokoll. Ein Pfeil, auf dem nur „Nutzt“ steht, sagt nichts.
• Eine Richtung pro Pfeil, beschrieben aus Sicht der Quelle.
• Füge eine Legende hinzu, die Formen, Farben, Linienstile und Abkürzungen erklärt. Eine gestrichelte Linie bedeutet nichts, bis du sagst, was sie bedeutet.
• Gib jedem Diagramm einen Titel mit Typ und Scope, etwa „Container-Diagramm: Folio“.
• Zeichne die Boundary des Systems im Scope, damit klar ist, was dir gehört und was du nur aufrufst.

Typische Fehler

1. Direkt bei Components einsteigen. Ohne Context- und Container-Sicht weiß niemand, wo eine Komponente lebt oder warum es sie gibt.
2. Ebenen vermischen. Eine Person, ein Pod und eine Java-Klasse auf demselben Diagramm – keins davon wird gut erklärt.
3. Unbeschriftete Pfeile. Linien ohne Absicht oder Protokoll zwingen zum Raten, und jede:r rät anders.
4. Die Code-Ebene von Hand zeichnen. Am Tag nach der Fertigstellung ist sie veraltet.
5. Infrastruktur im Container-Diagramm. Namespaces, Subnetze und Instanztypen gehören auf ein Deployment-Diagramm.

Ergänzende Diagramme: Deployment und Dynamic

C4 definiert auch unterstützende Sichten. Zwei sind besonders nützlich:

• Deployment-Diagramm: bildet Container auf Infrastruktur ab. Bei Folio könnten API Application und Order Worker als Deployments in einem Kubernetes-Cluster laufen, PostgreSQL als Managed Database und der E-book Store im Object Storage. Hier gehören Kubernetes- und Cloud-Details hin.
• Dynamic-Diagramm: zeigt einen konkreten Ablauf als nummerierte Schritte, etwa „Kund:in kauft ein E-Book“: 1) Storefront sendet den Checkout, 2) API bucht die Zahlung, 3) API publiziert OrderPaid, 4) Worker verschickt die E-Mail mit Download-Link.

Dieses C4-Modell-Diagramm-Beispiel in Archboard bauen

Archboard hat ein C4-Model-Pack mit Person-, Software-System-, Container-, Component- und Database-Nodes sowie Boundaries. Das sind vollwertige Nodes mit Ports, keine generischen Formen – Beziehungen verbindest du von Port zu Port.

1. Melde dich mit Google oder GitHub an und lege ein Diagramm an.
2. Ebene 1: Platziere zwei Person-Nodes (Customer, Back-office Staff), einen Software-System-Node für Folio und drei External-System-Nodes für die Payment-, E-Mail- und Fulfilment-Systeme. Verbinde die Ports und beschrifte jede Kante mit ihrer Absicht.
3. Ebene 2: Füge eine Boundary für Folio hinzu und platziere Container-Nodes für Web Storefront, Admin Portal, API Application, Order Worker, Order Events Queue und E-book Store sowie einen Database-Node für die Main Database. Trage Name, Technologie und Verantwortung ein und beschrifte die Kanten mit Absicht und Protokoll.
4. Ebene 3: Füge eine Boundary für die API Application hinzu und setze die Component-Nodes hinein.
5. Legende und Notizen: Nutze einen Markdown-Block oder eine Table aus den Core-Elementen für die Legende und einen Frame, um jede Ebene in ihrem eigenen Bereich des unendlichen Canvas zu halten.
6. Deployment-Sicht direkt daneben: C4-Views können auf demselben Canvas liegen wie das Kubernetes- und das Cloud-Pack. Zeichne einen Namespace-Frame mit Deployment-, Service- und Ingress-Nodes für API Application und Order Worker direkt neben die Container-Sicht, die sie umsetzen.

Weil Archboard ein Canvas ist, zeichnest du jede Sicht bewusst: Du entscheidest, was auf welche Ebene gehört, und C4-Nodes liegen auf demselben Board neben Nodes aus dem Kubernetes- und Cloud-Pack. So steht die Deployment-Sicht direkt neben der Container-Sicht.

Im Free-Plan fasst ein Diagramm 15 Diagramm-Nodes plus 150 Notizen, Texte, Sticker & Mindmap-Themen – für ein System wie Folio reicht das für eine C4-Ebene pro Diagramm. Pro hebt die Node- und Diagrammlimits auf, wenn du alle Ebenen auf einem Canvas willst. Mehr zu C4-Workflows: C4-Use-Case.

Kostenlose Vorlage

Das C4-Container-View-Beispiel ist ein öffentliches Diagramm, das du mit Dieses Beispiel verwenden in deinen Workspace kopieren kannst. Nutze es für das Boundary-Layout und beschrifte dann jede Kante wie oben beschrieben mit Absicht und Protokoll.

FAQ

Brauche ich alle vier Ebenen? Nein. Die meisten Teams ziehen den größten Nutzen aus Context- und Container-Diagramm. Component-Diagramme gezielt ergänzen, Code-Sichten nur bei Bedarf generieren.

Ist ein C4-Container ein Docker-Container? Nein. Gemeint ist jede separat lauffähige oder deploybare Einheit, auch Datenbanken und Single-Page-Apps. Ob sie in Docker läuft, ist offen.

Wohin gehören Kubernetes-Details? Auf ein Deployment-Diagramm. Das Container-Diagramm bleibt bei Verantwortungen und Kommunikation.

Kostenlos starten – ein Seat, keine Kreditkarte