C4-Diagramme mit PlantUML

Software-Architekturen sind komplex. Ohne die richtige Visualisierung kann es schwierig sein, den Überblick zu behalten, insbesondere wenn Teams wachsen oder Projekte über Jahre laufen. Hier kommen C4-Modelle ins Spiel – eine einfache, aber leistungsstarke Methode, um Software-Architekturen auf verschiedenen Abstraktionsebenen zu dokumentieren. Und mit PlantUML gibt es ein fantastisches Werkzeug, um diese Diagramme effizient zu erstellen und zu pflegen [1, 2].

Was sind C4-Diagramme?

Das C4-Modell (Context, Container, Component, Code) von Simon Brown [3] bietet eine hierarchische Sicht auf Software-Architekturen. Es hilft dabei, Systeme schrittweise zu “entfalten”, von einer hohen Geschäftsperspektive bis hin zu den Details des Codes:

Context-Diagramm (Level 1): Zeigt das Softwaresystem im Kontext seiner Benutzer und anderer Systeme.
Container-Diagramm (Level 2): Zerlegt das System in seine Hauptbausteine (Anwendungen, Datenbanken, Dateisysteme).
Component-Diagramm (Level 3): Vertieft einen Container und zeigt die Komponenten innerhalb davon.
Code-Diagramm (Level 4): Beschreibt die Implementierungsdetails einer Komponente (oft durch UML-Klassendiagramme oder IDE-Tools).

Warum PlantUML für C4-Diagramme?

PlantUML ist ein Open-Source-Tool, das die Generierung von Diagrammen aus einfachem Text ermöglicht. Die Kombination mit der C4-PlantUML-Bibliothek bietet mehrere entscheidende Vorteile:

Code-basiert: Diagramme werden als Textdateien gespeichert, was Versionskontrolle (Git!), Diffing und Automatisierung ermöglicht.
Wartbarkeit: Änderungen an der Architektur können einfach im Text vorgenommen und neu gerendert werden.
Konsistenz: Die vordefinierten C4-Elemente sorgen für ein konsistentes Aussehen der Diagramme.
Flexibilität: PlantUML kann in vielen Tools und Umgebungen genutzt werden (IDEs, Wikis, CI/CD).

Die wichtigsten C4-PlantUML-Befehle im Überblick

Die C4-PlantUML-Bibliothek stellt spezifische Makros zur Verfügung, die das Zeichnen von C4-Elementen vereinfachen. Hier sind die Befehle, die am häufigsten verwendet werden:

Grundlegende Elemente

Diese Befehle repräsentieren die Bausteine Ihrer Architektur:

Person(alias, "Label", "Beschreibung"): Ein menschlicher Nutzer.
- Beispiel: Person(kunde, "Kunde", "Nutzt unsere Anwendung")
Person_Ext(alias, "Label", "Beschreibung"): Eine externe Person.
System(alias, "Label", "Beschreibung"): Ein Softwaresystem innerhalb der Organisation.
- Beispiel: System(onlineshop, "Online-Shop", "Hauptanwendung für Bestellungen")
System_Ext(alias, "Label", "Beschreibung"): Ein externes Softwaresystem.
- Beispiel: System_Ext(zahlungsprovider, "Zahlungsdienstleister", "Externer Anbieter für Zahlungen")
Container(alias, "Label", "Technologie", "Beschreibung"): Eine ausführbare Anwendung oder ein Datenspeicher.
- Beispiel: Container(webapp, "Web-Applikation", "Java Spring Boot", "Stellt die Benutzeroberfläche bereit")
Component(alias, "Label", "Technologie", "Beschreibung"): Eine logische Code-Einheit innerhalb eines Containers.
- Beispiel: Component(bestellservice, "Bestell-Service", "REST API", "Verwaltet Produktbestellungen")
Database(alias, "Label", "Technologie", "Beschreibung"): Eine spezielle Form eines Containers für Datenbanken.

Grenzen und Gruppierungen

Diese Befehle helfen dabei, logische Bereiche und Hierarchien zu definieren:

Enterprise_Boundary(alias, "Label") { … }: Die Grenze eines Unternehmens.
- Alles, was hier eingeschlossen ist, gehört zu Ihrer Organisation.
System_Boundary(alias, "Label") { … }: Die Grenze eines bestimmten Softwaresystems.
- Ideal, um alle Container eines Systems zusammenzufassen.
Container_Boundary(alias, "Label") { … }: Die Grenze eines einzelnen Containers.
- Nützlich, um Komponenten innerhalb eines Containers zu gruppieren.
Boundary(alias, "Label") { … }: Eine generische Grenze für allgemeine Gruppierungen.

Beziehungen

Elemente sind selten isoliert. Beziehungen zeigen die Interaktionen:

Rel(quelle, ziel, "Label", "Technologie"): Die Standardbeziehung.
- Beispiel: Rel(kunde, onlineshop, “Nutzt”)
Rel_U(…), Rel_D(…), Rel_L(…), Rel_R(…): Beziehungs-Makros, die die Richtung des Pfeils explizit vorgeben (Up, Down, Left, Right). Das ist sehr hilfreich, um das Layout zu steuern!
Rel_D(quelle, ziel, "Label", "Technologie"): Bidirektionale Beziehung.

Beispiel: Ein einfaches C4 Context-Diagramm

Lassen Sie uns ein kleines Beispiel für ein Context-Diagramm erstellen:

@startuml
!include C4_Context.puml

title Bestellsystem - Context-Diagramm

Person(kunde, "Kunde", "Surft, bestellt Produkte")
System(onlineshop, "Online-Shop", "Ermöglicht Kunden, Produkte zu bestellen")
System_Ext(zahlungsprovider, "Zahlungsdienstleister", "Verarbeitet Online-Zahlungen")
System_Ext(lagerverwaltung, "Lagerverwaltungssystem", "Verwaltet Produktbestände und Versand")

Rel(kunde, onlineshop, "Nutzt")
Rel(onlineshop, zahlungsprovider, "Sendet Zahlungsanfragen an", "HTTPS/API")
Rel(onlineshop, lagerverwaltung, "Fragt Bestände ab und sendet Bestellungen an", "REST/JSON")
Rel(lagerverwaltung, kunde, "Sendet Versandbenachrichtigungen an")

@enduml

Dieses einfache Skript erzeugt ein klares Diagramm, das zeigt, wie der Online-Shop mit seinen externen Akteuren und Systemen interagiert:

Tipps für besseres Layout und mehr Kontrolle

Neben den grundlegenden Befehlen gibt es weitere Kniffe für die Layout-Gestaltung:

Beziehungs-Richtungen nutzen: Wenn ein Pfeil explizit nach oben gehen soll, wird Rel_Up() verwendet. Dies beeinflusst die Platzierung der Elemente.
Boundary für Gruppierung: Die Grenzen sind nicht nur logisch, sondern auch visuell extrem wichtig. Elemente innerhalb einer Grenze werden zusammengehalten.
Unsichtbare Beziehungen: Manchmal sollen Elemente nah beieinander liegen, ohne eine sichtbare Linie. Dafür kann Rel_Neighbor(element1, element2, "", $hidden=true) genutzt werden.
Layout_Landscape() oder Layout_Portrait(): BDie generelle Ausrichtung des Diagramms wird bestimmt.

Fazit

C4-Diagramme mit PlantUML sind eine unschlagbare Kombination für die Dokumentation von Software-Architekturen. Sie ermöglichen die Erstellung klarer, konsistenter und wartbarer Diagramme, die von jedem im Team verstanden werden können. Die Einarbeitung in die Befehle wird die Klarheit der Architekturdokumentation erheblich verbessern.

Referenzen

[1] Open-Source-Tool, das einfache Textbeschreibungen verwendet UML-Diagramme zu zeichnen.
[2] PlantUML Web Server
[3] GitHub – plantuml-stdlib/C4-PlantUML: C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures