45379a2639
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
2.1 KiB
2.1 KiB
GWÖ-Antragsprüfer — Dokumentation
Diese Dokumentation folgt dem Diátaxis-Framework und ist nach Funktion (nicht nach Themen) organisiert. Drift-immun durch klare Trennung: Reference wird aus dem Code generiert, ADRs sind immutable, Tutorials/How-to sind manuell gepflegt aber knapp.
Struktur
docs/
├── README.md ← du bist hier
├── adr/ Architecture Decision Records (immutable)
│ ├── README.md ADR-Index + Workflow
│ ├── template.md Template für neue ADRs
│ └── NNNN-titel.md Eine Datei pro Entscheidung
└── archive/ Historische Snapshots, nicht autoritativ
Geplant für später (siehe Issue #62):
docs/
├── reference/ ← mkdocs autodoc-Output (nicht eingecheckt)
├── tutorials/ ← Erst-Schritt-Anleitungen
├── how-to/ ← Aufgaben-orientiert, "wie deploye ich"
└── explanation/ ← Hintergründe, Konzepte
Nicht hier dokumentiert (bewusst)
| Was | Wo |
|---|---|
| API-Reference (Endpoints, Models, Schemas) | Auto-generiert aus FastAPI/Pydantic, nicht in docs/ einchecken |
| Code-Reference (Klassen, Funktionen) | mkdocstrings aus den Docstrings (geplant Phase 2) |
| Aktueller Projekt-Stand / Issues | Gitea Issues — repo.toppyr.de/tobias/gwoe-antragspruefer/issues |
| Onboarding für KI-assisted Coder | CLAUDE.md im Repo-Root |
| Live-System-Status | https://gwoe.toppyr.de/auswertungen (dynamisches Dashboard) |
| Memory der KI-Sessions | ~/.claude/projects/<projekt>/memory/ (privat) |
Gegen Drift
- ADRs sind immutable: nie überschreiben, sondern bei Änderung mit einem neuen ADR superseden, der den alten in seinem Header referenziert.
- Reference wird aus dem Code generiert, nie von Hand gepflegt.
docs/archive/enthält historische Status-Files. Werden gelesen aber nicht aktualisiert. Wenn etwas davon noch wahr ist, gehört es in einen ADR oder in die generierte Reference, nicht in einen neuen Status-Snapshot.