tobias/gwoe-antragspruefer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
8bd311dbc8
gwoe-antragspruefer/docs/adr/README.md
Dotty Dotter 45379a2639 #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

1.9 KiB
Raw Blame History

Architecture Decision Records (ADRs)

ADRs dokumentieren signifikante Architektur-Entscheidungen mit Kontext, Optionen und Konsequenzen. Format inspiriert von Michael Nygard.

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 LLM-Citations server-seitig binden statt prompt-seitig accepted 2026-04-10
0002 Adapter-Pattern mit ParlamentAdapter-Basisklasse + Registry accepted 2026-04-10
0003 Sub-D Property-Verification: Zitate als Substring der zitierten PDF-Seite accepted 2026-04-10
0004 Docker Compose Deploy mit DB-/Reports-Volume und SN-XML-Sonderpfad accepted 2026-04-10

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.