# 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: