# OmniRoute Codebase Documentation (Hausa)

🌐 **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) · 🇮🇱 [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) · 🇳🇬 [ig](../../../ig/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)

---

> **Sigar:** v3.8.51
> **Sabuntawa na ƙarshe:** 2026-06-28
> **Masu karatu:** Injiniyoyin da ke ba da gudummawa ga OmniRoute ko suke gina haɗe-haɗe a samansa.
>
> Don zane-zanen tsarin gine-gine na gaba ɗaya da dalilan da suka sa aka tsara kowane ƙaramin tsari, karanta
> [ARCHITECTURE.md](./ARCHITECTURE.md). Don cikakken bayani kan kowane ƙaramin tsari
> (Auto Combo, MCP server, A2A server, Skills, Memory, Cloud Agents, Resilience,
> Compression, da sauransu), duba fayilolinsu na musamman a cikin wannan kundin `docs/`.

Wannan fayil yana bayyana **abin da yake cikin ma'ajiyar a yau** domin sabon injiniya
ya iya kewaya tsarin kundin, ya fahimci matakan lokacin aiki, kuma ya san inda zai ƙara lamba
ba tare da ƙirƙiro sabbin modules ba.

---

## 1. Tarin Fasahohi

| Abin da ya shafa  | Zaɓi                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Tsarin yanar gizo | **Next.js 16** (App Router, standalone output, babu global middleware)                                                   |
| Harshe            | **TypeScript 6.0+** — target `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`                    |
| Muhallin aiki     | **Node.js** `>=22.22.2 <23` ko `>=24.0.0 <27` (ana tilasta shi ta `engines` + `SUPPORTED_NODE_RANGE`)                    |
| Ma'ajiyar bayanai | **SQLite** ta hanyar `better-sqlite3` (singleton, WAL journaling)                                                        |
| Manhajar tebur    | **Electron 41** + `electron-builder` 26.10 (wurin aiki na daban a `electron/`)                                           |
| Gwaje-gwaje       | **Node native test runner** (unit/integration), **Vitest** (MCP, autoCombo, cache), **Playwright** (e2e + protocols-e2e) |
| Ginawa            | Next.js standalone ta hanyar `scripts/build/build-next-isolated.mjs`                                                     |
| Lint/tsarawa      | ESLint flat config + Prettier (`lint-staged` ta hanyar Husky pre-commit)                                                 |
| Tsarin module     | ESM a ko'ina (`"type": "module"`)                                                                                        |
| Wuraren aiki      | npm workspace — `open-sse` ne kaɗai ƙaramin wurin aiki                                                                   |

Laƙaban hanyoyi (`tsconfig.json`):

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

Tsohuwar tashar HTTP: **`20128`** (API da dashboard suna amfani da process ɗaya). Kundin
bayanai shi ne env var `DATA_DIR`, kuma tsohuwar ƙimarsa ita ce `~/.omniroute/`.

---

## 2. Tsarin Ma'ajiya

```
OmniRoute/
├── src/                  Manhajar Next.js (App Router, libs, domain, server, shared)
├── open-sse/             Wurin aikin injin streaming (@omniroute/open-sse)
├── electron/             Marufin manhajar tebur (Electron 41 main + preload)
├── bin/                  Wuraren shigar CLI (omniroute, reset-password)
├── tests/                Unit, integration, e2e, protocols-e2e, translator, security, fixtures
├── scripts/              Rubutun taimako na build, sync, check, migration, da runtime
├── docs/                 Takardun jama'a (wannan kundin)
├── public/               Static assets, PWA manifest, service worker
├── config/               Samfuran runtime config
├── images/               Kadarorin tallace-tallace/hotunan allo
├── _ideia/, _references/, _mono_repo/, _tasks/   Rubuce-rubucen wucin-gadi / tsare-tsaren ciki (ba a haɗa su cikin abin da ake fitarwa)
├── CLAUDE.md             Dokokin ma'ajiya na Claude Code
├── AGENTS.md             Cikakken bayani kan tsarin gine-gine ga agents
├── package.json          v3.8.51, tushen workspace
└── tsconfig.json         Laƙaban hanyoyi + manyan zaɓuɓɓukan compiler
```

---

## 3. `src/` — Manhajar Next.js

```
src/
├── app/                  Shafukan App Router + hanyoyin API
├── lib/                  Muhimman ɗakunan karatu (DB, auth, OAuth, skills, memory, …)
├── domain/               Tsantsar matakin domain (policy, fallback, cost, lockout, …)
├── server/               Modules na uwar garke kawai (authz, cors, auth)
├── shared/               Nau'ikan bayanai, constants, validation, contracts, utils (amintattu don ketare iyakoki)
├── mitm/                 Mataimakan proxy na man-in-the-middle don haɗawa da CLI
├── models/               Metadata / aliasing na model na gida
├── sse/                  Tsofaffin handlers na SSE waɗanda har yanzu suke ƙarƙashin src/ (ba open-sse/ ba)
├── store/                Ma'ajiyoyin state na ɓangaren client
├── middleware/           Kayan aikin middleware na matakin hanya (ba global middleware na Next.js ba)
├── scripts/              Scripts na cikin bishiyar da lambar app za ta iya import
├── types/                Nau'ikan TS na ambient da na gama-gari
├── i18n/                 Tarin harsunan locale
├── instrumentation.ts    Hook na instrumentation na Next.js
├── instrumentation-node.ts
└── proxy.ts              Babban mataimakin fara proxy
```

### 3.1 `src/app/` — App Router

App Router yana samar da dashboard UI da kuma HTTP API na jama'a/gudanarwa.
**Babu global middleware** — ana yin interception ne ga kowace hanya.

Manyan sassan da ke ƙarƙashin `src/app/`:

| Hanya                                                                         | Manufa                                        |
| ----------------------------------------------------------------------------- | --------------------------------------------- |
| `api/`                                                                        | Duk hanyoyin HTTP API (duba rarrabuwar ƙasa)  |
| `a2a/`                                                                        | Endpoint na A2A JSON-RPC 2.0 (`POST /a2a`)    |
| `.well-known/agent.json/`                                                     | Takardar gano A2A Agent Card                  |
| `(dashboard)/`                                                                | Dashboard UI (rukunin hanya, babu URL prefix) |
| `auth/`, `login/`, `forgot-password/`, `callback/`                            | Matakan auth                                  |
| `landing/`                                                                    | Shafin talla/farawa                           |
| `docs/`                                                                       | Mai duba takardun API da aka saka ciki        |
| `status/`, `maintenance/`, `offline/`                                         | Shafukan gudanar da aiki                      |
| `privacy/`, `terms/`                                                          | Shafukan doka                                 |
| `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`                | Shafukan kuskure na static                    |
| `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | Iyakokin kuskure/loading na framework         |
| `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`                        | Babban tsarin tushe                           |

#### 3.1.1 `src/app/(dashboard)/dashboard/` — Shafukan 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`, tare da `page.tsx`, `HomePageClient.tsx`,
`BootstrapBanner.tsx` na tushe.

#### 3.1.2 `src/app/api/` — Manyan rukunin API

```
src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   Gudanar da ayyukan da aka saka ciki (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API na jama'a mai dacewa da OpenAI
├── v1beta/     Daidaituwa irin ta Gemini
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — Gudanar da Ayyukan da Aka Saka Ciki

Hanyoyin shigarwa, farawa, tsayarwa, da sa ido kan 9Router da CLIProxyAPI.
An ware duk hanyoyin a matsayin **LOCAL_ONLY** (loopback kawai, ƙa'ida mai tsauri #17) saboda za su
iya kiran `npm install` da ƙaddamar da child processes.

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             mataimakin getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install ta hanyar 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 na sabon sigar
│   ├── rotate-key/route.ts POST — samar da sabon API key + sake farawa
│   ├── status/route.ts     GET  — matsayin kai-tsaye + DB + metadata na siga
│   └── auto-start/route.ts POST — sauya tutar auto_start
├── cliproxy/
│   ├── _lib.ts             mataimakin 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 na sabon siga
│   ├── status/route.ts     GET  — matsayin kai-tsaye + DB + metadata na siga
│   └── auto-start/route.ts POST — sauya tutar auto_start
└── [name]/
    └── logs/route.ts       GET  — ƙarshen log na SSE (duk ayyuka suna amfani da shi)
```

UI na dashboard mai dacewa:
`src/app/(dashboard)/dashboard/providers/services/` — shafi mai tabs biyu (CLIProxyAPI + 9Router).
Reverse proxy don UI na 9Router da aka saka:
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

Bayani mai zurfi: `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — API na jama'a mai dacewa da OpenAI

```
v1/
├── accounts/[id]/                       nemo account
├── agents/tasks/[id]/, agents/tasks/    endpoints na task masu salon A2A
├── api/                                 mataimakan API na ciki da aka fallasa ƙarƙashin v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API na OpenAI Batches
├── chat/completions/                    Chat Completions (babban endpoint)
├── completions/                         tsoffin text completions
├── embeddings/                          Embeddings
├── files/[id]/, files/                  API na Files
├── _helpers/                            mataimakan route da ake rabawa (babu URL na jama'a)
├── images/{edits, generations}/         samarwa + gyaran hoto
├── issues/                              endpoints na mataimakin tantancewa
├── management/{proxies}/                routes masu iyakar management a cikin v1
├── messages/{count_tokens}/             dacewar messages mai salon Anthropic
├── models/                              jerin model (`route.ts`, `catalog.ts`)
├── moderations/                         Tantance abun ciki
├── music/                               samar da kiɗa
├── providers/[provider]/                ayyuka na kowane provider
├── quotas/{check}                       binciken quota
├── registered-keys/                     gudanar da key da aka yi wa rajista
├── rerank/                              Sake jeri
├── responses/[...path]/                 API na OpenAI Responses (mai kama duk hanyoyi)
├── search/                              Binciken yanar gizo
├── videos/                              samar da bidiyo
├── ws/                                  gadar WebSocket
└── route.ts                             mai sarrafa index
```

Kowane fayil na route yana bin tsari iri ɗaya:

```
Route → preflight na CORS → tabbatar da ingancin body ta Zod → auth na zaɓi
      → tilasta manufofin API key → miƙa aikin sarrafawa (open-sse)
```

`v1beta/` shi ne shimfiɗar dacewa mai salon Gemini (siririn wrapper da ke fassara zuwa
pipeline ɗin `open-sse/handlers/` iri ɗaya).

### 3.2 `src/lib/` — Muhimman libraries

Koyaushe shigo da data, sync, OAuth, skill, memory, da sauransu ta waɗannan modules. Wannan
teburin yana haɗa ainihin directories da muhimman fayilolin matakin sama.

| Module            | Manufa                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/`            | Sabar protokol ta A2A: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (ƙwarewa 6: nazarin kuɗi, rahoton lafiyar tsarin, gano mai samarwa, sarrafa ƙayyadaddun amfani, zaɓin hanya mai wayo, jera iyawa)                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `acp/`            | Protokol na Sarrafa Wakili: `index.ts`, `manager.ts`, `registry.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `api/`            | Kayan taimako na API na ciki: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `auth/`           | `managementPassword.ts` (sake saita kalmar sirri / hashing)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `batches/`        | Sabis na OpenAI Batches API (`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `catalog/`        | Daidaita kundin OpenRouter (`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `cloudAgent/`     | Rajistar wakilan cloud: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `combos/`         | Mataimakan warware haɗaka                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `compliance/`     | Binciken bin ƙa'ida + binciken mai bayarwa: `index.ts`, `providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `config/`         | Manne-haɗin saitunan lokacin aiki                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `db/`             | Modulolin fannin SQLite (duba §3.2.1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `display/`        | Mataimakan UI/nuni da martanin API ke amfani da su                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `embeddings/`     | Rajistar sabis na embedding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `env/`            | Loda Env + binciken ciki                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `evals/`          | Muhallin gudanar da Eval                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `guardrails/`     | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `jobs/`           | Ayyukan bango (`autoUpdate.ts`, …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `memory/`         | Ma’adanar dindindin: `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/`          | Modulolin masu samar da OAuth/shigo da bayanai (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`, tare da `services/`, `utils/`, da `constants/oauth.ts`                                                                                                                                                                                                                                                                                                                          |
| `plugins/`        | Mai loda plugin (`index.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `promptCache/`    | `prefixAnalyzer.ts`, `index.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `providerModels/` | Gudanar da zagayowar rayuwar model: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `providers/`      | Mataimakan provider: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `resilience/`     | `settings.ts` — saituna don circuit breaker, cooldown, lockout                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `runtime/`        | Gano fasalolin runtime                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `services/`       | Tsarin ayyukan da aka haɗa: `ServiceSupervisor.ts` (mai sa ido kan child-process na gama-gari tare da operation lock, ring buffer, da health checker), `bootstrap.ts` (rajista da farawa ta atomatik a matakin process), `registry.ts` (taswirar tool → supervisor), `apiKey.ts` (ma'ajiyar maɓalli ta AES-256-GCM), `modelSync.ts` (aiki tare na model lokaci-lokaci), `ringBuffer.ts` (ma'ajiyar log mai zagayawa ta 5 MB), `healthCheck.ts` (binciken lafiyar HTTP), `types.ts`, `embedWsProxy.ts` (wakilin WebSocket), `installers/{ninerouter,cliproxy}.ts`. Duba `docs/frameworks/EMBEDDED-SERVICES.md`                                                                                               |
| `agentSkills/`    | Kasidar Agent Skills + janareta: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → yana rubutawa zuwa `skills/{id}/SKILL.md`), `openapiParser.ts` (yana ciro REST endpoints daga ƙayyadaddun OpenAPI), `cliRegistryParser.ts` (yana ciro CLI subcommands daga bin/cli-registry), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). REST routes (`/api/agent-skills/*`), MCP tools (`omniroute_agent_skills_*`), da A2A skill `list-capabilities` suna amfani da shi. Duba [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md). |
| `skills/`         | Tsarin skill: `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`, tare da `builtin/browser.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `spend/`          | `batchWriter.ts` (ma'ajiyar rubutu mai jinkirta aiwatarwa)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `sync/`           | `bundle.ts`, `tokens.ts` (Cloud Sync)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `system/`         | Mataimaka na matakin tsarin kwamfuta                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `translator/`     | Manne-mahaɗin mai fassara na babban mataki (yana miƙa aikin zuwa `open-sse/translator/`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `usage/`          | Lissafin amfani: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `versionManager/` | Sabuntawa ta atomatik + kundin sigar                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `ws/`             | Gadar WebSocket                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `zed-oauth/`      | Tsarin OAuth na editan Zed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

Fayilolin babban mataki a cikin `src/lib/`:

- An cire tsohon fayil ɗin tara fitarwa na `localDb.ts` — masu amfani suna shigo da takamaiman kayayyaki daga `src/lib/db/*` kai tsaye.
- `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/`

Rumbun bayanan SQLite guda ɗaya (`getDbInstance()` a cikin `core.ts`, tare da rubutun mujallar WAL).
**Kada a taɓa rubuta ɗanyen SQL a cikin routes ko handlers** — sai an bi ta waɗannan kayayyaki.

![Bayanin tsarin rumbun bayanai (zaɓaɓɓun muhimman teburori)](../diagrams/exported/db-schema-overview.svg)

> Tushe: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd)

Kayayyakin fanni (kowannensu yana kula da tebur ɗaya ko fiye): `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/` yana ɗauke da fayilolin `.sql` guda 168 masu lamba bisa sigar (masu aminci ga maimaitawa, kuma masu gudana cikin transaction), kuma
`migrationRunner.ts` ne ke aiwatar da su lokacin farawa.

Teburorin da aka ƙirƙira a duk migrations ɗin (gaba ɗaya 123):

`a`, `account_key_limits`, `api_keys`, `batches`, `call_logs`,
`combo_adaptation_state`, `combos`, `command_code_auth_sessions`,
`compression_analytics`, `compression_cache_stats`,
`compression_combo_assignments`, `compression_combos`, `context_handoffs`,
`daily_usage_summary`, `db_meta`, `domain_budgets`, `domain_circuit_breakers`,
`domain_cost_history`, `domain_fallback_chains`, `domain_lockout_state`,
`eval_cases`, `eval_runs`, `eval_suites`, `files`, `hourly_usage_summary`,
`key_value`, `mcp_tool_audit`, `memories`, `model_combo_mappings`,
`provider_connections`, `provider_key_limits`, `provider_nodes`,
`proxy_assignments`, `proxy_logs`, `proxy_registry`, `quota_snapshots`,
`reasoning_cache`, `registered_keys`, `request_detail_logs`,
`routing_decisions`, `semantic_cache`, `session_account_affinity`,
`skill_executions`, `skills`, `sync_tokens`, `tier_assignments`,
`tier_config`, `upstream_proxy_config`, `usage_history`, `version_manager`,
`webhooks` (tare da teburorin kama-da-wane na FTS5 don binciken ƙwaƙwalwa).

### 3.3 `src/domain/` — Matakin fanni

Tsantsar dabarun kasuwanci, ba tare da I/O ba. Routes da handlers ne ke shigo da su.

| Fayil                                      | Manufa                                                |
| ------------------------------------------ | ----------------------------------------------------- |
| `policyEngine.ts`                          | Babban mai warware manufofi                           |
| `fallbackPolicy.ts`                        | Bishiyar yanke shawarar komawa madadin                |
| `costRules.ts`                             | Dokokin ƙididdige kuɗi                                |
| `lockoutPolicy.ts`                         | Shawarwarin kulle model                               |
| `tagRouter.ts`                             | Tsara hanyar zirga-zirga bisa tag                     |
| `comboResolver.ts`                         | Warware combo daga request → jerin wuraren nufi       |
| `connectionModelRules.ts`                  | Matatun model na kowane connection                    |
| `modelAvailability.ts`                     | Duba samuwar model                                    |
| `degradation.ts`                           | Sauye-sauyen yanayin raguwar aiki                     |
| `providerExpiration.ts`                    | Gano account/key da wa'adinsu ya ƙare                 |
| `quotaCache.ts`                            | Shawarwarin quota da aka adana a cache                |
| `responses.ts`, `omnirouteResponseMeta.ts` | Mataimakan tsarin response                            |
| `configAudit.ts`                           | Binciken sauye-sauyen config                          |
| `assessment/`                              | Tantance model (bisa RFC, an aiwatar da wani ɓangare) |
| `types.ts`                                 | Nau'ikan fanni da ake rabawa                          |

### 3.4 `src/server/` — Na server kaɗai

Ba za a iya shigo da su daga client components ba.

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Yana rarraba routes zuwa na jama'a ko na gudanarwa
│   ├── assertAuth.ts      Mataimakin tabbatarwa
│   ├── context.ts         Authz context na kowane request
│   ├── headers.ts
│   ├── pipeline.ts        Tsarin matakai na authz
│   ├── policies/          Takamaiman manufofi
│   └── types.ts
└── cors/origins.ts        Jerin CORS origins da aka yarda da su
```

### 3.5 `src/shared/` — Amintacce don rabawa

An raba shi zuwa ƙananan kundin adireshi masu takamaiman ayyuka:

- `constants/` — `providers.ts` (kundin masu samarwa da aka inganta ta Zod), `models.ts`,
  `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`,
  `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`,
  `headers.ts`, `upstreamHeaders.ts` (jerin hanawa), `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` (kimanin tsare-tsaren Zod 80), `compressionConfigSchemas.ts`,
  `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`.
- `contracts/` — yarjejeniyoyin API na jama'a da ake wallafawa zuwa npm.
- `types/` — nau'ikan TS da ake amfani da su tare.
- `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`, tare da hooks/ɓangarorin dashboard da ke ƙarƙashin `services/`, `network/`,
  `middleware/`, `schemas/`, `hooks/`, `components/`.

---

## 4. `open-sse/` — Wurin aikin injin yawo

Wurin aikin npm ne na daban da aka wallafa a matsayin `@omniroute/open-sse`. Yana kula da sarrafa buƙatu,
masu aiwatarwa, masu fassara, ayyuka, mai sauya tsari, da uwar garken MCP.

```
open-sse/
├── index.ts                Fitarwa ga jama'a
├── package.json            Bayanin wurin aiki
├── tsconfig.json
├── types.d.ts
├── config/                 Rajistocin masu samarwa, bayanan martabar kanun bayanai, ainihi, …
├── handlers/               Masu sarrafa buƙatu (taɗi, embeddings, sauti, hoto, …)
├── executors/              Masu aiwatar da HTTP na musamman ga masu samarwa guda 108
├── translator/             Sauya tsari (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Mai sauya Responses API ↔ rafin Chat Completions
├── services/               Modulolin ayyuka sama da 80 (haɗe-haɗe, madadin, ƙa’idojin amfani, ainihi, …)
├── utils/                  Mataimakan yawo, abokin cinikin TLS, AWS SigV4, proxy fetch, …
└── mcp-server/             Uwar garken MCP (hanyoyin sufuri 3, iyakoki 33, kayan aiki 110)
```

### 4.1 `open-sse/handlers/`

| Mai sarrafawa           | Manufa                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `chatCore.ts`           | Babban bututun taɗi (ma’aji, iyakar ƙima, tura haɗe-haɗe, aika zuwa mai aiwatarwa) |
| `responsesHandler.ts`   | Mashigar OpenAI Responses API                                                      |
| `embeddings.ts`         | Embeddings                                                                         |
| `imageGeneration.ts`    | Samar da hoto                                                                      |
| `audioSpeech.ts`        | Rubutu-zuwa-magana                                                                 |
| `audioTranscription.ts` | Magana-zuwa-rubutu                                                                 |
| `videoGeneration.ts`    | Samar da bidiyo                                                                    |
| `musicGeneration.ts`    | Samar da kiɗa                                                                      |
| `rerank.ts`             | Sake jeri                                                                          |
| `moderations.ts`        | Tacewa                                                                             |
| `search.ts`             | Binciken yanar gizo                                                                |
| `sseParser.ts`          | Mai rarraba al’amuran SSE                                                          |
| `usageExtractor.ts`     | Ciro ƙididdigar token daga rafukan sama                                            |
| `responseSanitizer.ts`  | Cire surutun da ya keɓanta ga mai samarwa                                          |
| `responseTranslator.ts` | Mahaɗi tsakanin amsar mai samarwa da matakin mai fassara                           |

### 4.2 `open-sse/executors/`

Masu aiwatarwa na masu samarwa guda 108, kowannensu yana faɗaɗa `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`, tare da `claudeIdentity.ts`
(mataimakin ainihi na gama-gari) da `index.ts` (rajista).

> Lura: masu samarwar da ba a jera a nan ba `default.ts` ne ke yi musu hidima ta amfani da mai aiwatarwa na gama-gari
> mai dacewa da OpenAI. Cikakken kundin masu samarwa (masu samarwa 355) yana cikin
> `src/shared/constants/providers.ts`.

### 4.3 `open-sse/translator/`

Fassarar cibiya-da-rassa (OpenAI ne cibiya).

- **Masu fassara buƙatu guda 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`.
- **Masu fassara amsoshi guda 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`.
- **Mataimaka guda 9** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`, da
  gwaje-gwajen mataimaka.
- **Mataimakan hoto** (`translator/image/sizeMapper.ts`).
- Matakin sama: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

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

- `responsesTransformer.ts` — Mai sauya Responses API ↔ Chat Completions wanda ya dogara da `TransformStream`
  (hanyar kama-duk ta `responses/` ke amfani da shi).

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

Muhimman abubuwa (cikakken jeri yana ƙarƙashin `open-sse/services/`):

| Batun damuwa        | Fayiloli                                                                                                                                                                                                                                                 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Jagorancin Combo    | `combo.ts` (dabaru 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`             |
| Juriya              | `accountFallback.ts` (lokacin jira + kullewa), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                                     |
| Ƙa’idojin amfani    | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| Adana wucin gadi    | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| Basirar jagoranci   | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| Sarrafa samfuri     | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| Matse bayanai       | `compression/` — cikakken haɗin injin matse bayanai                                                                                                                                                                                                      |
| Token + zaman aiki  | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| Mataki / manifest   | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / hanyar sadarwa | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| Rukunai             | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| Amfani              | `usage.ts`                                                                                                                                                                                                                                               |

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

- **Kayan aiki na musamman 110** da aka haɗa a cikin `server.ts` (na asali 45 a cikin `schemas/tools.ts` +
  tsarin ƙwaƙwalwa, ƙwarewa, ƙwarewar GitHub, pool, gamification, plugin, Notion, Obsidian,
  local-corpus da matse bayanai — an ƙirga haɗakar su ta `countUniqueMcpTools`).
- **Hanyoyin jigilar bayanai 3**: stdio, HTTP Streamable, SSE.
- **Scopes 33** da ake tilastawa yayin aiki — jerin tushe yana cikin `src/shared/constants/mcpScopes.ts`, cikakken saitin shi ne haɗakar scopes da kowane tsarin kayan aiki ya ayyana.
- Teburin dubawa: `mcp_tool_audit` (wanda `audit.ts` ke cika).
- Fayiloli: `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`,
  tare da gwaje-gwaje a ƙarƙashin `__tests__/`.
- Duba [MCP-SERVER.md](../frameworks/MCP-SERVER.md) don cikakken kundin kayan aiki.

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

Rajistocin masu samarwa (`providerRegistry.ts`, `providerModels.ts`,
`providerHeaderProfiles.ts`), rajistocin samfura na kowane tsari (`audioRegistry.ts`,
`embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`,
`musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`),
mataimakan shaidar ainihi (`codexIdentity.ts`, `codexInstructions.ts`,
`anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`,
`cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`),
mataimakan bayanan shaidar shiga (`credentialLoader.ts`, `codexClient.ts`), da
adaftocin 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/`

Abubuwan asali na streaming da mataimakan masu samarwa: `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/` — Kundin naɗe na Desktop

```
electron/
├── main.js                  Babban tsarin aikin Electron
├── preload.js               Gadar preload (an kunna contextIsolation)
├── types.d.ts
├── package.json             Saitin electron-builder, siga 3.8.51
├── README.md
├── assets/                  Albarkatun ginawa (gumaka, izini, …)
├── node_modules/            Keɓantaccen node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Sakamakon ginawa (ba a commit ba)
```

Akwai rubutun npm guda biyar a tushen workspace: `electron:dev`, `electron:build`,
`electron:build:{win,mac,linux}`, `electron:smoke:packaged`. Ana yin sabuntawa ta atomatik ta
`electron-updater` wanda yake nuni zuwa tushen sakin GitHub.

---

## 6. `bin/` — CLI

```
bin/
├── omniroute.mjs           Babban mashigin CLI (Node ESM)
├── reset-password.mjs      Sake saita kalmar sirrin gudanarwa daga CLI
├── mcp-server.mjs          Mai ƙaddamar da sabar MCP (stdio)
├── nodeRuntimeSupport.mjs  Mai duba sigar Node
└── cli/
    ├── program.mjs         Mai gina shirin Commander
    ├── runtime.mjs         Mataimakin withRuntime (server-first/db-fallback)
    ├── output.mjs          Masu tsara fitarwa (json/jsonl/table/csv)
    ├── i18n.mjs            Mataimakin t() tare da locales
    ├── api.mjs             Mataimakin API fetch
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Rijistar umarni
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (fayil ɗaya ga kowane umarni/rukuni)
```

Ana bayyanar da binaries guda biyu a cikin `package.json` → `bin`:

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

---

## 7. `tests/`

| Kundin adireshi                                      | Nau'i                                                                                                                          |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `tests/unit/`                                        | Gwaje-gwajen raka'a ta hanyar ginannen mai gudanar da gwajin Node (fayiloli 1821, da ƙananan kundin `api/`, `auth/`, `authz/`) |
| `tests/integration/`                                 | Gwaje-gwajen tsakanin kayayyaki + yanayin DB                                                                                   |
| `tests/e2e/`                                         | Gwaje-gwajen UI na Playwright                                                                                                  |
| `tests/e2e/protocol-clients.test.ts`                 | Gwajin e2e na ƙa'idojin MCP/A2A                                                                                                |
| `tests/translator/`                                  | Gwaje-gwaje na musamman ga mai fassara                                                                                         |
| `tests/security/`                                    | Gwaje-gwajen koma-bayan tsaro                                                                                                  |
| `tests/load/`                                        | Gwaje-gwajen lodi / matsin lamba                                                                                               |
| `tests/golden-set/`                                  | Sakamakon tunani don gwaje-gwajen koma-bayan mai fassara                                                                       |
| `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | Tallafi                                                                                                                        |

Umarni na gama-gari:

| Umarni                                                   | Abin da yake gudanarwa                                                                      |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `npm run test:unit`                                      | Duk `tests/unit/*.test.ts` ta hanyar mai gudanar da gwajin Node (gudanarwar lokaci guda 10) |
| `npm run test:vitest`                                    | Rukunin gwajin Vitest (MCP, autoCombo, cache)                                               |
| `npm run test:e2e`                                       | Rukunin gwajin UI na Playwright                                                             |
| `npm run test:protocols:e2e`                             | Gwajin e2e na ƙa'idojin MCP + A2A                                                           |
| `npm run test:coverage`                                  | Ƙofar ɗaukar gwaji (≥60% na layuka/bayani/ayyuka/rassa)                                     |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | Gudanar da fayil guda ɗaya                                                                  |

---

## 8. `scripts/`

An tsara su cikin ƙananan manyan fayiloli 6 bisa ga manufarsu.

- **`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. Bututun Aiwatar da Buƙata (Taƙaitawa)

![Bututun aiwatar da buƙata (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> Tushe: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
Buƙatar abokin ciniki
  → /v1/chat/completions (route.ts)
     Binciken share fage na CORS
     Tabbatarwar Zod (chatCompletionsSchema a cikin shared/validation/schemas.ts)
     Tantancewa (extractApiKey + isValidApiKey KO requireManagementAuth)
     Injin manufofi (src/server/authz/pipeline.ts)
     Matakan kariya (mai ɓoye PII, shigar da umarnin yaudara, gadar hangen nesa)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Binciken ma’ajiyar wucin gadi (ma’ana + ma’ajiyar karantawa)
     Ƙayyade ƙimar amfani (rateLimitManager, accountSemaphore)
     Rarrabawa ta haɗaka (idan samfurin ya warware zuwa haɗaka)
       comboResolver → maimaitawa ga kowace manufa → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       ɗauko daga uwar-garken sama → sake gwadawa/jinkirin ƙaruwa ta hanyar accountFallback
     translateResponse() (open-sse/translator/response/*)
     Kwararar SSE KO amsar JSON
     Idan Responses API ne: TransformStream ta hanyar open-sse/transformer/responsesTransformer.ts
  → Binciken bin ƙa’ida (src/lib/compliance/)
  → Amsa ga abokin ciniki
```

### Halin lokacin gudanarwa na juriya (hanyoyi uku)

| Hanya                         | Iyaka                        | Wuri                                                                                                                   |
| ----------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Mai katse da’irar mai samarwa | Dukan mai samarwa            | `src/shared/utils/circuitBreaker.ts`, an adana shi a cikin `domain_circuit_breakers`                                   |
| Lokacin hucewar haɗi          | Asusun/maɓalli guda ɗaya     | `markAccountUnavailable()` a cikin `src/sse/services/auth.ts`; `accountFallback.checkFallbackError()` ke amfani da shi |
| Hana amfani da samfuri        | Mai samarwa + haɗi + samfuri | `open-sse/services/accountFallback.ts`, an adana shi a cikin `domain_lockout_state`                                    |

Duba [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) da kuma sashen da aka keɓe a cikin
[CLAUDE.md](../../CLAUDE.md).

---

## 10. Yadda Ake Ba da Gudummawa

### Ƙara sabon provider

1. Yi rajista a `src/shared/constants/providers.ts` (ana tabbatar da shi da Zod lokacin lodawa).
2. Ƙara executor a `open-sse/executors/` idan ana buƙatar dabaru na musamman
   (a faɗaɗa `BaseExecutor`).
3. Ƙara translator a `open-sse/translator/` idan ba ya amfani da tsarin OpenAI.
4. Idan yana amfani da OAuth, ƙara config a ƙarƙashin `src/lib/oauth/providers/` da
   `src/lib/oauth/services/`.
5. Yi rajistar models a `open-sse/config/providerRegistry.ts` (ko registry na takamaiman
   tsari a ƙarƙashin `open-sse/config/`).
6. Rubuta gwaje-gwaje a ƙarƙashin `tests/unit/`.

### Ƙara sabuwar hanyar API

1. Ƙirƙiri `src/app/api/your-route/route.ts`.
2. Bi tsarin: CORS → tabbatar da body ta Zod → auth → miƙa aiki ga handler.
3. Idan tsarin request sabo ne: ƙara Zod schema a `src/shared/validation/schemas.ts`.
4. Idan na gudanarwa kawai ne: ƙara path ɗin zuwa `src/shared/constants/publicApiRoutes.ts`
   (denylist na ɓangaren API na jama'a).
5. Ƙara gwaje-gwaje a ƙarƙashin `tests/unit/`.
6. Sabunta `docs/reference/API_REFERENCE.md` da `docs/openapi.yaml`.

### Ƙara sabon module na DB

1. Ƙirƙiri `src/lib/db/yourModule.ts` sannan ka shigo da `getDbInstance()` daga `./core.ts`.
2. Fitar da ayyukan CRUD na domain ɗinka.
3. Idan akwai sababbin tables: ƙara migration a ƙarƙashin `src/lib/db/migrations/`, mai lamba
   a jere, idempotent, kuma transactional.
4. Masu shigo da abubuwa su yi amfani da direct imports daga `@/lib/db/yourModule` (babu barrel — an cire tsohon re-export layer na `localDb.ts`).
5. Ƙara gwaje-gwaje a ƙarƙashin `tests/unit/`.

### Ƙara sabon kayan aikin MCP

1. Ƙara ma'anar kayan aikin a ƙarƙashin `open-sse/mcp-server/tools/` (ko a faɗaɗa
   `open-sse/mcp-server/schemas/tools.ts`).
2. Sanya scope(s) da suka dace a `src/shared/constants/mcpScopes.ts`.
3. Yi rajistar kayan aikin a `open-sse/mcp-server/server.ts`.
4. Ƙara gwaje-gwaje a ƙarƙashin `open-sse/mcp-server/__tests__/`.
5. Sabunta [MCP-SERVER.md](../frameworks/MCP-SERVER.md).

### Ƙara sabuwar ƙwarewar A2A

Duba [A2A-SERVER.md § Ƙara Sabuwar Ƙwarewa](../frameworks/A2A-SERVER.md). Ƙwarewa suna cikin
`src/lib/a2a/skills/` kuma ana yi musu rajista ta hanyar mai sarrafa ayyukan A2A.

---

## 11. Ka'idoji

- **Salon code**: indent na spaces 2, double quotes, faɗin characters 100, semicolons,
  trailing commas na `es5` — Prettier yana tilasta su ta hanyar `lint-staged`.
- **Imports**: na waje → na ciki (`@/`, `@omniroute/open-sse`) → na dangi.
- **Sanya suna**: files su kasance `camelCase` ko `kebab-case`, components su kasance `PascalCase`,
  constants su kasance `UPPER_SNAKE`.
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = `error` a ko'ina;
  `no-explicit-any` = `warn` a `open-sse/` da `tests/`, error a sauran wurare.
- **TypeScript**: `strict: false` (tsarin legacy). Fi son bayyanannun types maimakon
  inference a iyakokin tsakanin modules.
- **Database**: kada a taɓa rubuta raw SQL a routes ko handlers — koyaushe a bi ta
  modules na `src/lib/db/`. Kada a taɓa yin barrel-import — a yi amfani da takamaiman modules na `src/lib/db/*` kai tsaye.
- **Typing na DB-entity (#3512)**: function da ke rubutawa ko karanta tsarin row na
  wani DB table ya kamata ya karɓa/maido da TS interface mai suna wanda ya yi daidai da
  columns na table ɗin 1:1, ba `any` ko inline anonymous type a wurin kira ba. Sanya
  interface ɗin kusa da function ɗin (misali `export interface UsageEntry` a
  `src/lib/usage/usageHistory.ts` sama da `saveRequestUsage`), bar kowane
  field a matsayin optional/nullable lokacin da writers daban-daban ke cika row ɗin
  a hankali, kuma a fi son `unknown` maimakon `any` ga field da tsarinsa
  ke bambanta tsakanin callers (a bayyana shi a field ɗin, misali `UsageEntry.tokens`
  yana karɓar duka raw usage mai tsarin provider da kuma normalized shape). Da zarar
  adadin `any` na file ya kai sifili ta wannan hanyar, ƙara shi zuwa allowlist na
  `check:any-budget:t11` (`scripts/check/check-t11-any-budget.mjs`,
  `maxAny: 0`) don kada ya koma baya. Wannan ƙa'ida ce ta matakin farko — aikin
  tsaftace "babu anonymous `any`" gaba ɗaya yana gudana ne a hankali a sauran
  codebase ɗin.
- **Errors**: yi amfani da try/catch tare da takamaiman error types, sannan a yi log da pino context. Kada a taɓa
  ɓoye errors a cikin SSE streams ba tare da sanarwa ba; yi amfani da abort signals don cleanup.
- **Tsaro**: kada a taɓa amfani da `eval()` / `new Function()` / implied eval. Tabbatar da
  duk inputs da Zod. Encrypt credentials yayin da suke ajiye (AES-256-GCM). Tabbatar
  denylist na `src/shared/constants/upstreamHeaders.ts` ya yi daidai da
  layer na sanitize/validation.
- **Commits**: Conventional Commits — `feat(scope): subject`. Scopes da aka yarda:
  `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
  `a2a`, `memory`, `skills`.
- **Branches**: prefixes `feat/`, `fix/`, `refactor/`, `docs/`, `test/`,
  `chore/`. Kada a taɓa yin commit kai tsaye zuwa `main`.
- **Husky**: pre-commit yana gudanar da `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11`; pre-push yana gudanar da `check:any-budget:t11` + `check:tracked-artifacts` (fast gates; baya haɗa `test:unit`).

---

## 12. Tsauraran Dokoki (daga CLAUDE.md)

1. Kada a taɓa commit na sirrika ko bayanan shiga.
2. Kada a taɓa yin barrel-import — yi amfani da takamaiman modules na `src/lib/db/*` kai tsaye.
3. Kada a taɓa amfani da `eval()` / `new Function()` / eval na ɓoye.
4. Kada a taɓa yin commit kai tsaye zuwa `main`.
5. Kada a taɓa rubuta raw SQL a cikin routes — koyaushe a bi ta modules na `src/lib/db/`.
6. Kada a taɓa haɗiye kurakurai ba tare da sanarwa ba a cikin SSE streams.
7. Koyaushe a tantance inputs da Zod schemas.
8. Koyaushe a haɗa tests yayin sauya production code.
9. Dole coverage ya kasance ≥ 60% (statements, lines, functions, branches).

---

## 13. Duba Kuma

- [ARCHITECTURE.md](./ARCHITECTURE.md) — babban tsarin architecture da nauyin da ke kan kowane module.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — bayanin public + management API.
- [FEATURES.md](../guides/FEATURES.md) — jadawalin features da muhimman abubuwan versions.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — cikakken bayani kan circuit breaker, cooldown,
  da lockout.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — tsarin scoring da dabarun Auto Combo.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — cikakken kundin MCP tools + transports.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — ƙwarewar A2A protocol da discovery.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK + Caveman compression.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — haɗaɗɗun CLI.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (idan yana nan), [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) — wuraren deployment.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — matsalolin aiki da aka saba fuskanta.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — tsarin aikin masu ba da gudummawa.
- [CLAUDE.md](../../CLAUDE.md) — dokokin repo na Claude Code (asalin ingantaccen bayani
  ga yawancin ƙa’idojin da ke sama).
- [AGENTS.md](../../AGENTS.md) — bayanin architecture mai zurfi da agents ke amfani da shi.