priorities

Themis - Priorisierte Roadmap für Production Readiness

Stand: 29. Oktober 2025, 22:15
Basis: IMPLEMENTATION_STATUS.md Audit-Ergebnisse

---

🎯 Entscheidungsmatrix: Nächste Schritte

Feature	Impact	Aufwand	Risiko	Prio	Empfehlung
Prometheus Histogramme (kumulative Buckets)	Mittel	2-4h	Niedrig	✅ ERLEDIGT	Quick Win - Abgeschlossen
HNSW Persistenz	Hoch	1-2 Tage	Mittel	✅ ERLEDIGT	Datenverlust-Risiko eliminiert
COLLECT/GROUP BY MVP	Hoch	3-5 Tage	Mittel	✅ ERLEDIGT	Basisfunktionalität implementiert
Vector Search HTTP Endpoint	Hoch	1-2 Tage	Niedrig	✅ ERLEDIGT	API-Integration vollständig
OR Query Index-Merge	Mittel	2-3 Tage	Mittel	✅ ERLEDIGT	DisjunctiveQuery implementiert
OpenTelemetry Tracing	Mittel	3-5 Tage	Niedrig	✅ ERLEDIGT	Production-Debugging enabled
Inkrementelle Backups	Niedrig	5-7 Tage	Hoch	📋 P2	Nice-to-Have
RBAC (Basic)	Hoch	7-10 Tage	Hoch	📋 P2	Security (später)
Apache Arrow Integration	Niedrig	10-15 Tage	Mittel	📋 P3	Analytics (später)

Status Update (30. Oktober 2025, 13:50):

• ✅ Alle P0-Features abgeschlossen!
• ✅ P1 OpenTelemetry Tracing: VOLLSTÄNDIG IMPLEMENTIERT
  • ✅ Infrastruktur: Tracer-Wrapper, OTLP HTTP Exporter, CMake integration
  • ✅ HTTP-Handler instrumentiert (7 Endpoints)
  • ✅ QueryEngine instrumentiert (11 Methoden + Child-Spans)
  • ✅ AQL-Operator-Pipeline instrumentiert (parse, translate, for, filter, limit, collect, return, traversal+bfs)
  • ✅ Dokumentation aktualisiert (docs/tracing.md)
  • Build erfolgreich, Server-Test bestanden
  • ALLE P1-TASKS ABGESCHLOSSEN!

Abgeschlossene Features:

• ✅ HNSW-Persistenz: Automatisches Save/Load implementiert
• ✅ COLLECT/GROUP BY MVP: Parser + In-Memory Aggregation (COUNT, SUM, AVG, MIN, MAX)
• ✅ Prometheus-Histogramme: Kumulative Buckets implementiert + validiert
• ✅ Vector Search HTTP Endpoint: POST /vector/search mit k-NN Suche
• ✅ OR Query Index-Merge: DisjunctiveQuery mit Index-Union
• ✅ OpenTelemetry Distributed Tracing: End-to-End Instrumentierung (HTTP → QueryEngine → AQL Operators)

Legende:

• 🔥 P0 = Kritisch (sofort/diese Woche) - ✅ ALLE ERLEDIGT
• ⚠️ P1 = Wichtig (nächste 2 Wochen) - ✅ ALLE ERLEDIGT
• 📋 P2 = Nice-to-Have (nächster Sprint) - NÄCHSTE PHASE
• 📋 P3 = Backlog (zukünftig)

---

🚀 Empfohlene Reihenfolge (Batch 1: Diese Woche)

Option A: Quick Wins zuerst (Momentum aufbauen) ✅ ABGESCHLOSSEN

Tag 1-2:  Prometheus Histogramme (kumulative Buckets) ✅
Tag 2-4:  OR/NOT Index-Merge (Query-Flexibilität) ✅
Tag 5-7:  HNSW Persistenz (Datenverlust-Risiko eliminieren) ✅

Ergebnis: Alle P0-Features implementiert und getestet!

Batch 2: P1 Features (Diese/Nächste Woche)

Tag 1-2:  OpenTelemetry Tracing - Infrastruktur ✅
Tag 2-3:  OpenTelemetry Tracing - Instrumentierung (HTTP, Query)
Tag 4-5:  Jaeger Integration testen + Dokumentation

Option B: Strategische Features zuerst (Fundamentals)

Tag 1-5:  COLLECT/GROUP BY MVP (Basisfunktionalität)
Tag 6-7:  HNSW Persistenz (Datenverlust-Risiko)
Tag 8:    Prometheus Histogramme (Quick Win zum Abschluss)

Vorteil: Kernfunktionalität (Aggregationen) schnell verfügbar
Nachteil: Längerer initialer Entwicklungszyklus

Option C: Risiko-Minimierung zuerst (Defensive)

Tag 1-2:  HNSW Persistenz (Datenverlust-Risiko eliminieren)
Tag 3-7:  COLLECT/GROUP BY MVP (Basisfunktionalität)
Tag 8:    Prometheus Histogramme (Quick Win)

Vorteil: Kritische Risiken (Datenverlust) sofort adressiert
Nachteil: Komplexes Feature am Anfang (HNSW save/load)

---

🔍 Detaillierte Analyse: Top 3 Features

1️⃣ Prometheus Histogramme (kumulative Buckets)

Problem:

• Aktuelle Implementation: Non-kumulative Buckets (jeder Bucket zählt nur seinen Range)
• Prometheus-Spec: Buckets müssen kumulativ sein (le="100" = alle Werte ≤ 100)
• Impact: Grafana/Prometheus-Tools zeigen falsche Percentiles

Lösung:

// Aktuell (FALSCH):
if (ms <= 1) page_bucket_1ms_++;
else if (ms <= 5) page_bucket_5ms_++;
// ...

// Korrekt (KUMULATIV):
if (ms <= 1) page_bucket_1ms_++;
if (ms <= 5) page_bucket_5ms_++;
if (ms <= 10) page_bucket_10ms_++;
// ... (jeder Wert inkrementiert ALLE passenden Buckets)

Aufwand:

• Änderungen: http_server.cpp (recordLatency, recordPageFetch)
• Tests: Smoke-Test erweitern (Bucket-Prüfung)
• Doku: README.md aktualisieren
• Geschätzt: 2-4 Stunden

DoD (Definition of Done):

• recordLatency() verwendet kumulative Bucket-Logik
• recordPageFetch() verwendet kumulative Bucket-Logik
• Smoke-Test validiert: Wert 150ms → buckets 1,5,10,25,50,100,250,500,1000,5000,Inf alle ≥ 1
• README.md Histogram-Beschreibung korrigiert

---

2️⃣ HNSW Persistenz (save/load)

Problem:

• Vector-Index ist nur In-Memory
• Server-Restart → alle Vektoren weg
• Manuelles Rebuild nötig (Performance-Impact)

Lösung:

// HNSWlib API:
index_->saveIndex("data/vector_index_<collection>.bin");
index_->loadIndex("data/vector_index_<collection>.bin", space_, max_elements_);

Implementierung:

1. Startup: VectorIndexManager::init() prüft auf existierende .bin, lädt wenn vorhanden
2. Shutdown: VectorIndexManager::shutdown() speichert Index
3. Background Save: Optional: Periodisches Save alle N Minuten
4. Versioning: Filename-Schema: <collection>_v<version>.bin

Aufwand:

• Code: vector_index.cpp (init/shutdown/save/load)
• Tests: test_vector_index.cpp (save → restart → load → verify results)
• Config: config.json (vector_save_interval_minutes)
• Geschätzt: 1-2 Tage

DoD:

• saveIndex() speichert bei Shutdown
• loadIndex() lädt bei Startup (wenn vorhanden)
• Test: Add 100 Vektoren → Restart → Search findet alle
• Config-Option: vector_auto_save: true/false

---

3️⃣ COLLECT/GROUP BY MVP

Problem:

• Aggregationen sind SQL/AQL-Standard-Feature
• AST-Node (CollectNode) existiert, aber keine Executor-Integration
• Queries wie SELECT city, COUNT(*) FROM users GROUP BY city unmöglich

Lösung (MVP-Scope):

// Beispiel:
FOR doc IN orders
  FILTER doc.created_at >= "2025-01-01"
  COLLECT city = doc.city
  AGGREGATE 
    total = SUM(doc.amount),
    count = COUNT()
  RETURN {city, total, count}

Implementierung:

1. Parser: CollectNode parsing (bereits vorhanden in AST)
2. Translator: handleCollect() in aql_translator.cpp
3. Executor:
   • Hash-Map für Gruppierung: std::unordered_map<string, AggregateState>
   • Aggregat-Funktionen: COUNT, SUM, AVG, MIN, MAX
   • Streaming-Execution (keine Full-Scan-Materialisierung)
4. Tests: Unit-Tests + HTTP-Integration-Tests

Aufwand:

• Code: aql_translator.cpp, query_engine.cpp
• Tests: test_aql_translator.cpp (mindestens 10 neue Tests)
• Doku: docs/aql_syntax.md aktualisieren
• Geschätzt: 3-5 Tage

MVP-Scope (Reduktion):

• ✅ Einspaltige Gruppierung (COLLECT city = doc.city)
• ✅ Basis-Aggregat-Funktionen (COUNT, SUM, AVG, MIN, MAX)
• ❌ Mehrspaltige Gruppierung (später)
• ❌ HAVING-Filter (später)
• ❌ KEEP/WITH COUNT (später)

DoD:

• COLLECT field = expr funktioniert
• AGGREGATE count = COUNT() funktioniert
• AGGREGATE sum = SUM(field) funktioniert
• Unit-Tests: 10+ Test-Cases PASS
• HTTP-Test: End-to-End GROUP BY Query
• Doku: Beispiel in docs/aql_syntax.md

---

📊 Impact-Analyse

Business Value

1. COLLECT/GROUP BY: ⭐⭐⭐⭐⭐ (Kernfunktionalität, Kundenerwartung)
2. HNSW Persistenz: ⭐⭐⭐⭐ (Datenverlust-Risiko, Produktionsfähigkeit)
3. Prometheus Histogramme: ⭐⭐⭐ (Observability, Ops-Qualität)

Technical Debt Reduction

1. Prometheus Histogramme: ⭐⭐⭐⭐⭐ (Compliance-Fix, behebt Spec-Verletzung)
2. HNSW Persistenz: ⭐⭐⭐⭐ (Architektur-Lücke schließen)
3. COLLECT/GROUP BY: ⭐⭐⭐ (AST-Code-Completion)

Risk Mitigation

1. HNSW Persistenz: ⭐⭐⭐⭐⭐ (Datenverlust-Risiko eliminieren)
2. COLLECT/GROUP BY: ⭐⭐ (Feature-Lücke, kein direktes Risiko)
3. Prometheus Histogramme: ⭐⭐ (Monitoring-Fehler, aber nicht kritisch)

---

✅ Empfehlung: Hybrid-Ansatz

Woche 1 (Tag 1-7):

🔥 Tag 1 (2-4h):    Prometheus Histogramme (Quick Win, Motivation)
🔥 Tag 1-3 (2 Tage): HNSW Persistenz (Risiko-Minimierung)
🔥 Tag 4-7 (4 Tage): COLLECT/GROUP BY MVP (Strategisch wichtig)

Rationale:

1. Quick Win am Anfang: Momentum, sichtbarer Fortschritt nach 4h
2. Risiko-Minimierung: HNSW-Persistenz vor Wochenende fertig
3. Strategisches Feature: COLLECT/GROUP BY nutzt volle Woche

Erwartete Ergebnisse (Ende Woche 1):

• ✅ Prometheus-konforme Histogramme
• ✅ Vector-Index überleben Server-Restart
• ✅ Basis-Aggregationen (COLLECT/COUNT/SUM) funktional
• 📈 Production-Readiness-Score: ~35% → ~55%

---

📅 Backlog (Woche 2+)

Woche 2:

• OR/NOT Index-Merge (2-3 Tage)
• OpenTelemetry Tracing (3-5 Tage)

Sprint 2:

• Inkrementelle Backups/WAL-Archiving
• Automated Restore-Verification
• Strukturierte JSON-Logs

Sprint 3:

• RBAC (Basic)
• Query/Plan-Cache
• POST /config (Hot-Reload)

Langfristig:

• Apache Arrow Integration
• Phase 4 (Filesystem/Content) Start
• Phase 7 (Security/Governance) Vollausbau

---

🎯 Entscheidung erforderlich

Bitte wählen:

1. Option A: Quick Wins zuerst (Prometheus → OR/NOT → HNSW)
2. Option B: Strategisch (COLLECT → HNSW → Prometheus)
3. Option C: Risiko-Minimierung (HNSW → COLLECT → Prometheus)
4. Empfehlung: Hybrid (Prometheus [Quick Win] → HNSW [Risiko] → COLLECT [Strategisch])

Oder eigene Priorisierung nennen.

---

Erstellt: 29. Oktober 2025
Nächster Review: Nach Abschluss von 3 P0-Features