ADR-004: LikeC4 fuer Architekturdiagramme¶
| Feld | Wert |
|---|---|
| Status | accepted |
| Datum | 2026-03-20 |
| Betrifft | homelab-documentation |
Kontext¶
Die Dokumentation umfasst 40+ Services ueber 5 Projekte. Es wird ein Diagramm-Tool benoetigt, das:
- Mehrere Views aus einem einzigen Modell generiert (System-Context, pro Projekt, Netzwerk, VPN-Verbindungen)
- Eigene Elementtypen erlaubt (
service,container,network) - Interaktive Diagramme mit Drilldown und Zoom unterstuetzt
- In MkDocs integrierbar ist
- Statische PNG-Exports fuer CI/CD bietet
Entscheidung¶
LikeC4 v1.53.x wird fuer alle Architekturdiagramme eingesetzt. Das Tool ist bereits im homeserver Repo in Verwendung und wird auf alle Projekte erweitert.
Die Integration in MkDocs erfolgt ueber das mkdocs-likec4 Plugin.
Fuer CI/CD stellt likec4 export png statische Fallback-Bilder bereit
(nutzt Playwright intern als CLI-Dependency — kein manuelles
Browser-Setup noetig).
Alternativen¶
| Option | Version | Ergebnis |
|---|---|---|
| Structurizr | vNext 2026.02 | Rigides 4-Ebenen-Schema (Person, System, Container, Component), Tooling im Umbau auf vNext, PNG-Export nur via Puppeteer. |
| D2 | v0.7.1 | Kein Multi-View aus einem Modell, Entwicklung seit 6 Monaten inaktiv. |
| Mermaid | v11.x | C4-Support experimentell und fehlerhaft, kein Modell-Konzept — jedes Diagramm ist standalone. |
| PlantUML + C4 | v1.2026.2 | Kein Modell-Konzept, Java-Dependency, statische Bilder ohne Interaktivitaet. |
Konsequenzen¶
Positiv:
- Flexible Elementhierarchie mit eigenen Typen
- Multi-View aus einem Modell — Konsistenz ueber alle Diagramme
- Interaktive Diagramme (Drilldown, Zoom, Relationship Browser)
- Sehr aktive Entwicklung (172 Releases, mehrere pro Monat)
- Native MkDocs-Integration via Plugin
Negativ:
- Playwright-Dependency fuer PNG-Export erhoeht Docker-Image-Groesse
- Junges Projekt, API-Aenderungen zwischen Versionen moeglich
- DSL muss erlernt werden (eigene Syntax, kein Standard-C4)