Was macht C4-Diagramme?
Quelle: Das offizielle C4-Modell unter https://c4model.com/. Wende diese Regeln an, wann immer ein C4-Diagramm gezeichnet, überprüft oder erklärt wird. Lade ebenfalls die Skill writing, wenn die Ausgabe Prosa enthält (ADRs, Dokumentation, PR-Beschreibungen).
1. Zweck
C4 ist eine Reihe von „Landkarten Ihres Codes" auf vier Zoom-Ebenen: Kontext, Container, Komponenten, Code. Simon Brown hat es in Anlehnung an UML und das 4+1-Sichtmodell entwickelt, um ad-hoc-Kästchen-und-Linien-Diagramme zu ersetzen. Typische Fehler, die es behebt: fehlende Legende, gemischte Abstraktionen, unbeschriftete Pfeile, fehlende Technologie und vage Bezeichnungen wie „Geschäftslogik".
C4 ist notations- und werkzeugunabhängig. Die Abstraktionen und die unten stehenden Regeln sind entscheidend; die Formen nicht.
2. Abstraktionen
Hierarchie: Person -> Softwaresystem -> Container -> Komponente -> Code. Jede Ebene zoomt in ein Element der darüber liegenden Ebene.
| Abstraktion | Definition | Beispiele |
|---|---|---|
| Person | Ein menschlicher Benutzer, Akteur, Rolle oder Persona des Systems | Kunde, Support-Mitarbeiter, Administrator |
| Softwaresystem | Höchste Abstraktionsebene; liefert Nutzen für Benutzer. Wird typischerweise von einem einzelnen Team entwickelt und betrieben. Es ist kein Produktbereich, begrenzter Kontext, Tribe oder Squad | Ticketing-Plattform, Zahlungssystem |
| Container | Eine eigenständig lauffähige/einsetzbare Anwendung oder Datenhaltung innerhalb eines Softwaresystems | Server-seitige Web-App, SPA, Desktop-App, mobile App, serverlose Funktion, Batch-/Konsolen-App, Microservice-API, Datenbankschema, S3/Blob-Speicher, CDN, Dateisystem, Shell-Skript |
| Komponente | Eine Gruppierung verwandter Funktionalität hinter einer klar definierten Schnittstelle, innerhalb eines Containers. Nicht separat einsetzbar: alle Komponenten eines Containers teilen sich einen Prozessraum | OrderController, PaymentService, EmailSender |
| Code | Klassen, Schnittstellen, Funktionen oder DB-Tabellen innerhalb einer Komponente | class OrderValidator, orders-Tabelle |
Container-Regeln (C4 FAQ)
- Ein C4-Container ist kein Docker. Es ist eine lauffähige/einsetzbare Anwendung oder Datenhaltung, unabhängig von der Verpackung.
- Eine serverseitig gerenderte HTML-App ist 1 Container. Ein Server plus eine SPA oder ein mobiler Client sind 2 Container, die über eine entfernte API kommunizieren.
- JARs, DLLs, Assemblies und Module sind keine Container. Sie organisieren Code innerhalb eines Containers.
- Verwaltete Datendienste (S3, RDS, CDN) sind Container innerhalb Ihrer Systemgrenze, wenn Sie die Buckets oder Schemas besitzen oder kontrollieren. Sie sind keine externen Systeme.
Komponenten-Regeln
- Eine Komponente ist kein Ordner, Paket oder JAR. Sie ist eine funktionale Gruppierung mit einer Schnittstelle.
- Komponenten sind nicht unabhängig einsetzbar. Wenn sie separat bereitgestellt wird, ist sie ein Container.
Terminologie anpassen
Teams können sprachspezifische Namen (z. B. Modul oder Funktion in funktionalem Code) verwenden, wenn sie den Begriff im Diagramm oder in dessen Dokumentation explizit definieren. Erfinde keine zusätzlichen Abstraktionsebenen, es sei denn, jede ist streng definiert.
3. Spezielle Modellierungsmuster
Warteschlangen und Topics
- Falsch: ein riesiger „Message Bus"-Container in der Mitte mit jedem verbundenen Dienst (Stern-Topologie). Es versteckt, wer was produziert und konsumiert.
- Option 1 (bevorzugt): modelliere jede Warteschlange oder jedes Topic als eigenen Container (einen Nachrichtendatenspeicher). Produzenten schreiben darauf, Konsumenten lesen oder abonnieren davon.
- Option 2: für direkte Punkt-zu-Punkt-Kopplung die Warteschlangen-Box weglassen und die Beziehung beschriften
„Veröffentlicht Bestellereignisse via Warteschlange orders [AMQP]". Optional diese Linien anders gestalten als HTTP-Aufrufe (in der Legende erklären).
Beispiel: Order API --„Veröffentlicht OrderPlaced an [Kafka]"--> [(orders topic)] --„Liest OrderPlaced von [Kafka]"--> Fulfilment Worker.
Microservices (Conway’s Law Regel)
- Ein Team besitzt das gesamte Softwaresystem: modelliere jeden Microservice als Gruppe von Containern innerhalb der Grenze dieses Systems (API-Container plus eigenes Datenbankschema-Container oder ein einzelner zustandsloser Lambda-Container).
- Getrennte Teams besitzen jeden Dienst: befördere jeden unabhängig besessenen Dienst zu einem eigenen Softwaresystem, jedes mit eigenem Systemkontext- und Container-Diagramm. Gib den Besitz von Warteschlangen/Topics explizit über Systemgrenzen hinweg an.
4. Diagrammkatalog
Kern-Statische Ebenen
| Ebene | Diagramm | Empfohlen | Bereich | Zielgruppe | Zeigen / Weglassen |
|---|---|---|---|---|---|
| 1 | Systemkontext | Ja | 1 Softwaresystem | Technisch & nicht-technisch | Personen und externe Systeme um das System herum. Niedrige Technologie und Protokolle weglassen |
| 2 | Container | Ja | 1 Softwaresystem | Technisch, Betrieb | Wichtige Technologieauswahl und Interprozessprotokolle. Clustering, Load Balancer, Failover weglassen |
| 3 | Komponente | Nein: nur wenn es klaren Mehrwert bringt, idealerweise automatisiert | 1 Container | Architekten, Entwickler | Komponenten innerhalb eines Containers und ihre Interaktionen |
| 4 | Code | Nein: bei Bedarf in der IDE generieren | 1 Komponente | Entwickler | UML-Klassendiagramm oder ERD |
Ergänzende Diagramme
| Diagramm | Empfohlen | Verwendung |
|---|---|---|
| Systemlandschaft | Ja, für Organisationen und Portfolios | Unternehmens- oder Abteilungskarte aller Systeme und Personen. Ein Kontextdiagramm ohne einzelnes Fokussystem |
| Dynamik | Nein: sparsam verwenden | Komplexe Laufzeit-Kollaborationen. Nummerierte Kollaborations- oder UML-Sequenzstil |
| Deployment | Ja | 1 Umgebung (Produktion, Staging, Entwicklung). Verschachtelte Deployment-Knoten (physisch, VM, Docker, Kubernetes, Laufzeit) mit System-/Container-Instanzen, plus Infrastrukturknoten (DNS, Load Balancer, Firewalls) |
Kompatibilität
- arc42: Kontext & Umfang -> L1; Baustein Ebene 1 -> L2; Baustein Ebene 2 -> L3; Baustein Ebene 3 -> L4.
- UML: ergänze C4 mit UML-Zustands-, Sequenz- und ERD-Diagrammen für Workflows, Zustandsmaschinen und Datenmodelle.
Skalierungsregel
Wenn ein Diagramm überladen wird, stopfe nicht Dutzende von Boxen in eine Leinwand. Teile auf derselben Abstraktionsebene nach Geschäftsbereich, begrenztem Kontext, Feature oder Einzeldienst-Fokus auf (der Fokusdienst plus seine eingehenden und ausgehenden Nachbarn).
5. Notationsregeln
Diagramm
- Der Titel gibt Diagrammtyp und Bereich an:
Container-Diagramm für das Checkout-System. - Füge immer eine Legende bei, die Formen, Farben, Ränder, Linientypen, Pfeilspitzen und Abkürzungen erklärt.
- Halte strenge Abstraktionsreinheit: Mische niemals Abstraktionsebenen (z. B. keine
Komponenten-Boxen innerhalb eines L2-Container-Diagramms) und setze niemals Protokolle oder interne Implementierungsschritte ([HTTPS],maskiertes Paket,tool_runner) in ein L1-Systemkontext-Diagramm. - Beim Vergleich konkurrierender oder historischer Architekturen beschrifte Grenztitel explizit (
Option A (Ersetzt)vs.Option B (Aktuell)) und aktualisiere alle Diagramme im Dokument, wann immer sich Anforderungen oder Annahmen ändern.
Element
- Name, expliziter Elementtyp (
Person,Softwaresystem,Container,Komponente,Datenbank,Deployment-Knoten) und eine präzise Aufgabenbeschreibung. - Explizite Technologie auf jedem Container, jeder Komponente und jedem Deployment-Knoten.
Beziehung
- Nur unidirektionale Pfeile. Niemals
<-->. Wenn Daten in beide Richtungen fließen, zeige die Richtung des Initiators und beschreibe die Antwort in der Beschriftung. - Spezifische aktive Verb-Beschriftungen. Niemals nacktes „Verwendet". Schreibe
Sendet Bestellungen an,Liest Sitzplan von. - Protokoll/Technologie auf Container-zu-Container-Beziehungen:
[JSON/HTTPS],[SQL],[gRPC],[AMQP].
6. Mermaid in Markdown
Standardmäßig flowchart (flowchart TB oder LR), nicht Mermaids native C4Context/C4Container. Die native C4-Syntax ist experimentell und rendert oft nicht in Markdown-Viewern. Verwende sie nur, wenn der Benutzer explizit danach fragt und die Renderer-Unterstützung bestätigt.
Flowchart-Konventionen:
subgraphfür die Systemgrenze (Container/Komponenten) oder Deployment-Knoten.[(...)]für Datenbanken, Datenspeicher, Warteschlangen und Topics.- HTML-Beschriftungen in Anführungszeichen:
"<b>Name</b><br/>«Container: Tech»<br/>Kurze Beschreibung". - Pfeile mit Beschriftungen in Anführungszeichen:
A -->|"Aktion [Protokoll]"| B. - Ein
classDefpro Elementtyp, konsistent angewendet. - Eine kompakte
Legend-Subgraph (nicht verbundene Knoten, unten verankert mit unsichtbarerbottomNode ~~~ Legend-Verbindung, wenn Dagre sie oben platziert) ist erforderlich, wann immer Farben, Zylinderformen oder mehrere Linienstile verwendet werden; platziere einen Titel als Überschrift oderTitle: ...-Zeile direkt über dem Codeblock. - Dynamische Diagramme:
sequenceDiagramoder einflowchartmit nummerierten Pfeilbeschriftungen (1. Sendet Bestellung [JSON/HTTPS]). - Deployment-Diagramme: verschachtelte
subgraphs in einemflowchart. - Setze Beschriftungen, die Klammern, eckige Klammern oder Doppelpunkte enthalten, immer in Anführungszeichen.
- Verwende niemals unescaped Semikolons (
;) insequenceDiagram- oderstateDiagram-v2-Beschriftungen (Mermaid behandelt;als Anweisungsterminator und teilt den restlichen Text in falsche Zustände oder Parse-Fehler auf); umschließe langeNote-Blöcke insequenceDiagrammit<br/>, sodass Text niemals am Rand des Viewports abgeschnitten wird.
Vorlage: L1 Systemkontext
Titel: Systemkontext-Diagramm für Ticketing-Plattform
flowchart TB
kunde["<b>Kunde</b><br/>«Person»<br/>Kauft Tickets für Veranstaltungen"]
ticketing["<b>Ticketing-Plattform</b><br/>«Softwaresystem»<br/>Ermöglicht Kunden das Durchsuchen von Veranstaltungen und den Ticketkauf"]
zahlung["<b>Zahlungsdienstleister</b><br/>«Softwaresystem, extern»<br/>Belastet Kreditkarten"]
email["<b>E-Mail-Dienst</b><br/>«Softwaresystem, extern»<br/>Sendet Bestätigungs-E-Mails"]
kunde -->|"Durchsucht Veranstaltungen und kauft Tickets mit"| ticketing
ticketing -->|"Fordert Kreditkartenbelastungen an von"| zahlung
ticketing -->|"Sendet Bestätigungs-E-Mails mit"| email
email -->|"Liefert Bestätigungs-E-Mails an"| kunde
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class kunde person
class ticketing system
class zahlung,email external
subgraph Legende
l1["Person"]:::person
l2["Softwaresystem (im Fokus)"]:::system
l3["Softwaresystem (extern)"]:::external
end
Vorlage: L2 Container (mit Warteschlangen-Container)
Titel: Container-Diagramm für Ticketing-Plattform
flowchart TB
kunde["<b>Kunde</b><br/>«Person»<br/>Kauft Tickets für Veranstaltungen"]
zahlung["<b>Zahlungsdienstleister</b><br/>«Softwaresystem, extern»<br/>Belastet Kreditkarten"]
subgraph grenze["Ticketing-Plattform [Softwaresystem]"]
spa["<b>Web-App</b><br/>«Container: React SPA»<br/>UI zum Durchsuchen von Veranstaltungen und Checkout"]
api["<b>Bestell-API</b><br/>«Container: Java, Spring Boot»<br/>Validiert und platziert Bestellungen"]
db[("<b>Bestell-DB</b><br/>«Container: PostgreSQL»<br/>Speichert Bestellungen und Tickets")]
topic[("<b>orders topic</b><br/>«Container: Kafka-Topic»<br/>OrderPlaced-Ereignisse")]
worker["<b>Fulfilment-Worker</b><br/>«Container: Python»<br/>Stellt Tickets aus und sendet E-Mails"]
end
kunde -->|"Durchsucht und kauft mit [HTTPS]"| spa
spa -->|"Sendet Bestellungen an [JSON/HTTPS]"| api
api -->|"Schreibt Bestellungen in [SQL/TCP]"| db
api -->|"Veröffentlicht OrderPlaced an [Kafka]"| topic
worker -->|"Liest OrderPlaced von [Kafka]"| topic
worker -->|"Aktualisiert Ticketstatus in [SQL/TCP]"| db
api -->|"Fordert Kreditkartenbelastungen an von [JSON/HTTPS]"| zahlung
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class kunde person
class spa,api,worker container
class db,topic store
class zahlung external
subgraph Legende
l1["Person"]:::person
l2["Container"]:::container
l3[("Datenspeicher / Warteschlange / Topic")]:::store
l4["Externes System"]:::external
end
Legendenhinweis: Pfeile zeigen vom Initiator zum Ziel. Die Beschriftung gibt die Aktion und [Protokoll] an.
Vorlage: Deployment
Titel: Deployment-Diagramm für Ticketing-Plattform (Produktion)
flowchart TB
benutzer["<b>Kundenbrowser</b><br/>«Deployment-Knoten: Chrome»"]
subgraph aws["AWS «Deployment-Knoten: Cloud, us-east-1»"]
dns["<b>Route 53</b><br/>«Infrastrukturknoten: DNS»"]
lb["<b>Load Balancer</b><br/>«Infrastrukturknoten: ALB»"]
subgraph eks["EKS «Deployment-Knoten: Kubernetes-Cluster»"]
subgraph pod["order-api Pod «Deployment-Knoten: Docker, x3»"]
api["<b>Bestell-API</b><br/>«Container-Instanz: Java, Spring Boot»"]
end
end
subgraph rds["RDS «Deployment-Knoten: PostgreSQL 16»"]
db[("<b>Bestell-DB</b><br/>«Container-Instanz: PostgreSQL-Schema»")]
end
end
benutzer -->|"Löst Hostnamen auf via [DNS]"| dns
benutzer -->|"Sendet Anfragen an [HTTPS]"| lb
lb -->|"Leitet Anfragen weiter an [HTTP]"| api
api -->|"Liest und schreibt Bestellungen in [SQL/TCP]"| db
Füge eine Legenden-Subgraph hinzu, wenn du Farben oder Stile über die Standardeinstellungen hinaus verwendest.
Vorlage: Dynamik (Sequenz)
Titel: Dynamik-Diagramm (Sequenzstil) für Bestell-Checkout in Ticketing-Plattform
sequenceDiagram
autonumber
actor kunde as Kunde
participant spa as Web-App (React SPA)
participant api as Bestell-API (Spring Boot)
participant zahlung as Zahlungsdienstleister
participant db as Bestell-DB (PostgreSQL)
participant topic as orders topic (Kafka)
kunde->>spa: Klickt „Bestellung aufgeben"
spa->>api: POST /orders [JSON/HTTPS]
api->>zahlung: Belastet Karte [JSON/HTTPS]
zahlung-->>api: Zahlung autorisiert
api->>db: Fügt Bestellzeile ein [SQL/TCP]
api->>topic: Veröffentlicht OrderPlaced [Kafka]
api-->>spa: 201 Created (Bestellbestätigung)
spa-->>kunde: Zeigt Bestellbeleg
Halte sequenceDiagram-Teilnehmer- und Nachrichtenbeschriftungen frei von unescape-slashes, Semikolons (;, die Mermaid als Anweisungsterminatoren parst) oder rohen Zeilenumbrüchen für maximale Kompatibilität mit Markdown-Viewern.