MtoRagSystem/TECHNICAL_ARCHITECTURE.md

TECHNICAL_ARCHITECTURE.md

mitho AI Agent – Enterprise Hybrid RAG System Stand: Februar 2026

---

1. Zielsetzung

Diese Dokumentation beschreibt die vollständige technische Architektur des mitho AI Agent RAG-Systems.

Ziele:

• Deterministisches Retrieval
• Governance-stabile Index-Struktur
• Versionierte Wissensbasis
• Reproduzierbare Builds
• Keine inkrementellen Vektor-Mutationen
• Job-basierte, asynchrone Ingest-Architektur
• Skalierbarkeit >200k Chunks

---

2. Architektur-Übersicht

Systemebenen:

1. Admin Layer (Symfony)
2. Ingest Layer
3. Storage Layer (NDJSON)
4. Vector Layer (FAISS)
5. Retrieval Layer (Hybrid)
6. Application Layer (LLM + SSE)

---

3. Core Architekturprinzipien

3.1 Determinismus

Gleiche Eingabe + gleiche Konfiguration → identisches Ergebnis.

• index.ndjson ist deterministisch
• FAISS wird vollständig neu gebaut
• Retrieval ist stabil reproduzierbar
• Keine impliziten Indexveränderungen

3.2 Governance

• Genau eine aktive Version pro Dokument
• Keine Inline-Rebuilds im HTTP-Request
• Strukturänderungen erzwingen Global Reindex
• Locking verhindert Parallel-Ingest

3.3 Skalierbarkeit

• NDJSON statt JSON-Array
• Streaming-Append
• Streaming-Compaction
• Kein RAM-Full-Load

---

4. Domain Model

4.1 Document

Primäre Wissenseinheit.

Eigenschaften:

• id (UUID)
• title
• createdAt
• createdBy
• archived (bool)
• currentVersion (ManyToOne → DocumentVersion)

4.2 DocumentVersion

Immutable Inhaltsversion.

Eigenschaften:

• id (UUID)
• document (ManyToOne)
• versionNumber
• filePath
• checksum
• active (bool)
• ingestStatus (PENDING, RUNNING, INDEXED, FAILED)

Regel: Nur eine Version pro Dokument darf active = true sein.

---

5. Ingest Architektur

5.1 Grundsatz

Kein Ingest läuft synchron im HTTP-Request.

Jede Indexänderung läuft über:

IngestJob → CLI Runner → IngestOrchestrator → IngestFlow

---

5.2 IngestJob

Entity mit:

• id
• type
• status
• documentId
• documentVersionId
• startedAt
• finishedAt
• errorMessage

Job-Typen:

DOCUMENT_VERSION_ACTIVATE DOCUMENT GLOBAL_REINDEX

Status:

QUEUED RUNNING COMPLETED FAILED ABORTED

---

5.3 Job-Execution

Start:

php bin/console mto:agent:ingest:run

Execution-Flow:

1. LockService.acquire()
2. Job → RUNNING
3. IngestFlow ausführen
4. Job → COMPLETED / FAILED
5. LockService.release()

---

6. IngestFlow Details

6.1 Local Ingest (Version aktivieren oder neue Datei)

Ablauf:

1. Extract (PDF/Text)
2. Normalize
3. Chunk deterministisch
4. Streaming Compaction:
   • Entferne alle Chunks mit document_id
5. Append neue Chunks
6. Full FAISS Rebuild

Wichtig: Es werden immer alle alten Chunks des Dokuments entfernt.

---

6.2 Global Reindex

Wird ausgelöst bei:

• embedding_model Änderung
• embedding_dimension Änderung
• chunk_size Änderung
• scoring_version Änderung
• index_format Änderung

Ablauf:

1. Alle aktiven Versionen extrahieren
2. Komplettes index.ndjson neu schreiben
3. FAISS neu bauen
4. index_version++

---

7. Storage Layer

7.1 index.ndjson

Single Source of Truth.

Eigenschaften:

• 1 JSON-Objekt pro Zeile
• Streaming-lesbar
• Append-only
• Compaction by document_id

Beispiel:

{ "chunk_id": "...", "document_id": "...", "document_version_id": "...", "text": "...", "meta": {...} }

---

7.2 index_meta.json

Enthält:

• index_version
• embedding_model
• embedding_dimension
• chunk_size
• chunk_overlap
• scoring_version
• index_format
• vector_backend

Bei strukturellem Mismatch: → Global Reindex zwingend.

---

8. Vector Layer (FAISS)

8.1 Build

vector_ingest.py:

• stream index.ndjson
• Embeddings berechnen
• FAISS IndexFlatIP bauen
• vector.index schreiben
• vector_meta.json schreiben

Immer vollständiger Rebuild. Keine Partial Updates.

8.2 Search

vector_search.py:

Input:

• Query
• Top-K

Output:

• chunk_id
• score

---

9. Hybrid Retrieval

Ablauf:

1. Keyword Retrieval (NDJSON Keyword Search)
2. Vector Retrieval (FAISS)
3. Score Fusion
4. Chunk Lookup
5. Context Builder
6. Prompt Builder
7. LLM

Keyword bleibt Primärsignal. Vector ergänzt semantische Nähe.

---

10. Locking

LockService schützt:

• NDJSON Mutationen
• FAISS Rebuild
• Global Reindex
• Aktivierungs-Parallelität

Keine zwei Ingest-Jobs gleichzeitig erlaubt.

---

11. Admin Flows

11.1 Neue Datei hochladen

1. Document + Version 1 erstellen
2. Version aktiv
3. DOCUMENT_VERSION_ACTIVATE Job anlegen
4. Async Runner starten
5. Redirect auf Job-Seite

11.2 Version aktivieren

1. DB-Status ändern
2. IngestStatus → PENDING
3. DOCUMENT_VERSION_ACTIVATE Job anlegen
4. Async Runner starten

11.3 Manuelles Ingest

1. DOCUMENT Job anlegen
2. Async Runner starten

---

12. Error Handling

Typische Fehler:

• exec deaktiviert → Async Start nicht möglich
• Lock aktiv → paralleler Ingest blockiert
• index_meta mismatch → Reindex erforderlich
• Vector-Dateien fehlen → Rebuild ausführen

---

13. Security & Stability

• Keine User-Uploads direkt ins Retrieval
• Kein Self-Learning
• Kein unkontrollierter Index-Mutate
• Strict Separation:
  • Admin Layer
  • Ingest Layer
  • Retrieval Layer
  • LLM Layer

---

14. System Guarantees

Dieses System garantiert:

• Reproduzierbarkeit
• Drift-Freiheit
• Auditierbarkeit
• Versionierte Wissensbasis
• Deterministische Retrieval-Ergebnisse
• Enterprise-taugliche Skalierbarkeit

---

15. Zusammenfassung

Das mitho AI Agent System ist eine:

• deterministische Hybrid-RAG Engine
• NDJSON-basierte Wissensplattform
• Full-Rebuild-FAISS Architektur
• Job-basierte Ingest-Pipeline
• Versionierte, governance-stabile Wissensstruktur

Keine Inline-Rebuilds. Keine inkrementellen Vektor-Updates. Keine impliziten Strukturänderungen.

Alles läuft kontrolliert über das Job-System.