# 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**: Управление на членство