# معماری 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   │
                     └─────────────┘
```