Baradb/ROADMAP.md

BaraDB — Мултимодална база данни на Nim

По-добра от GEL (EdgeDB) — нативна мултимодалност, без Python, без PostgreSQL зависимост

Защо BaraDB > GEL?

Критерий	GEL (EdgeDB)	BaraDB
Език на ядрото	Python + Cython + Rust	100% Nim
Storage backend	Само PostgreSQL	Нативен multi-engine
Векторно търсене	pgvector (разширение)	Нативен HNSW/IVF-PQ
Graph алгоритми	Няма	Нативни (BFS, PageRank, ...)
Full-Text Search	pg FTS (разширение)	Нативен инвертиран индекс
Embedded режим	Не	Да (като SQLite)
Кompилация към WASM	Не	Да
Транзакции cross-modal	Чрез PG	Нативен 2PC
Протокол	Binary + PG wire + HTTP	Binary + HTTP/WS + gRPC
Schema миграции	Декларативни (тежки)	Автоматични + версия

---

Архитектура

┌─────────────────────────────────────────────────────────────┐
│                     КЛИЕНТСКИ СЛОЙ                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
│  │ Binary   │  │ HTTP/REST│  │WebSocket │  │  Embedded   │ │
│  │ Protocol │  │ JSON API │  │  Stream  │  │  (in-proc)  │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬──────┘ │
├───────┼──────────────┼────────────┼────────────────┼────────┤
│                ЗАПИТЕН СЛОЙ (BaraQL)                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
│  │ Лексер   │──│ Парсер   │──│ Анализ   │──│ Оптимизатор │ │
│  │          │  │ (AST)    │  │ (IR)     │  │ (Plan)      │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                ИЗПЪЛНИТЕЛЕН ДВИГАТЕЛ                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
│  │ Document │  │  Graph   │  │  Vector  │  │  Columnar   │ │
│  │ Engine   │  │  Engine  │  │  Engine  │  │  Engine     │ │
│  │ (JSON/B) │  │ (AdjList)│  │ (HNSW)  │  │ (Arrow)     │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬──────┘ │
├───────┼──────────────┼────────────┼────────────────┼────────┤
│                STORAGE СЛОЙ                                 │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  LSM-Tree Storage Engine                                ││
│  │  ┌────────┐  ┌────────┐  ┌────────┐  ┌──────────────┐ ││
│  │  │MemTable│  │WAL     │  │SSTable │  │Bloom Filter  │ ││
│  │  └────────┘  └────────┘  └────────┘  └──────────────┘ ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Транзакции: MVCC + 2PC + Deadlock Detection            ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

---

Пътна карта (Roadmap)

Фаза 1: Ядро на базата данни ✅

• LSM-Tree storage engine (MemTable, WAL, SSTable)
• Bloom filter за бързо отхвърляне
• Типова система (int, float, string, bool, bytes, uuid, datetime, json, vector)
• Сериялизация на записите
• B-Tree индекс за точкови заявки
• Компактиране на SSTable (compaction strategies)
• Page cache и buffer pool (LRU)

Фаза 2: Език за заявки — BaraQL 🟡

• Лексер с Unicode поддръжка
• Рекурсивен парсер → AST
• SELECT, INSERT, UPDATE, DELETE
• WHERE, ORDER BY, LIMIT, OFFSET
• Бинарни оператори (+, -, *, /, =, !=, <, >, AND, OR, NOT)
• Подзаявки и EXISTS
• Array литерали
• Типов анализатор (type checker)
• IR (Intermediate Representation)
• Оптимизатор на заявки (predicate pushdown, projection pushdown)
• GROUP BY, HAVING
• JOIN (inner, left, right, full, cross)
• CTE (WITH)
• Агрегатни функции (count, sum, avg, min, max)
• Codegen — IR → storage операции (predicate pushdown, cost estimation)
• Потребителски функции (UDF) — stdlib + custom

Фаза 3: Мултимодален storage 🟡

• Документен engine — вложени JSON документи, масиви, вложени обекти
• Граф engine — adjacency list, edge properties, incident index
• Векторен engine — float32 arrays, distance metrics
• Колонен engine — column-oriented storage за analytics (RLE, dict encoding, GroupBy)
• Унифициран query interface през BaraQL (CrossModalEngine)
• Cross-modal заявки (document + vector + graph в една заявка) — hybridSearch

Фаза 4: Транзакции и ACID ✅

• WAL (Write-Ahead Log) за durability
• MVCC (Multi-Version Concurrency Control)
• Snapshot isolation
• Deadlock detection (wait-for graph)
• Savepoints и вложени транзакции
• 2PC за cross-modal транзакции (TPCTransaction)
• Recovery при crash (REDO/UNDO) — WAL replay + analysis

Фаза 5: Мрежов протокол ✅

• TCP сървър с async I/O
• Binary протокол (BaraDB Wire Protocol)
• HTTP/REST API (JSON)
• Connection pooling
• Authentication (JWT, SCRAM-SHA-256)
• WebSocket за streaming
• Rate limiting (token bucket, sliding window)
• TLS/SSL (certificate management, self-signed generation)

Фаза 6: Schema система ✅

• Декларативна schema (SDL)
• Object types с properties
• Links между типове (1:1, 1:N, N:M)
• Наследоване и mixins
• Constraints (unique, check, required)
• Computed properties
• Автоматични миграции (schema diff)
• Версиониране на schema

Фаза 7: Векторен engine ✅

• HNSW индекс (Hierarchical Navigable Small World)
• IVF-PQ индекс (Inverted File + Product Quantization)
• Дистанционни метрики (cosine, euclidean, dot product, Manhattan)
• Квантизация (scalar 8-bit/4-bit, product, binary)
• Metadata filtering при vector search
• Batch insert/update (batchInsert, batchSearch)
• Автоматичен index rebuild при threshold (IndexWatcher)

Фаза 8: Graph engine ✅

• Adjacency list storage
• Edge properties и weights
• BFS (Breadth-First Search)
• DFS (Depth-First Search)
• Най-къс път (Dijkstra)
• PageRank
• Community detection (Louvain)
• Pattern matching (subgraph isomorphism)
• Cypher-подобен query syntax (parseCypher, executeCypher)

Фаза 9: Full-Text Search ✅

• Инвертиран индекс
• Токенизация (Unicode, stemming, stop words)
• BM25 ранкиране
• Highlight на резултати
• TF-IDF ранкиране
• Fuzzy matching (Levenshtein)
• Regex търсене (wildcard patterns)
• Многоезикова поддръжка (EN, BG, DE, FR, RU)

Фаза 10: Клиентски библиотеки и CLI ✅

• CLI tool (bara shell) — интерактивен shell + autocomplete
• Nim client library (standalone nimble package — async/sync, query builder)
• Python client library (clients/python/baradb.py — binary protocol)
• JavaScript/TypeScript client library (clients/javascript/baradb.js)
• Go client library (clients/go/)
• Rust client library (clients/rust/)
• Import/Export (JSON, CSV, NDJSON)

Фаза 11: Кластеризация и разпределение ✅

• Raft консенсус протокол (leader election + log replication)
• Sharding (hash-based, range-based, consistent hashing)
• Replication (sync, async, semi-sync)
• Gossip protocol за membership (GossipProtocol)
• Distributed transactions (DistTxnManager + Saga pattern)
• Auto-rebalancing (ClusterMembership — onNodeJoin/Leave/Fail)
• Leader election timer loop (ElectionTimer — tick/check/reset)

Фаза 12: Оптимизации, бенчмаркове, документация ✅

• SIMD оптимизации за vector operations (unrolled loops, batch distance)
• Memory-mapped I/O (mmap + madvise hints)
• Zero-copy serialization (ZeroBuf + ZcSchema)
• Adaptive query execution (AdaptivePlanner + ExecutionContext)
• Бенчмаркове vs PostgreSQL, Redis, MongoDB (benchmarks/compare.nim)
• API документация (README.md — full API reference with examples)
• Архитектурна документация (docs/ARCHITECTURE.md)
• Tutorial и примери (examples/tutorial.nim — 8 tutorials)

---

Статус

Фаза	Статус	Напредък
1. Ядро	✅	100%
2. BaraQL	✅	100%
3. Мултимодален storage	✅	100%
4. Транзакции	✅	100%
5. Протокол	✅	100%
6. Schema	✅	100%
7. Векторен engine	✅	100%
8. Graph engine	✅	100%
9. FTS	✅	100%
10. Клиенти и CLI	✅	100%
11. Кластер	✅	100%
12. Оптимизации	✅	100%

Легенда: ⬜ Не стартирана | 🟡 В процес | ✅ Завършена