# OmniRoute Codebase Documentation (العربية)

🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇿 [az](../../../az/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../../bg/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../../bn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇦 [bs](../../../bs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../../cs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../../da/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../../de/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇷 [el](../../../el/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../../es/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇪 [et](../../../et/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../../fa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../../fi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../../fr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇪 [ga](../../../ga/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../../gu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ha](../../../ha/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../../he/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../../hi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇷 [hr](../../../hr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../../hu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇲 [hy](../../../hy/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../../id/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ig](../../../ig/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../../it/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../../ja/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇪 [ka](../../../ka/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇭 [km](../../../km/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../../ms/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇵 [ne](../../../ne/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../../nl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../../no/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [or](../../../or/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [pa](../../../pa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../../phi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../../pl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../../pt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../../ro/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../../ru/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇰 [si](../../../si/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../../sk/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇮 [sl](../../../sl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇸 [sr](../../../sr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../../sv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../../sw/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../../ta/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../../te/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../../th/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../../tr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../../ur/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇿 [uz](../../../uz/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../../vi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [yo](../../../yo/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md)

---

> **الإصدار:** v3.8.51
> **آخر تحديث:** 2026-06-28
> **الجمهور المستهدف:** المهندسون المساهمون في OmniRoute أو الذين يبنون عمليات تكامل فوقه.
>
> للاطلاع على مخططات البنية عالية المستوى والأسباب الكامنة وراء كل نظام فرعي، اقرأ
> [ARCHITECTURE.md](./ARCHITECTURE.md). وللتعمق في الأنظمة الفرعية الفردية
> (Auto Combo، وخادم MCP، وخادم A2A، والمهارات، والذاكرة، والوكلاء السحابيون، والمرونة،
> والضغط، وما إلى ذلك)، راجع الملفات المخصصة لها في دليل `docs/` هذا.

يصف هذا الملف **ما هو موجود في المستودع اليوم** لكي يتمكن المهندس الجديد
من التنقل في الشجرة، وفهم طبقات وقت التشغيل، ومعرفة أين يضيف التعليمات البرمجية
من دون ابتكار وحدات جديدة.

---

## 1. المكدس التقني

| الجانب          | الخيار                                                                                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| إطار عمل الويب  | **Next.js 16** (موجّه التطبيقات، ومخرجات مستقلة، ومن دون برمجيات وسيطة عامة)                                                                               |
| اللغة           | **TypeScript 6.0+** — الهدف `ES2022`، و`module: esnext`، و`moduleResolution: bundler`، و`strict: false`                                                    |
| وقت التشغيل     | **Node.js** `>=22.22.2 <23` أو `>=24.0.0 <27` (يُفرض عبر `engines` + `SUPPORTED_NODE_RANGE`)                                                               |
| قاعدة البيانات  | **SQLite** عبر `better-sqlite3` (نسخة مفردة، وتسجيل يومي بنمط WAL)                                                                                         |
| سطح المكتب      | **Electron 41** + `electron-builder` 26.10 (مساحة عمل منفصلة في `electron/`)                                                                               |
| الاختبارات      | **مشغّل الاختبارات الأصلي في Node** (اختبارات الوحدة/التكامل)، و**Vitest** (MCP، وautoCombo، وذاكرة التخزين المؤقت)، و**Playwright** (e2e + protocols-e2e) |
| البناء          | مخرجات Next.js مستقلة عبر `scripts/build/build-next-isolated.mjs`                                                                                          |
| التدقيق/التنسيق | إعداد ESLint المسطح + Prettier (`lint-staged` عبر خطّاف Husky لما قبل الإيداع)                                                                             |
| نظام الوحدات    | ESM في كل مكان (`"type": "module"`)                                                                                                                        |
| مساحات العمل    | مساحة عمل npm — تُعد `open-sse` مساحة العمل الفرعية الوحيدة                                                                                                |

الأسماء المستعارة للمسارات (`tsconfig.json`):

- `@/*` → `src/*`
- `@omniroute/open-sse` → `open-sse/index.ts`
- `@omniroute/open-sse/*` → `open-sse/*`

منفذ HTTP الافتراضي: **`20128`** (تتشارك واجهة API ولوحة المعلومات العملية نفسها). دليل
البيانات هو متغير البيئة `DATA_DIR`، ويكون افتراضيًا `~/.omniroute/`.

---

## 2. بنية المستودع

```
OmniRoute/
├── src/                  تطبيق Next.js (موجّه التطبيقات، والمكتبات، والمجال، والخادم، والمكونات المشتركة)
├── open-sse/             مساحة عمل محرك البث (@omniroute/open-sse)
├── electron/             غلاف سطح المكتب (العملية الرئيسية لـ Electron 41 + التحميل المسبق)
├── bin/                  نقاط دخول واجهة سطر الأوامر (omniroute، reset-password)
├── tests/                اختبارات الوحدة، والتكامل، وe2e، وprotocols-e2e، والمترجم، والأمان، والتجهيزات
├── scripts/              نصوص البناء، والمزامنة، والتحقق، والترحيل، والمساعدة في وقت التشغيل
├── docs/                 الوثائق العامة (هذا الدليل)
├── public/               الأصول الثابتة، وبيان PWA، وعامل الخدمة
├── config/               نماذج إعدادات وقت التشغيل
├── images/               أصول التسويق/لقطات الشاشة
├── _ideia/, _references/, _mono_repo/, _tasks/   مسودات / تخطيط داخلي (لا تُشحن)
├── CLAUDE.md             قواعد المستودع لـ Claude Code
├── AGENTS.md             مرجع بنية أكثر تفصيلًا للوكلاء
├── package.json          v3.8.51، جذر مساحة العمل
└── tsconfig.json         الأسماء المستعارة للمسارات + خيارات المترجم الأساسية
```

---

## 3. `src/` — تطبيق Next.js

```
src/
├── app/                  صفحات App Router + مسارات API
├── lib/                  المكتبات الأساسية (قاعدة البيانات، المصادقة، OAuth، المهارات، الذاكرة، …)
├── domain/               طبقة النطاق الخالصة (السياسة، الرجوع الاحتياطي، التكلفة، القفل، …)
├── server/               وحدات خاصة بالخادم (التخويل، CORS، المصادقة)
├── shared/               الأنواع، والثوابت، والتحقق، والعقود، والأدوات المساعدة (آمنة عبر الحدود)
├── mitm/                 أدوات مساعدة لوكيل الوسيط من أجل التكامل مع CLI
├── models/               البيانات الوصفية للنماذج المحلية / الأسماء البديلة
├── sse/                  معالجات SSE القديمة التي لا تزال موجودة ضمن src/ (وليست open-sse/)
├── store/                مخازن حالة جهة العميل
├── middleware/           أدوات middleware مساعدة على مستوى المسار (وليست middleware عامة لـ Next.js)
├── scripts/              سكربتات داخلية ضمن الشجرة يمكن استيرادها بواسطة شيفرة التطبيق
├── types/                أنواع TS المحيطة والمشتركة
├── i18n/                 حزم اللغات
├── instrumentation.ts    خطاف القياس في Next.js
├── instrumentation-node.ts
└── proxy.ts              أداة مساعدة عالية المستوى لتهيئة الوكيل
```

### 3.1 `src/app/` — App Router

يعرض App Router كلاً من واجهة مستخدم لوحة المعلومات وواجهة HTTP API العامة/الإدارية.
لا توجد **middleware عامة** — يتم الاعتراض لكل مسار على حدة.

المقاطع عالية المستوى ضمن `src/app/`:

| المسار                                                                        | الغرض                                                      |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `api/`                                                                        | جميع مسارات HTTP API (راجع التفاصيل أدناه)                 |
| `a2a/`                                                                        | نقطة نهاية A2A بتنسيق JSON-RPC 2.0 ‏(`POST /a2a`)          |
| `.well-known/agent.json/`                                                     | مستند اكتشاف بطاقة وكيل A2A                                |
| `(dashboard)/`                                                                | واجهة مستخدم لوحة المعلومات (مجموعة مسارات، بلا بادئة URL) |
| `auth/`, `login/`, `forgot-password/`, `callback/`                            | تدفقات المصادقة                                            |
| `landing/`                                                                    | صفحة التسويق/الهبوط                                        |
| `docs/`                                                                       | عارض مضمّن لوثائق API                                      |
| `status/`, `maintenance/`, `offline/`                                         | صفحات تشغيلية                                              |
| `privacy/`, `terms/`                                                          | صفحات قانونية                                              |
| `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`                | صفحات أخطاء ثابتة                                          |
| `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | حدود الأخطاء/التحميل الخاصة بإطار العمل                    |
| `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`                        | الغلاف الجذري                                              |

#### 3.1.1 `src/app/(dashboard)/dashboard/` — صفحات واجهة المستخدم

`agents`, `analytics`, `api-manager`, `audit`, `auto-combo`, `batch`, `cache`,
`changelog`, `cli-tools`, `cloud-agents`, `combos`, `compression`, `context`,
`costs`, `endpoint`, `health`, `limits`, `logs`, `memory`, `onboarding`,
`playground`, `providers`, `search-tools`, `settings`, `skills`, `system`,
`translator`, `usage`, `webhooks`، بالإضافة إلى `page.tsx` الجذرية، و`HomePageClient.tsx`،
و`BootstrapBanner.tsx`.

#### 3.1.2 `src/app/api/` — مجموعات API عالية المستوى

```
src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   إدارة الخدمات المضمّنة (9router، cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         واجهة API عامة متوافقة مع OpenAI
├── v1beta/     توافق بأسلوب Gemini
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — إدارة الخدمات المضمّنة

مسارات لتثبيت 9Router وCLIProxyAPI وتشغيلهما وإيقافهما ومراقبتهما.
تُصنّف جميع المسارات بأنها **LOCAL_ONLY** (الاسترجاع المحلي فقط، القاعدة الصارمة رقم 17) لأنها
يمكنها استدعاء `npm install` وإنشاء عمليات فرعية.

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             دالة getOrInitSupervisor() المساعدة
│   ├── install/route.ts    POST — تنفيذ npm install عبر execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — تثبيت إصدار أحدث عبر npm
│   ├── rotate-key/route.ts POST — إنشاء مفتاح API جديد + إعادة التشغيل
│   ├── status/route.ts     GET  — الحالة المباشرة + حالة قاعدة البيانات + بيانات الإصدار الوصفية
│   └── auto-start/route.ts POST — تبديل علامة auto_start
├── cliproxy/
│   ├── _lib.ts             دالة getOrInitSupervisor() المساعدة
│   ├── install/route.ts    POST — تنفيذ npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — تثبيت إصدار أحدث عبر npm
│   ├── status/route.ts     GET  — الحالة المباشرة + حالة قاعدة البيانات + بيانات الإصدار الوصفية
│   └── auto-start/route.ts POST — تبديل علامة auto_start
└── [name]/
    └── logs/route.ts       GET  — متابعة سجل SSE (مشتركة بين جميع الخدمات)
```

واجهة لوحة المعلومات المقابلة:
`src/app/(dashboard)/dashboard/providers/services/` — صفحة بعلامتي تبويب (CLIProxyAPI + 9Router).
الوكيل العكسي لواجهة 9Router المضمّنة:
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

شرح متعمّق: `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — واجهة API عامة متوافقة مع OpenAI

```
v1/
├── accounts/[id]/                       البحث عن حساب
├── agents/tasks/[id]/, agents/tasks/    نقاط نهاية للمهام بنمط A2A
├── api/                                 أدوات API مساعدة داخلية متاحة ضمن v1/api
├── audio/{speech, transcriptions}/      تحويل النص إلى كلام + تحويل الكلام إلى نص
├── batches/[id]/{cancel}, batches/      واجهة OpenAI Batches API
├── chat/completions/                    إكمالات المحادثة (نقطة النهاية الرئيسية)
├── completions/                         إكمالات النصوص القديمة
├── embeddings/                          التضمينات
├── files/[id]/, files/                  واجهة Files API
├── _helpers/                            أدوات مساعدة مشتركة للمسارات (من دون URL عام)
├── images/{edits, generations}/         إنشاء الصور + تحريرها
├── issues/                              نقاط نهاية مساعدة للفرز
├── management/{proxies}/                مسارات ذات نطاق إداري داخل v1
├── messages/{count_tokens}/             توافق الرسائل بنمط Anthropic
├── models/                              سرد النماذج (`route.ts`، `catalog.ts`)
├── moderations/                         الإشراف على المحتوى
├── music/                               إنشاء الموسيقى
├── providers/[provider]/                عمليات خاصة بكل مزوّد
├── quotas/{check}                       فحوصات الحصص
├── registered-keys/                     إدارة المفاتيح المسجّلة
├── rerank/                              إعادة الترتيب
├── responses/[...path]/                 واجهة OpenAI Responses API (مسار شامل)
├── search/                              البحث على الويب
├── videos/                              إنشاء الفيديو
├── ws/                                  جسر WebSocket
└── route.ts                             معالج الفهرس
```

يتبع كل ملف مسار النمط نفسه:

```
المسار → فحص CORS المسبق → التحقق من جسم الطلب باستخدام Zod → مصادقة اختيارية
       → فرض سياسة مفتاح API → تفويض المعالجة (open-sse)
```

يمثّل `v1beta/` سطح التوافق بنمط Gemini (غلافًا خفيفًا يترجم الطلبات إلى
مسار المعالجة نفسه `open-sse/handlers/`).

### 3.2 `src/lib/` — المكتبات الأساسية

استورد دائمًا البيانات والمزامنة وOAuth والمهارات والذاكرة وغيرها عبر هذه الوحدات. يجمع
الجدول الأدلة الفعلية والملفات البارزة ذات المستوى الأعلى.

| الوحدة            | الغرض                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/`            | خادم بروتوكول A2A: `taskManager.ts`، و`streaming.ts`، و`taskExecution.ts`، و`routingLogger.ts`، و`skills/` (6 مهارات: تحليل التكلفة، وتقرير الحالة، واكتشاف المزوّدين، وإدارة الحصص، والتوجيه الذكي، وسرد الإمكانات)                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `acp/`            | بروتوكول التحكم بالوكيل: `index.ts`، و`manager.ts`، و`registry.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `api/`            | أدوات مساعدة داخلية لواجهة API: `requireManagementAuth.ts`، و`requireCliToolsAuth.ts`، و`errorResponse.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `auth/`           | `managementPassword.ts` (إعادة تعيين كلمة المرور / التجزئة)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `batches/`        | خدمة OpenAI Batches API ‏(`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `catalog/`        | مزامنة كتالوج OpenRouter ‏(`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `cloudAgent/`     | سجلّ الوكلاء السحابيين: `api.ts`، و`baseAgent.ts`، و`db.ts`، و`index.ts`، و`registry.ts`، و`types.ts`، و`agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `combos/`         | أدوات مساعدة لحلّ التركيبات                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `compliance/`     | التدقيق + تدقيق المزوّدين: `index.ts`، و`providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `config/`         | طبقة ربط إعدادات وقت التشغيل                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `db/`             | وحدات نطاق SQLite (راجع §3.2.1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `display/`        | أدوات مساعدة لواجهة المستخدم/العرض تستخدمها استجابات API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `embeddings/`     | سجلّ خدمات التضمين                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `env/`            | تحميل بيئة التشغيل + استعراضها                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `evals/`          | بيئة تشغيل التقييمات                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `guardrails/`     | `piiMasker.ts`، و`promptInjection.ts`، و`visionBridge.ts`، و`visionBridgeHelpers.ts`، و`registry.ts`، و`base.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `jobs/`           | مهام الخلفية (`autoUpdate.ts`، …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `memory/`         | الذاكرة الدائمة: `store.ts`، و`cache.ts`، و`retrieval.ts`، و`summarization.ts`، و`extraction.ts`، و`injection.ts`، و`qdrant.ts`، و`settings.ts`، و`verify.ts`، و`schemas.ts`، و`types.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `monitoring/`     | `observability.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `oauth/`          | وحدات OAuth/استيراد المزوّدين (22): `agy`، و`antigravity`، و`claude`، و`cline`، و`codebuddy-cn`، و`codex`، و`cursor`، و`devin-desktop`، و`ghe-copilot`، و`github`، و`gitlab-duo`، و`grok-cli-oauth`، و`grok-cli`، و`kilocode`، و`kimi-coding`، و`kiro`، و`openference`، و`qoder`، و`trae`، و`xai-oauth`، و`zed-hosted`، و`zed`، بالإضافة إلى `services/`، و`utils/`، و`constants/oauth.ts`                                                                                                                                                                                                                                                                                                         |
| `plugins/`        | مُحمِّل الملحقات (`index.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `promptCache/`    | `prefixAnalyzer.ts`، و`index.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `providerModels/` | دورة حياة النماذج المُدارة: `modelDiscovery.ts`، و`managedModelImport.ts`، و`managedAvailableModels.ts`، و`cursorAgent.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `providers/`      | أدوات مساعدة للمزوّدين: `catalog.ts`، و`validation.ts`، و`imageValidation.ts`، و`claudeExtraUsage.ts`، و`codexConnectionDefaults.ts`، و`codexFastTier.ts`، و`webCookieAuth.ts`، و`managedAvailableModels.ts`، و`requestDefaults.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `resilience/`     | `settings.ts` — إعدادات قاطع الدائرة، وفترة التهدئة، والقفل                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `runtime/`        | اكتشاف ميزات وقت التشغيل                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `services/`       | إطار عمل الخدمات المضمّنة: `ServiceSupervisor.ts` (مشرف عام على العمليات الفرعية مزوّد بقفل عمليات، ومخزن حلقي، ومدقق للحالة)، و`bootstrap.ts` (التسجيل على مستوى العملية وبدء التشغيل التلقائي)، و`registry.ts` (خريطة الأداة ← المشرف)، و`apiKey.ts` (مخزن مفاتيح AES-256-GCM)، و`modelSync.ts` (مزامنة دورية للنماذج)، و`ringBuffer.ts` (مخزن دائري للسجلات بسعة 5 MB)، و`healthCheck.ts` (فحص حالة عبر HTTP)، و`types.ts`، و`embedWsProxy.ts` (وكيل WebSocket)، و`installers/{ninerouter,cliproxy}.ts`. راجع `docs/frameworks/EMBEDDED-SERVICES.md`                                                                                                                                            |
| `agentSkills/`    | كتالوج مهارات الوكيل + المُولِّد: `catalog.ts` ‏(getCatalog/getSkillById/filterCatalog/computeCoverage)، و`generator.ts` ‏(generateAgentSkills → يكتب إلى `skills/{id}/SKILL.md`)، و`openapiParser.ts` (يستخرج نقاط نهاية REST من مواصفات OpenAPI)، و`cliRegistryParser.ts` (يستخرج الأوامر الفرعية لـCLI من bin/cli-registry)، و`schemas.ts` ‏(Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema)، و`types.ts` ‏(AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). تستهلكه مسارات REST ‏(`/api/agent-skills/*`)، وأدوات MCP ‏(`omniroute_agent_skills_*`)، ومهارة A2A المسماة `list-capabilities`. راجع [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md). |
| `skills/`         | إطار عمل المهارات: `registry.ts`، و`executor.ts`، و`interception.ts`، و`injection.ts`، و`sandbox.ts`، و`custom.ts`، و`hybrid.ts`، و`builtins.ts`، و`a2a.ts`، و`providerSettings.ts`، و`schemas.ts`، و`skillssh.ts`، و`types.ts`، بالإضافة إلى `builtin/browser.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `spend/`          | `batchWriter.ts` (مخزن كتابة مؤجّلة)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sync/`           | `bundle.ts`، و`tokens.ts` (المزامنة السحابية)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `system/`         | أدوات مساعدة على مستوى النظام                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `translator/`     | طبقة ربط المترجم عالية المستوى (تفوض إلى `open-sse/translator/`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `usage/`          | احتساب الاستخدام: `costCalculator.ts`، و`tokenAccounting.ts`، و`usageHistory.ts`، و`aggregateHistory.ts`، و`usageStats.ts`، و`callLogs.ts`، و`callLogArtifacts.ts`، و`fetcher.ts`، و`providerLimits.ts`، و`migrations.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `versionManager/` | التحديث التلقائي + بيان الإصدار                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `ws/`             | جسر WebSocket                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `zed-oauth/`      | تدفق OAuth لمحرر Zed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

الملفات ذات المستوى الأعلى في `src/lib/`:

- أُزيل ملف التجميع القديم `localDb.ts` — يستورد المستهلكون وحدات `src/lib/db/*` المحددة مباشرةً.
- `proxyHealth.ts`, `proxyLogger.ts`, `tokenHealthCheck.ts`, `localHealthCheck.ts`
- `apiBridgeServer.ts`, `cacheLayer.ts`, `semanticCache.ts`, `settingsCache.ts`
- `cloudSync.ts`, `initCloudSync.ts`
- `cloudflaredTunnel.ts`, `ngrokTunnel.ts`, `tailscaleTunnel.ts`
- `consoleInterceptor.ts`, `container.ts`, `gracefulShutdown.ts`, `idempotencyLayer.ts`
- `ipUtils.ts`, `logEnv.ts`, `logPayloads.ts`, `logRotation.ts`
- `modelAliasSeed.ts`, `modelCapabilities.ts`, `modelMetadataRegistry.ts`, `modelsDevSync.ts`
- `piiSanitizer.ts`, `pricingSync.ts`
- `apiKeyExposure.ts`, `cacheControlSettings.ts`, `dataPaths.ts`, `toolPolicy.ts`
- `translatorEvents.ts`, `usageDb.ts`, `usageAnalytics.ts`, `webhookDispatcher.ts`

#### 3.2.1 `src/lib/db/`

قاعدة بيانات SQLite بنمط Singleton (`getDbInstance()` في `core.ts`، مع تسجيل WAL).
**لا تكتب أبدًا SQL خامًا في المسارات أو المعالجات** — استخدم هذه الوحدات.

![نظرة عامة على مخطط قاعدة البيانات (جداول أساسية محددة)](../diagrams/exported/db-schema-overview.svg)

> المصدر: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd)

وحدات النطاق (تمتلك كل منها جدولًا واحدًا أو أكثر): `apiKeys.ts`, `backup.ts`,
`batches.ts`, `cleanup.ts`, `cliToolState.ts`, `combos.ts`,
`commandCodeAuth.ts`, `compression.ts`, `compressionAnalytics.ts`,
`compressionCacheStats.ts`, `compressionCombos.ts`, `compressionScheduler.ts`,
`contextHandoffs.ts`, `core.ts`, `creditBalance.ts`, `databaseSettings.ts`,
`detailedLogs.ts`, `domainState.ts`, `encryption.ts`, `evals.ts`, `files.ts`,
`healthCheck.ts`, `jsonMigration.ts`, `migrationRunner.ts`,
`modelComboMappings.ts`, `models.ts`, `oneproxy.ts`, `prompts.ts`,
`providers.ts`, `providerLimits.ts`, `proxies.ts`, `quotaSnapshots.ts`,
`readCache.ts`, `reasoningCache.ts`, `registeredKeys.ts`, `secrets.ts`,
`sessionAccountAffinity.ts`, `settings.ts`, `stateReset.ts`, `stats.ts`,
`syncTokens.ts`, `tierConfig.ts`, `upstreamProxy.ts`, `versionManager.ts`,
`webhooks.ts`.

يحتوي `migrations/` على 168 ملف `.sql` مرقّمًا بالإصدارات (متكرر التنفيذ بأمان ويعمل ضمن معاملات)، ويُنفَّذ
بواسطة `migrationRunner.ts` عند الإقلاع.

الجداول المنشأة عبر عمليات الترحيل (إجمالي 123 جدولًا):

`a`, `account_key_limits`, `api_keys`, `batches`, `call_logs`,
`combo_adaptation_state`, `combos`, `command_code_auth_sessions`,
`compression_analytics`, `compression_cache_stats`,
`compression_combo_assignments`, `compression_combos`, `context_handoffs`,
`daily_usage_summary`, `db_meta`, `domain_budgets`, `domain_circuit_breakers`,
`domain_cost_history`, `domain_fallback_chains`, `domain_lockout_state`,
`eval_cases`, `eval_runs`, `eval_suites`, `files`, `hourly_usage_summary`,
`key_value`, `mcp_tool_audit`, `memories`, `model_combo_mappings`,
`provider_connections`, `provider_key_limits`, `provider_nodes`,
`proxy_assignments`, `proxy_logs`, `proxy_registry`, `quota_snapshots`,
`reasoning_cache`, `registered_keys`, `request_detail_logs`,
`routing_decisions`, `semantic_cache`, `session_account_affinity`,
`skill_executions`, `skills`, `sync_tokens`, `tier_assignments`,
`tier_config`, `upstream_proxy_config`, `usage_history`, `version_manager`,
`webhooks` (بالإضافة إلى جداول FTS5 الافتراضية للبحث في الذاكرة).

### 3.3 `src/domain/` — طبقة النطاق

منطق أعمال خالص دون عمليات إدخال/إخراج. تستورده المسارات والمعالجات.

| الملف                                      | الغرض                                    |
| ------------------------------------------ | ---------------------------------------- |
| `policyEngine.ts`                          | محلّل السياسات عالي المستوى              |
| `fallbackPolicy.ts`                        | شجرة قرارات الرجوع الاحتياطي             |
| `costRules.ts`                             | قواعد حساب التكلفة                       |
| `lockoutPolicy.ts`                         | قرارات حظر النماذج                       |
| `tagRouter.ts`                             | التوجيه المستند إلى الوسوم               |
| `comboResolver.ts`                         | تحليل المجموعة من الطلب ← قائمة الأهداف  |
| `connectionModelRules.ts`                  | مرشحات النماذج الخاصة بكل اتصال          |
| `modelAvailability.ts`                     | التحقق من توفر النموذج                   |
| `degradation.ts`                           | انتقالات الوضع المتدهور                  |
| `providerExpiration.ts`                    | اكتشاف الحسابات/المفاتيح منتهية الصلاحية |
| `quotaCache.ts`                            | قرارات الحصص المخزنة مؤقتًا              |
| `responses.ts`, `omnirouteResponseMeta.ts` | أدوات مساعدة لبنية الاستجابة             |
| `configAudit.ts`                           | تدقيق تغييرات الإعدادات                  |
| `assessment/`                              | تقييم النماذج (وفق RFC، منفذ جزئيًا)     |
| `types.ts`                                 | أنواع النطاق المشتركة                    |

### 3.4 `src/server/` — للخادم فقط

لا يمكن استيراده من مكونات العميل.

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        يصنّف المسارات إلى عامة أو إدارية
│   ├── assertAuth.ts      أداة مساعدة للتحقق
│   ├── context.ts         سياق التفويض الخاص بكل طلب
│   ├── headers.ts
│   ├── pipeline.ts        مسار معالجة التفويض
│   ├── policies/          سياسات فعلية
│   └── types.ts
└── cors/origins.ts        قائمة السماح بأصول CORS
```

### 3.5 `src/shared/` — آمن للمشاركة

مقسّم إلى أدلة فرعية متخصصة:

- `constants/` — ‏`providers.ts` (دليل مزوّدين متحقق منه باستخدام Zod)، و`models.ts`،
  و`modelSpecs.ts`، و`modelCompat.ts`، و`pricing.ts`، و`cliTools.ts`،
  و`cliCompatProviders.ts`، و`routingStrategies.ts`، و`comboConfigMode.ts`،
  و`headers.ts`، و`upstreamHeaders.ts` (قائمة حظر)، و`mcpScopes.ts`،
  و`errorCodes.ts`، و`publicApiRoutes.ts`، و`batch.ts`، و`batchEndpoints.ts`،
  و`bodySize.ts`، و`colors.ts`، و`appConfig.ts`، و`config.ts`،
  و`sidebarVisibility.ts`، و`visionBridgeDefaults.ts`.
- `validation/` — ‏`schemas.ts` (نحو 80 مخطط Zod)، و`compressionConfigSchemas.ts`،
  و`providerSchema.ts`، و`settingsSchemas.ts`، و`helpers.ts`.
- `contracts/` — عقود واجهة API العامة المنشورة على npm.
- `types/` — أنواع TS المشتركة.
- `utils/` — ‏`circuitBreaker.ts`، و`apiAuth.ts`، و`apiKey.ts`، و`apiKeyPolicy.ts`،
  و`api.ts`، و`classify429.ts`، و`cliCompat.ts`، و`clipboard.ts`، و`cloud.ts`، و`cn.ts`،
  و`cors.ts`، و`featureFlags.ts`،
  و`fetchTimeout.ts`، و`formatting.ts`، و`inputSanitizer.ts`، و`logger.ts`،
  و`machine.ts`، و`machineId.ts`، و`maskEmail.ts`، و`modelCatalogSearch.ts`،
  و`nodeRuntimeSupport.ts`، و`parseApiKeys.ts`، و`providerHints.ts`،
  و`providerModelAliases.ts`، و`rateLimiter.ts`، و`releaseNotes.ts`،
  و`a11yAudit.ts`، بالإضافة إلى خطافات/مكوّنات لوحة المعلومات ضمن `services/`، و`network/`،
  و`middleware/`، و`schemas/`، و`hooks/`، و`components/`.

---

## 4. `open-sse/` — مساحة عمل محرك البث

مساحة عمل npm منفصلة تُنشر باسم `@omniroute/open-sse`. تتولى معالجة
الطلبات، والمنفّذات، والمترجمات، والخدمات، والمحوّل، وخادم MCP.

```
open-sse/
├── index.ts                التصديرات العامة
├── package.json            بيان مساحة العمل
├── tsconfig.json
├── types.d.ts
├── config/                 سجلات المزوّدين، وملفات تعريف الترويسات، والهوية، …
├── handlers/               معالجات الطلبات (الدردشة، والتضمينات، والصوت، والصور، …)
├── executors/              156 وحدة تنفيذ للمزوّدين (فئات المنفّذات + أدوات مساعدة خاصة بكل مزوّد)
├── translator/             تحويل التنسيقات (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            محوّل تدفق Responses API ↔ Chat Completions
├── services/               أكثر من 80 وحدة خدمة (التركيبات، والبدائل، والحصص، والهوية، …)
├── utils/                  أدوات مساعدة للبث، وعميل TLS، وAWS SigV4، وجلب الوكيل، …
└── mcp-server/             خادم MCP (3 وسائل نقل، و33 نطاقًا، و110 أدوات)
```

### 4.1 `open-sse/handlers/`

| المعالج                 | الغرض                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `chatCore.ts`           | مسار الدردشة الرئيسي (التخزين المؤقت، وتحديد المعدل، وتوجيه التركيبات، وإرسال المنفّذ) |
| `responsesHandler.ts`   | نقطة دخول OpenAI Responses API                                                         |
| `embeddings.ts`         | التضمينات                                                                              |
| `imageGeneration.ts`    | توليد الصور                                                                            |
| `audioSpeech.ts`        | تحويل النص إلى كلام                                                                    |
| `audioTranscription.ts` | تحويل الكلام إلى نص                                                                    |
| `videoGeneration.ts`    | توليد الفيديو                                                                          |
| `musicGeneration.ts`    | توليد الموسيقى                                                                         |
| `rerank.ts`             | إعادة الترتيب                                                                          |
| `moderations.ts`        | الإشراف على المحتوى                                                                    |
| `search.ts`             | البحث على الويب                                                                        |
| `sseParser.ts`          | محلّل أحداث SSE                                                                        |
| `usageExtractor.ts`     | استخراج أعداد الرموز المميزة من التدفقات الواردة                                       |
| `responseSanitizer.ts`  | إزالة البيانات غير الضرورية الخاصة بالمزوّد                                            |
| `responseTranslator.ts` | طبقة ربط بين استجابة المزوّد وطبقة الترجمة                                             |

### 4.2 `open-sse/executors/`

156 وحدة تنفيذ من المستوى الأعلى (`*.ts` باستثناء `base.ts` و`index.ts` والاختبارات — وهو العدد
الذي يقيسه `npm run check:docs-counts`). توسّع كل فئة منفّذ `BaseExecutor` (`base.ts`)،
مباشرةً أو عبر `DefaultExecutor` أو منفّذ آخر؛ أما الوحدات المتبقية فهي أدوات مساعدة خاصة بكل مزوّد
(مخططات الأدوات، ومهايئات الجلب/TTS، ومعالجات السلوكيات الخاصة). تشمل المنفّذات:

`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`,
`chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`,
`muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`,
`pollinations`, `qoder`, `vertex`, `devin-desktop`، بالإضافة إلى `claudeIdentity.ts`
(أداة مساعدة مشتركة للهوية) و`index.ts` (السجل).

> ملاحظة: تُخدَم المزوّدات غير المدرجة هنا بواسطة `default.ts` باستخدام منفّذ
> عام متوافق مع OpenAI. يوجد كتالوج المزوّدين الكامل (375 مزوّدًا) في
> `src/shared/constants/providers.ts`.

### 4.3 `open-sse/translator/`

ترجمة وفق بنية المحور والأطراف (OpenAI هو المحور).

- **9 مترجمات للطلبات** (`translator/request/`):
  `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`,
  `gemini-to-openai`, `openai-responses`, `openai-to-claude`,
  `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`.
- **9 مترجمات للاستجابات** (`translator/response/`):
  `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`,
  `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`,
  `openai-to-claude`.
- **9 أدوات مساعدة** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`، بالإضافة إلى
  اختبارات الأدوات المساعدة.
- **أدوات مساعدة للصور** (`translator/image/sizeMapper.ts`).
- المستوى الأعلى: `bootstrap.ts`، و`formats.ts`، و`registry.ts`، و`index.ts`.

### 4.4 `open-sse/transformer/`

- `responsesTransformer.ts` — محوّل Responses API ↔ Chat
  Completions قائم على `TransformStream` (يستخدمه المسار الجامع `responses/`).

### 4.5 `open-sse/services/`

أبرز العناصر (القائمة الكاملة ضمن `open-sse/services/`):

| مجال الاهتمام   | الملفات                                                                                                                                                                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| توجيه Combo     | `combo.ts` (20 استراتيجية)، `comboConfig.ts`، `comboMetrics.ts`، `comboManifestMetrics.ts`، `comboAgentMiddleware.ts`                                                                                                                                    |
| محرك Auto Combo | `autoCombo/` — `engine.ts`، `scoring.ts`، `taskFitness.ts`، `virtualFactory.ts`، `modePacks.ts`، `autoPrefix.ts`، `persistence.ts`، `providerDiversity.ts`، `providerRegistryAccessor.ts`، `routerStrategy.ts`، `selfHealing.ts`، `index.ts`             |
| المرونة         | `accountFallback.ts` (فترة تهدئة + قفل)، `errorClassifier.ts`، `requestRejectedStreak.ts`، `emergencyFallback.ts`، `rateLimitManager.ts`، `rateLimitSemaphore.ts`، `accountSemaphore.ts`، `accountSelector.ts`                                           |
| الحصص           | `quotaMonitor.ts`، `quotaPreflight.ts`، `bailianQuotaFetcher.ts`، `codexQuotaFetcher.ts`، `deepseekQuotaFetcher.ts`، `openrouterQuotaFetcher.ts`، `openrouterFreeWindow.ts`، `llmgatewayQuotaFetcher.ts`، `crofUsageFetcher.ts`، `antigravityCredits.ts` |
| التخزين المؤقت  | `reasoningCache.ts`، `searchCache.ts`، `signatureCache.ts`، `requestDedup.ts`                                                                                                                                                                            |
| ذكاء التوجيه    | `intentClassifier.ts`، `taskAwareRouter.ts`، `backgroundTaskDetector.ts`، `volumeDetector.ts`، `wildcardRouter.ts`، `workflowFSM.ts`، `specificityDetector.ts`، `specificityRules.ts`، `specificityTypes.ts`                                             |
| معالجة النماذج  | `modelCapabilities.ts`، `modelDeprecation.ts`، `modelFamilyFallback.ts`، `modelStrip.ts`، `model.ts`، `provider.ts`، `providerRequestDefaults.ts`، `providerCostData.ts`، `payloadRules.ts`                                                              |
| الضغط           | `compression/` — التوصيل الكامل لمحرك الضغط                                                                                                                                                                                                              |
| الرموز + الجلسة | `tokenRefresh.ts`، `sessionManager.ts`، `apiKeyRotator.ts`، `contextManager.ts`، `contextHandoff.ts`، `systemPrompt.ts`، `roleNormalizer.ts`، `responsesInputSanitizer.ts`، `toolSchemaSanitizer.ts`، `toolLimitDetector.ts`، `thinkingBudget.ts`        |
| الفئة / البيان  | `tierResolver.ts`، `tierConfig.ts`، `tierDefaults.json`، `tierTypes.ts`، `manifestAdapter.ts`                                                                                                                                                            |
| IP / الشبكة     | `ipFilter.ts`، `webSearchFallback.ts`                                                                                                                                                                                                                    |
| الدفعات         | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| الاستخدام       | `usage.ts`                                                                                                                                                                                                                                               |

### 4.6 `open-sse/mcp-server/`

- **110 أدوات فريدة** موصولة في `server.ts` (45 أداة أساسية في `schemas/tools.ts` +
  وحدات الذاكرة والمهارات ومهارات GitHub والتجمّع والتلعيب والملحقات وNotion وObsidian
  والمحتوى المحلي والضغط — جرى حساب الاتحاد بواسطة `countUniqueMcpTools`).
- **3 وسائل نقل**: stdio وHTTP Streamable وSSE.
- **33 نطاقًا** تُفرض في وقت التشغيل — القائمة الأساسية في `src/shared/constants/mcpScopes.ts`، والمجموعة الكاملة هي اتحاد النطاقات التي تصرّح بها كل وحدة أدوات.
- جدول التدقيق: `mcp_tool_audit` (تتم تعبئته بواسطة `audit.ts`).
- الملفات: `server.ts`، `index.ts`، `httpTransport.ts`، `audit.ts`، `scopeEnforcement.ts`،
  `runtimeHeartbeat.ts`، `descriptionCompressor.ts`، `schemas/{tools, a2a, audit, index}.ts`،
  `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`،
  بالإضافة إلى الاختبارات ضمن `__tests__/`.
- راجع [MCP-SERVER.md](../frameworks/MCP-SERVER.md) للاطلاع على كتالوج الأدوات الكامل.

### 4.7 `open-sse/config/`

سجلات مزوّدي الخدمة (`providerRegistry.ts`، `providerModels.ts`،
`providerHeaderProfiles.ts`)، وسجلات النماذج الخاصة بكل تنسيق (`audioRegistry.ts`،
`embeddingRegistry.ts`، `imageRegistry.ts`، `moderationRegistry.ts`،
`musicRegistry.ts`، `rerankRegistry.ts`، `searchRegistry.ts`، `videoRegistry.ts`)،
ومساعدات الهوية (`codexIdentity.ts`، `codexInstructions.ts`،
`anthropicHeaders.ts`، `antigravityUpstream.ts`، `antigravityModelAliases.ts`،
`cliFingerprints.ts`، `toolCloaking.ts`، `defaultThinkingSignature.ts`)،
ومساعدات بيانات الاعتماد (`credentialLoader.ts`، `codexClient.ts`)، ومحوّلات
الخدمات السحابية (`azureAi.ts`، `bedrock.ts`، `datarobot.ts`، `glmProvider.ts`،
`maritalk.ts`، `oci.ts`، `petals.ts`، `runway.ts`، `sap.ts`، `watsonx.ts`،
`ollamaModels.ts`، `errorConfig.ts`، `constants.ts`، `registryUtils.ts`).

### 4.8 `open-sse/utils/`

بدائيات البث وأدوات موفّري الخدمة المساعدة: `stream.ts`، `streamHandler.ts`،
`streamHelpers.ts`، `streamPayloadCollector.ts`، `streamReadiness.ts`،
`sseHeartbeat.ts`، `proxyFetch.ts`، `proxyDispatcher.ts`، `tlsClient.ts`،
`networkProxy.ts`، `awsSigV4.ts`، `cacheControlPolicy.ts`،
`cursorChecksum.ts`، `cursorAgentProtobuf.ts`، `cursorVersionDetector.ts`،
`comfyuiClient.ts`، `kieTask.ts`، `bypassHandler.ts`، `aiSdkCompat.ts`،
`thinkTagParser.ts`، `urlSanitize.ts`، `usageTracking.ts`، `requestLogger.ts`،
`progressTracker.ts`، `cors.ts`، `error.ts`، `logger.ts`، `sleep.ts`،
`ollamaTransform.ts`.

---

## 5. `electron/` — غلاف سطح المكتب

```
electron/
├── main.js                  عملية Electron الرئيسية
├── preload.js               جسر التحميل المسبق (مع تمكين contextIsolation)
├── types.d.ts
├── package.json             إعدادات electron-builder، الإصدار 3.8.51
├── README.md
├── assets/                  موارد البناء (الأيقونات، الاستحقاقات، …)
├── node_modules/            مجلد node_modules مخصص (better-sqlite3، electron-updater)
└── dist-electron/           مخرجات البناء (غير مضمنة في المستودع)
```

خمسة نصوص برمجية لـ npm في جذر مساحة العمل: `electron:dev`، و`electron:build`،
و`electron:build:{win,mac,linux}`، و`electron:smoke:packaged`. يتم التحديث التلقائي عبر
`electron-updater` الذي يشير إلى موجز إصدارات GitHub.

---

## 6. `bin/` — واجهة سطر الأوامر

```
bin/
├── omniroute.mjs           نقطة الدخول الرئيسية لواجهة سطر الأوامر (Node ESM)
├── reset-password.mjs      إعادة تعيين كلمة مرور الإدارة من واجهة سطر الأوامر
├── mcp-server.mjs          مشغّل خادم MCP‏ (stdio)
├── nodeRuntimeSupport.mjs  أداة تحقق من إصدار Node
└── cli/
    ├── program.mjs         منشئ برنامج Commander
    ├── runtime.mjs         مساعد withRuntime (الخادم أولًا/الرجوع إلى قاعدة البيانات)
    ├── output.mjs          منسّقات المخرجات (json/jsonl/table/csv)
    ├── i18n.mjs            مساعد t() مع اللغات
    ├── api.mjs             مساعد جلب API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    تسجيل الأوامر
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (ملف واحد لكل أمر/مجموعة)
```

يتم توفير ملفين تنفيذيين في `package.json` ← `bin`:

- `omniroute` ← `bin/omniroute.mjs`
- `omniroute-reset-password` ← `bin/reset-password.mjs`

---

## 7. `tests/`

| الدليل                                               | النوع                                                                                                               |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`                                        | اختبارات الوحدات عبر مشغّل اختبارات Node الأصلي (1821 ملفًا، بالإضافة إلى الأدلة الفرعية `api/` و`auth/` و`authz/`) |
| `tests/integration/`                                 | اختبارات عبر الوحدات + حالة قاعدة البيانات                                                                          |
| `tests/e2e/`                                         | اختبارات واجهة المستخدم باستخدام Playwright                                                                         |
| `tests/e2e/protocol-clients.test.ts`                 | اختبارات شاملة لبروتوكولي MCP/A2A                                                                                   |
| `tests/translator/`                                  | اختبارات خاصة بالمترجم                                                                                              |
| `tests/security/`                                    | اختبارات تراجع الأمان                                                                                               |
| `tests/load/`                                        | اختبارات التحميل / الضغط                                                                                            |
| `tests/golden-set/`                                  | مخرجات مرجعية لاختبارات تراجع المترجم                                                                               |
| `tests/helpers/`، `tests/fixtures/`، `tests/manual/` | ملفات الدعم                                                                                                         |

الأوامر الشائعة:

| الأمر                                                    | ما يشغّله                                                                  |
| -------------------------------------------------------- | -------------------------------------------------------------------------- |
| `npm run test:unit`                                      | جميع ملفات `tests/unit/*.test.ts` عبر مشغّل اختبارات Node (بتزامن قدره 10) |
| `npm run test:vitest`                                    | حزمة اختبارات Vitest‏ (MCP، وautoCombo، وcache)                            |
| `npm run test:e2e`                                       | حزمة اختبارات واجهة المستخدم باستخدام Playwright                           |
| `npm run test:protocols:e2e`                             | اختبارات شاملة لبروتوكولي MCP وA2A                                         |
| `npm run test:coverage`                                  | بوابة التغطية (≥60% للأسطر/التعليمات/الدوال/الفروع)                        |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | تشغيل ملف واحد                                                             |

---

## 8. `scripts/`

منظَّمة في 6 مجلدات فرعية حسب الغرض.

- **`scripts/build/`** — `build-next-isolated.mjs`، `prepublish.ts`،
  `prepare-electron-standalone.mjs`، `pack-artifact-policy.ts`،
  `validate-pack-artifact.ts`، `postinstall.mjs`، `postinstallSupport.mjs`،
  `uninstall.mjs`، `bootstrap-env.mjs`، `runtime-env.mjs`،
  `native-binary-compat.mjs`.
- **`scripts/dev/`** — `run-next.mjs`، `run-next-playwright.mjs`،
  `run-standalone.mjs`، `standalone-server-ws.mjs`، `responses-ws-proxy.mjs`،
  `v1-ws-bridge.mjs`، `smoke-electron-packaged.mjs`،
  `run-playwright-tests.mjs`، `run-ecosystem-tests.mjs`،
  `run-protocol-clients-tests.mjs`، `sync-env.mjs`، `healthcheck.mjs`،
  `system-info.mjs`، بالإضافة إلى أدوات المساعدة للمتابعة غير المعدِّلة لطلبات السحب
  `ci-discriminate.sh` (تصنّف تواقيع عمليات التحقق الفاشلة في طلب سحب إلى خاصة به /
  موروثة / غير معروفة، بالمقارنة مع طلب سحب مرجعي أو مشكلة فشل الفرع الأساسي) و`audit-worktree.sh`
  (الملفات غير النظيفة، والأسطح المحمية، وعبارات التحقق المحذوفة، وأعداد عمليات التجاوز، وملفات
  tsconfig المؤقتة المتبقية، ورأس طلب السحب مقارنةً بـ HEAD المحلي — قبل قبول طلب سحب أحد العاملين).
- **`scripts/check/`** — `check-cycles.mjs`، `check-docs-sync.mjs`،
  `check-docs-counts-sync.mjs`، `check-env-doc-sync.mjs`،
  `check-deprecated-versions.mjs`، `check-route-validation.mjs`،
  `check-t11-any-budget.mjs`، `check-pr-test-policy.mjs`،
  `check-supported-node-runtime.ts`، `test-report-summary.mjs`.
- **`scripts/docs/`** — `generate-docs-index.mjs`، `gen-provider-reference.ts`.
- **`scripts/i18n/`** — `generate-multilang.mjs`، `run-visual-qa.mjs`،
  `generate-qa-checklist.mjs`، `apply-priority-overrides.mjs`،
  `validate_translation.py`، `check_translations.py`، `i18n_autotranslate.py`،
  `untranslatable-keys.json`.
- **`scripts/ad-hoc/`** — `cursor-tap.cjs`، `sync-cursor-models.mjs`،
  `migrate-env.mjs`، `dbsetup.js`.

---

## 9. مسار معالجة الطلب (ملخص)

![مسار معالجة الطلب (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> المصدر: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
طلب العميل
  → /v1/chat/completions (route.ts)
     فحص CORS المسبق
     التحقق باستخدام Zod ‏(chatCompletionsSchema في shared/validation/schemas.ts)
     المصادقة (extractApiKey + isValidApiKey أو requireManagementAuth)
     محرك السياسات (src/server/authz/pipeline.ts)
     ضوابط الحماية (أداة إخفاء معلومات تحديد الهوية الشخصية، وحقن الموجّهات، وجسر الرؤية)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     فحص ذاكرة التخزين المؤقت (التخزين الدلالي + ذاكرة القراءة المؤقتة)
     تحديد المعدل (rateLimitManager، accountSemaphore)
     التوجيه المركّب (إذا كان النموذج يُحلّ إلى مجموعة مركّبة)
       comboResolver → تكرار لكل هدف → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       الجلب من المصدر الأعلى → إعادة المحاولة/التراجع عبر accountFallback
     translateResponse() (open-sse/translator/response/*)
     تدفق SSE أو استجابة JSON
     في حالة Responses API: ‏TransformStream عبر open-sse/transformer/responsesTransformer.ts
  → تدقيق الامتثال (src/lib/compliance/)
  → الاستجابة إلى العميل
```

### حالة وقت تشغيل المرونة (ثلاث آليات)

| الآلية             | النطاق                      | الموضع                                                                                                     |
| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| قاطع دائرة المزوّد | المزوّد بالكامل             | `src/shared/utils/circuitBreaker.ts`، مع الاستمرار في `domain_circuit_breakers`                            |
| فترة تهدئة الاتصال | حساب/مفتاح واحد             | `markAccountUnavailable()` في `src/sse/services/auth.ts`؛ ويستخدمها `accountFallback.checkFallbackError()` |
| حظر النموذج        | المزوّد + الاتصال + النموذج | `open-sse/services/accountFallback.ts`، مع الاستمرار في `domain_lockout_state`                             |

راجع [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) والقسم المخصص في
[CLAUDE.md](../../CLAUDE.md).

---

## 10. كيفية المساهمة

### إضافة مزوّد جديد

1. سجّله في `src/shared/constants/providers.ts` (يتم التحقق منه بواسطة Zod عند التحميل).
2. أضف منفّذًا في `open-sse/executors/` إذا كان المنطق المخصص مطلوبًا
   (وسّع `BaseExecutor`).
3. أضف مترجمًا في `open-sse/translator/` إذا كان لا يدعم تنسيق OpenAI.
4. إذا كان يعتمد على OAuth، فأضف الإعدادات ضمن `src/lib/oauth/providers/` و
   `src/lib/oauth/services/`.
5. سجّل النماذج في `open-sse/config/providerRegistry.ts` (أو في السجل الخاص بالتنسيق
   ضمن `open-sse/config/`).
6. اكتب الاختبارات ضمن `tests/unit/`.

### إضافة مسار API جديد

1. أنشئ `src/app/api/your-route/route.ts`.
2. اتبع النمط: CORS ← التحقق من متن الطلب باستخدام Zod ← المصادقة ← تفويض المعالج.
3. إذا كان شكل الطلب جديدًا: فأضف مخطط Zod في `src/shared/validation/schemas.ts`.
4. إذا كان مخصصًا للإدارة فقط: فأضف المسار إلى `src/shared/constants/publicApiRoutes.ts`
   (قائمة الحظر لواجهة API العامة).
5. أضف الاختبارات ضمن `tests/unit/`.
6. حدّث `docs/reference/API_REFERENCE.md` و`docs/openapi.yaml`.

### إضافة وحدة قاعدة بيانات جديدة

1. أنشئ `src/lib/db/yourModule.ts` واستورد `getDbInstance()` من `./core.ts`.
2. صدّر دوال CRUD لنطاقك.
3. إذا كانت هناك جداول جديدة: فأضف ترحيلًا ضمن `src/lib/db/migrations/`، على أن يكون مرقمًا
   بالتسلسل، ومتكرر التنفيذ بأمان، ومعامليًا.
4. تستخدم الوحدات المستورِدة عمليات استيراد مباشرة من `@/lib/db/yourModule` (من دون ملف تجميعي — أُزيلت طبقة إعادة التصدير القديمة `localDb.ts`).
5. أضف الاختبارات ضمن `tests/unit/`.

### إضافة أداة MCP جديدة

1. أضف تعريف الأداة ضمن `open-sse/mcp-server/tools/` (أو وسّع
   `open-sse/mcp-server/schemas/tools.ts`).
2. عيّن النطاق أو النطاقات المناسبة في `src/shared/constants/mcpScopes.ts`.
3. سجّل الأداة في `open-sse/mcp-server/server.ts`.
4. أضف الاختبارات ضمن `open-sse/mcp-server/__tests__/`.
5. حدّث [MCP-SERVER.md](../frameworks/MCP-SERVER.md).

### إضافة مهارة A2A جديدة

راجع [A2A-SERVER.md § إضافة مهارة جديدة](../frameworks/A2A-SERVER.md). توجد المهارات في
`src/lib/a2a/skills/` وتُسجّل من خلال مدير مهام A2A.

---

## 11. الاصطلاحات

- **نمط الشيفرة**: مسافة بادئة بمقدار مسافتين، وعلامات اقتباس مزدوجة، وعرض 100 محرف، وفواصل منقوطة،
  وفواصل لاحقة وفق `es5` — يفرضها Prettier عبر `lint-staged`.
- **عمليات الاستيراد**: خارجية ← داخلية (`@/`، و`@omniroute/open-sse`) ← نسبية.
- **التسمية**: الملفات بصيغة `camelCase` أو `kebab-case`، والمكوّنات بصيغة `PascalCase`،
  والثوابت بصيغة `UPPER_SNAKE`.
- **ESLint**: القواعد `no-eval` و`no-implied-eval` و`no-new-func` = `error` في كل مكان؛
  والقاعدة `no-explicit-any` = `warn` في `open-sse/` و`tests/`، و`error` في الأماكن الأخرى.
- **TypeScript**: ‏`strict: false` (نهج متوارث). فضّل الأنواع الصريحة على
  الاستدلال عند الحدود بين الوحدات.
- **قاعدة البيانات**: لا تكتب SQL خامًا مطلقًا في المسارات أو المعالجات — استخدم دائمًا
  وحدات `src/lib/db/`. لا تستورد مطلقًا من ملف تجميعي — استخدم وحدات `src/lib/db/*` المحددة مباشرةً.
- **كتابة أنواع كيانات قاعدة البيانات (#3512)**: يجب أن تستخدم الدالة التي تكتب
  شكل صف جدول في قاعدة البيانات أو تقرؤه واجهة TS مسمّاة في معاملات الإدخال أو القيمة المعادة، تحاكي أعمدة ذلك الجدول
  بنسبة 1:1، بدلًا من `any` أو نوع مجهول مضمن في موضع الاستدعاء. ضع
  الواجهة بجوار الدالة (مثل `export interface UsageEntry` في
  `src/lib/usage/usageHistory.ts` أعلى `saveRequestUsage`)، وأبقِ الحقول الفردية
  اختيارية أو قابلة للقيمة الفارغة عندما يملأ كتّاب مختلفون الصف
  تدريجيًا، وفضّل `unknown` على `any` للحقل الذي يختلف شكله
  بين المستدعين (مع توثيق ذلك في الحقل؛ مثلًا، يقبل `UsageEntry.tokens`
  كلاً من بيانات الاستخدام الخام ذات الشكل الخاص بالمزوّد والشكل الموحّد). حالما يصل
  عدد مرات `any` في ملف إلى الصفر بهذه الطريقة، أضفه إلى قائمة السماح
  `check:any-budget:t11` ‏(`scripts/check/check-t11-any-budget.mjs`،
  و`maxAny: 0`) كي لا يتراجع. هذا اصطلاح للدفعة الأولى — أما
  التنظيف الأوسع لعبارة «لا أنواع `any` مجهولة» فيتم تكراريًا عبر بقية
  قاعدة الشيفرة.
- **الأخطاء**: استخدم try/catch مع أنواع أخطاء محددة، وسجّل باستخدام سياق pino. لا
  تتجاهل الأخطاء بصمت في تدفقات SSE مطلقًا؛ استخدم إشارات الإلغاء للتنظيف.
- **الأمان**: لا تستخدم `eval()` أو `new Function()` أو eval الضمني مطلقًا. تحقّق
  من جميع المدخلات باستخدام Zod. شفّر بيانات الاعتماد وهي مخزنة (AES-256-GCM). حافظ على
  مزامنة قائمة الحظر `src/shared/constants/upstreamHeaders.ts` مع
  طبقة التنقية/التحقق.
- **عمليات الإيداع**: Conventional Commits — ‏`feat(scope): subject`. النطاقات المسموح بها:
  `db`، و`sse`، و`oauth`، و`dashboard`، و`api`، و`cli`، و`docker`، و`ci`، و`mcp`،
  و`a2a`، و`memory`، و`skills`.
- **الفروع**: البادئات `feat/`، و`fix/`، و`refactor/`، و`docs/`، و`test/`،
  و`chore/`. لا تُجرِ إيداعًا مباشرًا إلى `main` مطلقًا.
- **Husky**: يشغّل خطاف ما قبل الإيداع `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11`؛ ويشغّل خطاف ما قبل الدفع `check:any-budget:t11` + `check:tracked-artifacts` (بوابات سريعة؛ تستثني `test:unit`).

---

## 12. قواعد صارمة (من CLAUDE.md)

1. لا تُضمِّن أبدًا الأسرار أو بيانات الاعتماد في الالتزامات.
2. لا تستخدم أبدًا الاستيراد التجميعي — استخدم وحدات `src/lib/db/*` المحددة مباشرةً.
3. لا تستخدم أبدًا `eval()` أو `new Function()` أو أي تقييم ضمني.
4. لا تُجرِ أبدًا التزامات مباشرةً على `main`.
5. لا تكتب أبدًا SQL خامًا في المسارات — استخدم دائمًا وحدات `src/lib/db/`.
6. لا تتجاهل الأخطاء بصمت أبدًا في تدفقات SSE.
7. تحقّق دائمًا من صحة المدخلات باستخدام مخططات Zod.
8. أدرج دائمًا اختبارات عند تغيير شيفرة الإنتاج.
9. يجب أن تظل التغطية ≥ 60% (التعليمات، والأسطر، والدوال، والفروع).

---

## 13. انظر أيضًا

- [ARCHITECTURE.md](./ARCHITECTURE.md) — البنية عالية المستوى ومسؤوليات
  الوحدات.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — مرجع واجهة API العامة والإدارية.
- [FEATURES.md](../guides/FEATURES.md) — مصفوفة الميزات وأبرز ما في الإصدارات.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — شرح متعمق لقاطع الدائرة، وفترة التهدئة،
  والقفل.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — تسجيل نقاط Auto Combo واستراتيجياته.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — الفهرس الكامل لأدوات MCP ووسائل النقل.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — مهارات بروتوكول A2A وآلية الاكتشاف.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — الضغط باستخدام RTK وCaveman.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — عمليات تكامل CLI.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (إن وُجد)، [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md)، [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md)، [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md)، [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md)، [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — أهداف النشر.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — المشكلات التشغيلية الشائعة.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — سير عمل المساهمين.
- [CLAUDE.md](../../CLAUDE.md) — قواعد المستودع الخاصة بـ Claude Code (المصدر الموثوق
  للعديد من الاصطلاحات المذكورة أعلاه).
- [AGENTS.md](../../AGENTS.md) — مرجع معماري أكثر تعمقًا تستخدمه الوكلاء.