Baradb/docs/ru/architecture.md

Архитектура 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   │
                     └─────────────┘