# بنية 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: طبقة العميل

- **البروتوكول الثنائي**: بروتوكول ثنائي فعال big-endian
- **HTTP/REST**: واجهة REST مبنية على JSON
- **WebSocket**: دفق ثنائي الاتجاه كامل
- **المدمج**: وصول مباشر داخل العملية

## الطبقة 2: طبقة الاستعلام (BaraQL)

1. **المحلل اللغوي** (`query/lexer.nim`): أكثر من 80 نوع رمز
2. **المحلل** (`query/parser.nim`): محلل تنازلي تكراري
3. **AST** (`query/ast.nim`): أكثر من 25 نوع عقدة
4. **IR** (`query/ir.nim`): تمثيل وسيط
5. **المحسن** (`query/adaptive.nim`): تحسين عبر الأنماط
6. **توليد الكود** (`query/codegen.nim`): ترجمة إلى عمليات التخزين
7. **المنفذ** (`query/executor.nim`): تنفيذ متوازي

## الطبقة 3: محركات التنفيذ

### محرك المستندات/KV
- **LSM-Tree** (`storage/lsm.nim`): MemTable، WAL، SSTables

### المحرك المتجهي (`vector/`)
- **فهرس HNSW** (`vector/engine.nim`): رسم بياني صغير قابل للملاحة هرمي
- **فهرس IVF-PQ**: ملف مقلوب مع تكميم المنتج
- **عمليات SIMD** (`vector/simd.nim`): محسّن بـ AVX2

### محرك الرسم البياني (`graph/`)
- BFS، DFS، Dijkstra، PageRank
- **Louvain**: كشف المجتمع

### البحث النصي الكامل (`fts/`)
- الفهرس المقلوب، BM25، TF-IDF
- **متعدد اللغات**: tokenizers لـ EN، BG، DE، FR، RU

## الطبقة 4: التخزين

- **LSM-Tree**: MemTable، WAL، SSTable، Bloom Filter
- **ذاكرة الصفحة**: ذاكرة مؤقتة LRU
- **I/O المعينة**: وصول قائم على mmap
- **الاستعادة**: إعادة تشغيل WAL

## الطبقة 5: الموزع

- **توافق Raft** (`core/raft.nim`): انتخاب القائد، نسخ السجل
- **التجزئة** (`core/sharding.nim`): hash، range، تجزئة متسقة
- **النسخ** (`core/replication.nim`): متزامن، غير متزامن، شبه متزامن
- **بروتوكول Gossip** (`core/gossip.nim`): مثل SWIM

## قرارات التصميم الرئيسية

1. **Nim نقي**: بدون تبعيات Cython أو Python أو Rust
2. **تخزين موحد**: محرك واحد لـ KV والرسم البياني والمتجة وFTS والعمودي
3. **الوضع المدمج**: يمكن تشغيله كمكتبة أو خادم
4. **البروتوكول الثنائي**: بروتوكول سلكي فعال مخصص
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، pool، auth، حد السعر، SSL |
| Schema | 1 | ~600 | الأنواع، الروابط، الوراثة |
| Client | 2 | ~800 | عميل Nim الثنائي |
| CLI | 1 | ~400 | صدفة BaraQL التفاعلية |
| **المجموع** | **49** | **~14,100** | |