# Архитектура BaraDB

## Обзор

BaraDB — это **мультимодальный движок баз данных** на языке Nim, объединяющий документное (KV), графовое, векторное, колоночное хранилище и полнотекстовый поиск в едином движке с унифицированным языком запросов **BaraQL**.

## Слоёвая архитектура

```
┌─────────────────────────────────────────────────────────┐
│ 1. СЛОЙ КЛИЕНТА                                         │
│    Бинарный протокол │ HTTP/REST │ WebSocket │ Встраивание│
├─────────────────────────────────────────────────────────┤
│ 2. СЛОЙ ЗАПРОСОВ (BaraQL)                               │
│    Лексер → Парсер → AST → IR → Оптимизатор → Кодоген  │
├─────────────────────────────────────────────────────────┤
│ 3. ДВИЖОК ВЫПОЛНЕНИЯ                                    │
│    Документы │ Граф │ Векторы │ Колоночный │ FTS         │
├─────────────────────────────────────────────────────────┤
│ 4. ХРАНИЛИЩЕ                                            │
│    LSM-Tree │ B-Tree │ WAL │ Bloom │ Компактификация │ Cache│
├─────────────────────────────────────────────────────────┤
│ 5. РАСПРЕДЕЛЁННОСТЬ                                     │
│    Raft │ Шардирование │ Репликация │ Gossip             │
└─────────────────────────────────────────────────────────┘
```

## Слой 1: Клиентский слой

Несколько протоколов связи:

- **Бинарный протокол** (`protocol/wire.nim`): Эффективный бинарный протокол в big-endian с 16 типами сообщений
- **HTTP/REST** (`core/httpserver.nim`): JSON-based REST API с многопоточностью
- **WebSocket** (`core/websocket.nim`): Полнодуплексная потоковая передача
- **Встраиваемый режим** (`storage/lsm.nim`): Прямой доступ внутри процесса

### Управление соединениями

- **Пул соединений** (`protocol/pool.nim`): Мин/макс лимиты соединений с таймаутом простоя
- **Ограничение скорости** (`protocol/ratelimit.nim`): Token-bucket глобальные и пери-клиент лимиты
- **Аутентификация** (`protocol/auth.nim`): JWT с HMAC-SHA256 и ролевой доступ
- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 с автогенерируемыми сертификатами

## Слой 2: Слой запросов (BaraQL)

Конвейер BaraQL:

1. **Лексер** (`query/lexer.nim`): Токенизация входных данных в 80+ типов токенов
2. **Парсер** (`query/parser.nim`): Рекурсивный нисходящий парсер, создающий AST
3. **AST** (`query/ast.nim`): 300+ строк, покрывающих 25+ видов узлов
4. **IR** (`query/ir.nim`): Промежуточное представление для планов выполнения
5. **Оптимизатор** (`query/adaptive.nim`): Адаптивная кросс-модальная оптимизация запросов
6. **Кодоген** (`query/codegen.nim`): Трансляция IR в операции хранилища
7. **Исполнитель** (`query/executor.nim`): Выполнение планов с параллелизацией

### Кросс-модальное планирование

Оптимизатор (`query/adaptive.nim`) определяет порядок выполнения между движками:

```
1. Оценить селективность каждого предиката
2. Направить наиболее селективный предикат в его движок первым
3. Использовать bloom-фильтры для KV поисков
4. Параллелизовать независимые ветви
5. Потоковая передача результатов для избежания материализации
```

## Слой 3: Движок выполнения

### Документный/KV движок
- **LSM-Tree** (`storage/lsm.nim`): Хранилище с оптимизацией записи с MemTable, WAL, SSTables
- **B-Tree индекс** (`storage/btree.nim`): Упорядоченный индекс для диапазонных сканирований с COW

### Векторный движок (`vector/`)
- **HNSW индекс** (`vector/engine.nim`): Иерархический навигируемый граф малого мира
- **IVF-PQ индекс** (`vector/engine.nim`): Инвертированный файловый индекс с продуктовым квантованием
- **SIMD операции** (`vector/simd.nim`): AVX2-оптимизированные вычисления расстояний
- **Квантование** (`vector/quant.nim`): Скалярное, продуктовое и бинарное квантование

### Графовый движок (`graph/`)
- **Список смежности** (`graph/engine.nim`): Граф с рёберными весами
- **Алгоритмы** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank
- **Обнаружение сообществ** (`graph/community.nim`): Алгоритм Louvain
- **Сопоставление шаблонов** (`graph/community.nim`): Изоморфизм подграфов
- **Cypher парсер** (`graph/cypher.nim`): Cypher-подобные графовые запросы

### Полнотекстовый поиск (`fts/`)
- **Инвертированный индекс** (`fts/engine.nim`): Терм-документ индекс
- **Ранжирование** (`fts/engine.nim`): BM25 и TF-IDF scoring
- **Нечёткий поиск** (`fts/engine.nim`): Сопоставление по расстоянию Левенштейна
- **Многоязычность** (`fts/multilang.nim`): Токенизаторы для EN, BG, DE, FR, RU

### Колоночный движок (`core/columnar.nim`)
- Поколоночное хранение для аналитических запросов
- RLE и словарное кодирование
- SIMD-ускоренные агрегаты

## Слой 4: Хранилище

- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom Filter, Компактификация
- **Page Cache** (`storage/compaction.nim`): LRU кэш с отслеживанием hit rate
- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-based доступ к файлам
- **Восстановление** (`storage/recovery.nim`): WAL replay и восстановление после сбоев

### Путь записи

```
Клиент → Протокол → Auth → Парсер → AST → IR → Кодоген
  → StorageOp → MVCC Txn → WAL Write → MemTable → Commit
```

### Путь чтения

```
Клиент → Протокол → Auth → Парсер → AST → IR → Кодоген
  → StorageOp → MVCC Snapshot → MemTable → SSTable → Result
```

## Слой 5: Распределённость

- **Raft Consensus** (`core/raft.nim`): Лидер-выборы, репликация лога
- **Шардирование** (`core/sharding.nim`): Hash, range и consistent hashing
- **Репликация** (`core/replication.nim`): Sync, async, semi-sync режимы
- **Gossip протокол** (`core/gossip.nim`): SWIM-like управление членством
- **Распределённые транзакции** (`core/disttxn.nim`): Two-phase commit

## Ключевые архитектурные решения

1. **Чистый Nim**: Без Cython, Python или Rust зависимостей
2. **Унифицированное хранилище**: Один движок для KV, графов, векторов, FTS и колоночного
3. **Встраиваемый режим**: Может работать как библиотека или сервер
4. **Бинарный протокол**: Кастомный эффективный wire протокол
5. **MVCC**: Многоверсионное управление параллелизмом
6. **Схема-первый**: Строго типизированная система схем с наследованием
7. **Кросс-модальность**: Единый язык запросов для всех моделей данных
8. **Формальная верификация**: Основные распределённые алгоритмы специфицированы в TLA+ и проверены с TLC

## Статистика по модулям

| Категория | Модули | Строк кода | Назначение |
|----------|---------|------------|------------|
| Core | 16 | ~4,200 | Сервер, протоколы, транзакции, распределённость |
| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, bloom, компактификация, mmap |
| Query | 7 | ~2,800 | Лексер, парсер, AST, IR, оптимизатор, кодоген, исполнитель |
| Vector | 3 | ~1,200 | HNSW, IVF-PQ, квантование, SIMD |
| Graph | 3 | ~1,000 | Список смежности, алгоритмы, обнаружение сообществ |
| FTS | 2 | ~900 | Инвертированный индекс, BM25, нечёткий, многоязычный |
| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, пул, auth, rate limit, SSL |
| Schema | 1 | ~600 | Типы, связи, наследование, миграции |
| Client | 2 | ~800 | Nim binary клиент, файловые хелперы |
| CLI | 1 | ~400 | Интерактивная BaraQL оболочка |
| **Всего** | **49** | **~14,100** | |

## Диаграммы потока данных

### Простой запрос

```
┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
│ Client │───→│ Lexer  │───→│ Parser │───→│  IR    │───→│ Codegen│
└────────┘    └────────┘    └────────┘    └────────┘    └───┬────┘
                                                             │
┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐       │
│ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘
└────────┘    └────────┘    └────────┘    └────────┘
```

### Кросс-модальный запрос

```
                     ┌─────────────┐
                     │   Parser    │
                     └──────┬──────┘
                            │
                     ┌──────▼──────┐
                     │   Adaptive  │
                     │   Optimizer │
                     └──────┬──────┘
                            │
            ┌───────────────┼───────────────┐
            │               │               │
     ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
     │    Vector   │ │    Graph    │ │     FTS     │
     │    Engine   │ │    Engine   │ │   Engine    │
     └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
            │               │               │
            └───────────────┼───────────────┘
                            │
                     ┌──────▼──────┐
                     │    Join     │
                     │   & Sort    │
                     └──────┬──────┘
                            │
                     ┌──────▼──────┐
                     │    Result   │
                     └─────────────┘
```