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

CODEBASE_DOCUMENTATION (አማርኛ)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 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

---

---

title: "የOmniRoute ኮድቤዝ ሰነድ" version: 3.8.40 lastUpdated: 2026-06-28

የOmniRoute ኮድቤዝ ሰነድ

ስሪት: v3.8.51 ለመጨረሻ ጊዜ የተዘመነው: 2026-06-28 ታዳሚዎች: ለOmniRoute አስተዋጽኦ የሚያደርጉ ወይም በእሱ ላይ ውህደቶችን የሚገነቡ መሐንዲሶች።

የከፍተኛ ደረጃ የሥነ ሕንፃ ንድፎችን እና ከእያንዳንዱ ንዑስ ስርዓት ጀርባ ያለውን ምክንያታዊ አስተሳሰብ ለማወቅ ARCHITECTURE.mdን ያንብቡ። ስለ እያንዳንዱ ንዑስ ስርዓት ዝርዝር ማብራሪያ (Auto Combo፣ MCP server፣ A2A server፣ Skills፣ Memory፣ Cloud Agents፣ Resilience፣ Compression፣ ወዘተ) ለማግኘት በዚህ 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 በኩል (singleton፣ WAL journaling)
ዴስክቶፕ	Electron 41 + electron-builder 26.10 (በelectron/ የሚገኝ የተለየ workspace)
ሙከራዎች	Node native test runner (unit/integration)፣ Vitest (MCP፣ autoCombo፣ cache)፣ Playwright (e2e + protocols-e2e)
ግንባታ	Next.js standalone በscripts/build/build-next-isolated.mjs በኩል
Lint/ቅርጸት	ESLint flat config + Prettier (lint-staged በHusky pre-commit በኩል)
የሞጁል ስርዓት	ESM በሁሉም ቦታ ("type": "module")
Workspaces	npm workspace — open-sse ብቸኛው ንዑስ-workspace ነው

የዱካ ተለዋጭ ስሞች (tsconfig.json)፦

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

ነባሪ HTTP port፦ 20128 (API እና dashboard ተመሳሳዩን process ይጋራሉ)። የውሂብ ማውጫው DATA_DIR env var ሲሆን፣ ነባሪ ዋጋው ~/.omniroute/ ነው።

---

2. የማከማቻው አቀማመጥ

OmniRoute/
├── src/                  የNext.js መተግበሪያ (App Router፣ libs፣ domain፣ server፣ shared)
├── open-sse/             የStreaming engine workspace (@omniroute/open-sse)
├── electron/             የዴስክቶፕ wrapper (Electron 41 main + preload)
├── bin/                  የCLI መግቢያ ነጥቦች (omniroute፣ reset-password)
├── tests/                Unit፣ integration፣ e2e፣ protocols-e2e፣ translator፣ security፣ fixtures
├── scripts/              የግንባታ፣ ማመሳሰል፣ ፍተሻ፣ migration እና የአሂድ ጊዜ አጋዥ scripts
├── docs/                 ይፋዊ ሰነዶች (ይህ ማውጫ)
├── public/               Static assets፣ PWA manifest፣ service worker
├── config/               የአሂድ ጊዜ config ናሙናዎች
├── images/               የግብይት/ቅጽበታዊ ገጽ እይታ assets
├── _ideia/, _references/, _mono_repo/, _tasks/   ውስጣዊ ሙከራ / ዕቅድ (በምርቱ ውስጥ አይካተትም)
├── CLAUDE.md             ለClaude Code የማከማቻ ደንቦች
├── AGENTS.md             ለagents የበለጠ ጥልቅ የሥነ ሕንፃ ማጣቀሻ
├── package.json          v3.8.51፣ የworkspace root
└── tsconfig.json         የዱካ ተለዋጭ ስሞች + ዋና የcompiler አማራጮች

---

3. src/ — Next.js መተግበሪያ

src/
├── app/                  የApp Router ገጾች + API መስመሮች
├── lib/                  ዋና ቤተ-መጻሕፍት (DB፣ ማረጋገጫ፣ OAuth፣ ክህሎቶች፣ ማህደረ ትውስታ፣ …)
├── domain/               ንጹህ የዶሜይን ንብርብር (ፖሊሲ፣ አማራጭ፣ ወጪ፣ መቆለፍ፣ …)
├── server/               የሰርቨር-ብቻ ሞጁሎች (ፈቃድ አሰጣጥ፣ cors፣ ማረጋገጫ)
├── shared/               ዓይነቶች፣ ቋሚዎች፣ ማረጋገጫ፣ ውሎች፣ መገልገያዎች (ድንበር ተሻጋሪ አስተማማኝ)
├── mitm/                 ከCLI ጋር ለማዋሃድ የመካከለኛ-ሰው ፕሮክሲ አጋዦች
├── models/               የአካባቢያዊ ሞዴል ሜታዳታ / ቅጽል ስም አሰጣጥ
├── sse/                  አሁንም በsrc/ ሥር ያሉ የቆዩ SSE አስተናጋጆች (በopen-sse/ ውስጥ ያልሆኑ)
├── store/                የደንበኛ-ወገን ሁኔታ ማከማቻዎች
├── middleware/           የመስመር-ደረጃ መካከለኛ ሶፍትዌር መገልገያዎች (የNext.js ዓለም-አቀፍ መካከለኛ ሶፍትዌር አይደለም)
├── scripts/              በመተግበሪያ ኮድ ሊጫኑ የሚችሉ በዛፉ ውስጥ ያሉ ስክሪፕቶች
├── types/                ዙሪያዊ እና የጋራ TS ዓይነቶች
├── i18n/                 የቋንቋ ጥቅሎች
├── instrumentation.ts    የNext.js መሣሪያ-መለኪያ ማያያዣ
├── instrumentation-node.ts
└── proxy.ts              ከፍተኛ-ደረጃ የፕሮክሲ ማስነሻ አጋዥ

3.1 src/app/ — App Router

App Router ሁለቱንም የዳሽቦርድ UI እና የሕዝብ/አስተዳደር HTTP API ያቀርባል። ዓለም-አቀፍ መካከለኛ ሶፍትዌር የለም — ጣልቃ መግባት በእያንዳንዱ መስመር ይከናወናል።

በsrc/app/ ሥር ያሉ ከፍተኛ-ደረጃ ክፍሎች፦

ዱካ	ዓላማ
api/	ሁሉም የHTTP API መስመሮች (ከታች ያለውን ዝርዝር ይመልከቱ)
a2a/	የA2A JSON-RPC 2.0 መጨረሻ ነጥብ (POST /a2a)
.well-known/agent.json/	የA2A Agent Card ማግኛ ሰነድ
(dashboard)/	የዳሽቦርድ UI (የመስመር ቡድን፣ የ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/ — የUI ገጾች

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/         ከOpenAI ጋር ተኳሃኝ የሕዝብ API
├── v1beta/     የGemini-ዓይነት ተኳሃኝነት
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — የተካተቱ አገልግሎቶች አስተዳደር

9Router እና CLIProxyAPIን ለመጫን፣ ለማስጀመር፣ ለማቆም እና ለመከታተል የሚያገለግሉ መስመሮች። npm installን ሊጠሩ እና ንዑስ ሂደቶችን ሊያስነሱ ስለሚችሉ፣ ሁሉም ዱካዎች LOCAL_ONLY (loopback ብቻ፣ ጥብቅ ደንብ #17) ተብለው ተመድበዋል።

src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() ረዳት
│   ├── install/route.ts    POST — በ execFile በኩል 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 ማድረግ
│   ├── rotate-key/route.ts POST — አዲስ API ቁልፍ ማመንጨት + እንደገና ማስጀመር
│   ├── status/route.ts     GET  — ቀጥታ + DB ሁኔታ + የስሪት ሜታዳታ
│   └── 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  — ቀጥታ + DB ሁኔታ + የስሪት ሜታዳታ
│   └── auto-start/route.ts POST — የ auto_start ጠቋሚን መቀያየር
└── [name]/
    └── logs/route.ts       GET  — የ SSE ሎግ ጭራ (በሁሉም አገልግሎቶች የሚጋራ)

ተዛማጅ የዳሽቦርድ UI፦ src/app/(dashboard)/dashboard/providers/services/ — ባለሁለት-ትር ገጽ (CLIProxyAPI + 9Router)። ለተካተተው የ9Router UI የተገላቢጦሽ ፕሮክሲ፦ src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

ጥልቅ ማብራሪያ፦ docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — ከOpenAI ጋር ተኳሃኝ የሕዝብ API

v1/
├── accounts/[id]/                       የመለያ ፍለጋ
├── agents/tasks/[id]/, agents/tasks/    የA2A ቅርጽ ያላቸው የተግባር መገልገያዎች
├── api/                                 በ v1/api ስር የቀረቡ የውስጥ API ረዳቶች
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    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/	Agent-Control-Protocol፦ 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 ምላሾች ውስጥ ጥቅም ላይ የሚውሉ የUI/ማሳያ አጋዥ መሳሪያዎች
embeddings/	የመክተት አገልግሎት መዝገብ
env/	የ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 (ከOpenAPI ዝርዝር መግለጫ REST መጨረሻ ነጥቦችን ያወጣል)፣ cliRegistryParser.ts (ከbin/cli-registry የCLI ንዑስ ትዕዛዞችን ያወጣል)፣ 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/	የZed አርታዒ OAuth ፍሰት

በsrc/lib/ ውስጥ ያሉ ከፍተኛ-ደረጃ ፋይሎች፦

• የቀድሞው localDb.ts barrel ተወግዷል — ተጠቃሚዎች የተወሰኑ src/lib/db/* ሞጁሎችን በቀጥታ import ያደርጋሉ።
• 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/

Singleton SQLite የውሂብ ጎታ (getDbInstance() በcore.ts ውስጥ፣ WAL journaling)። በroutes ወይም handlers ውስጥ raw SQL ፈጽሞ አይጻፉ — በእነዚህ ሞጁሎች በኩል ይጠቀሙ።

ምንጭ፦ diagrams/db-schema-overview.mmd

የdomain ሞጁሎች (እያንዳንዱ የአንድ ወይም ከዚያ በላይ ሰንጠረዦች ባለቤት ነው)፦ 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 ፋይሎችን (idempotent፣ transactional) ይይዛል፣ እና ሲነሳ በmigrationRunner.ts ይፈጸማል።

በmigrations በሙሉ የተፈጠሩ ሰንጠረዦች (በድምሩ 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 (በተጨማሪም ለmemory ፍለጋ የFTS5 virtual ሰንጠረዦች)።

3.3 src/domain/ — የDomain ንብርብር

I/O የሌለው ንጹህ የንግድ ሎጂክ። በroutes እና handlers import ይደረጋል።

ፋይል	ዓላማ
policyEngine.ts	ከፍተኛ-ደረጃ የpolicy resolver
fallbackPolicy.ts	የFallback ውሳኔ ዛፍ
costRules.ts	የወጪ ስሌት ደንቦች
lockoutPolicy.ts	የሞዴል lockout ውሳኔዎች
tagRouter.ts	በtag ላይ የተመሠረተ routing
comboResolver.ts	ከrequest → ዒላማ ዝርዝር የcombo resolution
connectionModelRules.ts	ለእያንዳንዱ connection የሞዴል filters
modelAvailability.ts	የሞዴል ተገኝነት ማረጋገጫ
degradation.ts	ወደ degraded-mode የሚደረጉ transitions
providerExpiration.ts	ጊዜው ያለፈበትን account/key መለየት
quotaCache.ts	Cache የተደረጉ የquota ውሳኔዎች
responses.ts, omnirouteResponseMeta.ts	የresponse shape አጋዥ መሣሪያዎች
configAudit.ts	የconfig ለውጥ audit
assessment/	የሞዴል ግምገማ (በRFC መሠረት፣ በከፊል ተተግብሯል)
types.ts	የጋራ የdomain types

3.4 src/server/ — ለServer ብቻ

ከclient components import ማድረግ አይቻልም።

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        routesን public ወይም management በማለት ይመድባል
│   ├── assertAuth.ts      የAssertion አጋዥ
│   ├── context.ts         ለእያንዳንዱ request የauthz context
│   ├── headers.ts
│   ├── pipeline.ts        የAuthz pipeline
│   ├── policies/          ተጨባጭ policies
│   └── types.ts
└── cors/origins.ts        የCORS origin allowlist

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/ — ወደ npm የሚላኩ ይፋዊ API ውሎች።
• types/ — የጋራ TS ዓይነቶች።
• utils/ — circuitBreaker.ts፣ apiAuth.ts፣ apiKey.ts፣ apiKeyPolicy.ts፣ api.ts፣ classify429.ts፣ cliCompat.ts፣ clipboard.ts፣ cloud.ts፣ cn.ts፣ cors.ts፣ featureFlags.ts፣ fetchTimeout.ts፣ formatting.ts፣ inputSanitizer.ts፣ logger.ts፣ machine.ts፣ machineId.ts፣ maskEmail.ts፣ modelCatalogSearch.ts፣ nodeRuntimeSupport.ts፣ parseApiKeys.ts፣ providerHints.ts፣ providerModelAliases.ts፣ rateLimiter.ts፣ releaseNotes.ts፣ a11yAudit.ts፣ እንዲሁም በservices/፣ network/፣ middleware/፣ schemas/፣ hooks/፣ components/ ስር ያሉ የዳሽቦርድ hooks/components።

---

4. open-sse/ — የዥረት ሞተር የሥራ ቦታ

እንደ @omniroute/open-sse የሚታተም የተለየ npm የሥራ ቦታ። የጥያቄ ሂደት፣ አስፈጻሚዎች፣ ተርጓሚዎች፣ አገልግሎቶች፣ ቀያሪው እና 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 (መዝገብ)።

ማስታወሻ፦ እዚህ ያልተዘረዘሩ አቅራቢዎች ከOpenAI ጋር ተኳሃኙን አጠቃላይ አስፈጻሚ በመጠቀም በdefault.ts ይስተናገዳሉ። ሙሉው የአቅራቢዎች ካታሎግ (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 ማዘዋወር	combo.ts (19 ስልቶች)፣ comboConfig.ts፣ comboMetrics.ts፣ comboManifestMetrics.ts፣ comboAgentMiddleware.ts
ራስ-ሰር 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፣ 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/           የግንባታ ውጤት (ወደ ማከማቻው አልተመዘገበም)

በworkspace ሥር አምስት npm ስክሪፕቶች አሉ፦ electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged። ራስ-ሰር ማዘመን የGitHub ልቀት ምንጭን በሚጠቁመው electron-updater በኩል ይከናወናል።

---

6. bin/ — CLI

bin/
├── omniroute.mjs           ዋናው የCLI መግቢያ (Node ESM)
├── reset-password.mjs      የአስተዳደር የይለፍ ቃልን ከCLI ዳግም ያስጀምሩ
├── mcp-server.mjs          የMCP አገልጋይ አስጀማሪ (stdio)
├── nodeRuntimeSupport.mjs  የNode ስሪት መከላከያ
└── cli/
    ├── program.mjs         የCommander ፕሮግራም ገንቢ
    ├── runtime.mjs         withRuntime ረዳት (ቅድሚያ-ለአገልጋይ/DB-አማራጭ)
    ├── output.mjs          የውጤት ቅርጸት አዘጋጆች (json/jsonl/table/csv)
    ├── i18n.mjs            ቋንቋዊ አካባቢዎች ያሉት t() ረዳት
    ├── api.mjs             የAPI fetch ረዳት
    ├── 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/	ተሻጋሪ-ሞጁል + የDB ሁኔታ ሙከራዎች
tests/e2e/	የPlaywright UI ሙከራዎች
tests/e2e/protocol-clients.test.ts	የMCP/A2A ፕሮቶኮል e2e
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 UI ስብስብ
npm run test:protocols:e2e	የMCP + A2A ፕሮቶኮል e2e
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/ ውስጥ executor ያክሉ (BaseExecutorን ያስፋፉ)።
3. OpenAI ቅርጸትን የማይጠቀም ከሆነ በopen-sse/translator/ ውስጥ translator ያክሉ።
4. በOAuth ላይ የተመሠረተ ከሆነ በsrc/lib/oauth/providers/ እና src/lib/oauth/services/ ስር config ያክሉ።
5. ሞዴሎችን በopen-sse/config/providerRegistry.ts (ወይም በopen-sse/config/ ስር ባለው ቅርጸት-ተኮር registry) ውስጥ ይመዝግቡ።
6. በtests/unit/ ስር ሙከራዎችን ይጻፉ።

አዲስ API route ማከል

1. src/app/api/your-route/route.tsን ይፍጠሩ።
2. ይህን ንድፍ ይከተሉ፦ CORS → የZod body ማረጋገጫ → auth → ወደ handler ማስተላለፍ።
3. አዲስ የrequest ቅርጽ ከሆነ፦ የZod schemaውን በsrc/shared/validation/schemas.ts ውስጥ ያክሉ።
4. ለአስተዳደር ብቻ ከሆነ፦ pathውን ወደ src/shared/constants/publicApiRoutes.ts ያክሉ (ለሕዝባዊ API በይነገጽ denylist)።
5. በtests/unit/ ስር ሙከራዎችን ያክሉ።
6. docs/reference/API_REFERENCE.mdን እና docs/openapi.yamlን ያዘምኑ።

አዲስ DB module ማከል

1. src/lib/db/yourModule.tsን ይፍጠሩ እና getDbInstance()ን ከ./core.ts import ያድርጉ።
2. ለdomainዎ CRUD functionsን export ያድርጉ።
3. አዲስ tables ካሉ፦ በsrc/lib/db/migrations/ ስር በተከታታይ ቁጥር የተሰጠው፣ idempotent እና transactional የሆነ migration ያክሉ።
4. Importers ከ@/lib/db/yourModule ቀጥተኛ importsን ይጠቀማሉ (barrel የለም — የቀድሞው localDb.ts re-export layer ተወግዷል)።
5. በtests/unit/ ስር ሙከራዎችን ያክሉ።

አዲስ MCP tool ማከል

1. የtool definitionን በopen-sse/mcp-server/tools/ ስር ያክሉ (ወይም open-sse/mcp-server/schemas/tools.tsን ያስፋፉ)።
2. ተገቢውን scope(ዎች) በsrc/shared/constants/mcpScopes.ts ውስጥ ይመድቡ።
3. toolውን በopen-sse/mcp-server/server.ts ውስጥ ይመዝግቡ።
4. በopen-sse/mcp-server/__tests__/ ስር ሙከራዎችን ያክሉ።
5. MCP-SERVER.mdን ያዘምኑ።

አዲስ A2A skill ማከል

A2A-SERVER.md § አዲስ Skill ማከልን ይመልከቱ። Skills በ src/lib/a2a/skills/ ውስጥ ይገኛሉ እና በA2A task manager በኩል ይመዘገባሉ።

---

11. ስምምነቶች

• የኮድ ቅጥ፦ ባለ2-space indent፣ double quotes፣ 100 char width፣ semicolons፣ es5 trailing commas — በlint-staged በኩል በPrettier ይተገበራል።
• Imports፦ external → internal (@/, @omniroute/open-sse) → relative።
• ስያሜ፦ files camelCase ወይም kebab-case፣ components PascalCase፣ constants UPPER_SNAKE።
• ESLint፦ no-eval፣ no-implied-eval፣ no-new-func = error በሁሉም ቦታ፤ no-explicit-any = warn በopen-sse/ እና tests/ ውስጥ፣ በሌሎች ቦታዎች error።
• TypeScript፦ strict: false (የቆየ አቋም)። በmodule ወሰኖች መካከል inferenceን ከመጠቀም ይልቅ explicit typesን ይምረጡ።
• Database፦ በroutes ወይም handlers ውስጥ raw SQLን በፍጹም አይጻፉ — ሁልጊዜ በsrc/lib/db/ modules በኩል ይሂዱ። barrel-import በፍጹም አያድርጉ — የተወሰኑ src/lib/db/* modulesን በቀጥታ ይጠቀሙ።
• የDB-entity typing (#3512)፦ የDB tableን row shape የሚጽፍ ወይም የሚያነብ function የዚያን table columns 1:1 የሚያንጸባርቅ named TS interface እንደ input መቀበል/መመለስ አለበት፤ anyን ወይም በcall site ላይ inline anonymous typeን መጠቀም የለበትም። interfaceውን ከfunction አጠገብ ያኑሩ (ለምሳሌ፣ በsrc/lib/usage/usageHistory.ts ውስጥ ከsaveRequestUsage በላይ export interface UsageEntry)፤ የተለያዩ writers rowውን በደረጃ ሲሞሉ እያንዳንዱን field optional/nullable አድርገው ያቆዩ፣ እና shapeው በcallers መካከል ለሚለዋወጥ field ከany ይልቅ unknownን ይምረጡ (በfieldው ላይ ይመዝገብ፤ ለምሳሌ፣ UsageEntry.tokens raw provider-shaped usageንም ሆነ normalized shapeን ይቀበላል)። በዚህ መንገድ የአንድ file any ብዛት ዜሮ ከደረሰ በኋላ ወደ check:any-budget:t11 allowlist (scripts/check/check-t11-any-budget.mjs, maxAny: 0) ያክሉት፣ ይህም ወደ ኋላ እንዳይመለስ ያደርጋል። ይህ first-slice convention ነው — ሰፊው "anonymous any የለም" cleanup በቀሪው codebase ላይ በየደረጃው ይከናወናል።
• ስህተቶች፦ ከተወሰኑ error types ጋር try/catchን ይጠቀሙ፣ ከpino context ጋር log ያድርጉ። በSSE streams ውስጥ ስህተቶችን በፍጹም በጸጥታ አይውጡ፤ ለcleanup abort signalsን ይጠቀሙ።
• ደኅንነት፦ eval() / new Function() / implied evalን በፍጹም አይጠቀሙ። ሁሉንም inputs በZod ያረጋግጡ። credentialsን ባሉበት ሁኔታ ያመስጥሩ (AES-256-GCM)። የsrc/shared/constants/upstreamHeaders.ts denylistን ከ sanitize/validation layer ጋር የተጣጣመ ያድርጉ።
• Commits፦ Conventional Commits — feat(scope): subject። የተፈቀዱ scopes፦ db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills።
• Branches፦ prefixes feat/, fix/, refactor/, docs/, test/, chore/። በቀጥታ ወደ main commit በፍጹም አያድርጉ።
• Husky፦ pre-commit lint-staged + check:docs-sync + check:any-budget:t11ን ያስኬዳል፤ pre-push check:any-budget:t11 + check:tracked-artifactsን ያስኬዳል (ፈጣን gates፤ test:unitን አያካትትም)።

---

12. ጥብቅ ደንቦች (ከCLAUDE.md)

1. ሚስጥሮችን ወይም የመግቢያ ማረጋገጫዎችን በፍጹም commit አታድርጉ።
2. barrel-import በፍጹም አይጠቀሙ — የተወሰኑ src/lib/db/* ሞጁሎችን በቀጥታ ይጠቀሙ።
3. eval() / new Function() / በተዘዋዋሪ የሚደረግ eval በፍጹም አይጠቀሙ።
4. በቀጥታ ወደ main commit በፍጹም አታድርጉ።
5. በroutes ውስጥ raw SQL በፍጹም አይጻፉ — ሁልጊዜ በsrc/lib/db/ ሞጁሎች በኩል ይጠቀሙ።
6. በSSE streams ውስጥ ስህተቶችን ያለማሳወቅ በፍጹም አይውጡ።
7. ግብዓቶችን ሁልጊዜ በZod schemas ያረጋግጡ።
8. production code በሚቀየርበት ጊዜ ሁልጊዜ tests ያካትቱ።
9. Coverage ≥ 60% ሆኖ መቆየት አለበት (statements፣ lines፣ functions፣ branches)።

---

13. በተጨማሪ ይመልከቱ

• ARCHITECTURE.md — ከፍተኛ ደረጃ አርክቴክቸር እና የሞጁሎች ኃላፊነቶች።
• API_REFERENCE.md — የይፋ + የአስተዳደር API ማጣቀሻ።
• FEATURES.md — የባህሪያት ማትሪክስ እና የስሪቶች ዋና ዋና ነጥቦች።
• RESILIENCE_GUIDE.md — ስለ circuit breaker፣ cooldown እና lockout ዝርዝር ማብራሪያ።
• AUTO-COMBO.md — የAuto Combo ነጥብ አሰጣጥ እና ስልቶች።
• MCP-SERVER.md — ሙሉ የMCP መሣሪያዎች ካታሎግ + ማጓጓዣዎች።
• A2A-SERVER.md — የA2A protocol ክህሎቶች እና ፍለጋ።
• COMPRESSION_GUIDE.md — RTK + Caveman compression።
• 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 — የdeployment ዒላማዎች።
• TROUBLESHOOTING.md — የተለመዱ የክወና ችግሮች።
• CONTRIBUTING.md — የአስተዋጽዖ አድራጊዎች የሥራ ፍሰት።
• CLAUDE.md — ለClaude Code የrepo ደንቦች (ከላይ ለተጠቀሱት ብዙዎቹ ስምምነቶች ዋና ምንጭ)።
• AGENTS.md — በagents ጥቅም ላይ የሚውል ዝርዝር የአርክቴክቸር ማጣቀሻ።