Doku-IA-Audit & Reorg-Plan — 2026-05-09¶
Status: Plan-Karte (kein File-Move, kein Inhalt-Edit) — Single-Source-of-Truth für die anstehende Doku-Reorganisation Erstellt: 2026-05-09 nach SaaS-Detail-Plan-Karte (
v1-0-0-saas-detail-plan.md) Schreib-Cap: 4h für die Plan-Karte selbst Folge-Karten: Reorg-1 (File-Move + nav), Reorg-2 (Konsolidierung + Lösch), Reorg-3 (Stub-Pages für Customer-Handbuch). Plus Karte B (Backlog-Inventur) und Karte C (Customer-Handbuch-Inhalt) — separat
Executive Summary¶
Die kora-Doku ist über 17+ Saga-Karten organisch gewachsen: 47 Markdown-Files (20.082 Zeilen) plus 3 Assets (.svg, .bpmn, .html) verteilt auf 8 nav-Sections. Inhaltlich ist die Doku inhaltlich solide (Architektur-Konzepte, Defense-in-Depth, Deployment-Runbooks, Saga-Lehren), aber strukturell organisch — die Sections (Konzepte / Operations / Deployment / Code-Reviews / Blocks / Releases / Sicherheit / Änderungen) folgen der Saga-Chronologie, nicht den Konsumenten-Zielgruppen.
Hauptbefund Lücken: Drei Zielgruppen-Cluster sind in kora-Doku strukturell leer, die in der parallelen AVS-Doku (44 Files) bereits als mature IA existieren:
- EndUser (Chatbot-Nutzer-Handbuch) — AVS hat 8 Pages in
docs/handbuch/*, kora hat 0 - Admin (Tenant-Verwaltungs-Handbuch) — AVS hat 15 Pages in
docs/betrieb/admin-handbuch/*, kora hat 0 - Developer (API + SDK + Webhooks) — AVS hat 5 Pages in
docs/entwicklung/*, kora hat 0
Diese Lücken sind das primäre Hindernis für externe Konsumenten (zukünftige Tenants, neue Entwickler, AVS-Stakeholder). Customer-Handbuch (Karte C) braucht eine IA-Struktur als Skelett — der vorliegende Plan liefert dieses Skelett mit Mapping-Tabelle für jeden der 47 existing Files plus Stub-Pages für die ~28 fehlenden Pages.
Kein Inhalt verloren, kein File destruktiv: Reorg ist git-mv-basiert mit Link-Update, keine inhaltlichen Deletions außer 4-5 explizit als deprecated klassifizierte Files. Die Saga-Spur (changelog, releases, code-reviews, action-plans) wird in einen eigenen audit-trail/-Cluster konsolidiert statt in den Hauptpfad zu mischen.
Aufwand-Bilanz für die 3 Reorg-Folge-Karten: ~6-9h Mechanik-Aufwand (File-Move + nav + Konsolidierung + Stub-Pages). Plus Customer-Handbuch-Inhalt (Karte C) ~30-50h für die 28 Stub-Pages, abhängig von Inhaltstiefe.
Phase 0 — Inventur¶
Phase 0.1 kora-Doku — vollständige File-Liste¶
47 .md-Files + 3 Assets (1 SVG, 1 BPMN, 1 HTML) = 50 Artefakte. Total: 20.082 Zeilen Markdown.
Verteilung nach existing nav-Section:
| Section | Files | Zeilen-Summe | Anteil |
|---|---|---|---|
konzepte/ |
5 | 2960 | 14.7 % |
security/ |
2 (+ 2 Assets) | 670 | 3.3 % |
operations/ |
9 (+ 1 Asset) | 1681 | 8.4 % |
deployment/ |
10 | 1610 | 8.0 % |
releases/ |
8 | 1136 | 5.7 % |
reviews/ |
5 | 867 | 4.3 % |
blocks/ |
1 | 124 | 0.6 % |
prozesse/ |
1 | 120 | 0.6 % |
Root-Pages (index, roadmap, changelog, offene-todos, cleanup-welle-discovery, drift-status) |
6 | 10.731 | 53.4 % |
Auffällig: mehr als die Hälfte des Doku-Volumens steckt in 6 Root-Pages, davon changelog.md allein 4818 Zeilen und roadmap.md 2511 Zeilen. Das sind die Hauptkandidaten für Konsolidierung+Slim (siehe Phase 2).
Phase 0.2 AVS-Doku Vergleich¶
Die AVS-Doku im selben Repo (docs/) hat 44 Files mit bereits mature IA-Struktur, gewachsen während der v0.x-Demo-Phase:
| AVS-Section | Files | Zweck |
|---|---|---|
archiv/ |
4 | Explizit als deprecated markiert |
betrieb/admin-handbuch/ |
15 | Admin-Handbuch für AVS-spezifische Operator-Aufgaben |
betrieb/ (root) |
3 | Deployment, LDAP, index |
diagnostics/ |
1 | Diagnose-Reference |
entwicklung/ |
5 | Developer-Doku (Conventions, Code-Review, Tooling, Projektplan) |
handbuch/ |
8 | End-User-Handbuch (Bedienung, FAQ, Sprachen, Support) |
roadmap/ |
1 | AVS-Roadmap-Index |
security-hardening/ |
4 | Action-Plan + Backlog |
| Root | 3 | index, audit, _handbuch-outline |
Pattern-Vorlage: betrieb/admin-handbuch/ (Analytics, Audit-Log, Dashboard, Dokumente, Einstellungen, Erste-Anmeldung, Evaluation, Feedback, Lizenz, Produkte, Rollen-und-Berechtigungen, Sessions, …) ist genau die Section, die in kora-Doku strukturell fehlt. AVS-Stand ist Customer-spezifisch, kora-Stand wäre generisch + Customer-Pattern-Reference.
Phase 0.3 Realitäts-Tabelle¶
| Item | Wert |
|---|---|
| Branch | platform/k-doku-ia-audit |
| HEAD | 0074b75 (SaaS-Detail-Plan-Merge) |
| kora-Doku Files Total | 47 .md + 3 Assets |
| kora-Doku Zeilen Total | 20.082 |
| AVS-Doku Files Total | 44 (Vergleich) |
| Saga-Spur-Files | 17 (changelog, offene-todos, roadmap-Mix, releases × 8, reviews × 5, blocks × 1, action-plan-via-AVS-Doku, cleanup-welle-discovery, drift-status) |
| Production-Ready-Files | ~25 (Architektur-Konzepte, Defense-in-Depth, Saga-Lehren, Deployment-Runbooks, Operations-References, Code-Review-Template) |
| Draft-Files | 1 (konzepte/index.md ist eher Übersichtskarte als Konzept-Page; technisch ok) |
| Deprecated-Kandidaten | 4-5 (deployment/mkdocs-container.md Legacy-Hinweis, operations/color-system-concepts/concept-b.md verworfen, bakeoff.html Bake-Off-Asset, möglicherweise cleanup-welle-discovery-2026-05-01.md und drift-status-2026-04-30.md — Zeitstempel-fixierte Discovery-Snapshots) |
| Erkennbare nav-Sections | 8 (Start, Roadmap, Konzepte, Prozesse, Operations, Code-Reviews, Blocks, Deployment, Sicherheit, Releases, Änderungen — laut mkdocs.yml) |
| Files NICHT in nav | 2 (cleanup-welle-discovery-2026-05-01.md, drift-status-2026-04-30.md — beim mkdocs-Strict-Build als orphan flagged) |
Stop-Bedingungen-Check:
- Files ≥ 40 ✅ (47 Files, im erwarteten Bereich)
- Deprecated > 5 ❌ (max 5 Kandidaten, kein eigener Lösch-Karten-Plan nötig — passt in Reorg-2)
- Mixed-Cluster > 10 ❌ (nur 2 echte Mixed-Files:
index.mdundroadmap.md)
Keine Stop-Bedingung getriggert. Phase 1 kann starten.
Phase 1 — Cluster + Reife + Lücken¶
Phase 1.1 Zielgruppen-Cluster¶
Pro File eine Zielgruppen-Klassifikation. Mehrfach-Zielgruppen sind als „Mixed" markiert.
Architect-Cluster (Architektur-Konzepte, interne Architekten)¶
| File | Zeilen | Reife |
|---|---|---|
konzepte/multitenancy-fundament.md |
1833 | Production (v5.3.4 konsolidiert) |
konzepte/v1-0-0-saas-detail-plan.md |
355 | Production (NEU 2026-05-09) |
konzepte/konnektor-roadmap.md |
340 | Production |
konzepte/knowledge-hub-modul.md |
396 | Production (für v2.0.0) |
konzepte/index.md |
36 | Production (Übersichtskarte) |
security/defense-in-depth.md |
335 | Production (Architektur-Pillar) |
security/defense-in-depth.bpmn |
— | Production (Asset) |
security/defense-in-depth.svg |
— | Production (Asset) |
operations/auth-stack-soll-zustand.md |
303 | Production (Source-of-Truth) |
operations/routing-and-endpoints.md |
475 | Production (Reference) |
operations/color-system-implementation.md |
119 | Production (Source-of-Truth) |
Cluster-Größe: 11 Files / ~4192 Zeilen
Methodology-Cluster (Saga-Lehren, Code-Review-Standards)¶
| File | Zeilen | Reife |
|---|---|---|
security/saga-lehren.md |
335 | Production (methodische Konstitution, 13 Lehren) |
prozesse/code-review-template.md |
120 | Production (Template) |
Cluster-Größe: 2 Files / 455 Zeilen
Operator-Cluster (Self-Hosting, Deployment, Backup, Performance)¶
| File | Zeilen | Reife |
|---|---|---|
deployment/qdrant-collections.md |
223 | Production (Runbook) |
deployment/keycloak-service-account.md |
230 | Production (Runbook) |
deployment/operator-ui-client.md |
218 | Production (Runbook) |
deployment/remote-vllm-node-setup.md |
215 | Production (Runbook) |
deployment/compose-invocations.md |
201 | Production (Discipline-Doku) |
deployment/platform-modules.md |
184 | Production (Reference) |
deployment/docs-deployment.md |
145 | Production (Self-Hosting) |
deployment/npmplus-auth-subdomain.md |
91 | Production (Runbook) |
deployment/bind-mount-discipline.md |
83 | Production (Discipline-Doku) |
deployment/mkdocs-container.md |
24 | Deprecated (Legacy-Hinweis-Stub) |
operations/restart-policies.md |
91 | Production (Reference) |
operations/test-data-cleanup.md |
208 | Production (Operator-Tool) |
operations/audit-conventions.md |
88 | Production (Reference) |
operations/image-cache-hygiene.md |
70 | Production (Tool-Doku) |
operations/block-19-observation-baseline.md |
78 | Saga-Spur (Zeitstempel: Block-19-Tag-0) |
Cluster-Größe: 15 Files / ~2149 Zeilen (davon 1 Deprecated, 1 Saga-Spur)
Admin-Cluster (Tenant-Verwaltung, Pattern-Konfiguration)¶
| File | Zeilen | Reife |
|---|---|---|
| (keine Files) | — | STRUKTURELL LEER |
Cluster-Größe: 0 Files. AVS-Vergleich: 15 Files in docs/betrieb/admin-handbuch/.
EndUser-Cluster (Chatbot-Nutzer-Handbuch)¶
| File | Zeilen | Reife |
|---|---|---|
| (keine Files) | — | STRUKTURELL LEER |
Cluster-Größe: 0 Files. AVS-Vergleich: 8 Files in docs/handbuch/.
Developer-Cluster (API, SDK, Webhooks)¶
| File | Zeilen | Reife |
|---|---|---|
| (keine Files) | — | STRUKTURELL LEER |
Cluster-Größe: 0 Files. AVS-Vergleich: 5 Files in docs/entwicklung/.
Saga-Spur-Cluster (Bilanz, Audit-Trails, organisch aus Karten)¶
| File | Zeilen | Reife |
|---|---|---|
changelog.md |
4818 | Saga-Spur (sehr groß; alle Releases + Sub-Block-Bilanzen) |
offene-todos.md |
2730 | Saga-Spur (Living-Document, M1/M2/L-Severity) |
cleanup-welle-discovery-2026-05-01.md |
300 | Saga-Spur (Discovery-Snapshot) |
drift-status-2026-04-30.md |
274 | Saga-Spur (Drift-Snapshot pre-Block-11) |
releases/v1.3.0.md |
195 | Saga-Spur (Release-Notes) |
releases/v1.3.0-acceptance.md |
81 | Saga-Spur (Akzeptanz-Matrix) |
releases/v1.2.0.md |
247 | Saga-Spur |
releases/v1.2.0-acceptance.md |
61 | Saga-Spur |
releases/v1.1.0.md |
195 | Saga-Spur |
releases/v1.1.0-acceptance.md |
132 | Saga-Spur |
releases/v1.0.0.md |
136 | Saga-Spur |
releases/v1.0.0-acceptance.md |
90 | Saga-Spur |
reviews/block-7-3-modules-and-packages.md |
199 | Saga-Spur (Code-Review) |
reviews/block-7-1a-tenants-backend.md |
182 | Saga-Spur |
reviews/block-7-2-templates-crud.md |
177 | Saga-Spur |
reviews/block-7-4-audit-bulk-connectors.md |
161 | Saga-Spur |
reviews/block-7-1b-operator-ui-frontend.md |
148 | Saga-Spur |
blocks/block-7-1b-porting.md |
124 | Saga-Spur (Pre-Flight) |
Cluster-Größe: 18 Files / ~10.250 Zeilen — größter Cluster, fast 51 % des Doku-Volumens.
Bake-Off-Cluster (Color-System spezifisch)¶
| File | Zeilen | Reife |
|---|---|---|
operations/color-system-concepts/concept-a.md |
219 | Production (Implementiert-Markierung) |
operations/color-system-concepts/concept-b.md |
208 | Deprecated (Verworfen-Markierung) |
operations/color-system-concepts/bakeoff.html |
— | Deprecated (Bake-Off-Asset, einmalig) |
Cluster-Größe: 3 Files (davon 2 Deprecated)
Mixed-Cluster (mehrere Zielgruppen)¶
| File | Zeilen | Bemerkung |
|---|---|---|
index.md |
98 | Mixed: Architect (Architektur-Pillar) + Operator (Quickstart) — sollte Übersichts-Page für alle Konsumenten sein |
roadmap.md |
2511 | Mixed: Architect (Block-Pläne) + Methodology (Saga-Bilanz) + Saga-Spur (Status-Box mit Commits) — sollte Roadmap-Index + verteilte Block-Pages sein |
Cluster-Größe: 2 Files / 2609 Zeilen
Phase 1.2 Reife-Bewertung — Aufschlüsselung¶
| Reife-Klasse | Files | Zeilen-Summe |
|---|---|---|
| Production-Ready | 30 | ~7900 |
| Saga-Spur (gehört in Audit-Trail-Section, nicht Hauptpfad) | 18 | ~10.250 |
| Mixed (sollte aufgeteilt werden) | 2 | 2609 |
| Deprecated (Reorg-2 Lösch-Kandidaten) | 4 | ~510 |
| Assets (.bpmn, .svg, .html) | 3 | — |
| Total | 47 + 3 Assets | ~20.082 + 3 Assets |
Phase 1.3 Lücken-Analyse pro Zielgruppe¶
EndUser-Handbuch (komplett leer):
Was muss ein generischer kora-Chatbot-Nutzer wissen, übertragbar auf alle künftigen Tenants?
| Stub-Page | Zweck | Aufwand-Schätzung |
|---|---|---|
enduser/erste-schritte.md |
Wie öffne ich den Chatbot? Wie stelle ich die erste Frage? | 2-3h |
enduser/bedienung.md |
UI-Elemente, Source-Chips, Feedback-Buttons, Eskalation-Pfad | 3-4h |
enduser/datenschutz.md |
Welche Daten werden gespeichert? Wie lange? Anonymität? Cookie-Lifecycle | 4-6h |
enduser/grenzen.md |
Was kann der Chatbot nicht? Wann an Mensch eskalieren? | 2-3h |
enduser/sprachen.md |
DE/EN-Unterstützung, sonstige Sprachen-Stand | 1-2h |
enduser/faq.md |
Häufige Fragen | 3-4h |
enduser/support.md |
Bei Problemen — Eskalations-Pfad zur Tenant-Admin | 1-2h |
| EndUser-Total | ~16-24h |
AVS-Pattern-Vorlage in docs/handbuch/* (8 Pages) übersetzbar mit AVS-spezifika rausgenommen.
Admin-Handbuch (komplett leer):
Was muss ein Tenant-Administrator (z.B. AVS-Operator pro Kurverwaltung) wissen?
| Stub-Page | Zweck | Aufwand-Schätzung |
|---|---|---|
admin/index.md |
Admin-Übersicht + Login-Flow | 1-2h |
admin/erste-anmeldung.md |
Initial-Login + Bootstrap-Setup | 2-3h |
admin/dashboard.md |
Operator-UI-Dashboard-Funktionen | 3-4h |
admin/chatbots.md |
Chatbot-Lifecycle (Erstellen, Editieren, Soft-Delete) | 4-6h |
admin/dokumente.md |
Dokument-Upload + Indexing-Status | 3-4h |
admin/templates.md |
System-Prompt-Templates verwalten | 2-3h |
admin/branding.md |
Tenant-/Chatbot-Branding (Farben, Logo, Welcome-Message) | 2-3h |
admin/audit-log.md |
Audit-Log-Reports lesen + interpretieren | 3-4h |
admin/feedback.md |
User-Feedback einsehen + Patterns erkennen | 2-3h |
admin/sessions.md |
Session-Liste + Querverweis Audit | 2-3h |
admin/evaluation.md |
Eval-Suite-Reports interpretieren | 3-5h |
admin/analytics.md |
Tenant-Analytics-Panel + Metriken | 2-3h |
admin/rollen-und-berechtigungen.md |
tenant-admin / tenant-editor / tenant-viewer Scope | 3-4h |
admin/einstellungen.md |
Tenant-spezifische Einstellungen (CORS, Rate-Limit, …) | 3-4h |
| Admin-Total | ~35-51h |
AVS-Pattern-Vorlage in docs/betrieb/admin-handbuch/* (15 Pages) — fast 1:1 portierbar mit AVS-Spezifika abstrahiert (z.B. „AVS-Lizenz" → „Tenant-Lizenz-Konfiguration", „AVS-Produkte" → „Chatbot-Pakete pro Tenant").
Operator-Handbuch (Self-Hosting, fragmentiert vorhanden):
15 Files in deployment/ und operations/ haben Operator-Material, aber keine end-to-end-Anleitung.
| Stub-Page | Zweck | Aufwand-Schätzung |
|---|---|---|
operator/index.md |
Operator-Quickstart-Übersicht | 1-2h |
operator/installation.md |
End-to-end Self-Hosting-Anleitung (Docker, Compose, NPMplus, DNS) | 4-6h |
operator/backup-restore.md |
Postgres-Dump + Qdrant-Snapshot + Redis-Persistence + MinIO-Bucket — koordinierter Backup | 4-6h |
operator/performance.md |
vLLM-Performance-Tuning + Embedder-Batch-Tuning + Reranker-Threshold | 3-4h |
operator/monitoring.md |
Prometheus-Scrape + Grafana-Dashboards + Alert-Konfiguration | 4-6h |
operator/troubleshooting.md |
Häufige Fehler + Diagnose-Pfade | 3-5h |
| Operator-Total NEU | (Plus Konsolidierung der 15 existing Files in operator/-Sub-Section) | ~19-29h NEU + ~3-5h Konsolidierung |
Developer-Handbuch (komplett leer):
| Stub-Page | Zweck | Aufwand-Schätzung |
|---|---|---|
developer/index.md |
Developer-Quickstart | 1h |
developer/api-reference.md |
OpenAPI-Spec + Endpoint-Übersicht | 4-6h (auto-gen + curate) |
developer/sdk.md |
SDK-Beispiele (Python + TypeScript) | 4-6h |
developer/webhooks.md |
Webhook-Konfiguration + Event-Types | 2-3h |
developer/connector-sdk.md |
Konnektor-Entwickler-Guide (§13.10 Fundament) — wird in Block 16 Karte D-16 vorbereitet | (out-of-Scope hier) |
| Developer-Total | ~11-16h |
Lücken-Total: ~81-120h Schreibaufwand für 28 Stub-Pages. Diese werden in Karte C (Customer-Handbuch-Inhalt) befüllt; Reorg-3 legt nur die Stub-Pages mit Inhalts-Skelett an (~1-2h Mechanik).
Phase 2 — Neue IA-Struktur¶
2.1 Neue Section-Struktur (mkdocs.yml-nav-Skelett)¶
nav:
# Eintrittspunkt — kurze Orientierung pro Konsumenten-Klasse
- Start: index.md # Refresh + Slim-Down (Architektur-Pillar in Architektur-Section verschoben)
# Konsumenten-orientierte Sections (Lese-Reihenfolge nach Zielgruppe)
- Für Endnutzer:
- Übersicht: enduser/index.md # NEU
- Erste Schritte: enduser/erste-schritte.md # NEU
- Bedienung: enduser/bedienung.md # NEU
- Datenschutz: enduser/datenschutz.md # NEU
- Grenzen: enduser/grenzen.md # NEU
- Sprachen: enduser/sprachen.md # NEU
- Häufige Fragen: enduser/faq.md # NEU
- Support: enduser/support.md # NEU
- Für Administratoren:
- Übersicht: admin/index.md # NEU
- Erste Anmeldung: admin/erste-anmeldung.md # NEU
- Dashboard: admin/dashboard.md # NEU
- Chatbots verwalten: admin/chatbots.md # NEU
- Dokumente: admin/dokumente.md # NEU
- Templates: admin/templates.md # NEU
- Branding: admin/branding.md # NEU
- Audit-Log: admin/audit-log.md # NEU
- Feedback: admin/feedback.md # NEU
- Sessions: admin/sessions.md # NEU
- Evaluation: admin/evaluation.md # NEU
- Analytics: admin/analytics.md # NEU
- Rollen & Berechtigungen: admin/rollen-und-berechtigungen.md # NEU
- Einstellungen: admin/einstellungen.md # NEU
- Für Operator:
- Übersicht: operator/index.md # NEU
- Installation: operator/installation.md # NEU
- Backup & Restore: operator/backup-restore.md # NEU
- Performance-Tuning: operator/performance.md # NEU
- Monitoring: operator/monitoring.md # NEU
- Troubleshooting: operator/troubleshooting.md # NEU
- Runbooks:
- NPMplus auth-Subdomain: operator/runbooks/npmplus-auth-subdomain.md # MOVE
- Keycloak Service-Account: operator/runbooks/keycloak-service-account.md # MOVE
- Operator-UI Keycloak-Client: operator/runbooks/operator-ui-client.md # MOVE
- Plattform-Module: operator/runbooks/platform-modules.md # MOVE
- Qdrant Collections: operator/runbooks/qdrant-collections.md # MOVE
- Remote vLLM-Node: operator/runbooks/remote-vllm-node-setup.md # MOVE
- Doku-Deployment: operator/runbooks/docs-deployment.md # MOVE
- Disziplinen:
- Bind-Mount-Discipline: operator/disziplinen/bind-mount-discipline.md # MOVE
- Compose-Invocations: operator/disziplinen/compose-invocations.md # MOVE
- Restart-Policies: operator/disziplinen/restart-policies.md # MOVE
- Image-Cache-Hygiene: operator/disziplinen/image-cache-hygiene.md # MOVE
- References:
- Routing & Endpunkte: operator/references/routing-and-endpoints.md # MOVE
- Audit-Konventionen: operator/references/audit-conventions.md # MOVE
- Auth-Stack Soll-Zustand: operator/references/auth-stack-soll-zustand.md # MOVE
- Test-Daten-Cleanup: operator/references/test-data-cleanup.md # MOVE
- Color-System Implementation: operator/references/color-system-implementation.md # MOVE
- Für Entwickler:
- Übersicht: developer/index.md # NEU
- API-Reference: developer/api-reference.md # NEU
- SDK-Beispiele: developer/sdk.md # NEU
- Webhooks: developer/webhooks.md # NEU
# Konnektor-Entwickler-Guide kommt aus Block 16 Karte D-16
# Architektur-orientierte Sections (interne Architekten + Methodik)
- Architektur:
- Übersicht: architektur/index.md # NEU (kurze Übersichts-Page)
- Multi-Tenancy-Fundament: architektur/multitenancy-fundament.md # MOVE aus konzepte/
- SaaS-Detail-Plan-Synthese: architektur/v1-0-0-saas-detail-plan.md # MOVE aus konzepte/
- Konnektor-Roadmap: architektur/konnektor-roadmap.md # MOVE aus konzepte/
- Knowledge-Hub-Modul (v2.0.0): architektur/knowledge-hub-modul.md # MOVE aus konzepte/
- Sicherheit:
- Defense-in-Depth: architektur/sicherheit/defense-in-depth.md # MOVE aus security/
# .bpmn + .svg als Asset zusammen mit dem .md-File
- Methodik:
- Übersicht: methodik/index.md # NEU
- Saga-Lehren: methodik/saga-lehren.md # MOVE aus security/
- Code-Review-Template: methodik/code-review-template.md # MOVE aus prozesse/
- IA-Audit 2026-05-09: methodik/doku-ia-audit-2026-05-09.md # diese Page (NEU)
# Roadmap & Saga-Spur (audit-orientiert, nicht Hauptpfad)
- Roadmap:
- Aktuelle Roadmap: roadmap/index.md # MOVE roadmap.md hierher (slim)
# Bei Bedarf später: separate Block-Pages roadmap/blocks/block-N.md
- Audit-Trail:
- Changelog: audit-trail/changelog.md # MOVE
- Offene TODOs: audit-trail/offene-todos.md # MOVE
- Code-Reviews:
- Block 7.1a Tenants-Backend: audit-trail/reviews/block-7-1a-tenants-backend.md # MOVE
- Block 7.1b Operator-UI Frontend: audit-trail/reviews/block-7-1b-operator-ui-frontend.md # MOVE
- Block 7.2 Templates-CRUD-UI: audit-trail/reviews/block-7-2-templates-crud.md # MOVE
- Block 7.3 Modules + Packages: audit-trail/reviews/block-7-3-modules-and-packages.md # MOVE
- Block 7.4 Audit + Bulk + Connectors: audit-trail/reviews/block-7-4-audit-bulk-connectors.md # MOVE
- Pre-Flight & Discovery:
- Block 7.1b Porting: audit-trail/discovery/block-7-1b-porting.md # MOVE
- Cleanup-Welle Discovery 2026-05-01: audit-trail/discovery/cleanup-welle-discovery.md # MOVE (orphan in nav before)
- Drift-Status 2026-04-30: audit-trail/discovery/drift-status.md # MOVE (orphan in nav before)
- Block 19 Observation-Baseline: audit-trail/discovery/block-19-observation-baseline.md # MOVE
- Releases:
- v1.3.0 — Cleanup-Welle: audit-trail/releases/v1.3.0.md # MOVE
- v1.3.0 Akzeptanz-Matrix: audit-trail/releases/v1.3.0-acceptance.md # MOVE
- v1.2.0 — Block 11 Widget: audit-trail/releases/v1.2.0.md # MOVE
- v1.2.0 Akzeptanz-Matrix: audit-trail/releases/v1.2.0-acceptance.md # MOVE
- v1.1.0 — Block 8: audit-trail/releases/v1.1.0.md # MOVE
- v1.1.0 Akzeptanz-Matrix: audit-trail/releases/v1.1.0-acceptance.md # MOVE
- v1.0.0 — Phase B: audit-trail/releases/v1.0.0.md # MOVE
- v1.0.0 Akzeptanz-Matrix: audit-trail/releases/v1.0.0-acceptance.md # MOVE
- Bake-Off Color-System:
- Konzept A — Operator-Pragmatik (✅ Implementiert): audit-trail/bakeoffs/color-system-concept-a.md # MOVE
# Konzept B + bakeoff.html als deprecated entfernen (siehe Lösch-Kandidaten)
2.2 Mapping-Tabelle existing → neu¶
Vollständige Liste pro File. Action-Codes: MOVE (git mv mit Link-Update), REFRESH (Inhalt aktualisieren ohne Verschieben), SLIM (Inhalt kürzen / aufteilen), NEU (neue Stub-Page für Reorg-3 oder Karte C), DELETE (Lösch-Kandidat), CONSOLIDATE (mit anderem File zusammenführen).
| Existing Pfad | Neuer Pfad | Action |
|---|---|---|
index.md |
index.md |
REFRESH (Architektur-Pillar nach architektur/index.md aussourcen, dafür kurze Konsumenten-Klassen-Übersicht aufnehmen) |
roadmap.md |
roadmap/index.md |
MOVE + SLIM (Saga-Bilanz-Mix in Audit-Trail aussourcen, nur aktuelle/geplante Blöcke + Phase-Status hier) |
changelog.md |
audit-trail/changelog.md |
MOVE (4818 Z. — sehr groß; SLIM optional, aber Karte D nicht in Scope) |
offene-todos.md |
audit-trail/offene-todos.md |
MOVE |
cleanup-welle-discovery-2026-05-01.md |
audit-trail/discovery/cleanup-welle-discovery.md |
MOVE (war orphan in nav) |
drift-status-2026-04-30.md |
audit-trail/discovery/drift-status.md |
MOVE (war orphan in nav) |
konzepte/index.md |
(entfällt — neue architektur/index.md) |
CONSOLIDATE |
konzepte/multitenancy-fundament.md |
architektur/multitenancy-fundament.md |
MOVE |
konzepte/v1-0-0-saas-detail-plan.md |
architektur/v1-0-0-saas-detail-plan.md |
MOVE |
konzepte/konnektor-roadmap.md |
architektur/konnektor-roadmap.md |
MOVE |
konzepte/knowledge-hub-modul.md |
architektur/knowledge-hub-modul.md |
MOVE |
security/defense-in-depth.md |
architektur/sicherheit/defense-in-depth.md |
MOVE |
security/defense-in-depth.bpmn |
architektur/sicherheit/defense-in-depth.bpmn |
MOVE (Asset) |
security/defense-in-depth.svg |
architektur/sicherheit/defense-in-depth.svg |
MOVE (Asset) |
security/saga-lehren.md |
methodik/saga-lehren.md |
MOVE |
prozesse/code-review-template.md |
methodik/code-review-template.md |
MOVE |
deployment/bind-mount-discipline.md |
operator/disziplinen/bind-mount-discipline.md |
MOVE |
deployment/compose-invocations.md |
operator/disziplinen/compose-invocations.md |
MOVE |
deployment/docs-deployment.md |
operator/runbooks/docs-deployment.md |
MOVE |
deployment/keycloak-service-account.md |
operator/runbooks/keycloak-service-account.md |
MOVE |
deployment/mkdocs-container.md |
(entfällt) | DELETE (Legacy-Hinweis-Stub, 24 Z., redundant zu docs-deployment.md) |
deployment/npmplus-auth-subdomain.md |
operator/runbooks/npmplus-auth-subdomain.md |
MOVE |
deployment/operator-ui-client.md |
operator/runbooks/operator-ui-client.md |
MOVE |
deployment/platform-modules.md |
operator/runbooks/platform-modules.md |
MOVE |
deployment/qdrant-collections.md |
operator/runbooks/qdrant-collections.md |
MOVE |
deployment/remote-vllm-node-setup.md |
operator/runbooks/remote-vllm-node-setup.md |
MOVE |
operations/audit-conventions.md |
operator/references/audit-conventions.md |
MOVE |
operations/auth-stack-soll-zustand.md |
operator/references/auth-stack-soll-zustand.md |
MOVE |
operations/block-19-observation-baseline.md |
audit-trail/discovery/block-19-observation-baseline.md |
MOVE (Saga-Spur, nicht Reference) |
operations/color-system-implementation.md |
operator/references/color-system-implementation.md |
MOVE |
operations/color-system-concepts/concept-a.md |
audit-trail/bakeoffs/color-system-concept-a.md |
MOVE (Bake-Off-Outcome dokumentiert) |
operations/color-system-concepts/concept-b.md |
(entfällt) | DELETE (Verworfen, 208 Z., Bake-Off-Bilanz reicht) |
operations/color-system-concepts/bakeoff.html |
(entfällt) | DELETE (Bake-Off-Asset, einmalig) |
operations/image-cache-hygiene.md |
operator/disziplinen/image-cache-hygiene.md |
MOVE |
operations/restart-policies.md |
operator/disziplinen/restart-policies.md |
MOVE |
operations/routing-and-endpoints.md |
operator/references/routing-and-endpoints.md |
MOVE |
operations/test-data-cleanup.md |
operator/references/test-data-cleanup.md |
MOVE |
releases/v1.0.0.md |
audit-trail/releases/v1.0.0.md |
MOVE |
releases/v1.0.0-acceptance.md |
audit-trail/releases/v1.0.0-acceptance.md |
MOVE |
releases/v1.1.0.md |
audit-trail/releases/v1.1.0.md |
MOVE |
releases/v1.1.0-acceptance.md |
audit-trail/releases/v1.1.0-acceptance.md |
MOVE |
releases/v1.2.0.md |
audit-trail/releases/v1.2.0.md |
MOVE |
releases/v1.2.0-acceptance.md |
audit-trail/releases/v1.2.0-acceptance.md |
MOVE |
releases/v1.3.0.md |
audit-trail/releases/v1.3.0.md |
MOVE |
releases/v1.3.0-acceptance.md |
audit-trail/releases/v1.3.0-acceptance.md |
MOVE |
reviews/block-7-1a-tenants-backend.md |
audit-trail/reviews/block-7-1a-tenants-backend.md |
MOVE |
reviews/block-7-1b-operator-ui-frontend.md |
audit-trail/reviews/block-7-1b-operator-ui-frontend.md |
MOVE |
reviews/block-7-2-templates-crud.md |
audit-trail/reviews/block-7-2-templates-crud.md |
MOVE |
reviews/block-7-3-modules-and-packages.md |
audit-trail/reviews/block-7-3-modules-and-packages.md |
MOVE |
reviews/block-7-4-audit-bulk-connectors.md |
audit-trail/reviews/block-7-4-audit-bulk-connectors.md |
MOVE |
blocks/block-7-1b-porting.md |
audit-trail/discovery/block-7-1b-porting.md |
MOVE |
| (neu) | methodik/doku-ia-audit-2026-05-09.md |
NEU (diese Page) |
| (neu) | architektur/index.md |
NEU (Übersichts-Page Architektur, ~50 Zeilen) |
| (neu) | methodik/index.md |
NEU (Übersichts-Page Methodik) |
| (neu) | enduser/* (8 Pages) |
NEU (Stub-Pages für Karte C) |
| (neu) | admin/* (15 Pages) |
NEU (Stub-Pages für Karte C) |
| (neu) | operator/index.md |
NEU (Operator-Übersicht) |
| (neu) | operator/installation.md |
NEU (Stub für Karte C) |
| (neu) | operator/backup-restore.md |
NEU (Stub für Karte C) |
| (neu) | operator/performance.md |
NEU (Stub für Karte C) |
| (neu) | operator/monitoring.md |
NEU (Stub für Karte C) |
| (neu) | operator/troubleshooting.md |
NEU (Stub für Karte C) |
| (neu) | developer/* (4 Pages) |
NEU (Stub-Pages für Karte C) |
Mapping-Bilanz:
- 47 Files Mapping-Action-Klassifikation:
- MOVE (git mv + Link-Update): 38 Files
- REFRESH (Inhalt-Update without move): 1 File (
index.md) - SLIM + MOVE (Inhalt aufteilen): 1 File (
roadmap.md) - CONSOLIDATE: 1 File (
konzepte/index.md→ inarchitektur/index.md) -
DELETE: 3 Files + 1 Asset (Lösch-Kandidaten unten)
-
Plus 30+ NEUE Stub-Pages für Karte C (EndUser/Admin/Operator/Developer-Cluster)
2.3 Konsolidierungs-Kandidaten¶
| Kandidat | Mit | Begründung |
|---|---|---|
konzepte/index.md (36 Z.) |
architektur/index.md (NEU) |
konzepte/index ist Übersichts-Karte; nach Move in Architektur-Section ist eine neue Architektur-Übersicht das natürliche Pendant |
(Nur ein Konsolidierungs-Kandidat — die Doku ist bereits gut faktorisiert; der Umzug + Restrukturierung ist die Hauptarbeit, nicht Inhalt-Merge.)
2.4 Lösch-Kandidaten¶
| Kandidat | Zeilen | Begründung |
|---|---|---|
deployment/mkdocs-container.md |
24 | „Legacy-Hinweis"-Stub, redundant zu docs-deployment.md |
operations/color-system-concepts/concept-b.md |
208 | „Verworfen"-Markierung; Bake-Off-Bilanz in Concept-A reicht als Audit-Trail |
operations/color-system-concepts/bakeoff.html |
— | Bake-Off-Asset, einmalig genutzt |
(potenziell) cleanup-welle-discovery-2026-05-01.md |
300 | Zeitstempel-Snapshot — Wert als Archive ja, aber Section ist audit-trail/discovery/. Kein Lösch — MOVE. |
(potenziell) drift-status-2026-04-30.md |
274 | analog. Kein Lösch — MOVE. |
Effektive Lösch-Bilanz: 3 Files + 1 Asset, ~232 Zeilen entfernt. Konservativ — keine inhaltliche Information verloren.
Phase 3 — Reorg-Karten-Skelette (Folge-Karten)¶
Reorg-Karte 1 — File-Move + nav-Update¶
- Status: 📋 Skizze (noch nicht gestartet)
- Aufwand-Range: 2-3h Mechanik
- Scope:
- 38 git mv (mit
--follow-Tracking für Diff-Lesbarkeit) - mkdocs.yml-nav komplett umbauen entsprechend 2.1
- Alle internen Links anpassen (relative Pfade in MD-Files)
- Externe Links (von außerhalb kora-Doku, z.B. Action-Plan in AVS-Repo) auf neue Pfade aktualisieren
- Validation:
mkdocs build --strictexit 0; keine Broken-Link-Warnings; Spot-Check mit 5 Live-URLs - Risiko: mittel — interne Links können kaputtgehen, externe Links zu
docs.kora.luki-net.orgebenso - Mitigation: Phase-0-Discovery der internen Links vor Move (
grep -rn "konzepte/\|security/\|operations/\|deployment/\|releases/\|reviews/" docs-kora/docs/); pro Section ein Sub-Commit für isolierte Reverts - Saga-Lehren anwendbar: Lehre 1 (Phase-0-Discovery der Links), Lehre 13 (Aufwands-Caps pro Sub-Phase)
Reorg-Karte 2 — Konsolidierung + Lösch¶
- Status: 📋 Skizze
- Aufwand-Range: 1-2h
- Scope:
- 3 Files + 1 Asset löschen (Lösch-Kandidaten Phase 2.4)
- 1 Konsolidierung (
konzepte/index.mdInhalt inarchitektur/index.mdeinfließen) index.mdSLIM (Architektur-Pillar inarchitektur/index.mdaussourcen, Konsumenten-Klassen-Übersicht stattdessen)roadmap.mdSLIM (Saga-Bilanz aus dem Roadmap-Hauptpfad inaudit-trail/saga-bilanzen.mdaussourcen, nur aktuelle/geplante Blöcke + Phase-Status inroadmap/index.mdbelassen)- Validation: Wortzahl-Bilanz vorher/nachher; keine inhaltlichen Deletions außer Lösch-Kandidaten
- Risiko: niedrig-mittel
- Saga-Lehren anwendbar: Lehre 13 (Honesty-over-Coverage — vertage SLIM falls Cap überschritten)
Reorg-Karte 3 — Stub-Pages für Customer-Handbuch¶
- Status: 📋 Skizze
- Aufwand-Range: 1-2h Mechanik (~5min pro Stub-Page × ~28 Pages)
- Scope:
- Pro neue nav-Sektion (EndUser, Admin, Operator-NEU, Developer) eine Stub-Page mit Inhalts-Skelett anlegen
- Skelett-Format: Frontmatter (Status: Stub, Karte-C-Aufgabe), 1-2 Sätze Zweck, Bullet-Liste der zu schreibenden Sektionen
- mkdocs.yml-nav um Stub-Pages erweitern
- Validation:
mkdocs build --strictexit 0; alle 28 nav-Pages existieren - Risiko: niedrig
- Beispiel-Stub: siehe Anhang am Ende dieses Audits
- Saga-Lehren anwendbar: Lehre 13
Aufwands-Bilanz Reorg gesamt¶
| Karte | Aufwand-Range |
|---|---|
| Reorg-1 File-Move + nav | 2-3h |
| Reorg-2 Konsolidierung + Lösch | 1-2h |
| Reorg-3 Stub-Pages | 1-2h |
| Reorg gesamt | 4-7h |
(Original-Schätzung ~6-9h reduziert auf 4-7h, weil die Inhalts-Bilanz weniger Konsolidierung als erwartet braucht — die Doku ist bereits sauber faktorisiert.)
Phase 4 — Verhältnis zu Karte B + C¶
Verhältnis zu Karte B (Backlog-Inventur)¶
Karte B sammelt offene Punkte aus alten Saga-Karten und Sub-Blöcken (z.B. „Doc-Upload-UI-Stub" aus Block 8.5, deferred Items aus Block 7-Reviews). Die Backlog-Items werden als Stub-Karten in audit-trail/backlog/ einsortiert — die IA-Struktur dieses Plans liefert dafür den Section-Anker.
Abhängigkeit: Karte B kann auf der neuen IA aufbauen, sobald Reorg-1 + Reorg-2 abgeschlossen sind. Sequenzierung empfohlen: IA-Audit (diese Karte) → Reorg-1 → Reorg-2 → Karte B → Karte C → Reorg-3.
Verhältnis zu Karte C (Customer-Handbuch-Inhalt)¶
Karte C füllt die Stub-Pages aus Reorg-3 mit produktivem Inhalt:
- 8 EndUser-Pages: ~16-24h
- 15 Admin-Pages: ~35-51h (größter Aufwand-Block, Pattern aus AVS-Doku)
- 6 NEUE Operator-Pages (zusätzlich zu den 15 vorhandenen Files die nur MOVE sind): ~19-29h
- 4 Developer-Pages: ~11-16h
Karte-C-Total-Range: ~81-120h. Das ist eine Multi-Saga-Karte und sollte selbst in Sub-Karten zerlegt werden (z.B. Karte C-1 EndUser, Karte C-2 Admin, Karte C-3 Operator-NEU, Karte C-4 Developer).
Sequenz-Empfehlung¶
- IA-Audit-Karte (diese, abgeschlossen ✅)
- Reorg-1 File-Move + nav (Mechanik, 2-3h)
- Reorg-2 Konsolidierung + Lösch (Mechanik, 1-2h)
- Karte B Backlog-Inventur (4-6h)
- Reorg-3 Stub-Pages (Mechanik, 1-2h)
- Karte C-1 .. C-4 Customer-Handbuch-Inhalt (Sub-Karten, ~81-120h gesamt — verteilbar über mehrere Sprints)
- (Parallel) SaaS-Sub-Karten aus
v1-0-0-saas-detail-plan.md— die Reorg ist nicht blocking für SaaS-Sub-Karte CI-1 oder DSGVO-1/2/3
Phase 5 — Saga-Lehren-Mapping pro Reorg-Karte¶
| Reorg-Karte | Saga-Lehren stark | Begründung |
|---|---|---|
| Reorg-1 File-Move | Lehre 1 (Discovery der internen Links), Lehre 13 (Cleanup-Disziplin pro Sub-Phase Commit) | Mechanik-Karten brauchen vorab-Discovery um Cap zu halten |
| Reorg-2 Konsolidierung | Lehre 13 (vertage SLIM falls überschreitet) | Inhaltliche Konsolidierung ist Cap-empfindlich |
| Reorg-3 Stub-Pages | Lehre 13 | mechanisch, klares Skelett-Format reduziert Cognitive-Load (Lehre 6) |
| Karte B Backlog | Lehre 1 (Discovery), Lehre 13 | Backlog-Inventur ist klassische Discovery-Karte |
| Karte C-1..C-4 | Lehre 1 (Phase-0-Discovery der AVS-Pattern), Lehre 6 (Convention pro Sub-Karte), Lehre 13 | Inhalts-Karten haben hohes Scope-Creep-Risiko |
Risiko-Bewertungs-Matrix¶
| Risiko-Klasse | Karten | Mitigation |
|---|---|---|
| Mittel (Broken-Links extern) | Reorg-1 File-Move | Phase-0-grep-Discovery aller docs-kora/-internen Links + docs.kora.luki-net.org-externen Links; Sub-Commit pro Section |
| Niedrig-Mittel (Inhalt-Verlust durch SLIM) | Reorg-2 Konsolidierung | Wortzahl-Bilanz vorher/nachher; Konsolidierte Inhalte in Audit-Trail-Section verschoben statt gelöscht |
| Niedrig (Stub-Page-Skelett unklar) | Reorg-3 + Karte C-1..C-4 | Skelett-Format als Anhang dieses Plans definiert; Karte C nutzt AVS-Pattern als Referenz |
Status nach Karte¶
- ✅ IA-Audit als Single-Source-of-Truth in
methodik/doku-ia-audit-2026-05-09.md(diese Page) - ✅ Vollständige Inventur der 47 Files + 3 Assets nach Zielgruppe (Architect 11, Methodology 2, Operator 15, Saga-Spur 18, Mixed 2, Bake-Off 3 davon 2 Deprecated) und Reife (Production 30, Saga-Spur 18, Mixed 2, Deprecated 4)
- ✅ Lücken-Analyse pro Zielgruppe mit Aufwand-Schätzungen für Karte C: EndUser ~16-24h, Admin ~35-51h, Operator-NEU ~19-29h, Developer ~11-16h. Karte-C-Total-Range ~81-120h.
- ✅ Neue IA-Struktur mit 8 Hauptsektionen (Start, EndUser, Admin, Operator, Developer, Architektur, Methodik, Roadmap, Audit-Trail) skizziert
- ✅ Mapping-Tabelle existing → neu für alle 47 Files + 3 Assets mit Action-Codes (MOVE 38, REFRESH 1, SLIM 1, CONSOLIDATE 1, DELETE 3+1)
- ✅ 3 Reorg-Karten skizziert als Folge-Karten mit Aufwands-Range 4-7h gesamt
- ✅ Verhältnis zu Karte B (Backlog-Inventur) und Karte C (Customer-Handbuch-Inhalt) dokumentiert
- ✅ Sequenz-Empfehlung mit klarer Reihenfolge
Nächste Karten:
- Reorg-1 (File-Move + nav, 2-3h) — kleinste Mechanik, schnellster Win
- Reorg-2 (Konsolidierung + Lösch, 1-2h) — schließt Pre-Customer-Handbuch-Strukturierung ab
- Karte B (Backlog-Inventur, 4-6h) — vor Reorg-3 sinnvoll, weil Backlog-Items Stub-Pages mit prägen
- Reorg-3 (Stub-Pages, 1-2h) — letzte IA-Mechanik vor Karte-C-Inhalts-Sprints
- Karte C-1 .. C-4 (Customer-Handbuch-Inhalt, ~81-120h) — Multi-Saga-Sequenz, parallelisierbar mit SaaS-Sub-Karten
Anhang — Stub-Page-Skelett-Format (für Reorg-3)¶
Pro neue Stub-Page in Reorg-3 dieses Format anlegen:
# <Titel der Page>
> **Status:** Stub für Customer-Handbuch (Karte C). Inhalt wird in Karte C-{1..4} ergänzt.
> **Erstellt:** 2026-MM-DD durch Reorg-3
> **Zielgruppe:** <EndUser | Admin | Operator | Developer>
## Zweck
<1-2 Sätze: Was wird auf dieser Page dokumentiert?>
## Geplante Sektionen (Karte C-Aufgabe)
- [ ] <Sektion 1>
- [ ] <Sektion 2>
- [ ] <Sektion 3>
## Verweise
- Pattern-Vorlage AVS-Doku: <Pfad falls vorhanden>
- Architektur-Anker: <Verweis auf Konzept-Page>
Dieses Format hält die Stub-Pages konsistent und macht Karte-C-Inhalts-Sprints planbar.