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

OmniRoute Codebase Documentation (Yorùbá)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 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 · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Ẹ̀yà: v3.8.51 Ìgbà ìmúdójúìwọ̀n tó kẹ́yìn: 2026-06-28 Àwọn olùkà: Àwọn onímọ̀-ẹ̀rọ tí ń ṣàfikún sí OmniRoute tàbí tí ń kọ́ àwọn ìṣọ̀kan lórí rẹ̀.

Fún àwọn àwòrán atọ́ka ìṣètò ìmọ̀-ẹ̀rọ gbogbogbò àti ìrònú tó wà lẹ́yìn ẹ̀ka-iṣẹ́ kọ̀ọ̀kan, ka ARCHITECTURE.md. Fún àlàyé jíjinlẹ̀ nípa àwọn ẹ̀ka-iṣẹ́ kọ̀ọ̀kan (Auto Combo, MCP server, A2A server, Skills, Memory, Cloud Agents, Resilience, Compression, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ), wo àwọn fáìlì tí a yàn fún wọn nínú àkójọpọ̀ docs/ yìí.

Fáìlì yìí ṣàpèjúwe ohun tó wà nínú ibi ìpamọ́ kóòdù náà lónìí kí onímọ̀-ẹ̀rọ tuntun lè lọ káàkiri ìṣètò igi náà, lóye bí àwọn ìpele runtime ṣe tò, kí ó sì mọ ibi tí yóò ti ṣàfikún kóòdù láì dá àwọn module tuntun sílẹ̀.

---

1. Àkójọpọ̀ Ìmọ̀ Ẹ̀rọ

Ohun tí a ń bójú tó	Àṣàyàn
Framework wẹ́ẹ̀bù	Next.js 16 (App Router, àbájáde standalone, kò sí middleware àgbáyé)
Èdè	TypeScript 6.0+ — ibi àfojúsùn ES2022, module: esnext, moduleResolution: bundler, strict: false
Àyíká ìṣiṣẹ́	Node.js >=22.22.2 <23 tàbí >=24.0.0 <27 (a fi tipátipá mú un ṣiṣẹ́ nípasẹ̀ engines + SUPPORTED_NODE_RANGE)
Ìpamọ́ data	SQLite nípasẹ̀ better-sqlite3 (singleton, ìkọ̀wé journal WAL)
Ẹ̀rọ orí tábìlì	Electron 41 + electron-builder 26.10 (workspace ọ̀tọ̀ ní electron/)
Àwọn ìdánwò	Ẹ̀rọ ìdánwò abinibi Node (unit/integration), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Ìkọ́	Next.js standalone nípasẹ̀ scripts/build/build-next-isolated.mjs
Lint/format	Àtòpọ̀ ESLint flat + Prettier (lint-staged nípasẹ̀ Husky pre-commit)
Ètò module	ESM níbi gbogbo ("type": "module")
Àwọn workspace	npm workspace — open-sse nìkan ni workspace abẹ́ rẹ̀

Àwọn alias ipa-ọ̀nà (tsconfig.json):

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

Port HTTP àìyípadà: 20128 (API àti dashboard ń lo process kan náà). Àkójọ data jẹ́ env var DATA_DIR, tí iye àìyípadà rẹ̀ jẹ́ ~/.omniroute/.

---

2. Ìṣètò Ibi Ìpamọ́ Kóòdù

OmniRoute/
├── src/                  Ohun èlò Next.js (App Router, libs, domain, server, shared)
├── open-sse/             Workspace ẹ̀rọ streaming (@omniroute/open-sse)
├── electron/             Ohun ìdìpọ̀ ẹ̀rọ orí tábìlì (Electron 41 main + preload)
├── bin/                  Àwọn ibi ìbẹ̀rẹ̀ CLI (omniroute, reset-password)
├── tests/                Unit, integration, e2e, protocols-e2e, translator, security, fixtures
├── scripts/              Àwọn script ìrànlọ́wọ́ fún ìkọ́, sync, check, migration, àti runtime
├── docs/                 Àkọsílẹ̀ gbogbogbò (àkójọ yìí)
├── public/               Àwọn asset static, manifest PWA, service worker
├── config/               Àwọn àpẹẹrẹ config runtime
├── images/               Àwọn asset fún ìpolówó/àwòrán ojú-iboju
├── _ideia/, _references/, _mono_repo/, _tasks/   Àwọn àkọsílẹ̀ inú ilé / ètò (a kò fi wọ́n ránṣẹ́)
├── CLAUDE.md             Àwọn òfin ibi ìpamọ́ kóòdù fún Claude Code
├── AGENTS.md             Ìtọ́kasí faaji tó jinlẹ̀ sí i fún àwọn agent
├── package.json          v3.8.51, gbòǹgbò workspace
└── tsconfig.json         Àwọn alias ipa-ọ̀nà + àwọn àṣàyàn compiler pàtàkì

---

3. src/ — Ìṣàfilọ́lẹ̀ Next.js

src/
├── app/                  Àwọn ojú-ewé App Router + àwọn ipa-ọ̀nà API
├── lib/                  Àwọn ibi-ìkówèésí pàtàkì (DB, ìfàṣẹsí, OAuth, àwọn ọgbọ́n, ìrántí, …)
├── domain/               Ìpele domain mímọ́ (ìlànà, fallback, iye owó, lockout, …)
├── server/               Àwọn module fún server nìkan (authz, cors, auth)
├── shared/               Àwọn irú, constant, ìfọwọ́sowọ́pọ̀, contract, utils (tó láìléwu láàárín ààlà)
├── mitm/                 Àwọn olùrànlọ́wọ́ proxy man-in-the-middle fún ìṣọ̀kan CLI
├── models/               Metadata model agbègbè / fífi alias sí
├── sse/                  Àwọn handler SSE àtijọ́ tí ó ṣì wà lábẹ́ src/ (kì í ṣe open-sse/)
├── store/                Àwọn ibi-ìpamọ́ state ní ẹ̀gbẹ́ client
├── middleware/           Àwọn ohun èlò middleware ipele-ipa-ọ̀nà (kì í ṣe middleware àgbáyé Next.js)
├── scripts/              Àwọn script inú igi tí kóòdù app lè import
├── types/                Àwọn irú TS àyíká àti pínpín
├── i18n/                 Àwọn àkójọpọ̀ locale
├── instrumentation.ts    Hook instrumentation Next.js
├── instrumentation-node.ts
└── proxy.ts              Olùrànlọ́wọ́ bootstrap proxy ipele-òkè

3.1 src/app/ — App Router

App Router ń ṣí UI dashboard àti API HTTP gbogbogbò/ìṣàkóso síta. Kò sí middleware àgbáyé — ìdádúró ń ṣẹlẹ̀ ní ipa-ọ̀nà kọ̀ọ̀kan.

Àwọn abala ipele-òkè lábẹ́ src/app/:

Ipa-ọ̀nà	Ète
api/	Gbogbo àwọn ipa-ọ̀nà API HTTP (wo ìtúpalẹ̀ ní ìsàlẹ̀)
a2a/	Endpoint A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Àkọsílẹ̀ ìṣàwárí A2A Agent Card
(dashboard)/	UI dashboard (ẹgbẹ́ ipa-ọ̀nà, kò ní ìpele URL níwájú)
auth/, login/, forgot-password/, callback/	Àwọn ìṣàn ìfàṣẹsí
landing/	Ojú-ewé títajà/ìbẹ̀rẹ̀
docs/	Olùwò docs API tí a fi sínú rẹ̀
status/, maintenance/, offline/	Àwọn ojú-ewé ìṣiṣẹ́
privacy/, terms/	Àwọn ojú-ewé òfin
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Àwọn ojú-ewé àṣìṣe static
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Àwọn ààlà àṣìṣe/ìrùjá framework
layout.tsx, page.tsx, globals.css, manifest.ts	Shell gbòǹgbò

3.1.1 src/app/(dashboard)/dashboard/ — Àwọn ojú-ewé 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, pẹ̀lú page.tsx, HomePageClient.tsx, BootstrapBanner.tsx gbòǹgbò.

3.1.2 src/app/api/ — Àwọn ẹgbẹ́ API ipele-òkè

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/   Ìṣàkóso iṣẹ́ tí a fi sínú rẹ̀ (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API gbogbogbò tó bá OpenAI mu
├── v1beta/     Ìbámu ara Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Ìṣàkóso Àwọn Iṣẹ́ Tí A Fi Sínú Rẹ̀

Àwọn ipa-ọ̀nà fún fífi 9Router àti CLIProxyAPI sílẹ̀, bíbẹ̀rẹ̀ wọn, dídá wọn dúró, àti ṣíṣọ́ wọn. Gbogbo àwọn ipa-ọ̀nà ni a pín sí ẹ̀ka LOCAL_ONLY (loopback nìkan, òfin líle #17) nítorí pé wọ́n lè pe npm install kí wọ́n sì dá àwọn process ọmọ sílẹ̀.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             olùrànlọ́wọ́ getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install nípasẹ̀ 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 ẹ̀yà tuntun
│   ├── rotate-key/route.ts POST — ṣe ìpilẹ̀ṣẹ̀ kọ́kọ́rọ́ API tuntun + tún bẹ̀rẹ̀
│   ├── status/route.ts     GET  — ipò lọ́wọ́lọ́wọ́ + ipò DB + metadata ẹ̀yà
│   └── auto-start/route.ts POST — yí àsíá auto_start padà
├── cliproxy/
│   ├── _lib.ts             olùrànlọ́wọ́ 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 ẹ̀yà tuntun
│   ├── status/route.ts     GET  — ipò lọ́wọ́lọ́wọ́ + ipò DB + metadata ẹ̀yà
│   └── auto-start/route.ts POST — yí àsíá auto_start padà
└── [name]/
    └── logs/route.ts       GET  — ìrù àkọsílẹ̀ SSE (gbogbo iṣẹ́ ló ń lò ó)

UI dásibọ́ọ̀dù tó bá a mu: src/app/(dashboard)/dashboard/providers/services/ — ojú-ewé táàbù méjì (CLIProxyAPI + 9Router). Aṣojú ìpadà fún UI 9Router tí a fi sínú: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Àlàyé jíjinlẹ̀: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API gbogbogbò tó bá OpenAI mu

v1/
├── accounts/[id]/                       ìṣàwárí àkọọ́lẹ̀
├── agents/tasks/[id]/, agents/tasks/    àwọn endpoint iṣẹ́ tó ní àbùdá A2A
├── api/                                 àwọn olùrànlọ́wọ́ API inú tí a ṣí sílẹ̀ lábẹ́ v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (endpoint pàtàkì)
├── completions/                         àwọn ìparí ọ̀rọ̀ àtijọ́
├── embeddings/                          àwọn ìfibsínú
├── files/[id]/, files/                  Files API
├── _helpers/                            àwọn olùrànlọ́wọ́ route tí a jọ ń lò (kò ní URL gbogbogbò)
├── images/{edits, generations}/         ìṣẹ̀dá + àtúnṣe àwòrán
├── issues/                              àwọn endpoint olùrànlọ́wọ́ fún ìṣètò ìṣòro
├── management/{proxies}/                àwọn route tó ní àyè ìṣàkóso nínú v1
├── messages/{count_tokens}/             ìbámu àwọn ìfiránṣẹ́ ara Anthropic
├── models/                              àtòjọ model (`route.ts`, `catalog.ts`)
├── moderations/                         àyẹ̀wò àkóónú
├── music/                               ìṣẹ̀dá orin
├── providers/[provider]/                àwọn iṣẹ́ fún provider kọ̀ọ̀kan
├── quotas/{check}                       àwọn ìdánwò quota
├── registered-keys/                     ìṣàkóso àwọn kọ́kọ́rọ́ tí a forúkọsílẹ̀
├── rerank/                              títún ṣe ìṣètò ipò
├── responses/[...path]/                 OpenAI Responses API (catch-all)
├── search/                              ìṣàwárí wẹ́ẹ̀bù
├── videos/                              ìṣẹ̀dá fídíò
├── ws/                                  afárá WebSocket
└── route.ts                             olùṣàkóso atọ́ka

Fáìlì route kọ̀ọ̀kan ń tẹ̀lé àpẹẹrẹ kan náà:

Route → ìṣàyẹ̀wò ìbẹ̀rẹ̀ CORS → ìfọwọ́sí body Zod → ìfàṣẹsí àṣàyàn
      → ìmúṣẹ ìlànà kọ́kọ́rọ́ API → fífi iṣẹ́ lé handler lọ́wọ́ (open-sse)

v1beta/ ni ojú ìbámu ara Gemini (àṣọ̀ ìta kékeré kan tó ń túmọ̀ rẹ̀ sínú pipeline open-sse/handlers/ kan náà).

3.2 src/lib/ — Àwọn ilé-ìkàwé pàtàkì

Nígbà gbogbo, ṣàgbéwọlé data, ìṣiṣẹ́pọ̀, OAuth, skill, memory, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ nípasẹ̀ àwọn module wọ̀nyí. Tábìlì náà ṣàkójọpọ̀ àwọn directory gangan àti àwọn fáìlì ipele-òkè tó ṣe pàtàkì.

Módùlù	Ète
a2a/	Sẹ́fà ìlànà A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (ọgbọ́n 6: ìtúpalẹ̀ iye owó, ìròyìn ìlera, ìṣàwárí olùpèsè, ìṣàkóso ìwọ̀n lílò, ìdarí ọlọ́gbọ́n, àkójọ àwọn agbára)
acp/	Ìlànà-Ìṣàkóso-Aṣojú: index.ts, manager.ts, registry.ts
api/	Àwọn olùrànlọ́wọ́ API inú: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (àtúntò ọ̀rọ̀ aṣínà / hashing)
batches/	Iṣẹ́ OpenAI Batches API (service.ts)
catalog/	Ìṣiṣẹ́pọ̀ katalogi OpenRouter (openrouterCatalog.ts)
cloudAgent/	Àkọsílẹ̀ aṣojú àwọsánmà: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Àwọn olùrànlọ́wọ́ ìyànjú àpapọ̀
compliance/	Àyẹ̀wò + àyẹ̀wò olùpèsè: index.ts, providerAudit.ts
config/	Àsopọ̀ àtúnṣe àsìkò-ṣiṣe
db/	Àwọn módùlù àgbègbè SQLite (wo §3.2.1)
display/	Àwọn olùrànlọ́wọ́ UI/ìfihàn tí àwọn ìdáhùn API ń lò
embeddings/	Àkọsílẹ̀ iṣẹ́ embedding
env/	Ìgbéwọlé Env + àyẹ̀wò inú
evals/	Àsìkò-ṣiṣe ìdánwò
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Àwọn iṣẹ́ abẹ́lẹ̀ (autoUpdate.ts, …)
memory/	Ìrántí alápẹ́: 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/	Àwọn módùlù OAuth/ìgbéwọlé olùpèsè (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, pẹ̀lú services/, utils/, àti constants/oauth.ts
plugins/	Olùgbé plugin wọlé (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Ìgbésí-ayé awoṣe tí a ń ṣàkóso: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Àwọn olùrànlọ́wọ́ olùpèsè: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — àwọn àtúnṣe fún olùdáwọ́lé iyíká, àkókò ìsinmi, àti títìpa
runtime/	Ìṣàwárí ẹ̀ya àsìkò-ṣiṣe
search/	executeWebSearch.ts
services/	Ètò iṣẹ́ àwọn iṣẹ́ àfikún: ServiceSupervisor.ts (alábòójútó ìlànà-ọmọ gbogbogbòò tó ní títì iṣẹ́, búfà òrùka, àti olùṣàyẹ̀wò ìlera), bootstrap.ts (ìforúkọsílẹ̀ ní ìpele ìlànà àti ìbẹ̀rẹ̀ aládàáṣiṣẹ́), registry.ts (maapu irinṣẹ́ → alábòójútó), apiKey.ts (ibi ìpamọ́ kọ́kọ́rọ́ AES-256-GCM), modelSync.ts (ìṣiṣẹ́pọ̀ awoṣe lẹ́ẹ̀kọ̀ọ̀kan), ringBuffer.ts (búfà àkọsílẹ̀ yíyípo 5 MB), healthCheck.ts (ìwádìí ìlera HTTP), types.ts, embedWsProxy.ts (aṣojú WebSocket), installers/{ninerouter,cliproxy}.ts. Wo docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Katalogi + olùpèsè Agent Skills: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → kọ skills/{id}/SKILL.md), openapiParser.ts (ń yọ àwọn endpoint REST jáde láti inú àlàyé OpenAPI), cliRegistryParser.ts (ń yọ àwọn àṣẹ abẹ́lẹ̀ CLI jáde láti inú bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Àwọn ipa-ọ̀nà REST (/api/agent-skills/*), àwọn irinṣẹ́ MCP (omniroute_agent_skills_*), àti ọgbọ́n A2A list-capabilities ló ń lò ó. Wo AGENT-SKILLS.md.
skills/	Ètò ọgbọ́n: 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, pẹ̀lú builtin/browser.ts
spend/	batchWriter.ts (búfà ìkọ̀wé lẹ́yìn)
sync/	bundle.ts, tokens.ts (Ìṣiṣẹ́pọ̀ Àwọsánmà)
system/	Àwọn olùrànlọ́wọ́ ìpele ètò
translator/	Àsopọ̀ olùtumọ̀ ìpele-òkè (ń fi iṣẹ́ lé open-sse/translator/ lọ́wọ́)
usage/	Ìṣírò lílò: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Ìmúdójúìwọ̀n aládàáṣiṣẹ́ + àfihàn ẹ̀yà
ws/	Afárá WebSocket
zed-oauth/	Ìṣàn OAuth olóòtú Zed

Àwọn fáìlì ipele-òkè nínú src/lib/:

• A yọ fáìlì àpapọ̀ localDb.ts àtijọ́ kúrò — àwọn olùlò ń ṣàgbéwọlé àwọn módù src/lib/db/* pàtó ní tààrà.
• 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/

Àkójọpọ̀ dátà SQLite singleton (getDbInstance() nínú core.ts, ìkọ̀wé WAL). Má ṣe kọ SQL àìṣètò sínú àwọn route tàbí handler láé — lo àwọn módù wọ̀nyí.

Orísun: diagrams/db-schema-overview.mmd

Àwọn módù ẹ̀ka iṣẹ́ (ọ̀kọ̀ọ̀kan ló ni tábìlì kan tàbí jù bẹ́ẹ̀ lọ): 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/ ní àwọn fáìlì .sql 168 tí a fi nọ́ńbà ẹ̀yà sí (tí ó jẹ́ idempotent, tí ó sì ń ṣiṣẹ́ gẹ́gẹ́ bí transaction), a sì ń ṣiṣẹ́ wọn nípasẹ̀ migrationRunner.ts nígbà ìbẹ̀rẹ̀.

Àwọn tábìlì tí a ṣẹ̀dá káàkiri àwọn ìṣípo náà (123 lápapọ̀):

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 (pẹ̀lú àwọn tábìlì virtual FTS5 fún ìṣàwárí ìrántí).

3.3 src/domain/ — Ìpele ẹ̀ka iṣẹ́

Ìrònú iṣẹ́ mímọ́, kò ní I/O. Àwọn route àti handler ló ń ṣàgbéwọlé rẹ̀.

Fáìlì	Ète
policyEngine.ts	Olùyanjú ìlànà ipele-òkè
fallbackPolicy.ts	Igi ìpinnu fallback
costRules.ts	Àwọn òfin ìṣírò iye owó
lockoutPolicy.ts	Àwọn ìpinnu títì model kúrò
tagRouter.ts	Ìdarí ipa-ọ̀nà tó dá lórí tag
comboResolver.ts	Ìyanjú combo láti ìbéèrè → àkójọ ibi àfojúsùn
connectionModelRules.ts	Àwọn àsẹ̀ model fún connection kọ̀ọ̀kan
modelAvailability.ts	Àyẹ̀wò wíwà model
degradation.ts	Àwọn ìyípadà sí ipò iṣẹ́ tí ó dínkù
providerExpiration.ts	Ìṣàwárí account/key tí àkókò rẹ̀ ti parí
quotaCache.ts	Àwọn ìpinnu quota tí a fi pamọ́ sínú cache
responses.ts, omnirouteResponseMeta.ts	Àwọn olùrànlọ́wọ́ fún ìrísí response
configAudit.ts	Àyẹ̀wò àyípadà config
assessment/	Àyẹ̀wò model (gẹ́gẹ́ bí RFC, a ṣe apá kan rẹ̀)
types.ts	Àwọn type ẹ̀ka iṣẹ́ tí a ń pín

3.4 src/server/ — Fún server nìkan

A kò lè ṣàgbéwọlé rẹ̀ láti inú àwọn component client.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Ń pín àwọn route sí ti gbogbo ènìyàn tàbí ti ìṣàkóso
│   ├── assertAuth.ts      Olùrànlọ́wọ́ assertion
│   ├── context.ts         Context authz fún ìbéèrè kọ̀ọ̀kan
│   ├── headers.ts
│   ├── pipeline.ts        Pipeline authz
│   ├── policies/          Àwọn ìlànà gidi
│   └── types.ts
└── cors/origins.ts        Àkójọ origin CORS tí a gbà láàyè

3.5 src/shared/ — Ó bójú mu láti pín

A pín in sí àwọn subdirectory tó dojú kọ iṣẹ́ pàtó:

• constants/ — providers.ts (àkójọ àwọn olùpèsè tí Zod ti fọwọ́sí), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (àkójọ ìdènà), 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 (nǹkan bí 80 àwòrán Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — àwọn àdéhùn API gbogbogbò tí a pín kiri sí npm.
• types/ — àwọn irú TS tí a ń lò pọ̀.
• 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, pẹ̀lú àwọn hook/ẹ̀yà dashboard lábẹ́ services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Ààyè iṣẹ́ ẹ̀rọ ṣiṣàn

Ààyè iṣẹ́ npm ọ̀tọ̀ tí a tẹ̀jáde gẹ́gẹ́ bí @omniroute/open-sse. Ó ń bójú tó ṣíṣe àwọn ìbéèrè, àwọn olùṣiṣẹ́, àwọn olùtumọ̀, àwọn iṣẹ́, olùyípadà, àti olupin MCP.

open-sse/
├── index.ts                Àwọn ohun tí a kó jáde fún gbogbo ènìyàn
├── package.json            Àkọsílẹ̀ ààyè iṣẹ́
├── tsconfig.json
├── types.d.ts
├── config/                 Àwọn àkọsílẹ̀ olùpèsè, àwọn prófáìlì àkọlé, ìdánimọ̀, …
├── handlers/               Àwọn olùdarí ìbéèrè (ìfọ̀rọ̀wérọ̀, embeddings, ohun, àwòrán, …)
├── executors/              Àwọn olùṣiṣẹ́ HTTP 108 tí ó jẹ́ pàtó sí olùpèsè
├── translator/             Ìyípadà fọ́ọ̀mù (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Olùyípadà ṣiṣàn Responses API ↔ Chat Completions
├── services/               Àwọn módùlù iṣẹ́ 80+ (àwọn àkópọ̀, àfidípò, iye ìlò, ìdánimọ̀, …)
├── utils/                  Àwọn olùrànlọ́wọ́ ṣiṣàn, oníbàárà TLS, AWS SigV4, ìgbàwá proxy, …
└── mcp-server/             Olupin MCP (àwọn ọ̀nà ìgbékalẹ̀ 3, àwọn ààlà 33, àwọn irinṣẹ́ 110)

4.1 open-sse/handlers/

Olùdarí	Ète
chatCore.ts	Ìlànà ìfọ̀rọ̀wérọ̀ àkọ́kọ́ (cache, ààlà ìwọ̀n, ìdarí àkópọ̀, fífi ránṣẹ́ sí olùṣiṣẹ́)
responsesHandler.ts	Ibi ìwọlé OpenAI Responses API
embeddings.ts	Àwọn embedding
imageGeneration.ts	Ṣíṣẹ̀dá àwòrán
audioSpeech.ts	Ọ̀rọ̀-kíkọ sí ohùn
audioTranscription.ts	Ohùn sí ọ̀rọ̀-kíkọ
videoGeneration.ts	Ṣíṣẹ̀dá fídíò
musicGeneration.ts	Ṣíṣẹ̀dá orin
rerank.ts	Àtúntò ipò
moderations.ts	Àyẹ̀wò àkóónú
search.ts	Ìṣàwárí lórí wẹ́ẹ̀bù
sseParser.ts	Olùtúpalẹ̀ ìṣẹ̀lẹ̀ SSE
usageExtractor.ts	Yíyọ iye token jáde láti inú àwọn ṣiṣàn orísun-òkè
responseSanitizer.ts	Yíyọ ariwo tí ó jẹ́ pàtó sí olùpèsè kúrò
responseTranslator.ts	Asopọ̀ láàárín ìdáhùn olùpèsè àti ìpele olùtumọ̀

4.2 open-sse/executors/

Àwọn olùṣiṣẹ́ olùpèsè 108, tí ọ̀kọ̀ọ̀kan ń jogún láti 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, pẹ̀lú claudeIdentity.ts (olùrànlọ́wọ́ ìdánimọ̀ tí a pín) àti index.ts (àkọsílẹ̀).

Àkíyèsí: àwọn olùpèsè tí a kò tò síbí ni default.ts ń ṣiṣẹ́ fún nípasẹ̀ olùṣiṣẹ́ gbogbogbòò tí ó bá OpenAI mu. Àkójọ olùpèsè kíkún (àwọn olùpèsè 355) wà nínú src/shared/constants/providers.ts.

4.3 open-sse/translator/

Ìtumọ̀ ọ̀nà ibùdó-àti-ẹ̀ka (OpenAI ni ibùdó).

• Àwọn olùtumọ̀ ìbéèrè 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.
• Àwọn olùtumọ̀ ìdáhùn 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.
• Àwọn olùrànlọ́wọ́ 9 (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, àti àwọn ìdánwò olùrànlọ́wọ́.
• Àwọn olùrànlọ́wọ́ àwòrán (translator/image/sizeMapper.ts).
• Ìpele òkè: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — Olùyípadà Responses API ↔ Chat Completions tí a gbé karí TransformStream (tí ọ̀nà responses/ catch-all ń lò).

4.5 open-sse/services/

Àwọn apá pàtàkì (àkójọ kíkún wà lábẹ́ open-sse/services/):

Ìbákẹ́dùn	Àwọn fáìlì
Ìtọ́sọ́nà Combo	combo.ts (àwọn ọgbọ́n 19), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Ẹ́ńjìnnì 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
Ìfaradà sí ìṣòro	accountFallback.ts (àkókò ìsinmi + ìdènà), errorClassifier.ts, requestRejectedStreak.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Àwọn ìdíwọ̀n lílò	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Ìfipamọ́ fún ìyára	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Òye inú ìtọ́sọ́nà	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Ìṣàkóso awoṣe	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Ìfúnpọ̀	compression/ — gbogbo ìsopọ̀ ẹ́ńjìnnì ìfúnpọ̀
Tókẹ́ẹ̀nì + sáà	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Ìpele / manifẹ́ẹ̀sì	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / nẹ́tíwọ̀ọ̀kì	ipFilter.ts, webSearchFallback.ts
Àwọn ìpele-iṣẹ́	batchProcessor.ts
Ìlò	usage.ts

4.6 open-sse/mcp-server/

• Àwọn irinṣẹ́ aláìlẹ́gbẹ́ 110 ni a so pọ̀ nínú server.ts (45 àtọwọ́dọ́wọ́ nínú schemas/tools.ts + ìrántí, ọgbọ́n, GitHub-skills, àkójọpọ̀, ìmúlò bí eré, plugin, Notion, Obsidian, local-corpus àti àwọn módù ìfúnpọ̀ — a ka ìṣọ̀kan wọn nípasẹ̀ countUniqueMcpTools).
• Àwọn ọ̀nà ìgbékalẹ̀ 3: stdio, HTTP Streamable, SSE.
• Àwọn ààyè-àṣẹ 33 ni a fi agbára mú ní àkókò ìṣiṣẹ́ — àtòjọ ìpìlẹ̀ wà nínú src/shared/constants/mcpScopes.ts, àkójọpọ̀ kíkún sì ni ìṣọ̀kan àwọn ààyè-àṣẹ tí módù irinṣẹ́ kọ̀ọ̀kan kéde.
• Tábìlì àyẹ̀wò: mcp_tool_audit (tí audit.ts ń fi dátà sínú rẹ̀).
• Àwọn fáìlì: 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, pẹ̀lú àwọn ìdánwò lábẹ́ __tests__/.
• Wo MCP-SERVER.md fún àkójọ irinṣẹ́ kíkún.

4.7 open-sse/config/

Àwọn ìforúkọsílẹ̀ olùpèsè (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), àwọn ìforúkọsílẹ̀ awoṣe fún ọ̀nà-kíkó kọ̀ọ̀kan (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), àwọn olùrànlọ́wọ́ ìdánimọ̀ (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), àwọn olùrànlọ́wọ́ ẹ̀rí ìdánimọ̀ (credentialLoader.ts, codexClient.ts), àti àwọn àdápọ̀ awọsánmà (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/

Àwọn ohun ìpìlẹ̀ fún ṣiṣàn àti àwọn olùrànlọ́wọ́ olùpèsè: 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/ — Àpò ìbáṣepọ̀ ojú-iṣẹ́

electron/
├── main.js                  Ìlànà àkọ́kọ́ Electron
├── preload.js               Afárá ìṣàkójọ́-tẹ́lẹ̀ (contextIsolation ti ṣiṣẹ́)
├── types.d.ts
├── package.json             Àtúnṣe electron-builder, ẹ̀yà 3.8.51
├── README.md
├── assets/                  Àwọn ohun àmúlò fún ìkọ́lé (àwọn àwòrán àmì, àwọn ẹ̀tọ́, …)
├── node_modules/            node_modules àkànṣe (better-sqlite3, electron-updater)
└── dist-electron/           Àbájáde ìkọ́lé (a kò fi sínú ibi ìpamọ́ kóòdù)

Àwọn script npm márùn-ún ní gbòǹgbò workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Ìmúdójúìwọ̀n aládàáṣiṣẹ́ ń gba electron-updater tí ó tọ́ka sí feed ìtújáde GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Ojú-ọ̀nà ìwọlé CLI àkọ́kọ́ (Node ESM)
├── reset-password.mjs      Ṣàtúnṣe ọ̀rọ̀ aṣínà ìṣàkóso láti CLI
├── mcp-server.mjs          Olùfilọ́lẹ̀ server MCP (stdio)
├── nodeRuntimeSupport.mjs  Olùṣọ́ ẹ̀yà Node
└── cli/
    ├── program.mjs         Olùkọ́ ètò Commander
    ├── runtime.mjs         Olùrànlọ́wọ́ withRuntime (server-first/db-fallback)
    ├── output.mjs          Àwọn olùṣàkóso ìrísí àbájáde (json/jsonl/table/csv)
    ├── i18n.mjs            Olùrànlọ́wọ́ t() pẹ̀lú àwọn locale
    ├── api.mjs             Olùrànlọ́wọ́ API fetch
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Ìforúkọsílẹ̀ àṣẹ
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (fáìlì kan fún àṣẹ/ẹgbẹ́ kọ̀ọ̀kan)

A ṣe àfihàn binary méjì nínú package.json → bin:

• omniroute → bin/omniroute.mjs
• omniroute-reset-password → bin/reset-password.mjs

---

7. tests/

Àpò-ìtọ́sọ́nà	Irú
tests/unit/	Àwọn ìdánwò ẹyọ̀ nípasẹ̀ olùṣiṣẹ́ ìdánwò abinibi Node (fáìlì 1821, pẹ̀lú àwọn àpò abẹ́ api/, auth/, authz/)
tests/integration/	Àwọn ìdánwò láàárín module àti ipò DB
tests/e2e/	Àwọn ìdánwò UI Playwright
tests/e2e/protocol-clients.test.ts	Ìdánwò e2e protocol MCP/A2A
tests/translator/	Àwọn ìdánwò pàtó fún olùtumọ̀
tests/security/	Àwọn ìdánwò ìfàsẹ́yìn ààbò
tests/load/	Àwọn ìdánwò ẹrù / ìfúnpá
tests/golden-set/	Àwọn àbájáde àtọ́ka fún àwọn ìfàsẹ́yìn olùtumọ̀
tests/helpers/, tests/fixtures/, tests/manual/	Àtìlẹ́yìn

Àwọn àṣẹ tí a sábà máa ń lò:

Àṣẹ	Ohun tí ó ń ṣiṣẹ́
npm run test:unit	Gbogbo tests/unit/*.test.ts nípasẹ̀ olùṣiṣẹ́ ìdánwò Node (ìṣiṣẹ́ pọ̀ 10)
npm run test:vitest	Àkójọpọ̀ ìdánwò Vitest (MCP, autoCombo, cache)
npm run test:e2e	Àkójọpọ̀ ìdánwò UI Playwright
npm run test:protocols:e2e	Ìdánwò e2e protocol MCP + A2A
npm run test:coverage	Ààlà coverage (≥60% àwọn ìlà/gbólóhùn/function/branch)
node --import tsx/esm --test tests/unit/<file>.test.ts	Ṣíṣe fáìlì kan ṣoṣo

---

8. scripts/

A ṣètò rẹ̀ sínú àwọn àpò kékeré 6 gẹ́gẹ́ bí ète wọn.

• 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. Ìṣàn Ìbéèrè (Àkótán)

Orísun: diagrams/request-pipeline.mmd

Ìbéèrè oníbàárà
  → /v1/chat/completions (route.ts)
     Àyẹ̀wò ìṣáájú CORS
     Ìfọwọ́sí Zod (chatCompletionsSchema nínú shared/validation/schemas.ts)
     Ìfàṣẹsí (extractApiKey + isValidApiKey TÀBÍ requireManagementAuth)
     Ẹ́ńjìnnì ìlànà (src/server/authz/pipeline.ts)
     Àwọn ààbò (ìbòjú PII, ìfàwọlé prompt, afárá ìríran)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Àyẹ̀wò cache (cache ìtumọ̀ + cache kíkà)
     Ìdíwọ̀n ìwọ̀n ìbéèrè (rateLimitManager, accountSemaphore)
     Ìdarí combo (bí model bá yanjú sí combo)
       comboResolver → yípo fún target kọ̀ọ̀kan → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       mú ìbéèrè láti upstream → tún gbìyànjú/dúró díẹ̀ nípasẹ̀ accountFallback
     translateResponse() (open-sse/translator/response/*)
     Ìṣàn SSE TÀBÍ ìdáhùn JSON
     Bí ó bá jẹ́ Responses API: TransformStream nípasẹ̀ open-sse/transformer/responsesTransformer.ts
  → Àyẹ̀wò ìbámu (src/lib/compliance/)
  → Ìdáhùn sí oníbàárà

Ipò runtime fún ìfaradà (àwọn ọ̀nà mẹ́ta)

Ọ̀nà	Ààlà	Ibi
Olùdáwọ́dúró iyíká provider	Gbogbo provider	src/shared/utils/circuitBreaker.ts, a fi pamọ́ sínú domain_circuit_breakers
Àkókò ìsinmi ìsopọ̀	Account/key kan	markAccountUnavailable() nínú src/sse/services/auth.ts; accountFallback.checkFallbackError() ń lò ó
Ìdènà model	Provider + connection + model	open-sse/services/accountFallback.ts, a fi pamọ́ sínú domain_lockout_state

Wo RESILIENCE_GUIDE.md àti abala tí a yà sọ́tọ̀ nínú CLAUDE.md.

---

10. Bí O Ṣe Lè Kópa

Ṣàfikún olùpèsè tuntun

1. Forúkọsílẹ̀ rẹ̀ nínú src/shared/constants/providers.ts (Zod máa ń fọwọ́sí i nígbà ìkójọpọ̀).
2. Ṣàfikún olùṣiṣẹ́ kan nínú open-sse/executors/ bí ọgbọ́n-àmúlò àkànṣe bá ṣe pàtàkì (fa BaseExecutor gùn).
3. Ṣàfikún olùtumọ̀ kan nínú open-sse/translator/ bí kò bá lo ọ̀nà-kíkó OpenAI.
4. Bí ó bá dá lórí OAuth, ṣàfikún ààtò lábẹ́ src/lib/oauth/providers/ àti src/lib/oauth/services/.
5. Forúkọsílẹ̀ àwọn model nínú open-sse/config/providerRegistry.ts (tàbí ibi ìforúkọsílẹ̀ tó bá ọ̀nà-kíkó náà mu lábẹ́ open-sse/config/).
6. Kọ àwọn àdánwò lábẹ́ tests/unit/.

Ṣàfikún ipa-ọ̀nà API tuntun

1. Ṣẹ̀dá src/app/api/your-route/route.ts.
2. Tẹ̀lé àpẹẹrẹ yìí: CORS → ìfọwọ́sí body pẹ̀lú Zod → ìjẹ́rìísí → fífi iṣẹ́ lé handler lọ́wọ́.
3. Bí request tuntun bá ní ìrísí tuntun: ṣàfikún schema Zod náà nínú src/shared/validation/schemas.ts.
4. Bí ó bá jẹ́ ti ìṣàkóso nìkan: ṣàfikún path náà sí src/shared/constants/publicApiRoutes.ts (denylist fún àyè API gbangba).
5. Ṣàfikún àwọn àdánwò lábẹ́ tests/unit/.
6. Ṣe àfikún sí docs/reference/API_REFERENCE.md àti docs/openapi.yaml.

Ṣàfikún módùlù DB tuntun

1. Ṣẹ̀dá src/lib/db/yourModule.ts, kí o sì import getDbInstance() láti ./core.ts.
2. Export àwọn iṣẹ́ CRUD fún domain rẹ.
3. Bí àwọn table tuntun bá wà: ṣàfikún migration lábẹ́ src/lib/db/migrations/, kí nọ́ńbà wọn tẹ̀lé ara wọn, kí wọ́n jẹ́ idempotent, kí wọ́n sì jẹ́ transactional.
4. Àwọn importer gbọ́dọ̀ lo direct imports láti @/lib/db/yourModule (kò sí barrel — a ti yọ layer re-export localDb.ts àtijọ́ kúrò).
5. Ṣàfikún àwọn àdánwò lábẹ́ tests/unit/.

Ṣàfikún irinṣẹ́ MCP tuntun

1. Ṣàfikún ìtumọ̀ irinṣẹ́ náà lábẹ́ open-sse/mcp-server/tools/ (tàbí fa open-sse/mcp-server/schemas/tools.ts gùn).
2. Yan scope tó yẹ (tàbí àwọn scope tó yẹ) nínú src/shared/constants/mcpScopes.ts.
3. Forúkọsílẹ̀ irinṣẹ́ náà nínú open-sse/mcp-server/server.ts.
4. Ṣàfikún àwọn àdánwò lábẹ́ open-sse/mcp-server/__tests__/.
5. Ṣe àfikún sí MCP-SERVER.md.

Ṣàfikún ọgbọ́n A2A tuntun

Wo A2A-SERVER.md § Ṣíṣàfikún Ọgbọ́n Tuntun. Àwọn ọgbọ́n wà nínú src/lib/a2a/skills/, a sì máa ń forúkọsílẹ̀ wọn nípasẹ̀ olùṣàkóso iṣẹ́ A2A.

---

11. Àwọn Àṣà

• Ọ̀nà-kíkọ code: indent aláyè méjì, double quotes, ìbú character 100, semicolons, es5 trailing commas — Prettier ń mú wọn ṣiṣẹ́ nípasẹ̀ lint-staged.
• Àwọn import: ti òde → ti inú (@/, @omniroute/open-sse) → relative.
• Ìsọrúkọ: àwọn file camelCase tàbí kebab-case, àwọn component PascalCase, àwọn constant UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error níbi gbogbo; no-explicit-any = warn nínú open-sse/ àti tests/, error ní àwọn ibòmíràn.
• TypeScript: strict: false (ìdúró àtijọ́). Yan àwọn type tó ṣe kedere dípò inference fún àwọn ààlà tó kọjá láàárín módùlù.
• Database: má ṣe kọ SQL tààrà nínú àwọn route tàbí handler — lo àwọn módùlù src/lib/db/ nígbà gbogbo. Má ṣe barrel-import láéláé — lo àwọn módùlù src/lib/db/* pàtó ní tààrà.
• Ìsọrúkọ entity DB (#3512): function tó ń kọ tàbí ka ìrísí row table DB gbọ́dọ̀ gba/dá TS interface tó ní orúkọ padà, tí ó ṣe àfihàn àwọn column table náà ní ìbámu 1:1, kì í ṣe any tàbí type aláìlórúkọ inline níbi ìpè náà. Fi interface náà sí lẹ́gbẹ̀ẹ́ function náà (fún àpẹẹrẹ, export interface UsageEntry nínú src/lib/usage/usageHistory.ts lókè saveRequestUsage), jẹ́ kí àwọn field kọ̀ọ̀kan jẹ́ optional/nullable nígbà tí àwọn writer ọ̀tọ̀ọ̀tọ̀ bá ń kún row náà díẹ̀díẹ̀, kí o sì yan unknown dípò any fún field tí ìrísí rẹ̀ ń yàtọ̀ láàárín àwọn caller (ṣàkọsílẹ̀ rẹ̀ lórí field náà, fún àpẹẹrẹ UsageEntry.tokens gba usage ìrísí provider gangan àti ìrísí normalized). Nígbà tí iye any inú file kan bá dé òdo ní ọ̀nà yìí, ṣàfikún un sí allowlist check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) kí ó má bàa padà sẹ́yìn. Èyí jẹ́ àṣà apá-àkọ́kọ́ — iṣẹ́ ìmótótó “kò sí any aláìlórúkọ” tó gbòòrò sí i ń tẹ̀síwájú ní ìpele káàkiri gbogbo codebase náà.
• Àwọn error: lo try/catch pẹ̀lú àwọn type error pàtó, kí o sì log pẹ̀lú context pino. Má ṣe pa àwọn error mọ́ ní ìdákẹ́jẹ nínú àwọn stream SSE; lo àwọn signal abort fún ìmótótó.
• Ààbò: má ṣe lo eval() / new Function() / implied eval láéláé. Fọwọ́sí gbogbo input pẹ̀lú Zod. Encrypt àwọn credential nígbà tí wọ́n wà ní ìpamọ́ (AES-256-GCM). Jẹ́ kí denylist src/shared/constants/upstreamHeaders.ts bá layer sanitize/validation mu.
• Àwọn commit: Conventional Commits — feat(scope): subject. Àwọn scope tí a gba: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Àwọn branch: prefix feat/, fix/, refactor/, docs/, test/, chore/. Má ṣe commit sí main ní tààrà láéláé.
• Husky: pre-commit máa ń ṣiṣẹ́ lint-staged + check:docs-sync + check:any-budget:t11; pre-push máa ń ṣiṣẹ́ check:any-budget:t11 + check:tracked-artifacts (àwọn ìdánwò yíyára; kò fi test:unit sínú).

---

12. Àwọn Òfin Tí Kò Gbọdọ̀ Yípadà (láti inú CLAUDE.md)

1. Má ṣe fi àwọn àṣírí tàbí ẹ̀rí ìdánimọ̀ sínú commit láé.
2. Má ṣe lo barrel-import láé — lo àwọn module src/lib/db/* pàtó ní tààrà.
3. Má ṣe lo eval() / new Function() / eval tí a fi ọ̀nà àìṣe-taara hàn láé.
4. Má ṣe ṣe commit ní tààrà sí main láé.
5. Má ṣe kọ SQL aláìṣàtúnṣe sínú àwọn route láé — máa gba inú àwọn module src/lib/db/ kọjá nígbà gbogbo.
6. Má ṣe fi ìdákẹ́jẹ́ gbé àwọn àṣìṣe mì nínú àwọn stream SSE láé.
7. Máa fìdí àwọn input múlẹ̀ pẹ̀lú àwọn schema Zod nígbà gbogbo.
8. Máa fi àwọn test kún un nígbà gbogbo tí o bá ń yí code production padà.
9. Coverage gbọ́dọ̀ dúró ní ≥ 60% (àwọn statement, line, function, àti branch).

---

13. Tún Wo

• ARCHITECTURE.md — architecture ìpele-gíga àti àwọn ojúṣe module.
• API_REFERENCE.md — ìtọ́kasí API gbogbogbò + ìṣàkóso.
• FEATURES.md — matrix àwọn feature àti àwọn àkànṣe pàtàkì version.
• RESILIENCE_GUIDE.md — àlàyé jinlẹ̀ nípa circuit breaker, cooldown, àti lockout.
• AUTO-COMBO.md — fífi àmì sí Auto Combo àti àwọn ọ̀nà ìmúlò.
• MCP-SERVER.md — àkójọ irinṣẹ́ MCP kíkún + àwọn ọ̀nà ìgbékalẹ̀.
• A2A-SERVER.md — àwọn ọgbọ́n protocol A2A àti ìṣàwárí.
• COMPRESSION_GUIDE.md — compression RTK + Caveman.
• CLI-TOOLS.md — àwọn ìṣọ̀kan CLI.
• ELECTRON_GUIDE.md (tí ó bá wà), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — àwọn ibi ìmúṣiṣẹ́.
• TROUBLESHOOTING.md — àwọn ìṣòro ìṣiṣẹ́ tí ó wọ́pọ̀.
• CONTRIBUTING.md — workflow àwọn olùkópa.
• CLAUDE.md — àwọn òfin repo fún Claude Code (orisun òtítọ́ fún ọ̀pọ̀ àwọn àṣà tó wà lókè).
• AGENTS.md — ìtọ́kasí architecture tó jinlẹ̀ sí i tí àwọn agent ń lò.