# OmniRoute Codebase Documentation (Igbo)

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

---

> **Ụ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](./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](../frameworks/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.

![Nchịkọta schema ebe nchekwa data (tebụl ndị bụ isi ahọpụtara)](../diagrams/exported/db-schema-overview.svg)

> Isi mmalite: [diagrams/db-schema-overview.mmd](../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/                 Ndebanye ndị na-eweta ọrụ, profaịlụ nkụnyeisi, njirimara, …
├── handlers/               Ndị njikwa arịrịọ (nkata, embeddings, ọdịyo, onyonyo, …)
├── executors/              Modulu mmebe 150 (klaasị mmebe + ndị enyemaka pụrụ iche maka onye 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/                  Ndị enyemaka nkwanye data, TLS client, 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`           | Usoro nkata bụ isi (cache, oke ọsọ, ntụgharị ngwakọta, iziga na mmebe) |
| `responsesHandler.ts`   | Ebe mbata OpenAI Responses API                                         |
| `embeddings.ts`         | Embeddings                                                             |
| `imageGeneration.ts`    | Mmepụta onyonyo                                                        |
| `audioSpeech.ts`        | Ederede gaa n'okwu ọnụ                                                 |
| `audioTranscription.ts` | Okwu ọnụ gaa n'ederede                                                 |
| `videoGeneration.ts`    | Mmepụta vidiyo                                                         |
| `musicGeneration.ts`    | Mmepụta egwu                                                           |
| `rerank.ts`             | Ịhazigharị ọkwa                                                        |
| `moderations.ts`        | Nnyocha ọdịnaya                                                        |
| `search.ts`             | Ọchụchọ webụ                                                           |
| `sseParser.ts`          | Ihe nyocha mmemme SSE                                                  |
| `usageExtractor.ts`     | Iwepụta ọnụọgụ token n'ime nkwanye data sitere n'elu                   |
| `responseSanitizer.ts`  | Iwepụ mkpọtụ pụrụ iche nke 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/`

Modulu mmebe ọkwa elu 150 (`*.ts` ewezuga `base.ts`, `index.ts` na ule — nke a bụ ọnụọgụ
`npm run check:docs-counts` na-atụ). Klaasị mmebe ọ bụla na-agbatị `BaseExecutor` (`base.ts`),
ozugbo ma ọ bụ site na `DefaultExecutor` ma ọ bụ mmebe ọzọ; modulu ndị fọdụrụ bụ ndị enyemaka
pụrụ iche maka onye na-eweta ọrụ (schemas ngwaọrụ, ihe nkwụnye fetch/TTS, ndị njikwa akparamagwa pụrụ iche). Ndị mmebe gụnyere:

`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`
(onye enyemaka njirimara a na-ekekọrịta) na `index.ts` (ndebanye).

> Rịba ama: `default.ts` na-eji mmebe izugbe dakọtara na OpenAI nye ọrụ maka ndị na-eweta ọrụ
> ndị a na-edeghị ebe a. Katalọgụ ndị na-eweta ọrụ zuru ezu (ndị na-eweta ọrụ 372) 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`.
- **Ndị enyemaka 9** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`, tinyere
  ule ndị enyemaka.
- **Ndị enyemaka onyonyo** (`translator/image/sizeMapper.ts`).
- Ọkwa elu: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

### 4.4 `open-sse/transformer/`

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

### 4.5 `open-sse/services/`

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

| Ihe gbasara ya   | Faịlụ                                                                                                                                                                                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nduzi 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 nwa oge  | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| Amamihe nduzi    | `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`                                                                                                                                                                                                                    |
| Nhazi n'ìgwè     | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| Ojiji            | `usage.ts`                                                                                                                                                                                                                                               |

### 4.6 `open-sse/mcp-server/`

- **Ngwaọrụ pụrụ iche 110** ejikọtara na `server.ts` (45 bụ ndị canonical dị na `schemas/tools.ts` +
  modulu ebe nchekwa, nka, GitHub-skills, pool, gamification, plugin, Notion, Obsidian,
  local-corpus na mkpakọ — `countUniqueMcpTools` na-agụ njikọ ha).
- **Ụzọ mbufe 3**: stdio, HTTP Streamable, SSE.
- **Scopes 33** a na-amanye n'oge sistemụ na-arụ ọrụ — ndepụta ntọala dị na `src/shared/constants/mcpScopes.ts`, usoro zuru ezu bụ njikọ scopes ndị modulu ngwaọrụ ọ bụla kwupụtara.
- Tebụl nyocha: `mcp_tool_audit` (nke `audit.ts` na-ejupụta).
- 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__/`.
- Lee [MCP-SERVER.md](../frameworks/MCP-SERVER.md) maka katalọgụ ngwaọrụ zuru ezu.

### 4.7 `open-sse/config/`

Ndebanye ndị na-eweta ọrụ (`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)

![Usoro arịrịọ (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> Isi mmalite: [diagrams/request-pipeline.mmd](../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](./RESILIENCE_GUIDE.md) na ngalaba pụrụ iche dị na
[CLAUDE.md](../../CLAUDE.md).

---

## 10. Otu E Si Nye Aka

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

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

### Tinye ụzọ API ọhụrụ

1. Mepụta `src/app/api/your-route/route.ts`.
2. Soro usoro a: CORS → nkwado body site na Zod → auth → inyefe ọrụ n'aka handler.
3. Ọ bụrụ na ọ bụ nhazi arịrịọ ọhụrụ: tinye schema Zod na `src/shared/validation/schemas.ts`.
4. Ọ 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).
5. Tinye ule n'okpuru `tests/unit/`.
6. Melite `docs/reference/API_REFERENCE.md` na `docs/openapi.yaml`.

### Tinye modul DB ọhụrụ

1. Mepụta `src/lib/db/yourModule.ts` ma webata `getDbInstance()` site na `./core.ts`.
2. Bupụ ọrụ CRUD maka ngalaba gị.
3. Ọ 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.
4. 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`).
5. Tinye ule n'okpuru `tests/unit/`.

### Tinye ngwa MCP ọhụrụ

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

### Tinye nka A2A ọhụrụ

Lee [A2A-SERVER.md § Ịtinye Nka Ọhụrụ](../frameworks/A2A-SERVER.md). 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)

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

---

## 13. Hụkwa

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