Jedes Engineering-Team kennt dieses Problem. Es gibt eine Confluence-Seite, ein Miro-Board oder ein Lucidchart-Diagramm — erstellt von jemandem, der es ernst nahm, vor drei Architekturentscheidungen. Es zeigt das System, wie es damals existierte. Es ist jetzt an mindestens sechs Stellen falsch. Niemand aktualisiert es, weil es in niemandens Stellenbeschreibung steht — und sobald man es aktualisiert hat, merged jemand ein Refactoring, das es wieder falsch macht.
Das ist kein Disziplinproblem. Es ist ein Tooling-Problem. Die Architektur lebt in der Codebasis; die Dokumentation lebt woanders. Diese Lücke ist, wo Genauigkeit stirbt.
Warum manuelle Architekturdokumentation bei Skalierung scheitert
In einem Monolithen kann ein einzelner Entwickler das vollständige Systemmodell im Kopf behalten. In einer Microservice-Architektur mit 20, 50 oder 200 Services hat niemand ein vollständiges mentales Modell. Dokumentation wird zum gemeinsamen mentalen Modell — was bedeutet, dass ihre Genauigkeit tragend ist, nicht dekorativ.
Das Fehlermuster ist konsistent: Dokumentation beginnt akkurat, wird autoritär, dann veraltet, während sie autoritär bleibt. Engineers hören auf, ihr zu vertrauen, können sie aber nicht aufhören zu referenzieren, weil es nichts Besseres gibt.
Der Architecture-as-Code-Ansatz
Die Lösung: Behandle Architekturdokumentation als Nebenprodukt einer strukturierten Datendatei, die im Repository lebt, nicht als manuell gepflegtes Diagramm in einem separaten Tool.
Der Mechanismus: Jeder Service wird in einer YAML-Konfiguration definiert, die Name, Abhängigkeiten, besitzendes Team, Tech-Stack und Status deklariert. Eine Visualisierungsschicht liest das YAML und generiert automatisch das interaktive Diagramm. Wenn sich das YAML ändert, aktualisiert sich das Diagramm beim nächsten Deploy.
Was gute Architekturdokumentation braucht
- Service-Name und Beschreibung — Was macht dieser Service in einem Satz?
- Upstream- und Downstream-Abhängigkeiten — Was ruft er auf, was ruft ihn auf?
- Besitzendes Team — Wer ist für Incidents verantwortlich?
- Tech-Stack — Sprache, Framework, Datenspeicher.
- Status — Aktiv / veraltet / in-Migration.
Service Map basiert genau auf diesem Prinzip: Services in YAML definieren, statische Visualisierungsschicht auf der eigenen Infrastruktur deployen und einen interaktiven Abhängigkeitsgraphen erhalten, der sich automatisch aktualisiert. Keine SaaS-Gebühr, kein Pro-Seat-Pricing. Einmalige Zahlung.
