Add comprehensive documentation with i18n support (EN/BG)

- Add docs/ folder with English (en/) and Bulgarian (bg/) documentation - Create index.md with language switching and links - English docs: installation, quickstart, architecture, baraql, storage, schema, lsm, btree, vector, graph, fts, columnar, transactions, distributed, protocol, udf, api-binary, api-http, api-websocket - Bulgarian docs: installation, quickstart, architecture, baraql, schema, lsm, btree, vector, graph, fts, transactions, distributed - Update README license to BSD 3-Clause - Add LICENSE file with BSD 3-Clause text
2026-05-06 16:51:14 +03:00
parent f9f77b3a18
commit e1bae0c7a0
34 changed files with 2370 additions and 1 deletions
@@ -0,0 +1,78 @@
+# BaraDB Архитектура
+
+## Преглед
+
+BaraDB е **мултимодална база данни** написана на Nim, която комбинира документно (KV), графично, векторно, колонно и пълнотекстово търсене в един двигател с обединен език за заявки наречен **BaraQL**.
+
+## Слоеста Архитектура
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. СЛОЙ ЗА КЛИЕНТИ                                       │
+│    Binary Protocol │ HTTP/REST │ WebSocket │ Embedded    │
+├─────────────────────────────────────────────────────────┤
+│ 2. ЗАЯВКИ СЛОЙ (BaraQL)                                 │
+│    Lexer → Parser → AST → IR → Optimizer → Codegen     │
+├─────────────────────────────────────────────────────────┤
+│ 3. ИЗПЪЛНИТЕЛЕН ДВИГАТЕЛ                                  │
+│    Document │ Graph │ Vector │ Columnar │ FTS           │
+├─────────────────────────────────────────────────────────┤
+│ 4. СЪХРАНЕНИЕ                                            │
+│    LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache │
+├─────────────────────────────────────────────────────────┤
+│ 5. РАЗПРЕДЕЛЕНО                                          │
+│    Raft Consensus │ Sharding │ Replication │ Gossip    │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Слой 1: Клиентски Слой
+
+Множество протоколи за комуникация:
+
+- **Binary Protocol**: Ефективен протокол с 16 типа съобщения
+- **HTTP/REST**: JSON-basiran REST API
+- **WebSocket**: Пълен дуплекс стрийминг
+- **Embedded**: Директен достъп в процеса
+
+## Слой 2: Заявки (BaraQL)
+
+Pipeline-а на BaraQL:
+
+1. **Lexer**: Токенизира входа в 80+ типа токени
+2. **Parser**: Рекурсивен descent парсър произвеждащ AST
+3. **AST**: 300+ реда покриващи 25+ вида възли
+4. **IR**: Междинно представяне за планове за изпълнение
+5. **Optimizer/Codegen**: Транслира IR към операции върху съхранение
+
+## Слой 3: Изпълнителен Двигател
+
+### Document/KV Двигател
+- **LSM-Tree**: Оптимизиран за запис
+- **B-Tree Index**: Подреден индекс за диапазони
+
+### Vector Engine
+- **HNSW**: Иерархичен навигируем малък свят
+- **IVF-PQ**: Инвертиран файл с продуктово квантуване
+- **SIMD**: Ускорени разстояния
+
+### Graph Engine
+- **Списък със съседи**: Насочен граф с тегла
+- **Алгоритми**: BFS, DFS, Dijkstra, PageRank, Louvain
+
+### FTS
+- **Инвертиран индекс**: Термин-документ индекс
+- **Ранжиране**: BM25 и TF-IDF
+- **Многоезичен**: Токенизация за EN, BG, DE, FR, RU
+
+## Слой 4: Съхранение
+
+- **LSM-Tree**: MemTable, WAL, SSTable, Bloom Filter, Compaction
+- **Page Cache**: LRU кеш
+- **Memory-mapped I/O**: mmap-базиран достъп
+
+## Слой 5: Разпределено
+
+- **Raft Consensus**: Лидерско избиране, репликация на логове
+- **Sharding**: Hash, range и консистентно хеширане
+- **Replication**: Sync, async, semi-sync режими
+- **Gossip Protocol**: Управление на членство