phase a audit

PHASE_A_AUDIT.md

@@ -0,0 +1,79 @@
+# Technische Projektdokumentation
+## RAG-System – Phase A Abschluss
+
+**Projekt:** KI-RAG System  
+**Architekturstand:** Phase A abgeschlossen  
+**Datum:** Februar 2026  
+**Status:** Verbindliche Referenzdokumentation
+
+---
+
+# 1. Zielsetzung von Phase A
+
+Phase A hatte das Ziel, das bestehende Retrieval-Augmented-Generation-System strukturell zu stabilisieren und produktionsreif zu machen.
+
+Im Fokus standen:
+
+- Speicherstabilität (Streaming statt RAM-Load)
+- Deterministische Indexierung
+- Strikte Trennung von Domain (PHP) und Runtime (Python)
+- Zentrale Konfigurationssteuerung
+- Drift-Sicherheit des Vector-Index
+
+Phase A beinhaltete **keine funktionale Erweiterung**, sondern ausschließlich strukturelle und architektonische Stabilisierung.
+
+---
+
+# 2. Architekturprinzipien
+
+Das System folgt folgenden verbindlichen Grundprinzipien:
+
+1. **NDJSON ist Single Source of Truth**  
+   Alle Vektoren werden deterministisch aus `index.ndjson` erzeugt.
+
+2. **Full Rebuild statt inkrementeller Mutation**  
+   Der FAISS-Index wird bei Änderungen vollständig neu aufgebaut.
+
+3. **Streaming statt Full-RAM-Load**  
+   Keine vollständigen JSON-Arrays im Speicher.
+
+4. **Runtime und Domain sind strikt getrennt**  
+   PHP enthält Orchestrierung und Governance, Python enthält Vektor-Runtime.
+
+5. **Atomare Dateioperationen**  
+   Schreibvorgänge erfolgen über `.tmp` + `rename()`.
+
+6. **Konfigurationszentrierung**  
+   Alle Pfade und Script-Referenzen sind über `services.yaml` parametriert.
+
+---
+
+# 3. Umsetzung Phase A
+
+## A1 – Streaming-Architektur
+
+### Problem
+RAM-basierte JSON-Verarbeitung hätte bei steigender Chunk-Zahl zu Speicherproblemen geführt.
+
+### Umsetzung
+
+- Einführung von NDJSON als persistentes Format
+- Streaming-Verarbeitung in:
+    - `ChunkManager::streamAll()`
+    - `ChunkManager::countAllChunks()`
+    - `ChunkManager::compactByDocument()`
+    - `ChunkManager::rewriteAll()`
+- Entfernung von `iterator_to_array` im IngestFlow
+
+### Ergebnis
+
+- Speicherverbrauch unabhängig von Chunk-Anzahl
+- Stabil bis mindestens 120.000 Chunks
+
+---
+
+## A2 – Strukturtrennung Runtime / Domain
+
+### Umsetzung
+
+Python-Runtime wurde vollständig aus `src/` entfernt und ausgelagert nach: