OmniRoute/docs/i18n/he/docs/architecture/CODEBASE_DOCUMENTATION.md

OmniRoute Codebase Documentation (עברית)

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

---

גרסה: v3.8.51 עדכון אחרון: 2026-06-28 קהל יעד: מהנדסים התורמים ל-OmniRoute או בונים אינטגרציות על גביו.

לתרשימי ארכיטקטורה ברמה גבוהה ולהסבר ההיגיון שמאחורי כל תת-מערכת, קראו את ARCHITECTURE.md. לצלילה מעמיקה לתוך תת-מערכות ספציפיות (Auto Combo, שרת MCP, שרת A2A, Skills, Memory, Cloud Agents, Resilience, Compression וכו'), עיינו בקבצים הייעודיים שלהן בתיקייה docs/ זו.

קובץ זה מתאר מה קיים כיום במאגר כדי שמהנדס חדש יוכל להתמצא בעץ, להבין את שכבות זמן הריצה ולדעת היכן להוסיף קוד מבלי להמציא מודולים חדשים.

---

1. מחסנית טכנולוגית

תחום	בחירה
מסגרת Web	Next.js 16 ‏(App Router, פלט standalone, ללא 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 ‏(singleton, יומן WAL)
שולחן עבודה	Electron 41 + ‏electron-builder 26.10 (סביבת עבודה נפרדת ב-electron/)
בדיקות	מריץ הבדיקות המובנה של Node ‏(יחידה/אינטגרציה), Vitest ‏(MCP,‏ autoCombo,‏ cache),‏ Playwright ‏(e2e + protocols-e2e)
בנייה	Next.js standalone באמצעות scripts/build/build-next-isolated.mjs
Lint/עיצוב	תצורת flat של 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 + preload)
├── bin/                  נקודות כניסה ל-CLI ‏(omniroute, reset-password)
├── tests/                בדיקות יחידה, אינטגרציה, e2e,‏ protocols-e2e, מתרגם, אבטחה ו-fixtures
├── 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    נקודת חיבור לאינסטרומנטציה של 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 באמצעות 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
│   ├── 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}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API האצוות של OpenAI
├── chat/completions/                    השלמות צ'אט (נקודת הקצה הראשית)
├── completions/                         השלמות טקסט מדור קודם
├── embeddings/                          הטמעות
├── files/[id]/, 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]/                 API התגובות של OpenAI (נתיב כוללני)
├── 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.
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/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/              108 מבצעי HTTP ייעודיים לספקים
├── 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/

108 מבצעים של ספקים, שכל אחד מהם מרחיב את BaseExecutor ‏(base.ts):

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. קטלוג הספקים המלא (355 ספקים) נמצא ב- 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.ts (19 אסטרטגיות), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
מנוע שילוב אוטומטי	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, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
מכסות	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.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.

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.
• 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. צינור עיבוד הבקשה (סיכום)

מקור: 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 ואת הסעיף הייעודי בתוך 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.

הוספת מודול DB חדש

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.

הוספת מיומנות A2A חדשה

ראו 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/* ספציפיים.
• טיפוס ישויות DB‏ (#3512): פונקציה שכותבת או קוראת את מבנה הרשומה של טבלת DB צריכה לקבל או להחזיר ממשק 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: ‏pre-commit מריץ lint-staged + check:docs-sync + check:any-budget:t11; ‏pre-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 — ארכיטקטורה ברמה גבוהה ותחומי האחריות של המודולים.
• API_REFERENCE.md — תיעוד API ציבורי וממשקי API לניהול.
• FEATURES.md — מטריצת תכונות ונקודות עיקריות בגרסאות.
• RESILIENCE_GUIDE.md — סקירה מעמיקה של מפסק מעגל, תקופת צינון ונעילה.
• AUTO-COMBO.md — ניקוד ואסטרטגיות של Auto Combo.
• MCP-SERVER.md — קטלוג מלא של כלי MCP ואמצעי תעבורה.
• A2A-SERVER.md — יכולות וגילוי בפרוטוקול A2A.
• COMPRESSION_GUIDE.md — דחיסת RTK ו-Caveman.
• CLI-TOOLS.md — שילובי CLI.
• ELECTRON_GUIDE.md (אם קיים), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — יעדי פריסה.
• TROUBLESHOOTING.md — בעיות תפעוליות נפוצות.
• CONTRIBUTING.md — תהליך העבודה לתורמים.
• CLAUDE.md — כללי המאגר עבור Claude Code (מקור האמת לרבות מהמוסכמות שלעיל).
• AGENTS.md — תיעוד ארכיטקטורה מעמיק יותר המשמש סוכנים.