#62 Phase 1+3: ADRs + Doku-Struktur in webapp/docs/
Architektur-Entscheidung aus Issue #62: Diátaxis-Framework für Doku-
Pflege ohne Drift. Pflege im Repo, ADRs immutable, Stale-Snapshots
explizit als Archiv markiert.
Phase 1 — Architecture Decision Records:
- docs/README.md — Diátaxis-Index, Erklärung was wo dokumentiert wird
- docs/adr/README.md — ADR-Workflow + Index
- docs/adr/template.md — Vorlage für neue ADRs
- docs/adr/0001-llm-citation-binding.md — Issue #60 Doppel-Fix-Story
(A=ENUM-Anker, B=server-seitige Rekonstruktion, warum Option C verworfen)
- docs/adr/0002-adapter-architecture.md — ParlamentAdapter-Basisklasse
+ Registry, Klassen vs. Strategy vs. Modul-pro-Adapter
- docs/adr/0003-citation-property-tests.md — Sub-D Strategie, warum
Property-Test gegen echte PDFs statt Schema-Tests oder Online-Verify
- docs/adr/0004-deployment-workflow.md — Docker-Compose + Volumes
Standard-Workflow + SN-XML-Sonderpfad + Container-UTC-Gotcha
Phase 3 — Stale Doku archiviert:
- DOKUMENTATION.md (24.März, Skript-Architektur vor Webapp-Migrate)
→ docs/archive/DOKUMENTATION-2026-03-24.md
- STATUS-2026-03-28.md (Tagesstand-Snapshot)
→ docs/archive/STATUS-2026-03-28.md
- README.md (28.März, listet nur NRW-Adapter, vor 16 weiteren BLs)
→ docs/archive/README-2026-03-28.md
- docs/archive/README.md erklärt warum die Files da sind und warum
niemand sie überschreiben oder ersetzen sollte
Plus neue Top-Level-README.md im Project-Root (außerhalb git, da
project-root kein Repo ist) als Folder-Index für den User.
CLAUDE.md ergänzt um Doku-Sektion mit Verweis auf docs/adr/.
Phase 2 (mkdocs Setup) folgt separat — braucht eine Docker-Image-
Erweiterung, die ich nicht autark einrollen will ohne Decision.
Tests: 194/194 grün (keine Code-Änderung).
Refs: #62
2026-04-10 01:38:03 +02:00
|
|
|
# Architecture Decision Records (ADRs)
|
|
|
|
|
|
|
|
|
|
ADRs dokumentieren signifikante Architektur-Entscheidungen mit Kontext, Optionen
|
|
|
|
|
und Konsequenzen. Format inspiriert von [Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).
|
|
|
|
|
|
|
|
|
|
## Workflow
|
|
|
|
|
|
|
|
|
|
1. Neue Entscheidung steht an → Kopie von `template.md` mit nächster freier
|
|
|
|
|
Nummer (`NNNN-kebap-titel.md`).
|
|
|
|
|
2. Status `proposed` → diskutiert in Issue/PR → bei Akzeptanz auf `accepted`.
|
|
|
|
|
3. **Niemals editieren nach `accepted`.** Wenn eine Entscheidung sich ändert,
|
|
|
|
|
neuer ADR mit `Supersedes: NNNN-…` im Header und der alte ADR bekommt
|
|
|
|
|
`Superseded by: MMMM-…`.
|
|
|
|
|
4. Status `deprecated` für Entscheidungen, die ohne Nachfolger auslaufen.
|
|
|
|
|
|
|
|
|
|
## Index
|
|
|
|
|
|
|
|
|
|
| ID | Titel | Status | Datum |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| [0001](0001-llm-citation-binding.md) | LLM-Citations server-seitig binden statt prompt-seitig | accepted | 2026-04-10 |
|
|
|
|
|
| [0002](0002-adapter-architecture.md) | Adapter-Pattern mit ParlamentAdapter-Basisklasse + Registry | accepted | 2026-04-10 |
|
|
|
|
|
| [0003](0003-citation-property-tests.md) | Sub-D Property-Verification: Zitate als Substring der zitierten PDF-Seite | accepted | 2026-04-10 |
|
|
|
|
|
| [0004](0004-deployment-workflow.md) | Docker Compose Deploy mit DB-/Reports-Volume und SN-XML-Sonderpfad | accepted | 2026-04-10 |
|
2026-04-10 16:33:52 +02:00
|
|
|
| [0005](0005-keycloak-sso-with-dev-bypass.md) | Keycloak SSO mit Dev-Bypass für Read/Write-Trennung | accepted | 2026-04-10 |
|
#62 Phase 1+3: ADRs + Doku-Struktur in webapp/docs/
Architektur-Entscheidung aus Issue #62: Diátaxis-Framework für Doku-
Pflege ohne Drift. Pflege im Repo, ADRs immutable, Stale-Snapshots
explizit als Archiv markiert.
Phase 1 — Architecture Decision Records:
- docs/README.md — Diátaxis-Index, Erklärung was wo dokumentiert wird
- docs/adr/README.md — ADR-Workflow + Index
- docs/adr/template.md — Vorlage für neue ADRs
- docs/adr/0001-llm-citation-binding.md — Issue #60 Doppel-Fix-Story
(A=ENUM-Anker, B=server-seitige Rekonstruktion, warum Option C verworfen)
- docs/adr/0002-adapter-architecture.md — ParlamentAdapter-Basisklasse
+ Registry, Klassen vs. Strategy vs. Modul-pro-Adapter
- docs/adr/0003-citation-property-tests.md — Sub-D Strategie, warum
Property-Test gegen echte PDFs statt Schema-Tests oder Online-Verify
- docs/adr/0004-deployment-workflow.md — Docker-Compose + Volumes
Standard-Workflow + SN-XML-Sonderpfad + Container-UTC-Gotcha
Phase 3 — Stale Doku archiviert:
- DOKUMENTATION.md (24.März, Skript-Architektur vor Webapp-Migrate)
→ docs/archive/DOKUMENTATION-2026-03-24.md
- STATUS-2026-03-28.md (Tagesstand-Snapshot)
→ docs/archive/STATUS-2026-03-28.md
- README.md (28.März, listet nur NRW-Adapter, vor 16 weiteren BLs)
→ docs/archive/README-2026-03-28.md
- docs/archive/README.md erklärt warum die Files da sind und warum
niemand sie überschreiben oder ersetzen sollte
Plus neue Top-Level-README.md im Project-Root (außerhalb git, da
project-root kein Repo ist) als Folder-Index für den User.
CLAUDE.md ergänzt um Doku-Sektion mit Verweis auf docs/adr/.
Phase 2 (mkdocs Setup) folgt separat — braucht eine Docker-Image-
Erweiterung, die ich nicht autark einrollen will ohne Decision.
Tests: 194/194 grün (keine Code-Änderung).
Refs: #62
2026-04-10 01:38:03 +02:00
|
|
|
|
|
|
|
|
## Wann ADR, wann nicht
|
|
|
|
|
|
|
|
|
|
| ADR-würdig | nicht ADR-würdig |
|
|
|
|
|
|---|---|
|
|
|
|
|
| Wahl zwischen mehreren plausiblen Architekturen mit Trade-offs | Bug-Fix |
|
|
|
|
|
| Strukturelle Konsequenzen für mehrere Module | Refactoring innerhalb eines Moduls |
|
|
|
|
|
| Reverse-Engineering-Findings die andere Adapter beeinflussen | Stiländerungen, Linting-Konventionen |
|
|
|
|
|
| Neue externe Abhängigkeiten oder APIs | Dependency-Bumps ohne API-Änderung |
|
|
|
|
|
| Workflow-Konventionen die mehrere Sessions überdauern müssen | Tagesgeschäft, Issue-Tracking |
|
|
|
|
|
|
|
|
|
|
Faustregel: Wenn ein neuer Kollege (oder eine neue Session) die Entscheidung
|
|
|
|
|
sonst rückgängig machen würde, gehört sie in einen ADR.
|