Add monorepo summary and presentation docs

2026-06-30 21:45:14 +02:00
parent 88a1ee03d2
commit e4256d3222
2 changed files with 274 additions and 0 deletions
@@ -0,0 +1,109 @@
+# Monorepo-Konsolidierung – Präsentation
+
+---
+
+## Problem
+
+- **18+ einzelne Repositories** — kein Überblick, kein Zusammenhang
+- **Secrets manuell transportieren** — .gitignore-basiert, geht bei neuem Rechner verloren
+- **3 Arbeitskontexte** (Bahn, dhive, Privat) — vermischen sich unkontrolliert
+- **AI-Agenten** greifen unkontrolliert auf Dateien aller Kontexte zu
+- **Team-Zusammenarbeit** erfordert separate Repos — aber ich will den Überblick behalten
+- **Wissen verstreut** — Confluence, Jira, lokale Notizen, Chats, keine Suche darüber
+
+---
+
+## Lösung: Ein Monorepo mit Kontextgrenzen
+
+```
+monorepo/
+├── bahn/           ← 10 DB-InfraGO-Projekte
+├── dhive/          ← 2 dhive-Projekte
+├── privat/         ← 2 persönliche Projekte
+└── shared/         ← Übergreifende Tools, Orchestrator, Wissen
+```
+
+**Grundprinzip:** Alles an einem Ort, aber mit klaren Grenzen.
+
+---
+
+## Kernideen
+
+### 1. Kontextbasierte Sicherheit
+- Jeder Kontext hat eigene Secrets (verschlüsselt im Repo via git-crypt)
+- AI-Agent im Kontext "bahn" kann nicht auf "privat"-Secrets zugreifen
+- Zugriffsverletzungen werden geloggt und der Task wird abgebrochen
+
+### 2. Maschinenkontext
+- Jeder Rechner hat nur Zugriff auf autorisierte Kontexte
+- dhive-Laptop → nur dhive-Secrets entschlüsselbar
+- Hauptrechner → alles entschlüsselbar
+- Neue Maschine? Dokumentierter Onboarding-Prozess
+
+### 3. Föderierte Team-Zusammenarbeit
+- Bahn-Team sieht nur `bahn/` als eigenständiges Git-Repo
+- dhive-Team sieht nur `dhive/` als eigenständiges Git-Repo
+- Nur ich sehe das vollständige Monorepo (Hub-and-Spoke)
+- Bidirektionale Synchronisation, Team hat Vorrang bei Konflikten
+
+### 4. Multi-Harness AI-Dispatch
+- Pro Kontext/Task den optimalen AI-Agenten wählen
+- Kiro, Codex, Claude Code, Antigravity — einheitliche Schnittstelle
+- Agent bekommt nur Workspace + Secrets seines Kontexts
+
+### 5. Übergreifender Wissensspeicher
+- ETL-Pipeline für alle Wissensquellen (Markdown, Confluence, Jira, PDFs)
+- Progressive Disclosure: Agent liest erst Index, lädt bei Bedarf Details
+- Kontextübergreifende Suche mit Berechtigungsprüfung
+- Kontextbrücke: Wissen gezielt freigeben (mit Sensitive-Content-Filter)
+
+---
+
+## Benefits
+
+| Vorteil | Details |
+|---------|---------|
+| **Ein Repo, voller Überblick** | Alle Projekte an einem Ort, klar strukturiert |
+| **Secrets sicher & portabel** | Verschlüsselt committet, nicht gitignored — kein manueller Transport |
+| **AI-Agent-Sicherheit** | Kein versehentlicher Zugriff auf fremde Kontexte |
+| **Team-Kollaboration** | Teams arbeiten unabhängig, ohne zu wissen dass ein Monorepo existiert |
+| **Wissen verfügbar** | Jeder AI-Agent bekommt relevantes Wissen aus dem Index injiziert |
+| **Multi-Maschinen** | Neuer Rechner = git clone + Schlüssel installieren, fertig |
+| **Bahn-Repos unverändert** | Bestehende Workflows bleiben, Monorepo zieht nur rein |
+
+---
+
+## Drawbacks / Risiken
+
+| Risiko | Mitigation |
+|--------|-----------|
+| **Monorepo wird groß** | Git-Subtrees statt Submodules (flache Checkouts möglich); Wissensdatenbank-Output kann via .gitignore ausgeschlossen werden |
+| **git-crypt-Komplexität** | Dokumentierter Onboarding-Prozess; Schlüssel in Passwort-Manager |
+| **OneDrive-Sync-Konflikte** | Index.lock-Handling dokumentiert; Steering-Files für zukünftige Sessions |
+| **Single Point of Failure** | Regelmäßige Pushes zu GitHub/GitLab; Team-Repos als unabhängige Backups |
+| **Federation-Komplexität** | Einfache team-wins-Strategie; Manuelle Konfliktauflösung nur bei echten Merge-Konflikten |
+| **Lernkurve** | CLI-Tool `ctx-guard` vereinfacht alle Operationen; 13 dokumentierte Commands |
+
+---
+
+## Tech Stack
+
+- **Python** — Alle Tools in `shared/tools/monorepo-cli/`
+- **git-crypt** — Encryption at rest, pro Kontext
+- **git subtree** — Repo-Einbindung und Federation
+- **YAML** — Konfiguration, Frontmatter, Index
+- **Hypothesis** — 27 Property-Based Tests für Korrektheit
+- **300+ Tests** — Unit, Property, Integration (E2E)
+
+---
+
+## Status
+
+✅ Architektur designed und implementiert (12 Module, 300+ Tests)
+✅ Repos in Kontextordner migriert
+✅ Wissensdatenbank als Upstream eingebunden
+✅ CLI-Tool funktionsfähig
+⬜ git-crypt einrichten (Schlüssel generieren)
+⬜ Team-Repos auf GitLab erstellen
+⬜ Knowledge-Management-System für Notizen starten
+⬜ NoteGraph-Neuentwicklung auf Basis des Wissensspeichers