# OmniRoute Codebase Documentation (עברית)

🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../../ar/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) · 🇮🇳 [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** ‏(App Router, פלט עצמאי, ללא middleware גלובלי)                                                                 |
| שפה             | **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 לפני commit)                                                   |
| מערכת מודולים   | 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 ‏(App Router, ספריות, תחום, שרת, רכיבים משותפים)
├── open-sse/             סביבת עבודה של מנוע הזרמה (@omniroute/open-sse)
├── electron/             מעטפת שולחן עבודה (התהליך הראשי של Electron 41 + טעינה מקדימה)
├── bin/                  נקודות כניסה של CLI ‏(omniroute, reset-password)
├── tests/                בדיקות יחידה, אינטגרציה, e2e,‏ protocols-e2e, מתרגם, אבטחה ונתוני בדיקה
├── scripts/              סקריפטים לבנייה, סנכרון, בדיקה, מיגרציה וכלי עזר לזמן ריצה
├── docs/                 תיעוד ציבורי (תיקייה זו)
├── public/               נכסים סטטיים, מניפסט PWA,‏ service worker
├── 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    נקודת חיבור ל-instrumentation של Next.js
├── instrumentation-node.ts
└── proxy.ts              כלי עזר עליון לאתחול proxy
```

### 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/`                                                     | מסמך גילוי Agent Card של 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` | גבולות שגיאה/טעינה של ה-framework                       |
| `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 install של גרסה חדשה יותר
│   ├── 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 install של גרסה חדשה יותר
│   ├── 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}/      TTS + STT
├── 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/`:

- קובץ ה־barrel הישן `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 (`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`, וכן hooks ורכיבי לוח מחוונים תחת `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` — ממיר מבוסס-`TransformStream` בין Responses API ↔ Chat
  Completions (משמש את נתיב ברירת המחדל `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`, וכן כלי העזר לקריאה בלבד להשגחה על PR:
  `ci-discriminate.sh` (מסווג את חתימות הבדיקות שנכשלו ב-PR לשלו / בירושה /
  לא ידוע, בהשוואה ל-PR ייחוס או לבעיה האדומה בבסיס) ו-`audit-worktree.sh`
  (קבצים עם שינויים, אזורים מוגנים, בדיקות assert שהוסרו, ספירת השתקות, קובצי
  tsconfig זמניים שנותרו, ראש ה-PR לעומת HEAD המקומי — לפני קבלת ה-PR של עובד).
- **`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)
     אמצעי הגנה (מיסוך PII, הזרקת פרומפטים, גשר ראייה)
  → 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` (ללא barrel — שכבת הייצוא מחדש הישנה `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. מוסכמות

- **סגנון קוד**: הזחה של 2 רווחים, מירכאות כפולות, רוחב של 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/`, ושגיאה במקומות אחרים.
- **TypeScript**:‏ `strict: false` (מצב תאימות למערכת ותיקה). העדיפו טיפוסים מפורשים על פני
  הסקת טיפוסים בגבולות שבין מודולים.
- **מסד נתונים**: לעולם אל תכתבו SQL גולמי בנתיבים או במטפלים — עברו תמיד דרך
  המודולים שב-`src/lib/db/`. לעולם אל תייבאו דרך barrel — השתמשו ישירות במודולי `src/lib/db/*` ספציפיים.
- **טיפוס ישויות מסד נתונים (#3512)**: פונקציה שכותבת או קוראת מבנה שורה של
  טבלת מסד נתונים צריכה לקבל/להחזיר ממשק TS בעל שם המשקף את עמודות הטבלה
  ביחס 1:1, ולא `any` או טיפוס אנונימי מוטבע בנקודת הקריאה. מקמו
  את הממשק לצד הפונקציה (למשל `export interface UsageEntry` בתוך
  `src/lib/usage/usageHistory.ts` מעל `saveRequestUsage`), השאירו שדות בודדים
  כאופציונליים/ניתנים ל-null כאשר כותבים שונים מאכלסים את השורה
  בהדרגה, והעדיפו `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/`. לעולם אל תבצעו commit ישירות ל-`main`.
- **Husky**: לפני commit מופעלים `lint-staged` +‏ `check:docs-sync` +
  `check:any-budget:t11`; לפני push מופעלים `check:any-budget:t11` +‏ `check:tracked-artifacts` (שערים מהירים; לא כולל `test:unit`).

---

## 12. כללים מחייבים (מתוך CLAUDE.md)

1. לעולם אין לבצע commit של סודות או פרטי גישה.
2. לעולם אין להשתמש ב-barrel import — יש להשתמש ישירות במודולים ספציפיים מתוך `src/lib/db/*`.
3. לעולם אין להשתמש ב-`eval()` / `new Function()` / eval משתמע.
4. לעולם אין לבצע commit ישירות אל `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 הציבורי ול-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) — תיעוד ארכיטקטורה מעמיק יותר המשמש סוכנים.