Dokumentation
1. Menschliche Dokumentation in Markdown
Die menschliche Dokumentation sollte in Markdown liegen. Beispiele:
docs/architecture/overview.md
docs/architecture/context.md
docs/architecture/containers.md
docs/architecture/runtime.md
docs/architecture/deployment.md
docs/adr/*.md
docs/quality/quality-goals.md
docs/quality/known-risks.md
docs/glossary/glossary.md
Diese Dokumente sind für Menschen gedacht. Sie sollen schnell verständlich machen, was ein Service tut, warum er existiert und wie er mit anderen Systemen zusammenhängt.
Wichtig: Diese Dokumente dürfen von KI erstellt oder aktualisiert werden, müssen aber durch Menschen reviewt und durch CI-Regeln validiert werden.
→ Markdown-Vorlagen siehe Vorlagen und CLI.
2. C4-Diagramme
AURA verwendet C4 als Standardmodell für Architekturvisualisierung.
C4 besteht im Kern aus mehreren Ebenen:
C1: System Context
C2: Container
C3: Component
C4: Code
Für AURA sind vor allem C1 und C2 wichtig. C3 ist bei komplexeren Services sinnvoll. C4 sollte nur selten oder automatisiert genutzt werden.
Minimalanforderung pro relevantem System oder Service:
C1: System Context
C2: Container
optional C3: Component
Ein gutes C4-Diagramm beantwortet schnell:
- Wo bin ich?
- Was gehört dazu?
- Was gehört nicht dazu?
- Wer spricht mit wem?
- Über welche Schnittstelle?
- Warum ist das so?
3. Diagrammquellen statt Screenshots
Diagramme sollten nicht nur als Bilder gespeichert werden. Die Quelle des Diagramms sollte versioniert im Repository liegen.
Mögliche Formate:
Mermaid
PlantUML
Structurizr DSL
C4-PlantUML
Beispiele:
docs/architecture/context.mmd
docs/architecture/container.mmd
docs/architecture/workspace.dsl
docs/architecture/container.puml
Die zentrale AURA-Webseite kann daraus gerenderte Diagramme anzeigen. Die prüfbare Wahrheit bleibt aber die textuelle Diagrammquelle im Repository.
4. Mermaid, PlantUML oder Structurizr?
Für den Start ist Mermaid attraktiv, weil es einfach in Markdown eingebettet werden kann. Für komplexere Landschaften mit vielen Services kann ein modellbasierter Ansatz besser sein.
Mögliche Stufen:
Einfach:
Markdown + Mermaid
Robuster:
Markdown + Mermaid oder PlantUML + feste Regeln
Architekturmodelliert:
Structurizr DSL / C4-Modell / Service Graph
Empfehlung:
- Für einzelne Repo-Diagramme kann Mermaid reichen.
- Für organisationsweite Architektur- und Abhängigkeitsmodelle sollte AURA langfristig ein strukturiertes Modell pflegen.
- Structurizr DSL oder ein eigener normalisierter Service Graph können dafür sinnvoll sein.
5. ADRs — Architecture Decision Records
C4 zeigt, wie die Architektur aussieht. ADRs erklären, warum sie so ist.
Jedes Repository sollte relevante Architekturentscheidungen versioniert speichern:
docs/adr/0001-use-postgres.md
docs/adr/0002-introduce-event-driven-billing.md
docs/adr/0003-remove-direct-user-service-dependency.md
Ein ADR sollte mindestens enthalten:
Titel
Status
Kontext
Entscheidung
Alternativen
Konsequenzen
Links zu Jira, PRs, Diagrammen und Code
Beispiel-ADR
# ADR-0003: Remove direct dependency to user-service
## Status
Accepted
## Context
The billing-service currently calls user-service synchronously during invoice creation.
## Decision
We will replace the synchronous call with user-profile events.
## Consequences
- billing-service becomes less coupled to user-service
- eventual consistency must be handled
- additional event processing is required
## Related
- Jira: PAY-123
- PR: #847
- Services: billing-service, user-service
→ ADR-Template siehe Vorlagen und CLI.
6. Qualitäts- und Risikodokumentation
Neben Architekturstruktur und Entscheidungen braucht AURA Informationen zu Qualität und Risiken.
Beispiele:
docs/quality/quality-goals.md
docs/quality/known-risks.md
docs/quality/technical-debt.md
Diese Dokumente sollten beantworten:
- Welche Qualitätsziele sind besonders wichtig?
- Ist Performance kritisch?
- Ist Ausfallsicherheit kritisch?
- Gibt es regulatorische Anforderungen?
- Welche Risiken sind bekannt?
- Welche technischen Schulden existieren?
- Welche Teile sind schwer wartbar?
- Welche Teile wurden von KI generiert und noch nicht ausreichend geprüft?
7. Trust Status pro Dokument
Jede Service-Seite und jedes Dokument in AURA sollte einen sichtbaren Vertrauensstatus haben.
Mögliche Status:
validated
outdated
missing owner
missing C4
missing ADR
documentation drift detected
AI-generated, not human-approved
last reviewed over threshold
source unavailable
Beispiel:
documentation_status: validated
last_human_review: 2026-05-01
last_ingested: 2026-05-09
source_commit: a81f3c2
ai_generated: true
human_approved: true
drift_detected: false
Das ist wichtig, damit Menschen und KI der Dokumentation nicht blind vertrauen.
Weiterlesen
- Nächste Seite: PR Check — wie AURA Doku-Pflicht durchsetzt
- Vorlagen und CLI — vollständige Markdown- und ADR-Templates
- Governance und Drift — Drift-Erkennung und Trust-Bewertung