Softwarearchitektur visualisieren mit C4-Modell

Hast du jemals ein Architekturdiagramm zeichnen müssen? Ich nehme an, ja! Auch wenn die verwendeten Mittel (Whiteboard, Miro-Board, draw.io etc.) nicht so entscheidend sind, nehme ich an, dass du einfach sofort angefangen hast zu kritzeln und am Ende Kästen mit Linien verbunden hast. Dabei hast du begonnen, eigene Beschriftungen hinzuzufügen – entweder an den Linien oder an den Kästen. Vielleicht hast du sogar angefangen, verschiedene Formen für unterschiedliche Arten von Artefakten in deinem Diagramm zu verwenden, wie zum Beispiel den typischen Silo für Datenspeicher.

So könnte dein endgültiges Diagramm aussehen:

Obwohl dieses fiktive System nun visuell dokumentiert ist, hat der gewählte Ansatz einige gravierende Nachteile. Und der Betrachtende könnte mit Fragen zurückgelassen werden, die das Diagramm nicht beantwortet.

Erfahrene AWS-Entwickler*innen erkennen sofort, dass die orangenen Icons auf EC2-Instanzen (virtuelle Maschinen) hinweisen. Andere Entwickler*innen, die eher mit anderen Cloud-Anbietern vertraut sind, bemerken dies hingegen nicht unbedingt sofort.

Obwohl wir jetzt eine ansprechende Anordnung von Kästen haben, die durch Linien verbunden sind, fehlt es an einer klaren Semantik. Während die Linien, die mit dem Benutzer verbunden sind, deutliche Beschriftungen haben, fehlen bei den anderen Linien jegliche Beschriftungen. Selbst wenn du allen Kanten Beschriftungen hinzufügen würdest, welche Informationen würdest du dort unterbringen? Die verwendete Technologie, das Protokoll oder etwas ganz anderes?

Um sich einen Eindruck vom ACME INC Storefront-System zu verschaffen, mag das Diagramm ausreichend sein. Aber was, wenn du mehr über die internen Abläufe des Webservers wissen möchtest? Das Diagramm liefert diese Informationen nicht. Und wie würdest du ein solches Diagramm so erstellen, dass diese Technik auf alle deine Diagramme anwendbar ist – damit deine “detaillierten” Diagramme mit denen anderer Teams vergleichbar wären?

...und das wird laut meiner Werkstudent*in auch heute noch gerne von Dozent*innen gelehrt ;-)

Obwohl das C4-Modell versucht, die genannten Probleme zu lösen, fragst du dich vielleicht: Aber was ist mit den bestehenden Standards für Diagramme, wie zum Beispiel UML-Diagramme?

Obwohl UML heute noch einen gewissen Wert bieten kann – insbesondere bei bestimmten Diagrammtypen (z.B. bei Sequenzdiagrammen, nach meiner persönlichen Erfahrung) – wurde der Standard ursprünglich in einer ganz anderen Zeit entwickelt. Es war die Ära von Java 1.4, in der objektorientierte Programmierung das Maß aller Dinge war und Infrastructure-as-Code höchstens als verheißungsvolles Konzept am Horizont auftauchte.

Kurz gesagt: UML und UML-Diagramme werden dir heute nicht dabei helfen, moderne Softwarearchitekturen zu dokumentieren und zu visualisieren – oder um es mit einem Meme auszudrücken:

Die offizielle Webseite des C4-Modells ist ein sehr guter Ausgangspunkt, um sich umfassend über das Modell zu informieren. Dennoch möchte ich dir hier eine kurze Einführung geben, was das Modell besser macht als unsere eigene Semantik, die wir in unserem ACME INC Storefront-Beispiel verwendet haben.

Die Kernidee des C4-Modells besteht darin, Software-Systeme aus vier verschiedenen Perspektiven bzw. Zoomstufen zu betrachten. Jede Zoomstufe hat einen unterschiedlichen Detaillierungsgrad und kann somit unterschiedliche Informationen für verschiedene Interessengruppen bereitstellen (z.B. kann die höchste Ebene für das obere Management genutzt werden, während die unteren Ebenen eher für Entwickler*innen geeignet sind). Jede Ebene beginnt mit einem „C“, daher der Name C4. Schauen wir uns die einzelnen Ebenen genauer an:

Deine C4-Reise beginnt in der Regel mit der ersten Ebene: dem Systemkontextdiagramm. Dieses Diagramm zeigt dein Softwaresystem auf höchster Ebene, wobei das eigentliche System als Blackbox dargestellt wird und alle Details, wie beispielsweise Services, Datenbanken usw., verborgen bleiben. Auf dieser Ebene werden auch die primären Akteure des Systems neben den umliegenden externen Systemen angezeigt.

Dieses Diagramm eignet sich hervorragend, um es Nicht-Techniker*innen in deiner Organisation zu zeigen – etwa Produktverantwortlichen, Stakeholder*innen und Führungskräften. Für viele Systeme mag dieses Diagramm nicht sehr komplex oder detailliert erscheinen, aber genau darum geht es: Das System als Blackbox mit seinen primären Nutzer*innen und den umgebenden Systemen darzustellen – mehr nicht.

Während dir das Systemkontextdiagramm einen (sehr) groben Überblick über das System und seine Umgebung gibt, ist das Containerdiagramm der interessanteste Diagrammtyp. Zu diesem Diagramm gelangst du, indem du in das zuvor als Blackbox dargestellte Software-System „hineinzoomst“.

In diesem Diagramm werden alle relevanten „Container“ oder Infrastrukturressourcen dargestellt und miteinander verbunden, wenn sie voneinander abhängig sind (z.B. ist ein Java-Backend mit einer Mongo-Datenbank verbunden, weil der Java-Service seine Daten in einer Mongo-Collection speichert).

Auch wenn bei den meisten Entwickler*innen zunächst Docker-Container in den Sinn kommen, bezeichnet ein Container in diesem Kontext eine einzelne, deploybare Einheit des Systems, die benötigt wird, um die Funktion zu erfüllen. Ein Container kann also eine Java-Anwendung sein, die auf Kubernetes bereitgestellt wird – aber auch eine Datenbankinstanz, ein Redis-Cache, ein S3-Bucket oder eine andere Cloud-Ressource, die deine Anwendung zum Betrieb benötigt.

Wenn du in einen Container aus der vorherigen Ebene hineinzoomst, gelangst du zum Komponentendiagramm dieses Containers. Zwar kannst du kein Komponentendiagramm für z.B. S3 erstellen, da der Quellcode und die internen Abläufe nicht öffentlich zugänglich sind, aber für dein Java-Backend ist das möglich.

Jede Komponente in diesem Diagramm entspricht in der Regel einer Klasse in deiner Anwendung, einem Modul oder einer Bibliothek. In großen Systemen kann dieses Diagramm schnell sehr unübersichtlich werden – daher ist es wichtig, den Zweck des Diagramms im Blick zu behalten: Was möchtest du deinem Publikum zeigen? Geht es um einen spezifischen Datenfluss innerhalb deines Systems? Oder möchtest du die spezifische Modularisierung des Systems und die Interaktion der Module miteinander darstellen?

Füge nicht einfach alle möglichen Komponenten in dieses Diagramm ein, denn dadurch würde die Übersichtlichkeit stark abnehmen.

Die letzte Ebene des C4-Modells ist dein Quellcode. Wenn du ein Diagramm aus deinem Code erstellen möchtest, könnte UML eine gute Wahl sein – üblicherweise würdest du einfach den Code gemeinsam mit anderen Entwickler*innen überfliegen, um die Details zu verstehen.

Wenn du den Quellcode-Snippet erkennst, schick mir eine Nachricht auf LinkedIn! :-)

Indem wir Ebene 4 erreicht haben, haben wir unser ursprüngliches Diagramm, das mit einer eigens entwickelten Notation erstellt wurde, erfolgreich in C4-Diagramme umgewandelt. Diese können leichter gelesen und verstanden werden.

Im Artikel habe ich gezeigt, wie du ein individuelles Diagramm einfach in eine Reihe von C4-konformen Diagrammen umwandeln kannst. Aber das ist nur die Spitze des Eisbergs – und während ich in den letzten Jahren das C4-Modell verwendet habe, habe ich mehrere Erkenntnisse gewonnen. Diese habe ich in den folgenden fünf Tipps zusammengefasst:

Auch wenn du die C4-Formen manuell zeichnen könntest, solltest du den Ansatz wählen, vordefinierte Formen zu verwenden, die für viele gängige Diagramm-Tools wie draw.io oder mermaid verfügbar sind.

Egal, ob du Diagramme manuell mit draw.io erstellst oder den Docs-as-Code-Ansatz mit mermaid nutzt – du solltest deine Diagramme immer in einem Git-Repository speichern. So können Kollegen die Diagramme auschecken, Änderungen vornehmen und einen Pull-Request für ihre Änderungen erstellen.

Dieser Ansatz stellt sicher, dass alle Änderungen an deinen Diagrammen sicher gespeichert werden und nicht auf jemandes privatem OneDrive oder – schlimmer noch – auf dessen lokalem Rechner verloren gehen. Außerdem kannst du die Möglichkeit nutzen, neue Diagramme automatisch auf Confluence oder einer statischen Webseite zu veröffentlichen, sobald ein Pull-Request gemerged wird.

Obwohl das C4-Modell bis zu vier Ebenen bietet, sind meiner Erfahrung nach die Ebenen 1 und 2 am wertvollsten und am häufigsten genutzt. Indem du also mit Ebene 1 beginnst und anschließend ein ausgefeiltes Diagramm für Ebene 2 erstellst, erhöhst du bereits die Qualität deiner Dokumentation. Für die meisten Systeme ist es vollkommen in Ordnung, Ebene 3 zu überspringen, denn eine gut aufgebaute Anwendung offenbart die meisten Dinge von selbst auf Ebene 4.

Wenn du beginnst, die C4-Notation zu verwenden, ist es entscheidend, dass du die Diagramme als Grundlage für Diskussionen nutzt, damit C4 allen Beteiligten technischer Diskussionen geläufig wird. Überlasse den Teams nicht die Wahl, welche Notation sie verwenden, sondern ermutige sie, C4 zu verwenden – denn es kann zur gemeinsamen Dokumentationssprache deines Unternehmens werden. Falls ihr nicht auf professionelle Tools umsteigen wollt (siehe Tipp #5), können die Teams weiterhin entscheiden, womit sie die C4 Diagramme erstellen wollen.

Ab einer bestimmten Unternehmensgröße kann es sinnvoll sein, auf ein gehostetes Diagramm-Tool zu setzen. Ein zentrales Tool kann dir dabei helfen, die Sichtbarkeit deiner Systemlandschaft zu erhöhen – was beim Entwerfen neuer Systeme oder beim Ändern bestehender Infrastrukturen sehr hilfreich ist.

Alle beteiligten Stakeholder können mit einem Klick auf die aktuelle Version eines Systems zugreifen, ohne in riesigen Confluence-Bereichen oder umfangreichen GitHub-Organisationsstrukturen suchen zu müssen und sich fragen zu müssen, ob das gefundene Diagramm wirklich die neueste Version des Systems ist. Natürlich ist dieser Ansatz mit Kosten verbunden, aber er wird die Qualität deiner gesamten Dokumentation verbessern und sie unter einem Dach zentralisieren.