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,62 @@
+# API البروتوكول الثنائي
+
+بروتوكول سلكي منخفض المستوى لاتصالات العميل عالية الأداء.
+
+## تنسيق الرسالة
+
+جميع الرسائل تستخدم ترتيب big-endian:
+
+```
+┌────────┬────────┬────────┬────────┬─────────────┐
+│ Length │  Type  │  Seq   │ Status │   Payload   │
+│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │  N bytes    │
+└────────┴────────┴────────┴────────┴─────────────┘
+```
+
+## أنواع الرسائل
+
+### Query (0x01)
+
+```nim
+let msg = makeQueryMessage(seq, "SELECT * FROM users")
+```
+
+### Insert (0x02)
+
+```nim
+let msg = makeInsertMessage(seq, "users", data)
+```
+
+### Update (0x03)
+
+```nim
+let msg = makeUpdateMessage(seq, "users", updates, where)
+```
+
+### Delete (0x04)
+
+```nim
+let msg = makeDeleteMessage(seq, "users", where)
+```
+
+### Ready (0x05)
+
+```nim
+let msg = makeReadyMessage(seq)
+```
+
+### Error (0x06)
+
+```nim
+let msg = makeErrorMessage(seq, code, message)
+```
+
+## رموز الاستجابة
+
+| الرمز | الاسم | الوصف |
+|-------|-------|-------|
+| 0x00 | OK | نجاح |
+| 0x01 | ERROR | خطأ عام |
+| 0x02 | AUTH_REQUIRED | مطلوب مصادقة |
+| 0x03 | INVALID_QUERY | خطأ في بناء الجملة |
+| 0x04 | NOT_FOUND | المورد غير موجود |
@@ -0,0 +1,62 @@
+# API HTTP/REST
+
+API REST مبني على JSON لتطبيقات الويب.
+
+## Base URL
+
+```
+http://localhost:9470/api
+```
+
+## نقاط النهاية
+
+### GET /api/users
+
+قائمة جميع المستخدمين:
+
+```bash
+curl http://localhost:9470/api/users
+```
+
+### GET /api/users/:id
+
+الحصول على المستخدم بالـ ID:
+
+```bash
+curl http://localhost:9470/api/users/1
+```
+
+### POST /api/users
+
+إنشاء مستخدم:
+
+```bash
+curl -X POST http://localhost:9470/api/users \
+  -d '{"Name": "Charlie", "age": 35}'
+```
+
+### PUT /api/users/:id
+
+تحديث مستخدم:
+
+```bash
+curl -X PUT http://localhost:9470/api/users/1 \
+  -d '{"Name": "Alice", "age": 31}'
+```
+
+### DELETE /api/users/:id
+
+حذف مستخدم:
+
+```bash
+curl -X DELETE http://localhost:9470/api/users/1
+```
+
+## نقطة نهاية الاستعلام
+
+تنفيذ استعلامات BaraQL عبر HTTP:
+
+```bash
+curl -X POST http://localhost:9470/api/query \
+  -d '{"sql": "SELECT * FROM users WHERE age > 18"}'
+```
@@ -0,0 +1,78 @@
+# API WebSocket
+
+دفق كامل للاتجاهين لتغذية البيانات في الوقت الفعلي والإشعارات.
+
+## الاتصال
+
+```
+ws://localhost:9471/ws
+```
+
+## مثال العميل
+
+```javascript
+const ws = new WebSocket('ws://localhost:9471/ws');
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'query',
+    sql: 'SELECT * FROM users'
+  }));
+};
+
+ws.onmessage = (event) => {
+  console.log('Received:', JSON.parse(event.data));
+};
+```
+
+## تنسيق الرسالة
+
+```json
+{
+  "type": "query",
+  "id": "uuid",
+  "sql": "SELECT * FROM users"
+}
+```
+
+## أنواع الرسائل
+
+### طلب الاستعلام
+
+```json
+{
+  "type": "query",
+  "id": "123",
+  "sql": "SELECT * FROM users"
+}
+```
+
+### استجابة الاستعلام
+
+```json
+{
+  "type": "result",
+  "id": "123",
+  "data": [{"id": 1, "name": "Alice"}]
+}
+```
+
+### الاشتراك
+
+```json
+{
+  "type": "subscribe",
+  "table": "users"
+}
+```
+
+### إشعار
+
+```json
+{
+  "type": "push",
+  "table": "users",
+  "action": "insert",
+  "data": {"id": 3, "name": "Charlie"}
+}
+```
@@ -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** | |
@@ -0,0 +1,82 @@
+# النسخ الاحتياطي والاستعادة
+
+## لقطات عبر الإنترنت
+
+تدعم BaraDB اللقطات عبر الإنترنت دون إيقاف الخادم.
+
+### إنشاء لقطة
+
+```nim
+import barabadb/core/backup
+
+var bm = newBackupManager()
+bm.createSnapshot("/backup/baradb_2025-01-15")
+```
+
+### عبر CLI
+
+```bash
+./build/baradadb --snapshot --output=/backup/snapshot.db
+```
+
+### عبر HTTP API
+
+```bash
+curl -X POST http://localhost:9470/api/backup \
+  -d '{"destination": "/backup/snapshot.db"}'
+```
+
+### النسخ الاحتياطي التلقائي
+
+```bash
+0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
+find /backup -name "baradb_*.db" -mtime +7 -delete
+```
+
+## استعادة نقطة في الوقت (PITR)
+
+### الاستعادة من اللقطة + WAL
+
+```bash
+./build/baradadb --recover \
+  --checkpoint=/backup/snapshot.db \
+  --wal-dir=/backup/wal
+```
+
+### الاستعادة عبر SQL
+
+```sql
+RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
+```
+
+## سيناريوهات استعادة الكوارث
+
+### السيناريو 1: تلف الملف
+
+```bash
+cp /backup/sstables/000012.sst ./data/sstables/
+./build/baradadb --rebuild-index
+```
+
+### السيناريو 2: فقدان البيانات الكامل
+
+```bash
+cp /backup/snapshot.db ./data/
+./build/baradadb --recover --wal-dir=/backup/wal
+```
+
+### السيناريو 3: فشل عقدة الكتلة
+
+```bash
+BARADB_RAFT_NODE_ID=newnode \
+BARADB_RAFT_PEERS=node1:9001,node2:9001 \
+./build/baradadb
+```
+
+## أفضل الممارسات
+
+1. اختبار الاستعادة بانتظام
+2. تخزين النسخ الاحتياطية خارج الموقع
+3. تشفير النسخ الاحتياطية
+4. مراقبة مهام النسخ الاحتياطي
+5. توثيق RTO/RPO
@@ -0,0 +1,101 @@
+# مرجع لغة استعلام BaraQL
+
+BaraQL هي لغة استعلام متوافقة مع SQL مع امتدادات لعمليات الرسم البياني والمتجة والمستندات.
+
+## أنواع البيانات
+
+| النوع | الوصف | مثال |
+|-------|-------|------|
+| `null` | قيمة فارغة | `null` |
+| `bool` | منطقي | `true`, `false` |
+| `int8` | عدد صحيح 8 بت | `127` |
+| `int16` | عدد صحيح 16 بت | `32767` |
+| `int32` | عدد صحيح 32 بت | `2147483647` |
+| `int64` | عدد صحيح 64 بت | `9223372036854775807` |
+| `float32` | فاصلة عائمة 32 بت | `3.14` |
+| `float64` | فاصلة عائمة 64 بت | `3.14159265359` |
+| `str` | سلسلة UTF-8 | `'hello'` |
+| `vector` | متجه float32 | `[0.1, 0.2, 0.3]` |
+| `datetime` | طابع زمني ISO 8601 | `'2025-01-15T10:30:00Z'` |
+| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` |
+
+## الاستعلامات الأساسية
+
+### SELECT
+
+```sql
+SELECT * FROM users;
+SELECT name, age FROM users;
+SELECT name AS full_name FROM users;
+SELECT * FROM users LIMIT 10 OFFSET 20;
+```
+
+### WHERE
+
+```sql
+SELECT * FROM users WHERE age > 18;
+SELECT * FROM users WHERE age BETWEEN 18 AND 65;
+SELECT * FROM users WHERE department IN ('Engineering', 'Sales');
+SELECT * FROM users WHERE name LIKE 'A%';
+```
+
+### INSERT
+
+```sql
+INSERT users { name := 'Alice', age := 30 };
+```
+
+### UPDATE
+
+```sql
+UPDATE users SET age = 31 WHERE name = 'Alice';
+```
+
+### DELETE
+
+```sql
+DELETE FROM users WHERE name = 'Bob';
+```
+
+## JOIN
+
+```sql
+SELECT u.name, o.total
+FROM users u
+INNER JOIN orders o ON u.id = o.user_id;
+```
+
+## CTE (تعبيرات الجدول المشترك)
+
+```sql
+WITH active_users AS (
+  SELECT * FROM users WHERE active = true
+)
+SELECT * FROM active_users;
+```
+
+## البحث المتجهي
+
+```sql
+INSERT articles { title := 'Nim Programming', embedding := [0.1, 0.2, 0.3, 0.4] };
+
+SELECT title FROM articles
+ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
+LIMIT 5;
+```
+
+## أنماط الرسم البياني
+
+```sql
+MATCH (p:Person)-[:KNOWS]->(friend:Person)
+WHERE p.name = 'Alice'
+RETURN friend.name;
+```
+
+## المعاملات
+
+```sql
+BEGIN;
+INSERT users { name := 'Alice', age := 30 };
+COMMIT;
+```
@@ -0,0 +1,26 @@
+# فهرس B-Tree
+
+هيكل فهرس مرتب للبحث النطاقي والنقطة الفعال.
+
+## الاستخدام
+
+```nim
+import barabadb/storage/btree
+
+var btree = newBTreeIndex[string, string]()
+
+btree.insert("key1", "value1")
+btree.insert("key2", "value2")
+
+let values = btree.get("key1")
+let range = btree.scan("key_a", "key_z")
+btree.delete("key1")
+```
+
+## الميزات
+
+- تخزين مفاتي-قيم مرتب
+- استعلامات النطاق (BETWEEN, >, <, >=, <=)
+- المسح بالبادئة
+- حجم الصفحة القابل للتكوين
+- دعم المكرر
@@ -0,0 +1,76 @@
+# سجل التغييرات
+
+## [0.1.0] — 2025-01-15
+
+### المضاف
+
+- **محركات التخزين الأساسية**
+  - LSM-Tree مع MemTable و WAL و SSTables و size-tiered compaction
+  - فهرس B-Tree مرتب مع المسح النطاقي و MVCC copy-on-write
+  - فلاتر Bloom
+  - I/O المعينة بالذاكرة
+  - ذاكرة صفحة LRU
+
+- **محرك الاستعلام (BaraQL)**
+  - lexer متوافق مع SQL مع 80+ نوع رمز
+  - parser تنازلي تكراري ينتج AST مع 25+ نوع عقدة
+  - تمثيل وسيط (IR)
+  - محسن استعلام تكيفي مع تخطيط عبر الأنماط
+  - منفذ استعلام مع 병렬화
+
+- **ميزات لغة BaraQL**
+  - SELECT و INSERT و UPDATE و DELETE
+  - WHERE و ORDER BY و LIMIT و OFFSET
+  - GROUP BY و HAVING ودوال التجميع
+  - INNER JOIN و LEFT JOIN و RIGHT JOIN و FULL JOIN و CROSS JOIN
+  - CTEs مع WITH
+  - الاستعلامات الفرعية
+  - تعبيرات CASE
+  - UNION و INTERSECT و EXCEPT
+
+- **محرك المتجهات**
+  - فهرس HNSW
+  - فهرس IVF-PQ
+  - دوال المسافة المحسنة بـ SIMD
+  - التكميم: 8-bit/4-bit القياسي والمنتج والثنائي
+
+- **محرك الرسم البياني**
+  - تخزين قائمة المجاورة
+  - BFS و DFS للعبور
+  - Dijkstra لأقصر مسار
+  - PageRank
+  - Louvain لكشف المجتمع
+  - محلل استعلامات Cypher
+
+- **البحث النصي الكامل**
+  - الفهرس المقلوب
+  - ترتيب BM25
+  - TF-IDF
+  - البحث الغامض
+  - tokenizers متعدد اللغات
+
+- **البروتوكولات**
+  - بروتوكول Wire الثنائي مع 16 نوع رسالة
+  - API HTTP/REST JSON
+  - WebSocket للدفق
+  - تجميع الاتصالات
+  - مصادقة JWT
+  - TLS/SSL
+
+- **الأنظمة الموزعة**
+  - توافق Raft
+  - تجزئة hash و range و consistent-hash
+  - نسخ متزامن/غير متزامن/شبه متزامن
+  - بروتوكول Gossip
+  - commit على مرحلتين
+
+### الأداء
+
+- LSM-Tree: 580K كتابة/ثانية، 720K قراءة/ثانية
+- B-Tree: 1.2M إدراج/ثانية، 1.5M بحث/ثانية
+- Vector SIMD: 850K مسافة جيب التمام/ثانية (dim=768)
+
+### الاختبارات
+
+- 262 اختبار عبر 56 مجموعة اختبار
+- 100% معدل النجاح
@@ -0,0 +1,66 @@
+# حزم العملاء
+
+توفر BaraDB مكتبات العملاء الرسمية لـ JavaScript/TypeScript و Python و Nim و Rust.
+
+## JavaScript / TypeScript
+
+### التثبيت
+
+```bash
+npm install baradb
+```
+
+### الاستخدام الأساسي
+
+```typescript
+import { Client } from 'baradb';
+
+const client = new Client('localhost', 9472);
+await client.connect();
+
+const result = await client.query('SELECT name, age FROM users WHERE age > 18');
+```
+
+## Python
+
+### التثبيت
+
+```bash
+pip install baradb
+```
+
+### الاستخدام الأساسي
+
+```python
+from baradb import Client
+
+client = Client("localhost", 9472)
+client.connect()
+result = client.query("SELECT name, age FROM users WHERE age > 18")
+```
+
+## Nim (الوضع المدمج)
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+db.put("key", cast[seq[byte]]("value"))
+let (found, val) = db.get("key")
+db.close()
+```
+
+## Rust
+
+```rust
+use baradb::Client;
+
+let mut client = Client::connect("localhost:9472").await?;
+```
+
+## HTTP/REST
+
+```bash
+curl -X POST http://localhost:9470/api/query \
+  -d '{"query": "SELECT * FROM users"}'
+```
@@ -0,0 +1,50 @@
+# التخزين العمودي
+
+تخزين موجهة للأعمدة للاستعلامات التحليلية والتجميعات.
+
+## الاستخدام
+
+```nim
+import barabadb/core/columnar
+
+var batch = newColumnBatch()
+var ageCol = batch.addInt64Col("age")
+var nameCol = batch.addStringCol("name")
+
+ageCol.appendInt64(25)
+nameCol.appendString("Alice")
+```
+
+## التجميعات
+
+```nim
+echo ageCol.sumInt64()
+echo ageCol.avgInt64()
+echo ageCol.minInt64()
+echo ageCol.maxInt64()
+```
+
+## الترميز
+
+### RLE
+
+```nim
+let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
+```
+
+### Dictionary
+
+```nim
+let dict = dictEncode(@["apple", "banana", "apple"])
+```
+
+## أنواع الأعمدة
+
+| النوع | الوصف |
+|-------|-------|
+| `int32` | عدد صحيح 32 بت |
+| `int64` | عدد صحيح 64 بت |
+| `float32` | فاصلة عائمة 32 بت |
+| `float64` | فاصلة عائمة 64 بت |
+| `string` | سلسلة متغيرة الطول |
+| `bool` | منطقي |
@@ -0,0 +1,96 @@
+# مرجع التكوين
+
+يمكن تكوين BaraDB عبر **متغيرات البيئة** أو **ملف التكوين** أو **علامات سطر الأوامر**.
+
+## ترتيب الأولوية
+
+1. علامات سطر الأوامر (الأعلى)
+2. متغيرات البيئة
+3. ملف التكوين (`baradb.conf` أو `baradb.json`)
+4. الإعدادات الافتراضية (الأدنى)
+
+## متغيرات البيئة
+
+### الشبكة
+
+| المتغير | الافتراضي | الوصف |
+|---------|-----------|-------|
+| `BARADB_ADDRESS` | `127.0.0.1` | عنوان الربط |
+| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
+| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP/REST API |
+| `BARADB_WS_PORT` | `9471` | منفذ WebSocket |
+
+### التخزين
+
+| المتغير | الافتراضي | الوصف |
+|---------|-----------|-------|
+| `BARADB_DATA_DIR` | `./data` | مسار دليل البيانات |
+| `BARADB_MEMTABLE_SIZE_MB` | `64` | حجم MemTable (MB) |
+| `BARADB_CACHE_SIZE_MB` | `256` | حجم ذاكرة الصفحة (MB) |
+
+### TLS/SSL
+
+| المتغير | الافتراضي | الوصف |
+|---------|-----------|-------|
+| `BARADB_TLS_ENABLED` | `false` | تمكين TLS |
+| `BARADB_CERT_FILE` | — | مسار شهادة TLS |
+| `BARADB_KEY_FILE` | — | مسار مفتاح TLS الخاص |
+
+### الأمان
+
+| المتغير | الافتراضي | الوصف |
+|---------|-----------|-------|
+| `BARADB_AUTH_ENABLED` | `false` | تمكين المصادقة |
+| `BARADB_JWT_SECRET` | — | سر توقيع JWT |
+| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | طلبات/ثانية عامة |
+| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | طلبات/ثانية لكل عميل |
+
+## ملف التكوين
+
+### baradb.conf
+
+```ini
+[server]
+address = "0.0.0.0"
+port = 9472
+http_port = 9470
+
+[storage]
+data_dir = "/var/lib/baradb"
+memtable_size_mb = 256
+cache_size_mb = 512
+
+[tls]
+enabled = true
+cert_file = "/etc/baradb/server.crt"
+key_file = "/etc/baradb/server.key"
+
+[auth]
+enabled = true
+jwt_secret = "change-me-in-production"
+```
+
+## علامات سطر الأوامر
+
+```bash
+./build/baradadb --help
+```
+
+## أمثلة التكوين
+
+### التطوير
+
+```bash
+./build/baradadb --log-level debug --data-dir ./dev_data
+```
+
+### الإنتاج - عقدة واحدة
+
+```bash
+BARADB_TLS_ENABLED=true \
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
+BARADB_MEMTABLE_SIZE_MB=256 \
+BARADB_CACHE_SIZE_MB=1024 \
+./build/baradadb
+```
@@ -0,0 +1,48 @@
+# الاستعلامات عبر الأنماط
+
+القدرة الفريدة لـ BaraDB هي تنفيذ استعلامات تمتد عبر محركات تخزين متعددة في بيان BaraQL موحد واحد.
+
+## نظرة عامة
+
+- **مستند/KV** (LSM-Tree) — السجلات المهيكلة
+- **رسم بياني** (قائمة المجاورة) — العلاقات
+- **متجهي** (HNSW/IVF-PQ) — بحث التشابه
+- **نص كامل** (الفهرس المقلوب) — البحث النصي
+- **عمودي** — التجميعات التحليلية
+
+## أنماط الاستعلام
+
+### متجه + نص كامل
+
+```sql
+SELECT title FROM articles
+WHERE MATCH(body) AGAINST('machine learning')
+ORDER BY cosine_distance(embedding, [...])
+LIMIT 10;
+```
+
+### رسم بياني + متجه
+
+```sql
+MATCH (u:User)-[:KNOWS]->(friend:User)
+WHERE u.name = 'Alice'
+ORDER BY cosine_distance(friend.taste_vector, u.taste_vector)
+RETURN friend.name;
+```
+
+## التحسين
+
+### مخطط استعلام عبر الأنماط
+
+1. العامل الأكثر انتقائية أولاً
+2. دفع المسندات إلى كل محرك
+3. استخدام فلاتر Bloom لعمليات KV
+4. 병렬화 الفروع المستقلة
+
+## الأداء
+
+| نوع الاستعلام | التأخير (10K صف) |
+|---------------|------------------|
+| FTS + Vector | 15 ms |
+| Graph + Vector | 25 ms |
+| FTS + Aggregate | 12 ms |
@@ -0,0 +1,68 @@
+# دليل النشر
+
+## Docker
+
+### البداية السريعة
+
+```bash
+docker build -t baradb:latest .
+docker compose up -d
+docker compose ps
+```
+
+### ملفات Docker Compose
+
+| الملف | الغرض |
+|-------|-------|
+| `docker-compose.yml` | التطوير |
+| `docker-compose.prod.yml` | الإنتاج |
+
+## المنافذ
+
+| المنفذ | الوصف |
+|--------|-------|
+| `9472` | بروتوكول Wire الثنائي |
+| `9470` | HTTP/REST API |
+| `9471` | WebSocket |
+
+## متغيرات البيئة
+
+| المتغير | الافتراضي | الوصف |
+|---------|-----------|-------|
+| `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع |
+| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
+| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP |
+| `BARADB_DATA_DIR` | `/data` | دليل البيانات |
+
+## المجلدات
+
+| المسار | الوصف |
+|--------|-------|
+| `/data` | دليل البيانات الرئيسي |
+| `/data/server/wal` | سجل write-ahead |
+| `/data/server/sstables` | ملفات SSTable |
+
+## قائمة التحقق للإنتاج
+
+- [ ] إنشاء شهادات TLS في `./certs/`
+- [ ] تعيين `BARADB_JWT_SECRET` قوي
+- [ ] تكوين قواعد جدار الحماية
+- [ ] تكوين النسخ الاحتياطي المنتظم
+- [ ] التحقق من حدود الموارد
+- [ ] تكوين المراقبة
+
+## TLS في Docker
+
+```bash
+mkdir -p certs
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout certs/server.key -out certs/server.crt
+```
+
+## النسخ الاحتياطي في Docker
+
+```bash
+docker exec baradb /app/backup backup --data-dir=/data
+docker exec baradb /app/backup list
+docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
+```
@@ -0,0 +1,73 @@
+# الأنظمة الموزعة
+
+تدعم BaraDB النشر الموزع مع توافق Raft والتجزئة والنسخ.
+
+## توافق Raft
+
+انتخاب القائد ونسخ السجل:
+
+```nim
+import barabadb/core/raft
+
+var cluster = newRaftCluster()
+cluster.addNode("node1")
+cluster.addNode("node2")
+cluster.addNode("node3")
+
+let n1 = cluster.nodes["n1"]
+n1.becomeCandidate()
+n1.becomeLeader()
+```
+
+## التجزئة
+
+```nim
+import barabadb/core/sharding
+
+var router = newShardRouter(ShardConfig(
+  numShards: 4,
+  replicas: 2,
+  strategy: ssHash
+))
+```
+
+### استراتيجيات التجزئة
+
+| الاستراتيجية | الوصف |
+|-------------|-------|
+| `ssHash` | تجزئة قائمة على hash |
+| `ssRange` | تجزئة قائمة على النطاق |
+| `ssConsistent` | تجزئة متسقة |
+
+## النسخ
+
+```nim
+import barabadb/core/replication
+
+var rm = newReplicationManager(rmSync)
+rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
+```
+
+### أوضاع النسخ
+
+| الوضع | الوصف |
+|-------|-------|
+| `rmSync` | نسخ متزامن |
+| `rmAsync` | نسخ غير متزامن |
+| `rmSemiSync` | نسخ شبه متزامن |
+
+## المعاملات الموزعة
+
+الالتزام على مرحلتين:
+
+```nim
+import barabadb/core/disttxn
+
+var dt = newDistributedTxn()
+dt.prepare(@["node1", "node2"])
+dt.commit()
+```
+
+## التحقق الرسمي
+
+تم تحديد الخوارزميات الموزعة الأساسية في TLA+ والتحقق منها.
@@ -0,0 +1,78 @@
+# دليل نشر Docker
+
+## البداية السريعة
+
+```bash
+git clone https://github.com/katehonz/barabaDB.git
+cd barabaDB
+
+docker build -t baradb:latest .
+
+docker compose up -d
+
+docker compose ps
+docker compose logs -f
+```
+
+## الملفات
+
+| الملف | الوصف |
+|-------|-------|
+| `Dockerfile` | بناء multi-stage للإنتاج |
+| `docker-compose.yml` | تكوين التطوير |
+| `docker-compose.prod.yml` | تكوين الإنتاج |
+
+## بناء الصورة
+
+```bash
+docker build -t baradb:latest .
+```
+
+## التشغيل
+
+### التطوير
+
+```bash
+docker compose up -d
+docker compose down
+```
+
+### الإنتاج
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+## المنافذ
+
+| المنفذ | الوصف |
+|--------|-------|
+| `9472` | بروتوكول Wire الثنائي |
+| `9470` | HTTP/REST API |
+| `9471` | WebSocket |
+
+## متغيرات البيئة
+
+| المتغير | الافتراضي | الوصف |
+|---------|-----------|-------|
+| `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع |
+| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
+| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP |
+| `BARADB_DATA_DIR` | `/data` | دليل البيانات |
+
+## المجلدات
+
+| المسار | الوصف |
+|--------|-------|
+| `/data` | دليل البيانات الرئيسي |
+| `/data/server/wal` | سجل write-ahead |
+| `/data/server/sstables` | ملفات SSTable |
+
+## قائمة التحقق للإنتاج
+
+- [ ] إنشاء شهادات TLS في `./certs/`
+- [ ] تعيين `BARADB_JWT_SECRET` قوي
+- [ ] تكوين قواعد جدار الحماية
+- [ ] تكوين النسخ الاحتياطي المنتظم
+- [ ] التحقق من حدود الموارد
+- [ ] تكوين المراقبة
@@ -0,0 +1,47 @@
+# محرك البحث النصي الكامل
+
+فهرس مقلوب مع ترتيب BM25 و TF-IDF للبحث النصي.
+
+## الاستخدام
+
+```nim
+import barabadb/fts/engine
+
+var idx = newInvertedIndex()
+idx.addDocument(1, "Nim is a fast programming language")
+idx.addDocument(2, "Python is popular for data science")
+
+let results = idx.search("programming language")
+let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
+```
+
+## طرق الترتيب
+
+### BM25
+
+```nim
+let bm25 = idx.searchBM25("query terms")
+```
+
+### TF-IDF
+
+```nim
+let tfidf = idx.searchTfidf("query terms")
+```
+
+## ميزات البحث
+
+| الميزة | الوصف |
+|---------|-------|
+| Fuzzy search | تساهل مسافة Levenshtein |
+| Wildcard | بادئة، لاحقة،wildcard中间 |
+| Regex | أنماط التعبير العادي |
+| Phrase search | تطابق عبارة تامة |
+| Boolean | عوامل AND, OR, NOT |
+
+## واجهة SQL
+
+```sql
+CREATE INDEX idx_fts ON articles(body) USING FTS;
+SELECT * FROM articles WHERE body @@ 'machine learning';
+```
@@ -0,0 +1,42 @@
+# محرك الرسم البياني
+
+تخزين قائمة المجاورة مع خوارزميات مدمجة للعبور والتحليل.
+
+## الاستخدام
+
+```nim
+import barabadb/graph/engine
+
+var g = newGraph()
+let alice = g.addNode("Person", {"Name": "Alice"}.toTable)
+let bob = g.addNode("Person", {"Name": "Bob"}.toTable)
+discard g.addEdge(alice, bob, "knows")
+
+let bfs = g.bfs(alice)
+let path = g.shortestPath(alice, bob)
+let ranks = g.pageRank()
+```
+
+## الخوارزميات
+
+| الخوارزمية | الوصف |
+|------------|-------|
+| `bfs` | عبور بالعرض |
+| `dfs` | عبور بالعمق |
+| `dijkstra` | أقصر مسار موزون |
+| `pageRank` | ترتيب أهمية العقدة |
+| `louvain` | كشف المجتمع |
+| `patternMatch` | تماثل الرسم الفرعي |
+
+## استعلام Cypher
+
+```nim
+import barabadb/graph/cypher
+
+var engine = newCypherEngine(g)
+let results = engine.execute("""
+  MATCH (p:Person)-[:KNOWS]->(friend:Person)
+  WHERE p.name = 'Alice'
+  RETURN friend.name
+""")
+```
@@ -0,0 +1,59 @@
+# توثيق BaraDB (العربية)
+
+**محرك قاعدة بيانات متعدد الأنماط مكتوب بـ Nim — 100% أصلي، بدون تبعيات.**
+
+## روابط سريعة
+
+> **ملاحظة:** التوثيق العربي قيد التطوير. يرجى الرجوع إلى [النسخة الإنجليزية](../en/) للمعلومات الكاملة.
+
+### البدء
+- [التثبيت](../en/installation.md)
+- [البداية السريعة](../en/quickstart.md)
+- [نظرة عامة على البنية](../en/architecture.md)
+- [مرجع التكوين](../en/configuration.md)
+- [دليل النشر](../en/deployment.md)
+
+### المفاهيم الأساسية
+- [لغة استعلام BaraQL](../en/baraql.md)
+- [محركات التخزين](../en/storage.md)
+- [نظام المخطط](../en/schema.md)
+- [الاستعلامات عبر الأنماط](../en/crossmodal.md)
+
+### المحركات
+- [تخزين LSM-Tree](../en/lsm.md)
+- [فهرس B-Tree](../en/btree.md)
+- [البحث المتجهي](../en/vector.md)
+- [محرك الرسم البياني](../en/graph.md)
+- [البحث النصي الكامل](../en/fts.md)
+- [التخزين العمودي](../en/columnar.md)
+
+### API والعملاء
+- [SDK للعملاء](../en/clients.md)
+- [البروتوكول الثنائي](../en/api-binary.md)
+- [HTTP/REST API](../en/api-http.md)
+- [WebSocket API](../en/api-websocket.md)
+- [مرجع البروتوكول](../en/protocol.md)
+
+### العمليات
+- [الأداء والمعايير](../en/performance.md)
+- [دليل الأمان](../en/security.md)
+- [المراقبة](../en/monitoring.md)
+- [النسخ الاحتياطي والاستعادة](../en/backup.md)
+- [حل المشكلات](../en/troubleshooting.md)
+
+### متقدم
+- [المعاملات و MVCC](../en/transactions.md)
+- [الأنظمة الموزعة](../en/distributed.md)
+- [الدوال المحددة من المستخدم](../en/udf.md)
+
+---
+
+## معلومات المشروع
+
+- [سجل التغييرات](../en/changelog.md)
+- [الترخيص](../../LICENSE)
+- [مستودع GitHub](https://github.com/katehonz/barabaDB)
+
+---
+
+*التوثيق العربي قيد الترجمة.*
@@ -0,0 +1,62 @@
+# دليل تثبيت BaraDB
+
+## المتطلبات
+
+- **مترجم Nim** >= 2.2.0
+- **ملفات رأس OpenSSL** (لدعم TLS)
+- **نظام التشغيل**: لينكس، macOS، ويندوز
+
+### المنصات المدعومة
+
+| نظام التشغيل | البنية | الحالة |
+|-------------|--------|--------|
+| لينكس | x86_64 | ✅ دعم كامل |
+| لينكس | ARM64 | ✅ دعم كامل |
+| macOS | x86_64 | ✅ دعم كامل |
+| macOS | ARM64 | ✅ دعم كامل |
+| ويندوز | x86_64 | ✅ مدعوم |
+| FreeBSD | x86_64 | 🟡 اختبار المجتمع |
+
+## تثبيت Nim
+
+### لينكس
+
+```bash
+curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+```
+
+### macOS
+
+```bash
+brew install nim
+```
+
+### ويندوز
+
+```powershell
+winget install nim
+```
+
+## بناء BaraDB
+
+```bash
+git clone https://github.com/katehonz/barabaDB.git
+cd barabaDB
+nimble install -d -y
+nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
+```
+
+## التشغيل الأول
+
+```bash
+./build/baradadb
+curl http://localhost:9470/health
+./build/baradadb --shell
+```
+
+## الخطوات التالية
+
+- [دليل البداية السريعة](quickstart.md)
+- [مرجع التكوين](configuration.md)
+- [نظرة عامة على البنية](architecture.md)
+- [لغة استعلام BaraQL](baraql.md)
@@ -0,0 +1,48 @@
+# محرك تخزين LSM-Tree
+
+محرك التخزين الأساسي في BaraDB باستخدام بنية Log-Structured Merge-Tree.
+
+## البنية
+
+```
+┌─────────────────────────────────────────────┐
+│                   Writes                     │
+│         (append to WAL + MemTable)           │
+└─────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────┐
+│                  MemTable                    │
+│         (in-memory sorted buffer)            │
+└─────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────┐
+│                  SSTable                     │
+│          (sorted string table on disk)       │
+└─────────────────────────────────────────────┘
+```
+
+## الاستخدام
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+
+db.put("key1", cast[seq[byte]]("value1"))
+
+let (found, value) = db.get("key1")
+
+db.delete("key1")
+
+db.close()
+```
+
+## الميزات
+
+- **محسن للكتابة**: هيكل log-only إضافي
+- **الدائمة**: WAL يضمن استعادة بعد الانهيار
+- **Bloom Filter**: بحث سلبي سريع
+- **الضغط**: استراتيجية size-tiered
+- **ذاكرة الصفحة**: LRU للصفحاتaccessed بشكل متكرر
@@ -0,0 +1,84 @@
+# المراقبة والقابلية للملاحظة
+
+## فحوصات الصحة
+
+### نقطة نهاية صحة HTTP
+
+```bash
+curl http://localhost:9470/health
+```
+
+الاستجابة:
+
+```json
+{
+  "status": "healthy",
+  "version": "0.1.0",
+  "uptime_seconds": 86400,
+  "checks": {
+    "storage": "ok",
+    "memory": "ok",
+    "connections": "ok"
+  }
+}
+```
+
+## المقاييس
+
+### مقاييس متوافقة مع Prometheus
+
+```bash
+curl http://localhost:9470/metrics
+```
+
+مثال على المخرجات:
+
+```
+baradb_queries_total 152340
+baradb_queries_duration_seconds_bucket{le="0.001"} 45000
+baradb_storage_lsm_size_bytes 2147483648
+baradb_cache_hit_rate 0.94
+baradb_active_connections 42
+```
+
+## التسجيل
+
+### مستويات السجل
+
+| المستوى | الوصف |
+|---------|-------|
+| `debug` | عمليات داخلية مفصلة |
+| `info` | عمليات عادية |
+| `warn` | مشاكل قابلة للاسترداد |
+| `error` | فشل يستلزم الاهتمام |
+
+### سجلات JSON المهيكلة
+
+```bash
+BARADB_LOG_LEVEL=info \
+BARADB_LOG_FORMAT=json \
+BARADB_LOG_FILE=/var/log/baradb/baradb.log \
+./build/baradadb
+```
+
+## لوحة Grafana
+
+استيراد معرف اللوحة `baradb-001` أو استخدام JSON في `monitoring/grafana-dashboard.json`.
+
+اللوحات الرئيسية:
+- الاستعلامات في الثانية
+- نسب مئوية لتأخير الاستعلام (p50, p95, p99)
+- حجم التخزين وعدد SSTable
+- معدل إصابة ذاكرة التخزين المؤقت
+- الاتصالات النشطة
+- معدل المعاملات
+- معدل الأخطاء
+
+## حل المشكلات بالمقاييس
+
+| العَرَض | المقاييس | الإجراء |
+|---------|----------|---------|
+| استعلامات بطيئة | `baradb_queries_duration_seconds` | فحص معدل إصابة ذاكرة التخزين المؤقت، إضافة فهارس |
+| ذاكرة عالية | `process_resident_memory_bytes` | تقليل أحجام memtable/cache |
+| نمو التخزين | `baradb_storage_lsm_size_bytes` | تشغيل الضغط اليدوي |
+| أخطاء الاتصال | `baradb_active_connections` | زيادة تجمع الاتصالات أو إضافة العقد |
@@ -0,0 +1,68 @@
+# دليل الأداء
+
+## منهجية المعايير
+
+جميع المعايير تعمل بـ:
+- **المترجم**: Nim 2.2.0 مع `-d:release --opt:speed`
+- **CPU**: AMD Ryzen 9 5900X (12 نواة / 24 خيط)
+- **الذاكرة**: 64 GB DDR4-3600
+- **التخزين**: Samsung 980 Pro NVMe SSD
+
+```bash
+nim c -d:ssl -d:release -r benchmarks/bench_all.nim
+```
+
+## معايير محركات التخزين
+
+### LSM-Tree
+
+| المقاييس | القيمة |
+|----------|--------|
+| إنتاجية الكتابة | ~580,000 ops/s |
+| إنتاجية القراءة | ~720,000 ops/s |
+| متوسط تأخير الكتابة | 1.7 µs |
+| متوسط تأخير القراءة | 1.4 µs |
+
+### فهرس B-Tree
+
+| المقاييس | القيمة |
+|----------|--------|
+| إنتاجية الإدراج | ~1,200,000 ops/s |
+| إنتاجية البحث النقطي | ~1,500,000 ops/s |
+
+## معايير المحرك المتجهي
+
+### فهرس HNSW
+
+| المقاييس | القيمة |
+|----------|--------|
+| الإدراج (dim=128) | ~45,000 vectors/s |
+| البحث top-10 (n=100K) | ~8 ms |
+
+المعلمات: `M=16`, `efConstruction=200`, `efSearch=64`.
+
+## دليل الضبط
+
+### لأحمال الكتابة الثقيلة
+
+```bash
+BARADB_MEMTABLE_SIZE_MB=256
+BARADB_WAL_SYNC_INTERVAL_MS=10
+BARADB_COMPACTION_INTERVAL_MS=30000
+```
+
+### لأحمال القراءة الثقيلة
+
+```bash
+BARADB_CACHE_SIZE_MB=1024
+BARADB_BLOOM_BITS_PER_KEY=10
+BARADB_COMPACTION_INTERVAL_MS=120000
+```
+
+### للبحث المتجهي
+
+```bash
+BARADB_VECTOR_EF_CONSTRUCTION=200
+BARADB_VECTOR_EF_SEARCH=128
+BARADB_VECTOR_M=32
+```
@@ -0,0 +1,67 @@
+# مرجع البروتوكول
+
+يدعم BaraDB بروتوكولات متعددة للتواصل مع العملاء:
+- **Binary Wire Protocol** — عالي الأداء، منخفض التأخير
+- **HTTP/REST API** — لغةagnostic، سهل التصحيح
+- **WebSocket** — الدفق و pub/sub
+
+## Binary Wire Protocol
+
+يستخدم ترميز big-endian لجميع القيم متعددة البايت.
+
+### دورة الاتصال
+
+```
+Client                          Server
+  |                               |
+  |─── TCP connect ──────────────>|
+  |─── Auth message ─────────────>|
+  |<── Auth_OK / Error ───────────|
+  |─── Query message ────────────>|
+  |<── Data / Complete / Error ───|
+```
+
+### تنسيق الرسالة
+
+```
+┌─────────────┬─────────────┬─────────────┬─────────────────────┐
+│  Length     │  Type       │  Sequence   │  Payload            │
+│  (4 bytes)  │  (1 byte)   │  (1 byte)   │  (Length - 6 bytes) │
+└─────────────┴─────────────┴─────────────┴─────────────────────┘
+```
+
+### أنواع الرسائل
+
+| النوع | ID | الوصف |
+|-------|----|-------|
+| Query | 0x01 | تنفيذ استعلام |
+| Insert | 0x02 | إدراج بيانات |
+| Update | 0x03 | تحديث بيانات |
+| Delete | 0x04 | حذف بيانات |
+| Ready | 0x05 | جاهز للامر التالي |
+| Error | 0x06 | استجابة خطأ |
+
+## HTTP/REST API
+
+Base URL: `http://localhost:9470/api/v1`
+
+### نقاط النهاية
+
+#### Health
+
+```http
+GET /health
+```
+
+#### استعلام
+
+```http
+POST /query
+{
+  "query": "SELECT * FROM users"
+}
+```
+
+## WebSocket Protocol
+
+URL: `ws://localhost:9471`
@@ -0,0 +1,99 @@
+# دليل البداية السريعة لـ BaraDB
+
+## تشغيل الخادم
+
+```bash
+./build/baradadb
+```
+
+الخادم يبدأ افتراضياً على `localhost:9470`.
+
+## الاتصال عبر CLI
+
+```bash
+./build/baradadb --shell
+```
+
+## العمليات الأساسية
+
+### إنشاء المخطط
+
+```sql
+CREATE TYPE Person {
+  name: str,
+  age: int32
+};
+```
+
+### إدراج البيانات
+
+```sql
+INSERT Person { name := 'Alice', age := 30 };
+```
+
+### استعلام البيانات
+
+```sql
+SELECT name, age FROM Person WHERE age > 18;
+```
+
+### تحديث البيانات
+
+```sql
+UPDATE Person SET age = 31 WHERE name = 'Alice';
+```
+
+### حذف البيانات
+
+```sql
+DELETE FROM Person WHERE name = 'Bob';
+```
+
+## الاستعلامات المتقدمة
+
+### JOIN
+
+```sql
+SELECT u.name, o.total
+FROM users u
+INNER JOIN orders o ON u.id = o.user_id;
+```
+
+### CTE
+
+```sql
+WITH active_users AS (
+  SELECT * FROM users WHERE active = true
+)
+SELECT * FROM active_users;
+```
+
+## البحث المتجهي
+
+```sql
+INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] };
+SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10;
+```
+
+## عمليات الرسم البياني
+
+```sql
+MATCH (p:Person)-[:KNOWS]->(other:Person)
+WHERE p.name = 'Alice'
+RETURN other.name;
+```
+
+## HTTP/REST API
+
+```bash
+curl http://localhost:9470/api/users
+curl -X POST http://localhost:9470/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "age": 30}'
+```
+
+## الخطوات التالية
+
+- [مرجع BaraQL](baraql.md)
+- [محركات التخزين](storage.md)
+- [نظرة عامة على البنية](architecture.md)
@@ -0,0 +1,46 @@
+# نظام المخطط
+
+يستخدم BaraDB تصميم schema-first مع وراثة النوع والهجرة التلقائية.
+
+## تحديد الأنواع
+
+```nim
+import barabadb/schema/schema
+
+var s = newSchema()
+
+let person = newType("Person")
+person.addProperty("name", "str", required = true)
+person.addProperty("age", "int32")
+s.addType("default", person)
+```
+
+## وراثة النوع
+
+```nim
+let employee = newType("Employee")
+employee.setBases(@["Person"])
+employee.addProperty("department", "str")
+s.addType("default", employee)
+```
+
+## عمليات المخطط
+
+### Diff
+
+```nim
+let diff = s.diff(oldSchema, newSchema)
+```
+
+## أنواع الخصائص
+
+| النوع | الوصف |
+|-------|-------|
+| `str` | سلسلة |
+| `int32` | عدد صحيح 32 بت |
+| `int64` | عدد صحيح 64 بت |
+| `float32` | فاصلة عائمة 32 بت |
+| `float64` | فاصلة عائمة 64 بت |
+| `bool` | منطقي |
+| `datetime` | تاريخ/وقت |
+| `bytes` | بيانات ثنائية |
@@ -0,0 +1,76 @@
+# دليل الأمان
+
+## تشفير TLS/SSL
+
+تدعم BaraDB TLS 1.3 لجميع البروتوكولات. إذا لم يتم توفير شهادة، ينشئ الخادم شهادة ذاتية التوقيع تلقائياً عند البدء.
+
+### استخدام شهادات مخصصة
+
+```bash
+BARADB_TLS_ENABLED=true \
+BARADB_CERT_FILE=/etc/baradb/server.crt \
+BARADB_KEY_FILE=/etc/baradb/server.key \
+./build/baradadb
+```
+
+### إنشاء شهادة ذاتية التوقيع
+
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
+  -days 365 -nodes -subj "/CN=localhost"
+```
+
+## المصادقة
+
+### المصادقة المبنية على JWT
+
+تستخدم BaraDB JWT مع توقيع HMAC-SHA256.
+
+### تمكين المصادقة
+
+```bash
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
+./build/baradadb
+```
+
+### التحكم في الوصول القائم على الأدوار
+
+| الدور | الأذونات |
+|-------|----------|
+| `admin` | وصول كامل |
+| `write` | قراءة + كتابة |
+| `read` | قراءة فقط |
+| `monitor` | المقاييس والصحة فقط |
+
+## تحديد المعدل
+
+منع إساءة الاستخدام:
+
+```nim
+var rl = newRateLimiter(
+  rlaTokenBucket,
+  globalRate = 10000,
+  perClientRate = 1000,
+  burstSize = 100
+)
+```
+
+## أمان الشبكة
+
+### عنوان الربط
+
+```bash
+BARADB_ADDRESS=0.0.0.0 ./build/baradadb
+```
+
+## قائمة التحقق الأمنية
+
+- [ ] تغيير سر JWT الافتراضي
+- [ ] تمكين TLS بشهادات صالحة
+- [ ] الربط بواجهات محددة
+- [ ] تمكين المصادقة في الإنتاج
+- [ ] تكوين تحديد المعدل
+- [ ] تمكين سجل التدقيق
+- [ ] تشفير البيانات في حالة السكون
+- [ ] تشغيل BaraDB كمستخدم غير root
@@ -0,0 +1,67 @@
+# محركات التخزين
+
+توفر BaraDB محركات تخزين متعددة محسنة لأنماط الوصول المختلفة.
+
+## LSM-Tree (مفتاح-قيمة)
+
+محرك التخزين الأساسي المحسن للكتابة مع بنية log-only إلحاقية.
+
+### الاستخدام
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+db.put("key1", cast[seq[byte]]("value1"))
+let (found, value) = db.get("key1")
+db.close()
+```
+
+### المكونات
+
+- **MemTable**: مخزن مؤقت مرتب في الذاكرة
+- **WAL**: سجل write-ahead للدائمة
+- **SSTable**: جداول السلاسل المرتبة على القرص
+- **Bloom Filter**: بنية احتمالية للبحث السلبي السريع
+- **الضغط**: استراتيجية ذات طبقات بحجم مع إدارة المستويات
+- **ذاكرة الصفحة**: ذاكرة مؤقتة LRU مع تتبع معدل الإصابة
+
+## فهرس B-Tree
+
+فهرس مرتب للبحث بالنطاق والبحث النقطي.
+
+### الاستخدام
+
+```nim
+import barabadb/storage/btree
+
+var btree = newBTreeIndex[string, string]()
+btree.insert("key1", "value1")
+let values = btree.get("key1")
+let range = btree.scan("key_a", "key_z")
+```
+
+## Write-Ahead Log (WAL)
+
+يضمن دائمة عمليات الكتابة.
+
+```nim
+import barabadb/storage/wal
+
+var wal = newWAL("./wal")
+wal.append("txn1", "SET key1 value1")
+wal.flush()
+```
+
+## Bloom Filter
+
+هيكل بيانات احتمالي للبحث السلبي السريع.
+
+```nim
+import barabadb/storage/bloom
+
+var filter = newBloomFilter(10000, 0.01)
+filter.add("key1")
+if filter.mightContain("key1"):
+  echo "ربما موجود"
+```
@@ -0,0 +1,47 @@
+# المعاملات و MVCC
+
+MVCC (تحكم التزامن متعدد الإصدارات) مع عزل اللقطة واكتشاف الجمود.
+
+## الاستخدام
+
+```nim
+import barabadb/core/mvcc
+
+var tm = newTxnManager()
+let txn = tm.beginTxn()
+
+discard tm.write(txn, "key1", cast[seq[byte]]("value1"))
+discard tm.write(txn, "key2", cast[seq[byte]]("value2"))
+
+tm.savepoint(txn)
+discard tm.write(txn, "key3", cast[seq[byte]]("value3"))
+discard tm.rollbackToSavepoint(txn)
+
+discard tm.commit(txn)
+```
+
+## عزل المعاملات
+
+تستخدم BaraDB **عزل اللقطة**:
+- القراء لا يحظرون الكتاب
+- الكتاب لا يحظرون القراء
+- كل معاملة ترى لقطة متسقة
+
+## اكتشاف الجمود
+
+```nim
+import barabadb/core/deadlock
+
+var detector = newDeadlockDetector()
+if detector.detectCycle(txn1, txn2):
+  echo "تم اكتشاف الجمود!"
+```
+
+## التحقق الرسمي
+
+تم تحديد بروتوكول MVCC/Snapshot Isolation رسمياً في TLA+:
+
+```bash
+cd formal-verification
+java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
+```
@@ -0,0 +1,81 @@
+# دليل حل المشكلات
+
+## مشاكل التثبيت
+
+### Nim غير موجود
+
+```bash
+curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+```
+
+### خطأ تجميع SSL
+
+```bash
+nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
+```
+
+### تبعيات مفقودة
+
+```bash
+nimble install -d -y
+```
+
+## مشاكل وقت التشغيل
+
+### المنفذ قيد الاستخدام
+
+```bash
+BARADB_PORT=5433 ./build/baradadb
+```
+
+### تم رفض الإذن
+
+```bash
+mkdir -p ./data
+chmod 755 ./data
+```
+
+### ذاكرة غير كافية
+
+```bash
+BARADB_MEMTABLE_SIZE_MB=32 \
+BARADB_CACHE_SIZE_MB=128 \
+./build/baradadb
+```
+
+## مشاكل الاستعلام
+
+### خطأ في الصياغة
+
+```sql
+SELECT name, age FROM users WHERE age > 18;
+```
+
+### الجدول غير موجود
+
+```sql
+CREATE TYPE User { name: str, age: int32 };
+```
+
+## مشاكل الاتصال
+
+### تم رفض الاتصال
+
+```bash
+./build/baradadb
+sudo ufw allow 9472
+```
+
+## مشاكل الأداء
+
+### استعلامات بطيئة
+
+1. إضافة فهارس: `CREATE INDEX idx_users_name ON users(name);`
+2. استخدام LIMIT
+3. زيادة ذاكرة التخزين المؤقت: `BARADB_CACHE_SIZE_MB=1024`
+
+## وضع التصحيح
+
+```bash
+BARADB_LOG_LEVEL=debug ./build/baradadb
+```
@@ -0,0 +1,47 @@
+# الدوال المحددة من المستخدم
+
+توسيع BaraQL بالدوال المخصصة.
+
+## الاستخدام
+
+```nim
+import barabadb/query/udf
+
+var reg = newUDFRegistry()
+
+reg.registerStdlib()
+
+reg.register("greet", @[UDFParam(name: "name", typeName: "str")],
+  "str", proc(args: seq[Value]): Value =
+    return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!"))
+```
+
+## دوال المكتبة القياسية
+
+| الدالة | الوصف | مثال |
+|--------|-------|------|
+| `abs(n)` | القيمة المطلقة | `abs(-5)` → 5 |
+| `sqrt(n)` | الجذر التربيعي | `sqrt(16)` → 4 |
+| `pow(n, e)` | الأس | `pow(2, 3)` → 8 |
+| `lower(s)` | حروف صغيرة | `lower('ABC')` → 'abc' |
+| `upper(s)` | حروف كبيرة | `upper('abc')` → 'ABC' |
+| `len(s)` | الطول | `len('hello')` → 5 |
+| `trim(s)` | إزالة المسافات | `trim(' hello ')` → 'hello' |
+
+## تسجيل الدالة
+
+```nim
+reg.register(
+  name: "my_function",
+  params: @[UDFParam(name: "arg1", typeName: "str")],
+  returnType: "str",
+  body: proc(args: seq[Value]): Value =
+    result = Value(kind: vkString, strVal: "")
+)
+```
+
+## استخدام UDF في الاستعلامات
+
+```sql
+SELECT greet(name) FROM users;
+```
@@ -0,0 +1,65 @@
+# محرك البحث المتجهي
+
+فهارس HNSW و IVF-PQ للبحث عن التشابه.
+
+## الاستخدام
+
+```nim
+import barabadb/vector/engine
+
+var idx = newHNSWIndex(dimensions = 128)
+idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable)
+
+let results = idx.search(queryVector, k = 10)
+```
+
+## أنواع الفهارس
+
+### HNSW
+
+رسم بياني Small World قابل للملاحة هرمي للبحث عن أقرب الجيران.
+
+```nim
+var hnsw = newHNSWIndex(
+  dimensions = 128,
+  m = 16,
+  efConstruction = 200,
+  efSearch = 100
+)
+```
+
+### IVF-PQ
+
+فهرس ملف مقلوب مع تكميم المنتج.
+
+```nim
+var ivfpq = newIVFPQIndex(
+  dimensions = 128,
+  numCentroids = 256,
+  subQuantizers = 8
+)
+```
+
+## مقاييس المسافة
+
+| المقياس | الوصف |
+|---------|-------|
+| `cosine` | تشابه جيب التمام |
+| `euclidean` | مسافة L2 |
+| `dotproduct` | تشابه المنتج النقطي |
+| `manhattan` | مسافة L1 |
+
+## التكميم
+
+```nim
+let scalar = scalarQuantize(data, bits = 8)
+let pq = productQuantize(data, subVectors = 8, bits = 8)
+```
+
+## تسريع SIMD
+
+```nim
+import barabadb/vector/simd
+
+let dist = simdCosineDistance(vec1, vec2)
+```