Was ist das C4-Modell? Ein vollständiger Leitfaden für Software-Teams

Software-Architekturdiagramme haben ein Imageproblem. Sie sind entweder zu abstrakt, um nützlich zu sein, oder zu detailliert, um wartbar zu bleiben. Sie haben wahrscheinlich beides schon gesehen: das einzelne Kästchen mit der Beschriftung "Das System", das nichts aussagt, und das ausufernde UML-Diagramm mit 200 Klassen, das alles zeigt -- außer dem, was Sie tatsächlich wissen müssen.

Das C4-Modell, entwickelt von Simon Brown, löst dieses Problem, indem es eine Idee aus der Kartographie übernimmt. Karten funktionieren auf mehreren Zoom-Ebenen. Man beginnt mit einer Weltkarte, um sich zu orientieren, zoomt dann auf ein Land, dann eine Stadt, dann eine Straße. Jede Ebene zeigt den richtigen Detailgrad für die jeweiligen Fragen. Das C4-Modell wendet genau dieses Prinzip auf Software-Architektur an.

In diesem Leitfaden gehen wir alles durch, was Sie über das C4-Modell wissen müssen: was jede Ebene darstellt, wann sie eingesetzt wird, häufige Fallstricke und wie moderne Teams C4 in der Praxis umsetzen.

Wofür steht C4?

C4 steht für die vier Abstraktionsebenen, die das Modell definiert:

1. Context -- Das große Ganze. Wie Ihr System in die Welt passt.
2. Containers -- Die technischen Bausteine Ihres Systems auf hoher Ebene.
3. Components -- Die interne Struktur jedes Containers.
4. Code -- Die tatsächlichen Implementierungsdetails.

Jede Ebene beantwortet unterschiedliche Fragen für unterschiedliche Zielgruppen. Ein Product Manager interessiert sich für den Context. Ein Plattform-Ingenieur für die Container. Ein Entwickler, der an einem bestimmten Service arbeitet, für die Components. Die Code-Ebene braucht eigentlich niemand von Hand zu zeichnen -- dazu später mehr.

Die Stärke von C4 liegt nicht in einem einzelnen Diagramm. Sie liegt in der Hierarchie. Jedes Element auf einer Ebene wird zu einem Diagramm auf der nächsten Ebene aufgelöst. Ein Kästchen mit der Beschriftung "Backend API" im Container-Diagramm wird zu einem eigenen Komponenten-Diagramm, das die internen Module zeigt. So entsteht eine navigierbare, zoombare Ansicht Ihrer Architektur.

Ebene 1: Systemkontext-Diagramm

Das Systemkontext-Diagramm ist der Ausgangspunkt für jedes C4-Modell. Es beantwortet eine Frage: Wie passt Ihr System in die übergeordnete Umgebung?

Was es zeigt

• Ihr Software-System als einzelnes Kästchen in der Mitte
• Die Personen (Akteure, Rollen, Personas), die es nutzen
• Die externen Systeme, mit denen es integriert
• Die Beziehungen zwischen all diesen Elementen

Was es nicht zeigt

• Interne Struktur Ihres Systems
• Technologieentscheidungen
• Datenbanken, Queues oder Infrastruktur
• Deployment-Details

Ein konkretes Beispiel

Stellen Sie sich vor, Sie dokumentieren eine E-Commerce-Plattform. Ihr Systemkontext-Diagramm würde zeigen:

[Kunde] --> [E-Commerce-Plattform] : Durchsucht Produkte, gibt Bestellungen auf
[Lagermitarbeiter] --> [E-Commerce-Plattform] : Verwaltet Bestand
[E-Commerce-Plattform] --> [Payment Gateway (Stripe)] : Verarbeitet Zahlungen
[E-Commerce-Plattform] --> [Versanddienstleister (FedEx API)] : Erstellt Sendungen
[E-Commerce-Plattform] --> [E-Mail-Service (SendGrid)] : Sendet Benachrichtigungen

Fünf Nutzer und externe Systeme. Ein Kästchen für Ihre gesamte Plattform. Das ist alles.

Warum diese Ebene wichtig ist

Das Systemkontext-Diagramm erzwingt Klarheit über Grenzen. Was gehört Ihnen? Wovon sind Sie abhängig? Wer sind Ihre Nutzer? Diese Fragen erscheinen offensichtlich, aber Teams haben regelmäßig Schwierigkeiten, sie einheitlich zu beantworten.

Dieses Diagramm ist auch dasjenige, das Sie nicht-technischen Stakeholdern zeigen. Ihr CEO kann es ansehen und verstehen, was das System tut, wer es nutzt und von welchen Drittanbieter-Services es abhängt. Versuchen Sie das mal mit einem UML-Klassendiagramm.

Tipps für ein gutes Systemkontext-Diagramm

• Halten Sie es auf einer Seite. Wenn es nicht passt, stimmt möglicherweise Ihre Systemgrenze nicht.
• Beschriften Sie jede Beziehung mit einer Verb-Phrase: "sendet E-Mails über", "verarbeitet Zahlungen über", "liest Bestand von."
• Führen Sie alle externen Systeme auf, auch die selbstverständlichen (DNS, CDN, Monitoring).
• Fügen Sie keine internen Details ein. Widerstehen Sie der Versuchung.

Ebene 2: Container-Diagramm

Das Container-Diagramm zoomt in Ihr System hinein und zeigt die technischen Bausteine auf hoher Ebene. In der C4-Terminologie ist ein "Container" jede separat deploybare oder ausführbare Einheit -- nicht zwingend ein Docker-Container.

Was zählt als Container

• Eine Webanwendung (React SPA, Next.js App)
• Eine mobile Anwendung (iOS-App, Android-App)
• Ein Backend-API-Service (Go API, Node.js Server)
• Eine Datenbank (PostgreSQL, MongoDB, Redis)
• Ein Message Broker (Kafka, RabbitMQ)
• Ein Dateispeichersystem (S3, MinIO)
• Eine Serverless Function (AWS Lambda, Cloud Functions)

Jeder Container läuft in einem eigenen Prozess oder hat seinen eigenen Datenspeicher. Das ist das Unterscheidungsmerkmal. Zwei Go-Packages, die zusammen deployed werden, sind Teil desselben Containers. Zwei Go-Services, die unabhängig deployed werden, sind separate Container.

Ein konkretes Beispiel

Hineinzoomen in unsere E-Commerce-Plattform:

[Single-Page Application (React)] --> [API Gateway (Kong)] : API-Aufrufe (HTTPS/JSON)
[API Gateway] --> [Order Service (Go)] : Leitet Anfragen weiter
[API Gateway] --> [Product Service (Go)] : Leitet Anfragen weiter
[API Gateway] --> [User Service (Go)] : Leitet Anfragen weiter
[Order Service] --> [Order Database (PostgreSQL)] : Liest/schreibt Bestellungen
[Product Service] --> [Product Database (PostgreSQL)] : Liest/schreibt Produkte
[User Service] --> [User Database (PostgreSQL)] : Liest/schreibt Benutzer
[Order Service] --> [Message Queue (Kafka)] : Publiziert Bestellungs-Events
[Notification Service (Go)] --> [Message Queue] : Konsumiert Bestellungs-Events

Jetzt sehen Sie die Technologieentscheidungen, die Kommunikationsmuster und die Datenspeicher. Ein Architekt kann diskutieren, ob die Order- und Product-Datenbanken zusammengelegt werden sollten. Ein DevOps-Ingenieur kann die Deployment-Topologie planen. Ein neuer Entwickler kann verstehen, wo das React-Frontend endet und das Go-Backend beginnt.

Tipps für ein gutes Container-Diagramm

• Geben Sie die Technologie in Klammern an: "Order Service (Go)", "Database (PostgreSQL)".
• Zeigen Sie das Kommunikationsprotokoll an Beziehungen: "HTTPS/JSON", "gRPC", "AMQP".
• Bei mehr als 15-20 Containern erstellen Sie mehrere Container-Diagramme für verschiedene Subsysteme.
• Führen Sie Datenbanken und Queues auf. Die sind ebenfalls Container.
• Gehen Sie hier nicht unter die Container-Ebene. Interne Module gehören ins Komponenten-Diagramm.

Ebene 3: Komponenten-Diagramm

Das Komponenten-Diagramm zoomt in einen einzelnen Container hinein und zeigt dessen interne strukturelle Bausteine. Komponenten sind die wichtigsten Abstraktionen innerhalb eines Containers -- denken Sie an Packages, Module, Services oder Schichten.

Was zählt als Komponente

• Ein HTTP-Handler oder Controller
• Ein Business-Logic-Service
• Ein Repository oder Datenzugriffsschicht
• Ein externer API-Client
• Ein Hintergrund-Job-Prozessor
• Eine Middleware oder ein Interceptor

Komponenten sind logische Gruppierungen, nicht zwingend einzelne Dateien. Die OrderHandler-Komponente kann über mehrere Dateien implementiert sein, aber konzeptionell ist sie eine Einheit: der Teil des Systems, der HTTP-Anfragen zu Bestellungen verarbeitet.

Ein konkretes Beispiel

Hineinzoomen in den Order Service Container:

[Order Handler] --> [Order Service] : Delegiert Business-Logik
[Order Service] --> [Order Repository] : Persistiert Bestellungen
[Order Service] --> [Payment Client] : Validiert Zahlung
[Order Service] --> [Inventory Client] : Prüft Verfügbarkeit
[Order Repository] --> [Order Database (PostgreSQL)] : SQL-Abfragen
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Inventory Client] --> [Product Service] : gRPC

Ein Entwickler, der in dieses Team kommt, kann sofort sehen, wie der Order Service strukturiert ist: Anfragen kommen über den Handler herein, die Business-Logik lebt im Service, der Datenzugriff läuft über das Repository, und externe Aufrufe gehen über dedizierte Clients.

Wann Komponenten-Diagramme erstellen

Nicht jeder Container braucht ein Komponenten-Diagramm. Erstellen Sie eines, wenn:

• Der Container komplex genug ist, dass ein neuer Entwickler Schwierigkeiten hätte, sich zurechtzufinden
• Wichtige Design-Patterns (hexagonale Architektur, CQRS) vorhanden sind, die das Diagramm explizit machen kann
• Mehrere Teams zum selben Container beitragen und ein gemeinsames Verständnis der Struktur brauchen

Verzichten Sie auf das Komponenten-Diagramm, wenn:

• Der Container einfach ist (ein CRUD-Service mit drei Endpoints)
• Die Code-Struktur offensichtlich aus dem Ordner-Layout hervorgeht
• Der Container ein Drittanbieter-Tool ist (Redis, Kafka), bei dem Sie die Interna nicht kontrollieren

Ebene 4: Code-Diagramm

Die Code-Ebene zeigt die tatsächlichen Implementierungsdetails: Klassen, Interfaces, Funktionen und ihre Beziehungen. Im Wesentlichen ist das ein UML-Klassendiagramm oder ein Entity-Relationship-Diagramm.

Die ehrliche Wahrheit über Ebene 4

Simon Brown selbst rät davon ab, Code-Diagramme manuell zu erstellen. Hier die Gründe:

• Sie ändern sich zu häufig. Jeder Refactor macht sie ungültig.
• Sie sind teuer in der Wartung. Klassendiagramme von Hand zu zeichnen ist mühsam.
• Sie duplizieren Informationen, die bereits im Code vorhanden sind.
• Moderne IDEs können sie bei Bedarf generieren.

Wenn Sie Code-Level-Diagramme benötigen, generieren Sie sie aus Ihrem Quellcode mit Tools, die Ihre Sprache unterstützen. Zeichnen Sie sie nicht von Hand.

Wann Code-Diagramme tatsächlich helfen

Es gibt Ausnahmen:

• Komplexe Algorithmen, die von einer visuellen Darstellung profitieren
• Design Patterns (Strategy, Observer, State Machine), bei denen die Struktur das Interessante ist
• Öffentliche API-Oberflächen, bei denen Sie die Verträge dokumentieren möchten
• Interview- oder Onboarding-Materialien, bei denen Sie Patterns vermitteln

In der Praxis nutzen die meisten Teams drei C4-Ebenen (Context, Container, Component) und überlassen die Code-Ebene IDE-generierten Ansichten.

Die ergänzenden Diagramme

Über die vier Kernebenen hinaus definiert Simon Brown mehrere ergänzende Diagramme, die die C4-Hierarchie vervollständigen:

System-Landscape-Diagramm

Ein noch weiter herausgezoomtes Systemkontext-Diagramm. Es zeigt alle Software-Systeme in einem Unternehmen und wie sie zueinander in Beziehung stehen. Nützlich für Enterprise-Architekten, die ein Portfolio von Systemen verwalten.

Deployment-Diagramm

Ordnet Container der Infrastruktur zu. Zeigt, welche Container auf welchen Servern laufen, in welchen Cloud-Regionen, hinter welchen Load Balancern. Unverzichtbar für DevOps- und Plattform-Teams.

Dynamisches Diagramm

Zeigt, wie Elemente zur Laufzeit zusammenarbeiten, um einen bestimmten Anwendungsfall zu erfüllen. Ähnlich einem UML-Sequenzdiagramm, aber mit C4-Notation. Nützlich für die Dokumentation komplexer Abläufe wie "Was passiert, wenn ein Benutzer eine Bestellung aufgibt."

C4-Modell vs. andere Ansätze

C4 vs. UML

UML definiert 14 Diagrammtypen. Die meisten Teams nutzen 2-3 davon, und oft inkonsistent. C4 bietet 4 Ebenen mit klaren Zwecken. Es ist einfacher zu lernen, einfacher zu nutzen und einfacher zu warten.

Allerdings schließen sich C4 und UML nicht gegenseitig aus. Sie können UML-Klassendiagramme auf Ebene 4 verwenden, oder UML-Sequenzdiagramme als dynamische Diagramme. C4 liefert die Hierarchie; UML liefert spezifische Notationen, wenn sie benötigt werden.

C4 vs. Arc42

Arc42 ist ein Template für Architekturdokumentation. Es deckt weit mehr ab als nur Diagramme: Qualitätsanforderungen, Einschränkungen, Risiken, Deployment-Ansichten und mehr. C4 konzentriert sich speziell auf hierarchische Diagramme. Viele Teams nutzen beides: Arc42 als Dokumentationsstruktur und C4 als Diagramm-Ansatz innerhalb davon.

C4 vs. "Einfach ein Whiteboard nehmen"

Whiteboards sind großartig für Exploration und Brainstorming. Sie sind schrecklich für Dokumentation. Whiteboard-Diagramme werden gelöscht, schlecht abfotografiert und nie aktualisiert. C4 bietet die Struktur, um Whiteboard-Erkundungen in dauerhafte Dokumentation zu verwandeln.

Häufige Fehler bei der C4-Einführung

Alles auf einmal zeigen wollen

Der ganze Sinn von C4 ist die schrittweise Offenlegung. Wenn Ihr Container-Diagramm einzelne Klassen zeigt, haben Sie die Hierarchie zusammengebrochen. Jedes Diagramm sollte Elemente auf genau einer Zoom-Ebene zeigen.

Beziehungen ignorieren

Kästchen ohne Pfeile sind ein Inventar, keine Architektur. Die Beziehungen -- wer ruft wen auf, welches Protokoll wird verwendet, welche Daten fließen dazwischen -- sind oft wertvoller als die Kästchen selbst. Beschriften Sie immer Ihre Beziehungen.

Es zu einer Ein-Personen-Aktivität machen

Architekturdokumentation ist Teamarbeit. Wenn nur eine Person die Diagramme erstellt und pflegt, werden sie das Verständnis (oder Missverständnis) dieser einen Person widerspiegeln. Überprüfen Sie C4-Diagramme im Team, idealerweise als Teil Ihres Architektur-Review-Prozesses.

Nicht mit anderer Dokumentation verknüpfen

Ein C4-Diagramm gewinnt an Kraft, wenn es mit anderen Artefakten verknüpft wird. Verknüpfen Sie Container mit ihren Deployment-Runbooks. Verknüpfen Sie Komponenten mit ihren Architecture Decision Records (ADRs). Verknüpfen Sie externe Systeme mit ihrer API-Dokumentation. Isolierte Diagramme sind weniger wertvoll als vernetzte.

Diagramme veralten lassen

Der größte Killer jedes Dokumentationsansatzes ist Veraltung. Ein Diagramm, das die Architektur vom letzten Jahr beschreibt, ist schlimmer als kein Diagramm, weil es aktiv in die Irre führt. Bauen Sie Diagramm-Updates in Ihren Workflow ein -- machen Sie sie Teil von Pull-Request-Checklisten, Sprint Reviews oder Architektur-Meetings.

Wie Archyl das C4-Modell umsetzt

Archyl wurde von Grund auf um das C4-Modell als erstklassiges Konzept gebaut. So wird jede Ebene auf Features in der Plattform abgebildet:

Systemkontext in Archyl

Wenn Sie ein Projekt in Archyl erstellen, definieren Sie Systeme und ihre Beziehungen zu externen Akteuren. Die Systemkontext-Ansicht wird automatisch aus Ihrem Modell gerendert -- kein manuelles Zeichnen nötig. Fügen Sie ein System hinzu, fügen Sie einen externen Akteur hinzu, zeichnen Sie eine Beziehung, und das Diagramm aktualisiert sich in Echtzeit.

Container-Diagramm in Archyl

Innerhalb jedes Systems definieren Sie Container mit ihren Technologie-Stacks. Archyl rendert das Container-Diagramm und ermöglicht es Ihnen, in jeden Container hineinzuzoomen, um seine Komponenten zu sehen. Beziehungen zwischen Containern zeigen die Kommunikationsprotokolle und Datenflüsse.

Komponenten-Diagramm in Archyl

Innerhalb jedes Containers definieren Sie Komponenten. Archyl verknüpft diese über das Code-Elements-Feature mit tatsächlichem Code, der Komponenten bestimmten Dateien und Verzeichnissen in Ihrem Repository zuordnet. Diese Verbindung zwischen Diagramm und Code ermöglicht die Drift-Erkennung.

KI-gestützte Discovery

Was Archyl von einem Zeichenwerkzeug unterscheidet, ist, dass Sie das Modell nicht manuell erstellen müssen. Verbinden Sie Ihr Repository, führen Sie die KI-Discovery aus, und Archyl generiert einen C4-Modell-Entwurf aus Ihrer Codebasis. Die KI identifiziert Systeme, Container, Komponenten und Beziehungen durch Analyse Ihrer Code-Struktur, Konfigurationsdateien und Abhängigkeitsgraphen.

Sie überprüfen die Vorschläge, akzeptieren oder modifizieren sie, und Sie haben ein C4-Modell in Minuten statt Wochen.

Drift-Erkennung

Sobald Ihr C4-Modell existiert, prüft Archyl kontinuierlich, ob es noch die Realität widerspiegelt. Der Drift Score zeigt Ihnen, welcher Prozentsatz Ihrer dokumentierten Architektur tatsächlich in der Codebasis vorhanden ist. Wenn jemand einen Service umbenennt oder eine Komponente löscht, sinkt der Drift Score, und Sie wissen, dass Ihre Dokumentation aktualisiert werden muss.

Das ist die Lücke, die den meisten C4-Tools fehlt. Diagramme zu erstellen ist der einfache Teil. Sie akkurat zu halten ist der schwierige Teil. Archyls Drift-Erkennung schließt diese Lücke.

Erste Schritte mit C4: Ein schrittweiser Ansatz

Wenn Ihr Team neu beim C4-Modell ist, hier ein praktischer Einführungsweg:

Woche 1: Systemkontext

Versammeln Sie Ihr Team für einen einstündigen Workshop. Zeichnen Sie Ihr System als einzelnes Kästchen. Identifizieren Sie jede Benutzerrolle und jedes externe System. Zeichnen Sie die Beziehungen. Sie werden überrascht sein, wie viel Diskussion diese einfache Übung auslöst -- und wie viel Abstimmung sie erzeugt.

Woche 2: Container-Diagramm

Nehmen Sie das System-Kästchen aus Ihrem Kontext-Diagramm und zerlegen Sie es in Container. Was sind die deploybaren Einheiten? Welche Datenbanken gibt es? Welche Message Broker oder Caches sind im Spiel? Hier machen Sie Technologieentscheidungen sichtbar.

Woche 3-4: Komponenten-Diagramme für Schlüssel-Container

Wählen Sie die zwei oder drei komplexesten Container. Zerlegen Sie jeden in Komponenten. Hier werden neue Entwickler den Großteil ihrer Zeit verbringen, also priorisieren Sie die Container, die am schwierigsten zu verstehen sind.

Fortlaufend: Pflegen und Weiterentwickeln

Die anfängliche Erstellung ist der einfache Teil. Die Disziplin, Diagramme aktuell zu halten, ist das, was Teams trennt, die Wert aus C4 ziehen, von Teams, die es nach einem Monat aufgeben. Automatisieren Sie, was Sie können. Nutzen Sie Tools, die Drift erkennen. Machen Sie Diagramm-Reviews zum Teil Ihres Entwicklungsworkflows.

Warum C4 funktioniert

Das C4-Modell ist technisch nicht bahnbrechend. Hierarchische Zerlegung und Abstraktionsebenen gibt es in der Informatik seit den 1960er Jahren. Was Simon Brown getan hat, war, diese Ideen in ein einfaches, einprägsames Framework mit klaren Regeln und minimaler Notation zu verpacken.

Es funktioniert, weil:

• Es leicht zu lernen ist. Vier Ebenen. Kästchen und Pfeile. Keine UML-Zertifizierung nötig.
• Es skaliert. Vom Wochenendprojekt bis zur Enterprise-Plattform gelten dieselben vier Ebenen.
• Es verschiedene Zielgruppen bedient. Führungskräfte, Architekten und Entwickler bekommen jeweils das Diagramm, das ihre Sprache spricht.
• Es werkzeugunabhängig ist. Sie können ein Whiteboard, ein Zeichenwerkzeug, ein textbasiertes Format oder eine dedizierte Plattform wie Archyl verwenden.
• Es sich auf die richtigen Dinge konzentriert. Struktur und Beziehungen, nicht Implementierungsdetails.

Wenn die Architekturdokumentation Ihres Teams aus veralteten Visio-Dateien, Whiteboard-Fotos in Slack und Stammwissen besteht, ist das C4-Modell der praktischste Weg zu etwas Besserem.

Bereit, Ihr C4-Modell zu erstellen? Testen Sie Archyl kostenlos und generieren Sie Ihr erstes Architekturdiagramm aus Code in Minuten. Oder erfahren Sie mehr: KI-gestützte Architektur-Discovery | Architecture as Code: Definieren Sie Ihr C4-Modell in YAML | Architecture Drift Score.