Was vorher fertig sein muss
Eine Liste der konkreten Leser der Doku (Architekten, neue Teammitglieder, Auditoren, Ops) mit ihren Informationsbedarfen liegt vor.
Wichtige Architekturentscheidungen sind als ADRs dokumentiert oder werden parallel erfasst, sodass Kapitel 9 (Entscheidungen) auf sie verlinken kann.
Was vor Start vorliegen muss
arc42-Template (Markdown-Variante von arc42/arc42-template auf GitHub); Diagramm-Tool (PlantUML, Structurizr, draw.io); Repo-Verzeichnis `docs/architecture/`; Glossar-Datei; Links auf ADR-Verzeichnis und ggf. C4-Diagramme.
Ein Hauptverfasser (oft Architekt oder Tech Lead) als Owner; ein bis drei Reviewer aus Engineering und Ops; optional Stakeholder aus Business für Kapitel 1 (Ziele).
Aktuelle System-Übersicht; Liste der externen Schnittstellen; bekannte Qualitätsziele (möglichst aus Quality Attribute Workshop); Constraints (regulatorisch, technisch, organisatorisch); existierende Diagramme.
1-2 Tage initial, danach Pflege in 1-2 h pro Sprint
Template-Repository klonen, in `docs/architecture/` als Markdown-Struktur ablegen. Kapitel 1-12 als eigene Dateien oder eine zusammenhängende. Konvention für Diagrammeinbindung festlegen (z. B. PlantUML im Repo, gerendert beim Build).
Die eine Frage, die diese Methode beantwortet
Welche Architektur-Entscheidungen, Strukturen und Qualitätsmerkmale braucht der Leser, um das System verstehen, betreiben und weiterentwickeln zu können?
Marker: Sektion
| Schritt | Dauer | Aktion | Hinweis |
|---|---|---|---|
1Kapitel 1-2: Einführung, Ziele, Constraints | 2-3 h | Aufgabenstellung in 5-10 Sätzen. Drei bis fünf Qualitätsziele in priorisierter Reihenfolge. Stakeholder-Tabelle mit Informationsbedarf. Constraints (technisch, organisatorisch, konventionell). | Qualitätsziele müssen priorisiert sein. Wer alle Quality Attributes als „wichtig“ markiert, hat keine Entscheidungsgrundlage und das Dokument wird beliebig. |
2Kapitel 3-4: Kontext und Lösungsstrategie | 3-4 h | Business Context und Technical Context als Diagramm plus Tabelle. Lösungsstrategie (Architekturansatz, Top-Level-Entscheidungen, Frameworks) als 1-2-seitige Zusammenfassung. | Kapitel 4 ist KEIN Detail-Design, sondern die Kurz-Antwort auf „wie ist das System gebaut“. Mehr als 2 Seiten ist zu viel, dann gehört es in Kapitel 5. |
3Kapitel 5: Bausteinsicht | 3-5 h | Whitebox-Sicht in 2-3 Ebenen (C4-Container, C4-Component). Pro Baustein: Verantwortlichkeit, Schnittstellen, Erfüllte Anforderungen. Keine Code-Klassen. | Nicht jeder Baustein braucht eine Whitebox. Nur die mit Komplexität oder Risiko. Sonst explodiert das Dokument und niemand liest weiter. |
4Kapitel 6-7: Laufzeitsicht und Verteilungssicht | 3-4 h | Laufzeit: 3-5 wichtige Szenarien als Sequenzdiagramme. Verteilung: Hardware/Cloud-Topologie mit Knoten, Netzwerken, Deployment-Einheiten. | Szenarien auswählen, die Architektur-Entscheidungen sichtbar machen (Failover, Skalierung, kritische Pfade). Happy-Path-Sequenz ist Beiwerk. |
5Kapitel 8-9: Querschnitt und Entscheidungen | 2-3 h | Querschnittliche Konzepte (Sicherheit, Logging, Fehlerbehandlung, Persistenz). Architekturentscheidungen als Liste mit ADR-Links und kurzer Begründung. | Konzepte konkret, nicht generisch. „Logging via ELK mit Trace-ID-Korrelation“ schlägt „Logging ist wichtig“. |
6Kapitel 10-12: Qualität, Risiken, Glossar | 2-3 h | Qualitätsszenarien (idealerweise aus QAW) tabellarisch. Technische Risiken und Schulden mit Owner und Eskalationsstand. Glossar mit Domain- und Tech-Begriffen. | Risiken offen benennen. Eine arc42-Doku ohne Risiken-Kapitel ist Marketing-Material, kein Architekturdokument. |
Was am Ende rauskommt
Markdown-Verzeichnis unter `docs/architecture/` mit 12 Kapitel-Dateien, eingebetteten Diagrammen (PlantUML oder rendered SVG), Verlinkung zu ADRs, Glossar und Test-Plänen. Im CI gerendert und als HTML deploybar.
Doku versioniert im selben Repo wie der Code. Änderungen via Pull Request mit Architektur-Reviewer. Releases der Doku gekoppelt an System-Releases (Tag), sodass jede Code-Version eine passende Doku hat.
Kompakte Arbeitsvorlage für arc42 mit Kontext, Input, Ergebnisartefakten und nächstem Schritt.
# arc42 Arbeitsvorlage
## Ziel
Pragmatisches Template für strukturierte, lebendige Softwarearchitektur-Dokumentation.
## Kontext
Wann und wofür nutzen wir diese Methode?
## Input
Welche Daten, Beobachtungen, Entscheidungen oder Materialien liegen vor?
## Durchführung
Kurze Notizen entlang des Run Sheets.
## Ergebnisartefakte
- Architecture Document:
- Context View:
- Runtime View:
- Deployment View:
## Annahmen und offene Fragen
- ...
## Entscheidung / Nächster Schritt
Owner, Datum und Erfolgssignal.Konkret gefülltes Szenario
## arc42 — Order Fulfillment Platform (v3.2, Stand 2026-05-18)
### 1. Einführung und Ziele
Verarbeitet Bestellungen von Web und Mobile, vom Eingang bis zur Auslieferung an externe Carrier. Top-3-Qualitätsziele:
1. Verfügbarkeit (99,95% gemessen monatlich)
2. Verarbeitungslatenz (P95 unter 800 ms vom Order-Submit bis zur Bestätigung)
3. Audit-Fähigkeit (jede Statusänderung lückenlos nachverfolgbar für 7 Jahre)
### 4. Lösungsstrategie
Event-driven über Kafka. 8 Bounded Contexts als Microservices, Sprachen Java 21 und Kotlin. Persistenz Postgres pro Service. Deployment auf AWS EKS in eu-central-1 mit Multi-AZ.
### 9. Architekturentscheidungen (Auszug)
- ADR-0023: PostgreSQL statt MongoDB für Order-Service (Stand: accepted, 2025-11-12)
- ADR-0031: Outbox-Pattern für Eventual Consistency (accepted, 2026-02-03)
- ADR-0044: Kein Service Mesh, direktes mTLS (accepted, 2026-04-19)
### 11. Risiken und Schulden
- R-04: TaxService ist Single Point of Failure (Eskalation an CTO, Fix Q3/2026)
- R-09: Postgres-Cluster läuft auf v14, EOL 2026-11. Migration-Plan in Vorbereitung.Symptome erkennen, gegensteuern
Alle 12 Kapitel sind ausgefüllt, jedes 10+ Seiten lang. Niemand liest mehr als die Einleitung.
Kapitel weglassen, wenn nichts Substantielles drinsteht. Lieber 6 gute Kapitel als 12 leere. arc42 explizit als opt-in pro Kapitel verstehen.
PNG- oder JPG-Diagramme im Repo, ohne PlantUML/Structurizr-Source. Änderung erfordert Original-Tool.
Diagramme als Text-Source (PlantUML, Mermaid, Structurizr DSL) im Repo, beim Build gerendert. Sonst veraltern Bilder schnell und werden nicht aktualisiert.
Kapitel 1 listet „Verfügbarkeit“ und „Performance“ als Ziele, ohne messbare Definition.
Pro Qualitätsziel ein Szenario in Kapitel 10 mit Stimulus, Response und Measure. Sonst keine Bewertung möglich.
Letzte Änderung der arc42-Doku war vor 9 Monaten, das System hat seitdem 3 Releases.
Doku-Pflege in Definition of Done. Pro Sprint Doku-Update-Slot. Bei großen Releases Doku-Review als Acceptance-Kriterium.
Entscheidungs-Kapitel enthält narrative Absätze, keine Links auf ADRs.
Kapitel 9 wird zur Liste mit Titel und ADR-Link. Begründung steht im ADR, nicht in arc42. Sonst doppelte Wahrheit.
Done-Signale, in unter einer Minute prüfbar
Zum Steckbrief für Zweck, ähnliche Methoden und Quellen — oder direkt zur nächsten Methode im Katalog.