Dieser Post setzt den zehnten Teil fort. Architekturentscheidungen landen oft in Markdown-Dateien irgendwo im Repository — und niemand weiß mehr, warum das Modell so aussieht wie es aussieht. Bausteinsicht löst das: ADRs lassen sich direkt mit Elementen und Beziehungen im Modell verknüpfen.
Was sind ADRs?
Architecture Decision Records (ADRs) dokumentieren eine Architekturentscheidung mit Kontext, Optionen und Begründung. Das Format ist bewusst leichtgewichtig — typischerweise eine kurze Markdown-Datei pro Entscheidung.
Das Problem: ohne direkte Verlinkung sind ADRs vom Modell isoliert. Man sieht im Diagramm dass ein Element existiert, aber nicht warum es so gestaltet wurde.
ADRs in der Specification definieren
ADRs gehören in specification.decisions in architecture.jsonc:
{
"specification": {
"decisions": [
{
"id": "ADR-001",
"title": "Monolith → Microservices Migration",
"status": "active",
"date": "2025-03-15",
"file": "docs/decisions/ADR-001-microservices.md"
},
{
"id": "ADR-002",
"title": "PostgreSQL als primäre Datenbank",
"status": "active",
"date": "2025-03-20",
"file": "docs/decisions/ADR-002-postgresql.md"
},
{
"id": "ADR-003",
"title": "Auth via JWT statt Sessions",
"status": "active",
"date": "2025-04-01",
"file": "docs/decisions/ADR-003-jwt-auth.md"
},
{
"id": "ADR-004",
"title": "REST API Gateway Pattern",
"status": "superseded",
"date": "2025-02-10",
"file": "docs/decisions/ADR-004-api-gateway.md"
}
]
}
}Mögliche Status-Werte:
| Status | Bedeutung |
|---|---|
| Entscheidung vorgeschlagen, noch nicht final |
| Aktuelle, gültige Entscheidung |
| Veraltet, aber noch nicht abgelöst |
| Durch eine neuere ADR ersetzt |
Das file-Feld zeigt auf die eigentliche ADR-Datei im Repository.
Bausteinsicht öffnet sie nicht automatisch — es ist ein Zeiger für Entwickler und Werkzeuge.
ADRs an Elemente verknüpfen
Jedes Element kann ein decisions-Array mit ADR-IDs enthalten:
{
"model": {
"authservice": {
"kind": "service",
"title": "Auth Service",
"technology": "Go",
"decisions": ["ADR-003"]
},
"shop": {
"kind": "system",
"title": "Shop System",
"decisions": ["ADR-001"],
"children": {
"db": {
"kind": "database",
"title": "Shop DB",
"technology": "PostgreSQL",
"decisions": ["ADR-002"]
}
}
}
}
}ADRs an Beziehungen verknüpfen
Auch Beziehungen können ADRs referenzieren — etwa wenn eine Entscheidung die Kommunikationsarchitektur betrifft:
{
"relationships": [
{
"from": "shop.frontend",
"to": "authservice",
"label": "authenticate",
"decisions": ["ADR-003"]
}
]
}bausteinsicht adr list
Alle ADRs im Modell anzeigen:
bausteinsicht adr listAusgabe:
Decisions (4): ────────────────────────────────────────── ADR-001 ✓ Monolith → Microservices Migration Date: 2025-03-15 File: docs/decisions/ADR-001-microservices.md ADR-002 ✓ PostgreSQL als primäre Datenbank Date: 2025-03-20 File: docs/decisions/ADR-002-postgresql.md ADR-003 ✓ Auth via JWT statt Sessions Date: 2025-04-01 File: docs/decisions/ADR-003-jwt-auth.md ADR-004 ✗ REST API Gateway Pattern Date: 2025-02-10 File: docs/decisions/ADR-004-api-gateway.md
Status-Icons: ✓ aktiv, ◯ proposed, ⚠ deprecated, ✗ superseded.
ADRs für ein bestimmtes Element
bausteinsicht adr list --element shop.dbZeigt nur ADRs die direkt mit shop.db verknüpft sind.
JSON-Ausgabe
bausteinsicht adr list --format json[
{
"id": "ADR-001",
"title": "Monolith → Microservices Migration",
"status": "active",
"date": "2025-03-15",
"file": "docs/decisions/ADR-001-microservices.md"
}
]bausteinsicht adr show
Details zu einer einzelnen ADR — inklusive welche Elemente und Beziehungen sie referenzieren:
bausteinsicht adr show ADR-003Ausgabe:
ADR: ADR-003 ✓ ────────────────────────────────────────── Title: Auth via JWT statt Sessions Status: active Date: 2025-04-01 File: docs/decisions/ADR-003-jwt-auth.md Referenced by: - element: authservice - relationship: shop.frontend → authservice
Das zeigt auf einen Blick: diese Entscheidung betrifft den Auth Service und die Verbindung vom Frontend zum Auth Service.
Typischer ADR-Workflow
Neue Entscheidung dokumentieren
ADR-Datei schreiben (z.B.
docs/decisions/ADR-005-event-sourcing.md)Eintrag in
specification.decisionshinzufügenBetroffene Elemente/Beziehungen mit
"decisions": ["ADR-005"]verknüpfenbausteinsicht validate— stellt sicher dass alle referenzierten ADR-IDs existieren
bausteinsicht validate
# ✓ All ADR references are validValidate prüft dass alle ADR-IDs in decisions-Arrays auch in specification.decisions definiert sind.
Entscheidung ablösen
Wenn ADR-004 durch ADR-007 abgelöst wird:
{
"id": "ADR-004",
"title": "REST API Gateway Pattern",
"status": "superseded",
"date": "2025-02-10",
"file": "docs/decisions/ADR-004-api-gateway.md"
},
{
"id": "ADR-007",
"title": "GraphQL Federation statt REST Gateway",
"status": "active",
"date": "2025-07-01",
"file": "docs/decisions/ADR-007-graphql-federation.md"
}ADR-004 bleibt im Modell — der Status superseded zeigt dass sie nicht mehr gilt.
So bleibt der Entscheidungsverlauf nachvollziehbar.
Warum direkt im Modell statt in separaten Werkzeugen?
ADR-Werkzeuge wie adr-tools oder Log4brains verwalten ADRs gut — aber sie wissen nichts über das Architekturmodell.
Die Verknüpfung in Bausteinsicht bringt beides zusammen:
| Bausteinsicht speichert nur Metadaten (ID, Titel, Status, Datum, Pfad) — nicht den ADR-Inhalt selbst. Die eigentlichen Dateien liegen weiterhin im Repository, Bausteinsicht verweist nur darauf. |
Beispiel-Modell
Das Beispiel für diesen Teil (Elemente und Beziehungen mit decisions-Referenzen) liegt unter teil_11.jsonc.
So sieht das Ergebnis in draw.io aus (bausteinsicht sync):
Das draw.io-File dafür findest du hier: teil_11.drawio
Generierte PNG-Dateien via bausteinsicht export --image-format png:
Generierte PlantUML-Diagramme via bausteinsicht export-diagram:
Was als nächstes kommt
Teil 12: Overlay & Heatmap — Metriken wie Error-Rate oder Coverage auf Architekturdiagramme legen
Teil 13: Graph-Analyse — Zyklen und Abhängigkeitsmuster im Modellgraphen aufdecken
Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org