OmniRoute Codebase Documentation (Igbo)

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

Ụdị: v3.8.51 Emelitere ikpeazụ: 2026-06-28 Ndị e bu n’obi: Ndị injinia na-atụnye ụtụ na OmniRoute ma ọ bụ na-ewulite njikọta n’elu ya.

Maka eserese nhazi usoro dị elu na ihe kpatara sistemụ nta ọ bụla, gụọ ARCHITECTURE.md. Maka nkọwa miri emi banyere sistemụ nta dị iche iche (Auto Combo, sava MCP, sava A2A, Nkà, Ncheta, Ndị nnọchi anya Cloud, Nkwụsi ike, Mkpakọ, wdg.), lee faịlụ ndị a raara nye ha n’ime ndekọ docs/ a.

Faịlụ a na-akọwa ihe dị n’ebe nchekwa koodu ugbu a ka injinia ọhụrụ wee nwee ike ịgagharị n’usoro ndekọ ahụ, ghọta nhazi oyi akwa n’oge ọrụ, ma mara ebe ọ ga-etinye koodu n’emeghị modulu ọhụrụ.

1. Ngwa Teknụzụ

Ihe metụtara ya	Nhọrọ
Framework weebụ	Next.js 16 (App Router, mmepụta standalone, enweghị middleware zuru ụwa ọnụ)
Asụsụ	TypeScript 6.0+ — ebumnuche `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`
Oge ọrụ	Node.js `>=22.22.2 <23` ma ọ bụ `>=24.0.0 <27` (a na-amanye ya site na `engines` + `SUPPORTED_NODE_RANGE`)
Ebe nchekwa data	SQLite site na `better-sqlite3` (singleton, ndekọ WAL)
Desktọọpụ	Electron 41 + `electron-builder` 26.10 (ebe ọrụ dị iche na `electron/`)
Nnwale	Ngwa nnwale mbụ nke Node (unit/integration), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Mwube	Next.js standalone site na `scripts/build/build-next-isolated.mjs`
Lint/nhazi	Nhazi kwụ ọtọ ESLint + Prettier (`lint-staged` site na Husky pre-commit)
Usoro modul	ESM n'ebe niile (`"type": "module"`)
Ebe ọrụ	ebe ọrụ npm — `open-sse` bụ naanị ebe ọrụ nta

Aha ndị ọzọ maka ụzọ (tsconfig.json):

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

Ọdụ ụgbọ mmiri HTTP ndabara: 20128 (API na dashboard na-eji otu usoro ahụ). Ndekọ data bụ env var DATA_DIR, nke ndabara ya bụ ~/.omniroute/.

2. Nhazi Ebe Nchekwa

OmniRoute/
├── src/                  Ngwa Next.js (App Router, libs, domain, server, shared)
├── open-sse/             Ebe ọrụ injin nkwanye data (@omniroute/open-sse)
├── electron/             Ihe mkpuchi desktọọpụ (Electron 41 main + preload)
├── bin/                  Ebe mbido CLI (omniroute, reset-password)
├── tests/                Unit, integration, e2e, protocols-e2e, translator, security, fixtures
├── scripts/              Skripụ enyemaka maka mwube, mmekọrịta, nyocha, mbugharị, na oge ọrụ
├── docs/                 Akwụkwọ nkọwa ọha (ndekọ a)
├── public/               Akụrụngwa static, PWA manifest, service worker
├── config/               Ihe atụ nhazi oge ọrụ
├── images/               Akụrụngwa ahịa/eserese ihuenyo
├── _ideia/, _references/, _mono_repo/, _tasks/   Ebe ide ihe / atụmatụ nke ime (anaghị ebupu ha)
├── CLAUDE.md             Iwu ebe nchekwa maka Claude Code
├── AGENTS.md             Ntụaka nhazi usoro miri emi maka ndị nnọchi anya
├── package.json          v3.8.51, mgbọrọgwụ ebe ọrụ
└── tsconfig.json         Aha ndị ọzọ maka ụzọ + nhọrọ isi nke compiler

3. `src/` — Ngwa Next.js

src/
├── app/                  Ibe App Router + ụzọ API
├── lib/                  Ọba akwụkwọ ndị bụ isi (DB, auth, OAuth, skills, memory, …)
├── domain/               Oyi akwa domain dị ọcha (policy, fallback, cost, lockout, …)
├── server/               Modulu ndị bụ naanị maka sava (authz, cors, auth)
├── shared/               Ụdị, ihe ndị anaghị agbanwe agbanwe, nkwado, nkwekọrịta, utils (dị nchebe n'ofe oke)
├── mitm/                 Ndị enyemaka proxy man-in-the-middle maka njikọta CLI
├── models/               Metadata / aliasing nke model mpaghara
├── sse/                  Ndị njikwa SSE ochie ka nọ n'okpuru src/ (ọ bụghị open-sse/)
├── store/                Ebe nchekwa state nke akụkụ client
├── middleware/           Ngwa middleware nke ọkwa route (ọ bụghị middleware zuru ụwa ọnụ nke Next.js)
├── scripts/              Skript dị n'ime osisi nke koodu ngwa nwere ike ibubata
├── types/                Ụdị TS ambient na ndị a na-ekekọrịta
├── i18n/                 Ngwugwu locale
├── instrumentation.ts    Hook instrumentation nke Next.js
├── instrumentation-node.ts
└── proxy.ts              Onye enyemaka bootstrap proxy nke ọkwa elu

3.1 `src/app/` — App Router

App Router na-ewepụta ma UI dashboard ma HTTP API ọha/njikwa. Enweghị middleware zuru ụwa ọnụ — a na-eme interception n'ụzọ route ọ bụla.

Ngalaba ọkwa elu dị n'okpuru src/app/:

Ụzọ	Ebumnuche
`api/`	Ụzọ HTTP API niile (lee nkọwa n'okpuru)
`a2a/`	Endpoint A2A JSON-RPC 2.0 (`POST /a2a`)
`.well-known/agent.json/`	Dọkụmentị nchọpụta A2A Agent Card
`(dashboard)/`	UI dashboard (otu route, enweghị prefix URL)
`auth/`, `login/`, `forgot-password/`, `callback/`	Usoro auth
`landing/`	Ibe ahịa/landing
`docs/`	Ihe nlele dọkụmentị API etinyere n'ime ya
`status/`, `maintenance/`, `offline/`	Ibe ọrụ
`privacy/`, `terms/`	Ibe iwu
`400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`	Ibe njehie static
`error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx`	Oke njehie/nbudata nke framework
`layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`	Shell mgbọrọgwụ

3.1.1 `src/app/(dashboard)/dashboard/` — Ibe 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, tinyekwara page.tsx, HomePageClient.tsx, BootstrapBanner.tsx nke mgbọrọgwụ.

3.1.2 `src/app/api/` — Otu API ndị dị n'ọkwa elu

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/   Njikwa ọrụ etinyere n'ime ya (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API ọha dakọtara na OpenAI
├── v1beta/     Ndakọrịta ụdị Gemini
├── version-manager/
└── webhooks/

3.1.2a `src/app/api/services/` — Njikwa Ọrụ Etinyere N'ime Ya

Ụzọ maka ịwụnye, ịmalite, ịkwụsị, na inyocha 9Router na CLIProxyAPI. E kewara ụzọ niile dịka LOCAL_ONLY (naanị loopback, iwu siri ike #17) n'ihi na ha nwere ike ịkpọ npm install ma mepụta child processes.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             ihe enyemaka getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install site na 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 ụdị ọhụrụ
│   ├── rotate-key/route.ts POST — mepụta API key ọhụrụ + malitegharịa
│   ├── status/route.ts     GET  — ọnọdụ ozugbo + ọnọdụ DB + metadata ụdị
│   └── auto-start/route.ts POST — gbanye ma ọ bụ gbanyụọ ọkọlọtọ auto_start
├── cliproxy/
│   ├── _lib.ts             ihe enyemaka 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 ụdị ọhụrụ
│   ├── status/route.ts     GET  — ọnọdụ ozugbo + ọnọdụ DB + metadata ụdị
│   └── auto-start/route.ts POST — gbanye ma ọ bụ gbanyụọ ọkọlọtọ auto_start
└── [name]/
    └── logs/route.ts       GET  — njedebe ndekọ SSE (ọrụ niile na-ekekọrịta ya)

UI dashboard kwekọrọ: src/app/(dashboard)/dashboard/providers/services/ — ibe taabụ abụọ (CLIProxyAPI + 9Router). Proxy ntụgharị maka UI agbakwunyere nke 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Nkọwa miri emi: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 `src/app/api/v1/` — API ọha dakọtara na OpenAI

v1/
├── accounts/[id]/                       ịchọta akaụntụ
├── agents/tasks/[id]/, agents/tasks/    endpoint ọrụ nwere ụdị A2A
├── api/                                 ihe enyemaka API ime nke e kpughere n'okpuru v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (endpoint bụ isi)
├── completions/                         mmecha ederede ochie
├── embeddings/                          embeddings
├── files/[id]/, files/                  Files API
├── _helpers/                            ihe enyemaka route a na-ekekọrịta (enweghị URL ọha)
├── images/{edits, generations}/         imepụta + idezi onyonyo
├── issues/                              endpoint enyemaka maka nhazi nsogbu
├── management/{proxies}/                route nwere oke njikwa n'ime v1
├── messages/{count_tokens}/             ndakọrịta ozi ụdị Anthropic
├── models/                              ndepụta model (`route.ts`, `catalog.ts`)
├── moderations/                         nyocha ọdịnaya
├── music/                               imepụta egwu
├── providers/[provider]/                ọrụ nke provider ọ bụla
├── quotas/{check}                       nyocha quota
├── registered-keys/                     njikwa key e debanyere aha
├── rerank/                              ịhazi ọkwa ọzọ
├── responses/[...path]/                 OpenAI Responses API (na-ejide ihe niile)
├── search/                              ọchụchọ webụ
├── videos/                              imepụta vidiyo
├── ws/                                  njikọ àkwà mmiri WebSocket
└── route.ts                             handler index

Faịlụ route ọ bụla na-agbaso otu usoro a:

Route → nyocha mbụ CORS → nkwado body site na Zod → auth ma ọ bụrụ na achọrọ ya
      → mmanye iwu API key → inyefe ọrụ n'aka handler (open-sse)

v1beta/ bụ akụkụ ndakọrịta ụdị Gemini (ihe mkpuchi dị mfe nke na-atụgharị gaa n'otu pipeline open-sse/handlers/ ahụ).

3.2 `src/lib/` — Ọba akwụkwọ ndị bụ isi

Na-ebubata data, sync, OAuth, skill, memory, wdg. mgbe niile site na modul ndị a. Tebụl ahụ na-achịkọta directory ndị dị adị na faịlụ ndị dị mkpa nọ n'ọkwa elu.

Modul	Ebumnuche
`a2a/`	Sava protocol A2A: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (nka 6: nyocha ọnụahịa, akụkọ ahụike, nchọpụta ndị na-eweta ọrụ, njikwa oke, nhazi ụzọ nwere ọgụgụ isi, depụta-ikike)
`acp/`	Agent-Control-Protocol: `index.ts`, `manager.ts`, `registry.ts`
`api/`	Ngwa enyemaka API dị n'ime: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`
`auth/`	`managementPassword.ts` (ịtọgharịa okwuntughe / hashing)
`batches/`	Ọrụ OpenAI Batches API (`service.ts`)
`catalog/`	Mmekọrịta katalọgụ OpenRouter (`openrouterCatalog.ts`)
`cloudAgent/`	Ndekọ ndị nnọchiteanya igwe ojii: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`
`combos/`	Ngwa enyemaka maka idozi ngwakọta
`compliance/`	Nnyocha + nyocha onye na-eweta ọrụ: `index.ts`, `providerAudit.ts`
`config/`	Njikọ nhazi runtime
`db/`	Modul ngalaba SQLite (lee §3.2.1)
`display/`	Ngwa enyemaka UI/ngosi nke nzaghachi API na-eji
`embeddings/`	Ndekọ ọrụ embedding
`env/`	Ibu env + nyocha ime ya
`evals/`	Runtime eval
`guardrails/`	`piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`
`jobs/`	Ọrụ ndabere (`autoUpdate.ts`, …)
`memory/`	Ebe nchekwa na-adịgide adịgide: `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/`	Modul OAuth/mbubata ndị na-eweta ọrụ (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`, tinyere `services/`, `utils/`, na `constants/oauth.ts`
`plugins/`	Ihe na-ebu plugin (`index.ts`)
`promptCache/`	`prefixAnalyzer.ts`, `index.ts`
`providerModels/`	Usoro ndụ model a na-achịkwa: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`
`providers/`	Ngwa enyemaka ndị na-eweta ọrụ: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`
`resilience/`	`settings.ts` — ntọala maka circuit breaker, cooldown, lockout
`runtime/`	Nchọpụta atụmatụ runtime
`search/`	`executeWebSearch.ts`
`services/`	Framework ọrụ agbakwunyere: `ServiceSupervisor.ts` (onye nlekọta child-process izugbe nwere mkpọchi ọrụ, ring buffer, na onye nyocha ahụike), `bootstrap.ts` (ndebanye aha n'ogo process na mmalite akpaaka), `registry.ts` (maapụ tool → supervisor), `apiKey.ts` (ebe nchekwa igodo AES-256-GCM), `modelSync.ts` (mmekọrịta model nke oge na-aga), `ringBuffer.ts` (ebe nchekwa ndekọ okirikiri 5 MB), `healthCheck.ts` (nyocha ahụike HTTP), `types.ts`, `embedWsProxy.ts` (proxy WebSocket), `installers/{ninerouter,cliproxy}.ts`. Lee `docs/frameworks/EMBEDDED-SERVICES.md`
`agentSkills/`	Katalọgụ + generator nke Agent Skills: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → na-ede `skills/{id}/SKILL.md`), `openapiParser.ts` (na-ewepụta endpoints REST site na nkọwapụta OpenAPI), `cliRegistryParser.ts` (na-ewepụta subcommands CLI site na bin/cli-registry), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Ụzọ REST (`/api/agent-skills/`), ngwaọrụ MCP (`omniroute_agent_skills_`), na nka A2A `list-capabilities` na-eji ya. Lee AGENT-SKILLS.md.
`skills/`	Framework nka: `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`, tinyere `builtin/browser.ts`
`spend/`	`batchWriter.ts` (buffer write-behind)
`sync/`	`bundle.ts`, `tokens.ts` (Cloud Sync)
`system/`	Ngwa enyemaka n'ogo sistemụ
`translator/`	Njikọ onye ntụgharị n'ogo kachasị elu (na-enyefe ọrụ n'ime `open-sse/translator/`)
`usage/`	Ngụkọ ojiji: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`
`versionManager/`	Mmelite akpaaka + manifest ụdị
`ws/`	Àkwà mmiri WebSocket
`zed-oauth/`	Usoro OAuth nke editọ Zed

Faịlụ ndị nọ n'ọkwa kachasị elu na src/lib/:

E wepụrụ barrel ochie localDb.ts — ndị na-eji ya na-ebubata modul src/lib/db/* ndị akọwapụtara kpọmkwem.
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/`

Ebe nchekwa data SQLite singleton (getDbInstance() dị na core.ts, ndekọ WAL). Edela SQL raw n'ime routes ma ọ bụ handlers ma ọlị — jiri modul ndị a gafee.

Isi mmalite: diagrams/db-schema-overview.mmd

Modul domain (nke ọ bụla na-ahụ maka otu tebụl ma ọ bụ karịa): 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/ nwere faịlụ .sql 168 nwere ụdịrị nọmba (idempotent, transactional), migrationRunner.ts na-eme ha mgbe sistemụ na-amalite.

Tebụl ndị e kere n'ofe migrations ndị ahụ (123 n'ozuzu):

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 (tinyere tebụl virtual FTS5 maka ịchọ ebe nchekwa).

3.3 `src/domain/` — Oyi akwa domain

Ezi mgbagha azụmahịa na-enweghị I/O. Routes na handlers na-ebubata ya.

Faịlụ	Ebumnuche
`policyEngine.ts`	Onye na-edozi policy nke ọkwa kachasị elu
`fallbackPolicy.ts`	Osisi mkpebi fallback
`costRules.ts`	Iwu mgbakọ ọnụ ahịa
`lockoutPolicy.ts`	Mkpebi igbochi model
`tagRouter.ts`	Routing dabere na tag
`comboResolver.ts`	Idozi combo site na request → ndepụta target
`connectionModelRules.ts`	Nzacha model maka connection ọ bụla
`modelAvailability.ts`	Nlele nnweta model
`degradation.ts`	Mgbanwe gaa na site na degraded-mode
`providerExpiration.ts`	Nchọpụta account/key kubie ume
`quotaCache.ts`	Mkpebi quota echekwara na cache
`responses.ts`, `omnirouteResponseMeta.ts`	Ndị enyemaka maka ọdịdị response
`configAudit.ts`	Audit mgbanwe config
`assessment/`	Ntụle model (dịka RFC si dị, etinyere ya n'ọrụ naanị akụkụ)
`types.ts`	Types domain ndị a na-ekekọrịta

3.4 `src/server/` — Maka server naanị

Agaghị enwe ike ibubata ya site na client components.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Na-ekewa routes dịka public ma ọ bụ management
│   ├── assertAuth.ts      Onye enyemaka assertion
│   ├── context.ts         Context authz maka request ọ bụla
│   ├── headers.ts
│   ├── pipeline.ts        Pipeline authz
│   ├── policies/          Policies doro anya
│   └── types.ts
└── cors/origins.ts        Ndepụta origin CORS ndị anabatara

3.5 `src/shared/` — Dị mma maka ịkekọrịta

E kewara ya n'ime subdirectories lekwasịrị anya:

constants/ — providers.ts (katalọgụ ndị na-eweta ọrụ nke Zod kwadoro), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (ndepụta mgbochi), 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 skima Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
contracts/ — nkwekọrịta API ọha e wepụtara na npm.
types/ — ụdị TS ndị a na-ekekọrịta.
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, tinyere hooks/components nke dashboard dị n'okpuru services/, network/, middleware/, schemas/, hooks/, components/.

4. `open-sse/` — Ebe ọrụ injin nkwanye data

Ebe ọrụ npm dị iche e bipụtara dịka @omniroute/open-sse. Ọ na-ahụ maka nhazi arịrịọ, ndị mmebe, ndị ntụgharị, ọrụ, transformer, na sava MCP.

open-sse/
├── index.ts                Mbupụ ọhaneze
├── package.json            Nkọwa ebe ọrụ
├── tsconfig.json
├── types.d.ts
├── config/                 Ndekọ ndị na-eweta ọrụ, profaịlụ header, njirimara, …
├── handlers/               Ndị njikwa arịrịọ (nkata, embeddings, ọdịyo, onyonyo, …)
├── executors/              Ndị mmebe HTTP 108 akọwapụtara maka ndị na-eweta ọrụ
├── translator/             Ntughari usoro (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions transformer nkwanye data
├── services/               Modulu ọrụ 80+ (ngwakọta, fallback, oke ojiji, njirimara, …)
├── utils/                  Ngwa enyemaka nkwanye data, onye ahịa TLS, AWS SigV4, proxy fetch, …
└── mcp-server/             Sava MCP (ụzọ mbufe 3, scopes 33, ngwaọrụ 110)

4.1 `open-sse/handlers/`

Onye njikwa	Ebumnuche
`chatCore.ts`	Pipeline nkata bụ isi (cache, oke ọsọ, ntụgharị ngwakọta, izipu na executor)
`responsesHandler.ts`	Ebe mbata OpenAI Responses API
`embeddings.ts`	Embeddings
`imageGeneration.ts`	Mmepụta onyonyo
`audioSpeech.ts`	Ederede-gaa-na-okwu
`audioTranscription.ts`	Okwu-gaa-na-ederede
`videoGeneration.ts`	Mmepụta vidiyo
`musicGeneration.ts`	Mmepụta egwu
`rerank.ts`	Ịhazigharị ọkwa
`moderations.ts`	Nnyocha ọdịnaya
`search.ts`	Nchọgharị weebụ
`sseParser.ts`	Parser mmemme SSE
`usageExtractor.ts`	Iwepụta ọnụọgụ token n'ime iyi data upstream
`responseSanitizer.ts`	Iwepụ mkpọtụ akọwapụtara maka onye na-eweta ọrụ
`responseTranslator.ts`	Njikọ dị n'etiti nzaghachi onye na-eweta ọrụ na oyi akwa ntụgharị

4.2 `open-sse/executors/`

Ndị mmebe 108 maka ndị na-eweta ọrụ, nke ọ bụla na-agbatị 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, tinyere claudeIdentity.ts (ngwa enyemaka njirimara a na-ekekọrịta) na index.ts (ndekọ).

Rịba ama: default.ts na-eji generic executor kwekọrọ na OpenAI ejere ndị na-eweta ọrụ ndị a na-edepụtaghị ebe a ozi. Katalọgụ ndị na-eweta ọrụ niile (ndị na-eweta ọrụ 355) dị na src/shared/constants/providers.ts.

4.3 `open-sse/translator/`

Ntughari hub-and-spoke (OpenAI bụ hub).

Ndị ntụgharị arị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.
Ndị ntụgharị nzaghachi 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.
Ngwa enyemaka 9 (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, tinyere ule ngwa enyemaka.
Ngwa enyemaka onyonyo (translator/image/sizeMapper.ts).
Ọkwa kachasị elu: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 `open-sse/transformer/`

responsesTransformer.ts — Ihe ntụgharị Responses API ↔ Chat Completions dabere na TransformStream (nke ụzọ responses/ catch-all na-eji).

4.5 `open-sse/services/`

Ihe ndị pụtara ìhè (ndepụta zuru ezu dị n'okpuru open-sse/services/):

Nchegbu	Faịlụ
Ntụgharị Combo	`combo.ts` (usoro 19), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`
Injin 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`
Nkwụsi ike	`accountFallback.ts` (oge nchere + mkpọchi), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`
Oke ojiji	`quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts`
Nchekwa cache	`reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`
Amamihe ntụgharị	`intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`
Njikwa model	`modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`
Mkpakọ	`compression/` — njikọ zuru ezu nke injin mkpakọ
Token + nnọkọ	`tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`
Ọkwa / manifest	`tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`
IP / netwọkụ	`ipFilter.ts`, `webSearchFallback.ts`
Ogbe	`batchProcessor.ts`
Ojiji	`usage.ts`

4.6 `open-sse/mcp-server/`

Ngwaọrụ pụrụ iche 110 ejikọrọ na server.ts (45 bụ ndị ọkọlọtọ na schemas/tools.ts + modulu ebe nchekwa, nka, nka GitHub, pool, ime-ka-egwuregwu, plugin, Notion, Obsidian, local-corpus na mkpakọ — countUniqueMcpTools na-agụta njikọta ha).
Ụzọ mbufe 3: stdio, HTTP Streamable, SSE.
Oke ikike 33 a na-amanye n'oge arụmọrụ — ndepụta ntọala dị na src/shared/constants/mcpScopes.ts, usoro zuru ezu bụ njikọta oke ikike nke modulu ngwaọrụ ọ bụla kwupụtara.
Tebụl nyocha: mcp_tool_audit (audit.ts na-ejuputa ya).
Faị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, tinyere ule ndị dị n'okpuru __tests__/.
Hụ MCP-SERVER.md maka katalọgụ ngwaọrụ zuru ezu.

4.7 `open-sse/config/`

Ndebanye ndị na-eweta (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), ndebanye model nke usoro ọ bụla (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), ihe enyemaka njirimara (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), ihe enyemaka nzere (credentialLoader.ts, codexClient.ts), na ihe nkwụnye cloud (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/`

Ihe ndị bụ isi maka nkwanye data na ihe enyemaka ndị na-eweta ọrụ: 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/` — Ihe mkpuchi desktọọpụ

electron/
├── main.js                  Usoro isi nke Electron
├── preload.js               Njikọ preload (agbanyere contextIsolation)
├── types.d.ts
├── package.json             Nhazi electron-builder, ụdị 3.8.51
├── README.md
├── assets/                  Akụrụngwa build (akara ngosi, ikike, …)
├── node_modules/            node_modules pụrụ iche (better-sqlite3, electron-updater)
└── dist-electron/           Nsonaazụ build (etinyeghị ya na commit)

E nwere script npm ise na mgbọrọgwụ workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. A na-eme mmelite akpaaka site na electron-updater nke na-arụtụ aka na feed release GitHub.

6. `bin/` — CLI

bin/
├── omniroute.mjs           Ebe mbata isi nke CLI (Node ESM)
├── reset-password.mjs      Tọgharịa okwuntughe njikwa site na CLI
├── mcp-server.mjs          Ihe mmalite sava MCP (stdio)
├── nodeRuntimeSupport.mjs  Nchekwa ụdị Node
└── cli/
    ├── program.mjs         Ihe nrụpụta mmemme Commander
    ├── runtime.mjs         Ihe enyemaka withRuntime (sava-mbụ/db-ndabere)
    ├── output.mjs          Ndị nhazi nsonaazụ (json/jsonl/table/csv)
    ├── i18n.mjs            Ihe enyemaka t() nwere locales
    ├── api.mjs             Ihe enyemaka fetch API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Ndebanye iwu
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (otu faịlụ maka iwu/otu ọ bụla)

E gosipụtara binary abụọ na package.json → bin:

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

7. `tests/`

Ndekọ	Ụdị
`tests/unit/`	Nnwale unit site na ihe na-agba nnwale nke Node (faịlụ 1821, tinyere ndekọ nta `api/`, `auth/`, `authz/`)
`tests/integration/`	Nnwale gafee modulu dị iche iche + ọnọdụ DB
`tests/e2e/`	Nnwale UI Playwright
`tests/e2e/protocol-clients.test.ts`	Nnwale e2e protocol MCP/A2A
`tests/translator/`	Nnwale ndị metụtara onye ntụgharị kpọmkwem
`tests/security/`	Nnwale nlọghachi azụ nchekwa
`tests/load/`	Nnwale ibu / nrụgide
`tests/golden-set/`	Nsonaazụ ntụaka maka nlọghachi azụ nke onye ntụgharị
`tests/helpers/`, `tests/fixtures/`, `tests/manual/`	Nkwado

Iwu ndị a na-ejikarị:

Iwu	Ihe ọ na-agba
`npm run test:unit`	`tests/unit/*.test.ts` niile site na ihe na-agba nnwale Node (concurrency 10)
`npm run test:vitest`	Otu nnwale Vitest (MCP, autoCombo, cache)
`npm run test:e2e`	Otu nnwale UI Playwright
`npm run test:protocols:e2e`	Nnwale e2e protocol MCP + A2A
`npm run test:coverage`	Ọnụ ụzọ coverage (≥60% ahịrị/nkwupụta/function/alaka)
`node --import tsx/esm --test tests/unit/<file>.test.ts`	Ịgba otu faịlụ

8. `scripts/`

A haziri ya n'ime obere folda 6 dịka ebumnuche ha si dị.

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. Usoro Arịrịọ (Nchịkọta)

Isi mmalite: diagrams/request-pipeline.mmd

Arịrịọ onye ahịa
  → /v1/chat/completions (route.ts)
     Nyocha mbido CORS
     Nkwado Zod (chatCompletionsSchema dị na shared/validation/schemas.ts)
     Nyocha njirimara (extractApiKey + isValidApiKey MA Ọ BỤ requireManagementAuth)
     Injin amụma (src/server/authz/pipeline.ts)
     Ihe nchebe (ihe na-ekpuchi PII, mbanye n'ime prompt, àkwà mmiri ọhụụ)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Nyocha cache (cache semantic + cache ọgụgụ)
     Mmachi ọnụego (rateLimitManager, accountSemaphore)
     Ntugharị ngwakọta (ọ bụrụ na e kpebie na model bụ ngwakọta)
       comboResolver → megharịa maka ebe ezubere iche ọ bụla → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       kpọtụrụ upstream → nwalee ọzọ/cherekwuo site na accountFallback
     translateResponse() (open-sse/translator/response/*)
     Stream SSE MA Ọ BỤ nzaghachi JSON
     Ọ bụrụ na ọ bụ Responses API: TransformStream site na open-sse/transformer/responsesTransformer.ts
  → Nnyocha nrubeisi (src/lib/compliance/)
  → Nzaghachi nye onye ahịa

Ọnọdụ runtime nke nkwụsi ike (usoro atọ)

Usoro	Oke	Ebe
Ihe nkwụsị sekit provider	Provider niile	`src/shared/utils/circuitBreaker.ts`, echekwara na `domain_circuit_breakers`
Oge izu ike njikọ	Otu akaụntụ/key	`markAccountUnavailable()` na `src/sse/services/auth.ts`; `accountFallback.checkFallbackError()` na-eji ya
Mkpọchi model	Provider + njikọ + model	`open-sse/services/accountFallback.ts`, echekwara na `domain_lockout_state`

Lee RESILIENCE_GUIDE.md na ngalaba pụrụ iche dị na CLAUDE.md.

10. Otu E Si Nye Aka

Tinye onye na-eweta ọrụ ọhụrụ

Debanye aha ya na src/shared/constants/providers.ts (Zod na-enyocha ya mgbe a na-ebunye ya).
Tinye executor na open-sse/executors/ ma ọ bụrụ na achọrọ usoro arụmọrụ pụrụ iche (gbasawanye BaseExecutor).
Tinye translator na open-sse/translator/ ma ọ bụrụ na ọ naghị eji usoro OpenAI.
Ọ bụrụ na ọ dabere na OAuth, tinye nhazi n'okpuru src/lib/oauth/providers/ na src/lib/oauth/services/.
Debanye ụdịdị na open-sse/config/providerRegistry.ts (ma ọ bụ registry metụtara usoro ahụ n'okpuru open-sse/config/).
Dee ule n'okpuru tests/unit/.

Tinye ụzọ API ọhụrụ

Mepụta src/app/api/your-route/route.ts.
Soro usoro a: CORS → nkwado body site na Zod → auth → inyefe ọrụ n'aka handler.
Ọ bụrụ na ọ bụ nhazi arịrịọ ọhụrụ: tinye schema Zod na src/shared/validation/schemas.ts.
Ọ bụrụ na ọ bụ naanị maka njikwa: tinye path ahụ na src/shared/constants/publicApiRoutes.ts (ndepụta ihe a jụrụ ajụ maka ihu API ọha).
Tinye ule n'okpuru tests/unit/.
Melite docs/reference/API_REFERENCE.md na docs/openapi.yaml.

Tinye modul DB ọhụrụ

Mepụta src/lib/db/yourModule.ts ma webata getDbInstance() site na ./core.ts.
Bupụ ọrụ CRUD maka ngalaba gị.
Ọ bụrụ na e nwere tebụl ọhụrụ: tinye migration n'okpuru src/lib/db/migrations/, nye ha nọmba n'usoro, mee ka ha bụrụ idempotent na transactional.
Ndị na-ebubata ihe na-eji mbubata kpọmkwem site na @/lib/db/yourModule (enweghị barrel — ewepụla oyi akwa re-export ochie nke localDb.ts).
Tinye ule n'okpuru tests/unit/.

Tinye ngwa MCP ọhụrụ

Tinye nkọwa ngwa ahụ n'okpuru open-sse/mcp-server/tools/ (ma ọ bụ gbasawanye open-sse/mcp-server/schemas/tools.ts).
Kenye scope kwesịrị ekwesị n'ime src/shared/constants/mcpScopes.ts.
Debanye ngwa ahụ na open-sse/mcp-server/server.ts.
Tinye ule n'okpuru open-sse/mcp-server/__tests__/.
Melite MCP-SERVER.md.

Tinye nka A2A ọhụrụ

Lee A2A-SERVER.md § Ịtinye Nka Ọhụrụ. Nkà dị na src/lib/a2a/skills/, a na-edebanyekwa ha site na onye njikwa ọrụ A2A.

11. Ụkpụrụ

Ụdị koodu: oghere 2 maka indent, akara nhota abụọ, obosara mkpụrụedemede 100, semicolon, trailing comma es5 — Prettier na-amanye nke a site na lint-staged.
Mbubata: nke mpụga → nke ime (@/, @omniroute/open-sse) → nke metụtara ebe dị nso.
Ịkpọ aha: faịlụ camelCase ma ọ bụ kebab-case, components PascalCase, constants UPPER_SNAKE.
ESLint: no-eval, no-implied-eval, no-new-func = error n'ebe niile; no-explicit-any = warn na open-sse/ na tests/, ma bụrụ error n'ebe ndị ọzọ.
TypeScript: strict: false (ọnọdụ e ketara n'usoro ochie). Họrọ ụdị akọwapụtara nke ọma karịa inference maka oke dị n'etiti modul.
Database: edela raw SQL ozugbo n'ime routes ma ọ bụ handlers — gafee modul src/lib/db/ mgbe niile. Ejila barrel-import mgbe ọ bụla — jiri kpọmkwem modul src/lib/db/*.
Ịkọwa ụdị entity DB (#3512): ọrụ na-ede ma ọ bụ na-agụ ọdịdị row nke tebụl DB kwesịrị ịnata/weghachite interface TS nwere aha nke na-egosipụta columns tebụl ahụ 1:1, ọ bụghị any ma ọ bụ ụdị anonymous edere n'otu ahịrị n'ebe a kpọrọ ọrụ ahụ. Debe interface ahụ n'akụkụ ọrụ ahụ (dịka export interface UsageEntry n'ime src/lib/usage/usageHistory.ts n'elu saveRequestUsage), hapụ field nke ọ bụla ka ọ bụrụ optional/nullable mgbe ndị odee dị iche iche na-ejupụta row ahụ nke nta nke nta, ma họrọ unknown karịa any maka field nke ọdịdị ya na-agbanwe n'etiti ndị na-akpọ ya (kọwaa nke a na field ahụ, dịka UsageEntry.tokens na-anabata ma raw usage nwere ọdịdị nke provider ma ọdịdị normalized). Ozugbo ọnụọgụ any nke faịlụ rutere efu site n'ụzọ a, tinye ya na allowlist check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) ka ọ ghara ịlaghachi azụ. Nke a bụ ụkpụrụ maka akụkụ mbụ — nhicha sara mbara nke "enweghị anonymous any" na-aga n'ihu n'usoro n'akụkụ ndị ọzọ nke codebase.
Njehie: jiri try/catch nwere ụdị njehie akọwapụtara, ma jiri context pino dekọọ log. Ekwela ka njehie n'ime stream SSE laa n'iyi n'enweghị ngosi; jiri abort signals maka nhicha.
Nchekwa: ejila eval() / new Function() / implied eval mgbe ọ bụla. Jiri Zod kwado inputs niile. Zoo credentials n'ụdị encryption mgbe echekwara ha (AES-256-GCM). Mee ka denylist src/shared/constants/upstreamHeaders.ts kwekọọ na oyi akwa sanitize/validation.
Commits: Conventional Commits — feat(scope): subject. Scopes ndị e kwere: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
Branches: prefixes feat/, fix/, refactor/, docs/, test/, chore/. Etinyela commit ozugbo na main.
Husky: pre-commit na-agba lint-staged + check:docs-sync + check:any-budget:t11; pre-push na-agba check:any-budget:t11 + check:tracked-artifacts (nnyocha ngwa ngwa; ọ naghị agụnye test:unit).

12. Iwu Siri Ike (sitere na CLAUDE.md)

Etinyela ihe nzuzo ma ọ bụ ozi njirimara na commit ma ọlị.
Ejila barrel-import ma ọlị — jiri modulu src/lib/db/* ndị akọwapụtara kpọmkwem.
Ejila eval() / new Function() / eval ezoro ezo ma ọlị.
Emela commit ozugbo na main ma ọlị.
Edebela raw SQL n'ime routes ma ọlị — gafee na modulu src/lib/db/ mgbe niile.
Ezochila njehie n'ime SSE streams n'enweghị ngosi.
Jiri schemas Zod nyochaa inputs mgbe niile.
Tinye tests mgbe niile mgbe ị na-agbanwe production code.
Coverage ga-anọgide ≥ 60% (statements, lines, functions, branches).

13. Hụkwa

ARCHITECTURE.md — architecture dị elu na ọrụ dịịrị modulu dị iche iche.
API_REFERENCE.md — ntụaka API ọha na nke njikwa.
FEATURES.md — matriks atụmatụ na ihe ndị pụtara ìhè na version ọ bụla.
RESILIENCE_GUIDE.md — nkọwa miri emi banyere circuit breaker, cooldown, na lockout.
AUTO-COMBO.md — Auto Combo scoring na strategies.
MCP-SERVER.md — katalọgụ MCP tools zuru ezu na transports.
A2A-SERVER.md — nka protocol A2A na discovery.
COMPRESSION_GUIDE.md — compression RTK + Caveman.
CLI-TOOLS.md — njikọta CLI.
ELECTRON_GUIDE.md (ọ bụrụ na ọ dị), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — ebe e bu n'obi ime deployment.
TROUBLESHOOTING.md — nsogbu arụmọrụ ndị a na-ahụkarị.
CONTRIBUTING.md — usoro ọrụ onye na-enye aka.
CLAUDE.md — iwu repo maka Claude Code (isi mmalite eziokwu maka ọtụtụ n'ime conventions ndị dị n'elu).
AGENTS.md — ntụaka architecture miri emi nke agents na-eji.

FilesExpand file tree

CODEBASE_DOCUMENTATION.md

Latest commit

History

CODEBASE_DOCUMENTATION.md

File metadata and controls

OmniRoute Codebase Documentation (Igbo)

1. Ngwa Teknụzụ

2. Nhazi Ebe Nchekwa

3. src/ — Ngwa Next.js

3.1 src/app/ — App Router

3.1.1 src/app/(dashboard)/dashboard/ — Ibe UI

3.1.2 src/app/api/ — Otu API ndị dị n'ọkwa elu

3.1.2a src/app/api/services/ — Njikwa Ọrụ Etinyere N'ime Ya

3.1.3 src/app/api/v1/ — API ọha dakọtara na OpenAI

3.2 src/lib/ — Ọba akwụkwọ ndị bụ isi

3.2.1 src/lib/db/

3.3 src/domain/ — Oyi akwa domain

3.4 src/server/ — Maka server naanị

3.5 src/shared/ — Dị mma maka ịkekọrịta

4. open-sse/ — Ebe ọrụ injin nkwanye data

4.1 open-sse/handlers/

4.2 open-sse/executors/

4.3 open-sse/translator/

4.4 open-sse/transformer/

4.5 open-sse/services/

4.6 open-sse/mcp-server/

4.7 open-sse/config/

4.8 open-sse/utils/

5. electron/ — Ihe mkpuchi desktọọpụ

6. bin/ — CLI

7. tests/

8. scripts/