Baradb/docs/de/architecture.md

BaraDB Architektur

Überblick

BaraDB ist eine multimodale Datenbank-Engine in Nim, die Document (KV), Graph, Vector, Columnar und Full-Text Search Speicherung in einer einzigen Engine mit einer einheitlichen Abfragesprache namens BaraQL kombiniert.

Schichten-Architektur

┌─────────────────────────────────────────────────────────┐
│ 1. CLIENT LAYER                                          │
│    Binary Protocol │ HTTP/REST │ WebSocket │ Embedded    │
├─────────────────────────────────────────────────────────┤
│ 2. QUERY LAYER (BaraQL)                                  │
│    Lexer → Parser → AST → IR → Optimizer → Codegen      │
├─────────────────────────────────────────────────────────┤
│ 3. EXECUTION ENGINE                                      │
│    Document │ Graph │ Vector │ Columnar │ FTS            │
├─────────────────────────────────────────────────────────┤
│ 4. STORAGE                                               │
│    LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache  │
├─────────────────────────────────────────────────────────┤
│ 5. DISTRIBUTED                                           │
│    Raft Consensus │ Sharding │ Replication │ Gossip      │
└─────────────────────────────────────────────────────────┘

Schicht 1: Client-Layer

Mehrere Kommunikationsprotokolle:

• Binärprotokoll (protocol/wire.nim): Effizientes Big-Endian Binärprotokoll mit 16 Nachrichtentypen
• HTTP/REST (core/httpserver.nim): JSON-basierte REST API mit Multi-Threading
• WebSocket (core/websocket.nim): Vollduplex-Streaming
• Embedded (storage/lsm.nim): Direkter In-Process-Zugriff

Verbindungsmanagement

• Connection Pool (protocol/pool.nim): Min/Max Verbindungslimits mit Idle-Timeout
• Rate Limiting (protocol/ratelimit.nim): Token-Bucket globale und per-Client Limits
• Authentifizierung (protocol/auth.nim): JWT mit HMAC-SHA256 und rollenbasierter Zugriff
• TLS/SSL (protocol/ssl.nim): TLS 1.3 mit auto-generierten Zertifikaten

Schicht 2: Query-Layer (BaraQL)

Die BaraQL-Pipeline:

1. Lexer (query/lexer.nim): Tokenisiert Eingabe in 80+ Tokentypen
2. Parser (query/parser.nim): Rekursiver Descent-Parser produziert AST
3. AST (query/ast.nim): 300+ Zeilen mit 25+ Knotenarten
4. IR (query/ir.nim): Intermediate Representation für Ausführungspläne
5. Optimizer (query/adaptive.nim): Adaptive Cross-Modal Query-Optimierung
6. Codegen (query/codegen.nim): Übersetzt IR zu Speicheroperationen
7. Executor (query/executor.nim): Führt Pläne mit Parallelisierung aus

Cross-Modal Planning

Der Optimizer (query/adaptive.nim) bestimmt die Ausführungsreihenfolge über Engines:

1. Selektivität für jedes Prädikat schätzen
2. Selektivstes Prädikat zuerst an seine Engine pushen
3. Bloom-Filter für KV-Lookups verwenden
4. Unabhängige Zweige parallelisieren
5. Results streamen um Materialisierung zu vermeiden

Schicht 3: Execution Engine

Document/KV Engine

• LSM-Tree (storage/lsm.nim): Write-optimierte Speicherung mit MemTable, WAL, SSTables
• B-Tree Index (storage/btree.nim): Geordneter Index für Bereichsscans mit COW

Vector Engine (vector/)

• HNSW Index (vector/engine.nim): Hierarchical Navigable Small World Graph
• IVF-PQ Index (vector/engine.nim): Inverted File Index mit Product Quantization
• SIMD Operations (vector/simd.nim): AVX2-optimierte Distanzberechnungen
• Quantization (vector/quant.nim): Scalar, Product und Binary Quantization

Graph Engine (graph/)

• Adjacency List (graph/engine.nim): Kanten-gewichteter gerichteter Graph
• Algorithmen (graph/engine.nim): BFS, DFS, Dijkstra, PageRank
• Community Detection (graph/community.nim): Louvain-Algorithmus
• Pattern Matching (graph/community.nim): Subgraph-Isomorphie
• Cypher Parser (graph/cypher.nim): Cypher-ähnliche Graph-Abfragen

Full-Text Search (fts/)

• Inverted Index (fts/engine.nim): Term-Document Index
• Ranking (fts/engine.nim): BM25 und TF-IDF Scoring
• Fuzzy Search (fts/engine.nim): Levenshtein-Distanz-Matching
• Multi-Language (fts/multilang.nim): Tokenizer für EN, BG, DE, FR, RU

Columnar Engine (core/columnar.nim)

• Perspalten-Speicherung für analytische Abfragen
• RLE und Dictionary-Kodierung
• SIMD-beschleunigte Aggregatfunktionen

Schicht 4: Storage

• LSM-Tree (storage/lsm.nim): MemTable, WAL, SSTable, Bloom-Filter, Compaction
• Page Cache (storage/compaction.nim): LRU-Cache mit Trefferraten-Verfolgung
• Memory-mapped I/O (storage/mmap.nim): mmap-basierter Dateizugriff
• Recovery (storage/recovery.nim): WAL-Replay und Crash-Recovery

Write Path

Client → Protocol → Auth → Parser → AST → IR → Codegen
  → StorageOp → MVCC Txn → WAL Write → MemTable → Commit

Read Path

Client → Protocol → Auth → Parser → AST → IR → Codegen
  → StorageOp → MVCC Snapshot → MemTable → SSTable → Result

Schicht 5: Distributed

• Raft Consensus (core/raft.nim): Leader Election, Log-Replikation
• Sharding (core/sharding.nim): Hash, Range und Consistent Hashing
• Replication (core/replication.nim): Sync, Async, Semi-Sync Modi
• Gossip Protocol (core/gossip.nim): SWIM-ähnliches Membership-Management
• Distributed Transactions (core/disttxn.nim): Two-Phase Commit

Wichtige Designentscheidungen

1. Reines Nim: Keine Cython, Python oder Rust Abhängigkeiten
2. Unified Storage: Eine Engine-handelt KV, Graph, Vector, FTS und Columnar
3. Embedded Mode: Kann als Bibliothek oder Server laufen
4. Binärprotokoll: Custom effizientes Wire-Protokoll
5. MVCC: Multi-Version Concurrency Control
6. Schema-First: Stark typisiertes Schema-System mit Vererbung
7. Cross-Modal: Einheitliche Abfragesprache über alle Datenmodelle
8. Formally Verified: Kern-Algorithmen in TLA+ spezifiziert und mit TLC model-gecheckt

Modulstatistiken

Kategorie	Module	Codezeilen	Zweck
Core	16	~4,200	Server, Protokolle, Transaktionen, Distributed
Storage	7	~3,100	LSM, B-Tree, WAL, Bloom, Compaction, mmap
Query	7	~2,800	Lexer, Parser, AST, IR, Optimizer, Codegen, Executor
Vector	3	~1,200	HNSW, IVF-PQ, Quantization, SIMD
Graph	3	~1,000	Adjacency List, Algorithmen, Community Detection
FTS	2	~900	Inverted Index, BM25, Fuzzy, Multi-Language
Protocol	7	~2,400	Wire, HTTP, WebSocket, Pool, Auth, Rate Limit, SSL
Schema	1	~600	Typen, Links, Vererbung, Migrationen
Client	2	~800	Nim Binary Client, File Helpers
CLI	1	~400	Interaktive BaraQL Shell
Total	49	~14,100