Baradb/docs/fa/architecture.md

معماری BaraDB

بررسی اجمالی

BaraDB یک موتور پایگاه داده چند حالته است که با Nim نوشته شده و ذخیره‌سازی سندی (KV)، گرافی، برداری، ستونی و جستجوی تمام‌متن را در یک موتور واحد با زبان پرس‌وجوی واحد BaraQL ترکیب می‌کند.

معماری لایه‌ای

┌─────────────────────────────────────────────────────────┐
│ 1. لایه کلاینت                                           │
│    پروتکل باینری │ HTTP/REST │ WebSocket │ توکار          │
├─────────────────────────────────────────────────────────┤
│ 2. لایه پرس‌وجو (BaraQL)                                │
│    لکسر → پارسر → AST → IR → بهینه‌ساز → کد‌ژن          │
├─────────────────────────────────────────────────────────┤
│ 3. موتور اجرا                                            │
│    سند │ گراف │ بردار │ ستونی │ FTS                      │
├─────────────────────────────────────────────────────────┤
│ 4. ذخیره‌سازی                                            │
│    LSM-Tree │ B-Tree │ WAL │ Bloom │ فشردهسازی │ کش      │
├─────────────────────────────────────────────────────────┤
│ 5. توزیع‌شده                                             │
│    Raft │ شاردینگ │ ریپلیکیشن │ Gossip                   │
└─────────────────────────────────────────────────────────┘

لایه 1: لایه کلاینت

چندین پروتکل ارتباطی:

• پروتکل باینری (protocol/wire.nim): پروتکل باینری کارآمد big-endian با 16 نوع پیام
• HTTP/REST (core/httpserver.nim): API REST مبتنی بر JSON با چند نخی
• 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): بهینه‌سازی تطبیقی کross-modal
6. کد‌ژن (query/codegen.nim): ترجمه IR به عملیات ذخیره‌سازی
7. اجراکننده (query/executor.nim): اجرای نقشه‌ها با موازی‌سازی

برنامه‌ریزی کross-modal

بهینه‌ساز (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): گراف Navigable Small World سلسله‌مراتبی
• اندیس 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
• جستجوی تقریبی (fts/engine.nim): تطبیق با فاصله Levenshtein
• چندزبانه (fts/multilang.nim): توکنایزرهایی برای EN، BG، DE، FR، RU

موتور ستونی (core/columnar.nim)

• ذخیره‌سازی هر-ستونی برای پرس‌وجوهای تحلیلی
• کدگذاری RLE و دیکشنری
• تجمیع‌های شتاب‌گرفته با SIMD

لایه 4: ذخیره‌سازی

• LSM-Tree (storage/lsm.nim): MemTable، WAL، SSTable، Bloom Filter، فشرده‌سازی
• کش صفحه (storage/compaction.nim): کش LRU با ردیابی نرخ hit
• I/O نگاشته‌شده به حافظه (storage/mmap.nim): دسترسی فایل مبتنی بر mmap
• بازیابی (storage/recovery.nim): بازپخش WAL و بازیابی پس از خرابی

مسیر نوشتن

کلاینت → پروتکل → احراز → پارسر → AST → IR → کد‌ژن
  → StorageOp → MVCC Txn → WAL Write → MemTable → Commit

مسیر خواندن

کلاینت → پروتکل → احراز → پارسر → 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-مانند
• تراکنش‌های توزیع‌شده (core/disttxn.nim): commit دو مرحله‌ای

تصمیمات کلیدی طراحی

1. Nim خالص: بدون وابستگی به Cython، Python یا Rust
2. ذخیره‌سازی یکپارچه: یک موتور برای KV، گراف، بردار، FTS و ستونی
3. حالت توکار: می‌تواند به‌عنوان کتابخانه یا سرور اجرا شود
4. پروتکل باینری: پروتکل سیمی کارآمد سفارشی
5. MVCC: کنترل همزمانی چندنسخه‌ای
6. طرحواره-اول: سیستم طرحواره با نوع قوی با وراثت
7. کross-modal: زبان پرس‌وجوی واحد در تمام مدل‌های داده
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، محدودیت نرخ، SSL
Schema	1	~600	انواع، لینک‌ها، وراثت، مهاجرت‌ها
Client	2	~800	کلاینت باینری Nim، کمکی فایل
CLI	1	~400	شل تعاملی BaraQL
مجموع	49	~14,100

نمودارهای جریان داده

پرس‌وجوی ساده

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

پرس‌وجوی کross-modal

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