Architekturdiagramme, die nicht veralten: ein Living-Docs-Workflow

Jede Engineering-Organisation hat eins: das Architekturdiagramm im Wiki, das vor Jahren ein paar Wochen lang gestimmt hat. Neue Kolleginnen und Kollegen studieren es und erfahren dann nebenbei, dass die Hälfte der Kästen umbenannt wurde und die Queue in der Mitte letztes Frühjahr ersetzt wurde. Die meisten Best Practices zur Architekturdokumentation drehen sich darum, was du zeichnen sollst. In diesem Beitrag geht es um den schwierigeren Teil: Diagramme nach dem ersten Entwurf korrekt zu halten, mit einem Workflow, der sie als lebende Dokumentation behandelt statt als Einweg-Artefakte.

Warum Architekturdokumentation veraltet

Diagramme veralten selten, weil Leute faul sind. Sie veralten, weil der Prozess drumherum das Veralten zum Normalfall macht.

• Sie sind Einweg-Artefakte. Ein Diagramm entsteht für ein Design-Review, den Kickoff einer Migration oder ein Audit. Sobald das Meeting vorbei ist, hat niemand mehr einen Grund, es wieder zu öffnen.
• Screenshots landen überall. Die Quelldatei liegt auf irgendeinem Laptop, und ein PNG landet im Wiki, im Onboarding-Dokument, in drei Foliensätzen und in einer README. Jetzt gibt es fünf Kopien, und keine davon lässt sich bearbeiten.
• Niemandem gehören sie. „Das Platform-Team“ ist kein Owner. Wenn niemand konkret verantwortlich ist, geht jeder davon aus, dass jemand anderes das Update macht.
• Nichts löst ein Update aus. Codeänderungen laufen durch Pull Requests, Review und CI. Diagramme ändern sich nur, wenn sich jemand daran erinnert, und das ist selten der Moment, in dem sich das System ändert.
• Sie zeigen zu viel. Ein Diagramm mit jedem Pod, jeder Queue, jeder IAM-Rolle und jeder User Journey ist am Tag seiner Fertigstellung veraltet, weil jede Änderung irgendwo es falsch macht.

Nichts davon ist in erster Linie ein Tooling-Problem; ein besseres Zeichentool ersetzt keinen fehlenden Owner. Aber das Tool kann den richtigen Workflow billig oder teuer machen.

Best Practices für Architekturdokumentation mit lebenden Diagrammen

Hier ist der Workflow, den wir empfehlen. Er ist bewusst meinungsstark.

1. Eine Quelle der Wahrheit pro Diagramm

Jedes Diagramm existiert an genau einem bearbeitbaren Ort. Alles andere ist ein Link oder ein Embed, der auf diesen Ort zeigt. Wenn du gerade ein PNG exportieren willst, um es irgendwo einzufügen, frag dich, ob ein Link reichen würde. Meistens reicht er.

2. Verlinken statt kopieren

Wikis, Doku-Sites und READMEs sollten auf das lebende Diagramm zeigen, nicht ein Bild davon enthalten. Ein eingebettetes Live-Diagramm ändert sich, wenn sich die Quelle ändert; ein eingefügter Screenshot ist nach der nächsten Änderung für immer falsch. Wenn du wirklich ein statisches Bild brauchst, etwa ein PDF für einen Auditor, behandle es als datierten Export und halte es aus der Doku heraus, auf die sich Leute im Alltag verlassen.

3. Benenne einen Owner

Jedes Diagramm bekommt einen Owner: eine Person oder ein Team mit einer benannten Ansprechperson. Der Owner zeichnet nicht jede Änderung selbst, aber er merkt, wenn etwas nicht stimmt, und wird gefragt. Schreib den Owner direkt ins Diagramm und in deinen Diagramm-Index.

4. Hänge Update-Trigger an Ereignisse, die es schon gibt

Verlass dich nicht aufs Gedächtnis. Koppel Diagramm-Updates an Ereignisse, die ohnehin passieren:

• Pull Requests. Ergänze das PR-Template um eine Checkbox zur Architektur-Auswirkung.
• ADRs. Jeder angenommene Architecture Decision Record verlinkt das Diagramm, das er ändert, und das Diagramm wird als Teil der Annahme aktualisiert.
• Incident-Postmortems. Hat der Incident gezeigt, dass das Diagramm falsch war oder eine Abhängigkeit fehlte, wird die Korrektur zu einem Action Item.
• Quartalsreview. Owner nehmen sich pro Diagramm ein paar Minuten, prüfen, ob es noch zur Realität passt, und aktualisieren dann das Datum „zuletzt geprüft“.

Ein Ausschnitt für das PR-Template:

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. Wähle den richtigen Detailgrad

Arbeite mit Ebenen statt mit einem riesigen Bild. Das C4 model liefert ein gemeinsames Vokabular: eine System-Context-Sicht (Personen und Systeme), eine Container-Sicht (Anwendungen und Datenspeicher) und eine Component-Sicht innerhalb eines Containers. Höhere Ebenen ändern sich selten und sind billig aktuell zu halten. Niedrigere Ebenen ändern sich oft, also zeichne sie nur dort, wo Leute sie brauchen, und lass darunter den Code die Quelle der Wahrheit sein.

Eine nützliche Faustregel: Wenn sich ein Diagramm in jedem Sprint ändert, ist es wahrscheinlich eine Ebene zu tief gezeichnet.

6. Mach Datum und Version sichtbar

Setz den Owner und ein Datum „zuletzt geprüft“ in eine Ecke jedes Diagramms. So können Lesende auf einen Blick einschätzen, wie sehr sie ihm trauen: Ein Diagramm, das letzten Monat geprüft wurde, verdient ein anderes Vertrauen als eins von vor zwei Jahren. Ohne Datum wirkt jedes Diagramm gleich verbindlich, und das ist schlimmer, als ein altes Datum zu zeigen.

7. Führe einen Diagramm-Index

Eine Seite listet alle Diagramme, die zählen:

Der Index macht Lücken sichtbar (kein Owner, altes Datum) und ist der naheliegende Startpunkt für das Quartalsreview.

8. Kombiniere Diagramme mit ADRs

Ein Diagramm zeigt, was die Architektur ist. Es kann nicht zeigen, warum. Architecture Decision Records schließen diese Lücke. Michael Nygards ursprüngliches ADR-Format ist kurz genug, dass Leute sie tatsächlich schreiben: Titel, Status, Kontext, Entscheidung, Konsequenzen. Verlinke den ADR im Diagramm und das Diagramm im ADR:

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

Wenn sechs Monate später jemand fragt „Warum ist das so?“, ist die Antwort einen Klick entfernt.

Wie Archboard einen Living-Docs-Workflow unterstützt

Archboard ist ein gehosteter Architektur-Workspace, und der Großteil des Workflows oben lässt sich auf Funktionen abbilden, die es bereits gibt. Hier steht, was abgedeckt ist und wo du weiterhin deinen eigenen Prozess brauchst.

• Eine Quelle der Wahrheit. Jedes Diagramm ist ein einzelnes Dokument in deinem Workspace, mit Autosave und Revisions-Snapshots. Free behält die letzten 5 Revisionen; Pro bewahrt die Revisionshistorie ein Jahr lang auf, Enterprise ohne Limit.
• Verlinken statt kopieren. Jeder Plan hat öffentliche Share-Links (auf Free mit Branding). Auf Pro und Enterprise kannst du ein Diagramm per iframe in deine Doku-Site einbetten, sodass die Seite die aktuelle Version zeigt statt eines Screenshots, der langsam veraltet.
• Historie im Repo. Exportiere das Diagramm als strukturiertes JSON und committe es neben den Code oder deine ADRs. So bekommst du Git-Historie und einen Review-Schritt für Diagrammänderungen, zusätzlich zu den Revisionen in der App. Der Export ist ein manueller Schritt, also mach ihn zum Teil deiner PR-Routine.
• Notizen auf dem Canvas. Markdown-Nodes liegen direkt auf dem Canvas. Owner, Prüfdatum, ADR-Links und eine kurze Legende stehen so im Diagramm statt in einem separaten Dokument.
• Der richtige Detailgrad. Das C4-Model-Pack enthält die Nodes Person, Software System, Container, Component und Database sowie Boundaries. Nodes sind vollwertige Nodes mit Ports, und du verbindest sie über ihre Ports. Halte Context- und Container-Sicht als getrennte Diagramme.

Ein konkretes Setup für ein System:

1. Leg zwei Diagramme an: „Payments: Context“ und „Payments: Containers“.
2. Füge oben links einen Markdown-Node mit Owner, Prüfdatum und Links zu den zugehörigen ADRs hinzu.
3. Auf Pro bettest du die Container-Sicht in die Doku-Seite des Service ein. Auf Free nutzt du den Share-Link.
4. Wenn ein PR die Architektur ändert, aktualisierst du das Diagramm (oder lässt den Coding-Agenten, der am PR arbeitet, das über den MCP-Server von Archboard erledigen), exportierst das JSON und committest es im selben PR nach docs/architecture/.
5. Trag beide Diagramme in deine Index-Seite ein.

Den vollen Funktionsumfang zeigt die Produktübersicht, C4-spezifische Setups der C4-Anwendungsfall und was jeder Plan enthält die Seite Preise. Free gibt dir 3 Diagramme mit je 15 Diagramm-Nodes plus 150 Notizen, Texten, Stickern & Mindmap-Themen, um eine Kontextsicht für ein System auszuprobieren; Pro schaltet unbegrenzte Diagramme und Nodes frei, wenn du die ganze Plattform dokumentierst.

Checkliste für lebende Dokumentation

• Jedes Diagramm hat genau eine bearbeitbare Quelle
• Die Doku bettet das Live-Diagramm ein oder verlinkt es, ohne eingefügte Screenshots
• Jedes Diagramm hat einen benannten Owner, der im Diagramm steht
• Das PR-Template enthält eine Checkbox zur Architektur-Auswirkung
• Angenommene ADRs verlinken die Diagramme, die sie ändern
• Postmortems fragen: „Stimmt das Diagramm noch?“
• Owner prüfen ihre Diagramme quartalsweise und aktualisieren das Datum
• Diagramme sind nach C4-Ebenen getrennt, kein riesiges Gesamtbild
• Ein Diagramm-Index listet Ebene, Owner, Prüfdatum und ADRs
• Die Diagrammquelle (zum Beispiel ein JSON-Export) ist neben dem Code committet

FAQ

Wie viele Diagramme sollte ein System haben? Fang mit einer Context- und einer Container-Sicht an. Ergänze Component-Sichten nur für die Teile, nach denen regelmäßig gefragt wird. Wenige korrekte Diagramme sind besser als viele veraltete.

Sollen Diagramme im Repo oder in einem Tool liegen? Bearbeite sie an einem Ort und halte die Historie dort, wo dein Team Änderungen ohnehin reviewt. Mit Archboard bearbeitest du auf dem Canvas und committest den JSON-Export nach Git.

Kostenlos starten — ein Seat, keine Kreditkarte