docs: add multi-language documentation (ru, fa, zh, tr, ar)

2026-05-07 23:42:55 +03:00
parent abb382c419
commit e9d3c7e9de
157 changed files with 14339 additions and 0 deletions
@@ -0,0 +1,102 @@
+# بنية 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** | |