Orchestrator/bahn/O2C-Harness/documentation.md

Dokumentation (Arc42 docs-as-code)

Referenz: arc42.org, Ralf D. Müller docs-as-code Ansatz.

Verzeichnisstruktur

docs/
├── README.md              ← Übersicht + Links zu allen Kapiteln
├── arc42/
│   ├── README.md          ← Inhaltsverzeichnis der Arc42-Doku
│   ├── 01-introduction-and-goals.md
│   ├── 02-constraints.md
│   ├── 03-context-and-scope.md
│   ├── 04-solution-strategy.md
│   ├── 05-building-block-view.md
│   ├── 06-runtime-view.md
│   ├── 07-deployment-view.md
│   ├── 08-crosscutting-concepts.md
│   ├── 09-architecture-decisions.md
│   ├── 10-quality.md
│   ├── 11-risks-and-technical-debt.md
│   └── 12-glossary.md
└── session-notes.md

README.md in jedem Verzeichnis

Root README.md

Muss auf die Doku verlinken:

## Dokumentation

- [Arc42 Architekturdokumentation](docs/arc42/README.md)
- [Session Notes](docs/session-notes.md)

docs/README.md

# Dokumentation

- [Arc42 Architektur](arc42/README.md)
- [Session Notes](session-notes.md)

docs/arc42/README.md

# Arc42 Architekturdokumentation

| Kapitel | Inhalt |
|---------|--------|
| [01 - Einführung und Ziele](01-introduction-and-goals.md) | Aufgabenstellung, Qualitätsziele, Stakeholder |
| [02 - Randbedingungen](02-constraints.md) | Technische, organisatorische Constraints |
| [03 - Kontextabgrenzung](03-context-and-scope.md) | Systemkontext, externe Schnittstellen |
| [04 - Lösungsstrategie](04-solution-strategy.md) | Fundamentale Entscheidungen |
| [05 - Bausteinsicht](05-building-block-view.md) | Statische Zerlegung |
| [06 - Laufzeitsicht](06-runtime-view.md) | Wichtige Abläufe |
| [07 - Verteilungssicht](07-deployment-view.md) | Infrastruktur, Deployment |
| [08 - Querschnittliche Konzepte](08-crosscutting-concepts.md) | Übergreifende Patterns |
| [09 - Architekturentscheidungen](09-architecture-decisions.md) | ADRs |
| [10 - Qualitätsanforderungen](10-quality.md) | Qualitätsbaum, Szenarien |
| [11 - Risiken und technische Schulden](11-risks-and-technical-debt.md) | Bekannte Probleme |
| [12 - Glossar](12-glossary.md) | Begriffe |

Kapitel-Inhalte (Mindestanforderung)

01 - Einführung und Ziele

• Aufgabenstellung (was macht das System)
• Qualitätsziele (Top 3)
• Stakeholder-Tabelle

03 - Kontextabgrenzung

• C4 Context-Diagramm als Mermaid:

C4Context
    title System Context
    Person(user, "Benutzer")
    System(system, "Mein Service", "Beschreibung")
    System_Ext(ext, "Externes System")
    Rel(user, system, "Nutzt")
    Rel(system, ext, "Ruft auf")

05 - Bausteinsicht

• Komponenten-Diagramm (Mermaid)
• Beschreibung der Hauptbausteine

06 - Laufzeitsicht

• Sequenzdiagramm für Hauptflow (Mermaid)

07 - Verteilungssicht

• Deployment-Diagramm (Mermaid) wenn deployed

09 - Architekturentscheidungen

• Mindestens 1 ADR im Nygard-Format:

## ADR-1: Titel

### Status
Accepted

### Context
Problem/Situation.

### Decision
Entscheidung.

### Consequences
Auswirkungen (positiv + negativ).

11 - Risiken

• Bekannte Risiken und technische Schulden auflisten

12 - Glossar

• Fachbegriffe des Projekts erklären

Kontextabhängig

Arc42-Doku anlegen bei:

• Services/APIs mit Deployment → Vollständig (alle 12 Kapitel)
• Libraries → Minimal (01, 03, 05, 09)
• Doku-Repos → KEINE Arc42 nötig