Nach Jahren des Zeichnens verwirrender Architekturdiagramme entdeckte ich das C4-Modell. So hat es die Art verändert, wie unser Team über Systeme kommuniziert.

Einführung in das C4-Modell für Software-Architektur

Ich erinnere mich noch an die Whiteboard-Session, die mich alles über Architekturdiagramme überdenken ließ. Wir waren dabei, eine neue Entwicklerin einzuarbeiten, und ich verbrachte 45 Minuten damit, Kästen und Pfeile zu zeichnen, um unsere E-Commerce-Plattform zu erklären. Am Ende sah sie verwirrter aus als zu Beginn. Das Diagramm hatte alles — Microservices, Datenbanken, Message Queues, externe APIs — alles zusammengepfercht mit inkonsistenter Notation und ohne klare Hierarchie.

An diesem Abend stieß ich auf Simon Browns C4-Modell, und es war einer dieser "warum habe ich daran nicht gedacht?"-Momente. Die Idee ist trügerisch einfach: Anstatt alles in ein Diagramm zu packen, erstellt man mehrere Diagramme auf verschiedenen Zoom-Ebenen. Wie bei Google Maps beginnt man herausgezoomt, um das große Bild zu sehen, und zoomt dann schrittweise hinein, um mehr Details zu sehen.

Die vier Ebenen von C4

Das "C4" steht für vier Abstraktionsebenen, die jeweils unterschiedliche Fragen beantworten:

Ebene 1: Systemkontext

Dies ist die Vogelperspektive aus 10.000 Metern Höhe. Ihr gesamtes System ist eine einzige Box, und Sie zeigen:

Wer Ihr System nutzt (Personen oder Rollen)
Mit welchen externen Systemen Sie integrieren

Das ist alles. Keine internen Details, keine Technologieentscheidungen, keine Datenbanken. Nur "hier ist unser System, hier ist, wer es nutzt, und hier ist, womit es kommuniziert."

Als ich mein erstes Systemkontext-Diagramm für unsere Plattform zeichnete, passte es auf eine einzige Folie. Unser CEO konnte es verstehen. Das war vorher nie mit meinen Architekturdiagrammen passiert.

Das macht diese Ebene mächtig: Sie zwingt Sie, über Grenzen nachzudenken. Was ist innerhalb Ihres Systems versus was ist außerhalb? Was besitzen Sie versus wovon sind Sie abhängig? Diese Fragen scheinen offensichtlich, aber ich habe Teams gesehen, die Schwierigkeiten hatten, sie klar zu beantworten.

Ebene 2: Container-Diagramm

Jetzt zoomen wir eine Ebene hinein. Ein "Container" in der C4-Terminologie ist kein Docker-Container — es ist jede deploybare Einheit, die Code ausführt oder Daten speichert:

Webanwendungen
Mobile Apps
Backend-Services
Datenbanken
Message Queues
Dateispeicher

Dieses Diagramm zeigt die technische Architektur auf hoher Ebene. Sie können die wichtigsten Technologieentscheidungen sehen (React-Frontend, Go-Backend, PostgreSQL-Datenbank) und wie die Daten zwischen ihnen fließen.

Ich finde diese Ebene am nützlichsten für:

Planung von Infrastruktur und Deployments
Diskussion von Technologieentscheidungen mit dem Team
Erklärung des Systems für neue Backend- oder Frontend-Entwickler

Eine Sache, die ich gelernt habe: Seien Sie hier vorsichtig mit der Granularität. Wenn Sie 30 Microservices haben, zeigen Sie nicht alle 30 als separate Container. Gruppieren Sie verwandte Services oder erstellen Sie mehrere Container-Diagramme für verschiedene Bereiche Ihres Systems.

Ebene 3: Komponenten-Diagramm

Hier zoomen wir in einen einzelnen Container hinein. Komponenten sind die wichtigsten strukturellen Bausteine innerhalb dieses Containers — denken Sie an Services, Repositories, Controller oder Module.

Für unser Go-Backend könnte ein Komponenten-Diagramm zeigen:

HTTP-Handler
Business-Logic-Services
Repository-Interfaces
Externe API-Clients

Ich bin ehrlich: Ich erstelle nicht für jeden Container Komponenten-Diagramme. Nur für die komplexen, die neue Entwickler schwer verstehen. Für einen einfachen CRUD-Service ist der Code selbst die Dokumentation.

Ebene 4: Code-Diagramm

Die tiefste Ebene zeigt tatsächliche Code-Elemente — Klassen, Interfaces, Funktionen. Simon Brown selbst sagt, dass diese Ebene optional ist und oft automatisch aus dem Code generiert wird.

In der Praxis erstelle ich selten manuell Code-Diagramme. Wenn ich es tue, ist es für besonders komplexe Algorithmen oder Muster, die von einer visuellen Erklärung profitieren. Meistens, wenn Sie dieses Detailniveau brauchen, sollten Sie den tatsächlichen Code lesen.

Warum C4 bei unserem Team funktioniert hat

Vor C4 war unsere Architekturdokumentation ein Chaos. Wir hatten:

Visio-Diagramme von 2019, die niemand aktualisierte
Whiteboard-Fotos in zufälligen Slack-Kanälen
README-Dateien mit ASCII-Art, die Dinge irgendwie erklärten
Stammwissen, das zur Tür hinausging, wenn Leute das Unternehmen verließen

Das C4-Modell gab uns ein Framework, das tatsächlich funktioniert. Hier ist warum:

Es ist einfach genug, um es sich zu merken

Vier Ebenen. Das ist alles. Kein Auswendiglernen von 14 verschiedenen UML-Diagrammtypen oder Diskutieren, ob etwas ein "Komponente" oder ein "Modul" im UML-Sinne sein sollte.

Verschiedene Zielgruppen, verschiedene Diagramme

Unser CEO schaut sich das Systemkontext-Diagramm an. Unsere Architekten diskutieren das Container-Diagramm. Unsere Entwickler arbeiten mit Komponenten-Diagrammen. Jeder bekommt das richtige Detailniveau für seine Bedürfnisse.

Es bleibt aktuell

Weil C4-Diagramme relativ einfach sind, ist es nicht schmerzhaft, sie zu aktualisieren. Wenn wir eine neue externe Integration hinzufügen, dauert das Aktualisieren des Systemkontext-Diagramms 5 Minuten. Vergleichen Sie das mit dem Aktualisieren eines detaillierten UML-Diagramms mit jeder Klasse und Methode.

Es ist werkzeugunabhängig

Wir haben mit draw.io angefangen, sind zu Miro für Zusammenarbeit gewechselt, und nutzen jetzt Archyl für KI-unterstützte Diagrammerstellung. Das C4-Modell funktioniert mit jedem Werkzeug, weil es um die Konzepte geht, nicht um die Notation.

Häufige Fehler, die ich gemacht habe (damit Sie sie nicht machen)

Fehler 1: Zu früh zu viele Details zeigen

Mein erstes Container-Diagramm hatte 47 Kästen. Es war genau, aber nutzlos. Jetzt folge ich einer Regel: Wenn Ihr Diagramm nicht auf einen Bildschirm passt, sind Sie auf der falschen Zoom-Ebene.

Fehler 2: Die Beziehungen vergessen

Ein Diagramm mit Kästen aber ohne Pfeile ist nur ein Inventar. Die Beziehungen — wer ruft wen auf, welche Daten fließen wohin — sind oft wichtiger als die Kästen selbst. Beschriften Sie Ihre Pfeile. Beschreiben Sie die Protokolle und Datenformate.

Fehler 3: Nach Änderungen nicht aktualisieren

Das beste Diagramm ist nutzlos, wenn es das System von vor zwei Jahren beschreibt. Wir haben das gelöst, indem Diagramm-Updates Teil unserer PR-Checkliste für architektonische Änderungen wurden. Es ist nicht perfekt, aber es hilft.

Fehler 4: Über-Engineering der Notation

Ich habe eine Woche damit verbracht, benutzerdefinierte Icons und Farbschemata für unsere C4-Diagramme zu entwerfen. Totale Zeitverschwendung. Einfache Kästen mit klaren Beschriftungen funktionieren prima. Konzentrieren Sie sich auf den Inhalt, nicht auf die Ästhetik.

Erste Schritte

Wenn Sie neu bei C4 sind, hier ist was ich vorschlagen würde:

Beginnen Sie mit Systemkontext. Nehmen Sie sich 30 Minuten, um Ihr System als einzelne Box zu zeichnen, umgeben von den Nutzern und externen Systemen. Allein das hat Wert.
Fügen Sie ein Container-Diagramm hinzu. Wählen Sie Ihr komplexestes System und zerlegen Sie es in deploybare Einheiten. Zeigen Sie, wie sie kommunizieren.
Stoppen Sie hier erstmal. Versuchen Sie nicht, alles auf einmal zu dokumentieren. Lassen Sie die Diagramme ihren Wert beweisen, bevor Sie mehr Zeit investieren.
Machen Sie es kollaborativ. Teilen Sie die Diagramme mit Ihrem Team. Holen Sie Feedback ein. Architekturdokumentation sollte keine Solo-Aktivität sein.

Wie wir C4 bei Archyl nutzen

Beim Bau von Archyl essen wir offensichtlich unser eigenes Hundefutter. Unsere Architekturdokumentation nutzt durchgehend C4:

Das Systemkontext-Diagramm zeigt Archyl, das sich mit verschiedenen Git-Anbietern, KI-Services und Zahlungssystemen verbindet
Container-Diagramme detaillieren das Go-Backend und das React-Frontend
Komponenten-Diagramme detaillieren den Discovery-Service und die Diagramm-Rendering-Engine

Was mächtig ist, ist diese Diagramme mit anderer Dokumentation zu verknüpfen. Ein Architecture Decision Record über die Wahl von PostgreSQL statt MongoDB verknüpft direkt zum Datenbank-Container in unserem Container-Diagramm. User Flows referenzieren die spezifischen Komponenten, die sie durchlaufen.

Diese vernetzte Dokumentation ist es, was wir in Archyl aufbauen — die Fähigkeit, Ihre Architektur nicht als isolierte Diagramme zu sehen, sondern als verbundenen Wissensgraphen.

Fazit

Das C4-Modell ist nicht revolutionär in seinen Konzepten. Abstraktionsebenen und hierarchische Zerlegung gibt es schon ewig. Was Simon Brown brillant gemacht hat, war, diese Ideen in ein einfaches, einprägsames Framework zu verpacken, das tatsächlich genutzt wird.

Wenn Ihre Architekturdokumentation ein Chaos aus veralteten Visio-Dateien und Whiteboard-Fotos ist, probieren Sie C4. Fangen Sie klein an, mit nur einem Systemkontext-Diagramm. Sie könnten überrascht sein, wie viel Klarheit ein einzelnes, gut durchdachtes Diagramm bringen kann.

Dies ist Teil unserer Serie über Architekturdokumentation. Als Nächstes: Wie KI automatisch Ihre Architektur entdecken kann und Warum Dokumentation wichtiger ist als Sie denken.

Einführung in das C4-Modell für Software-Architektur - Archyl Blog