# OmniRoute Codebase Documentation (తెలుగు)

🌐 **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) · 🇳🇬 [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) · 🇹🇭 [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)

---

> **వెర్షన్:** v3.8.51
> **చివరిగా నవీకరించబడింది:** 2026-06-28
> **లక్ష్య పాఠకులు:** OmniRouteకు సహకరిస్తున్న లేదా దాని పైన ఇంటిగ్రేషన్లను నిర్మిస్తున్న ఇంజినీర్లు.
>
> ఉన్నత-స్థాయి ఆర్కిటెక్చర్ రేఖాచిత్రాలు మరియు ప్రతి ఉపవ్యవస్థ వెనుక ఉన్న తార్కికత కోసం,
> [ARCHITECTURE.md](./ARCHITECTURE.md) చదవండి. వ్యక్తిగత ఉపవ్యవస్థలపై లోతైన సమాచారం కోసం
> (Auto Combo, MCP సర్వర్, A2A సర్వర్, Skills, Memory, Cloud Agents, Resilience,
> Compression మొదలైనవి) ఈ `docs/` డైరెక్టరీలో వాటికి కేటాయించిన ఫైళ్లను చూడండి.

ఈ ఫైల్ **ప్రస్తుతం రిపోజిటరీలో ఏముందో** వివరిస్తుంది, తద్వారా కొత్త ఇంజినీర్
ట్రీలో నావిగేట్ చేయగలరు, రన్టైమ్ లేయరింగ్ను అర్థం చేసుకోగలరు మరియు కొత్త మాడ్యూల్లను
సృష్టించకుండానే కోడ్ను ఎక్కడ జోడించాలో తెలుసుకోగలరు.

---

## 1. సాంకేతిక స్టాక్

| అంశం             | ఎంపిక                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| వెబ్ ఫ్రేమ్వర్క్ | **Next.js 16** (App Router, స్వతంత్ర అవుట్పుట్, గ్లోబల్ మిడిల్వేర్ లేదు)                                                      |
| భాష              | **TypeScript 6.0+** — లక్ష్యం `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`                        |
| రన్టైమ్          | **Node.js** `>=22.22.2 <23` లేదా `>=24.0.0 <27` (`engines` + `SUPPORTED_NODE_RANGE` ద్వారా అమలు చేయబడుతుంది)                  |
| డేటాబేస్         | `better-sqlite3` ద్వారా **SQLite** (సింగిల్టన్, WAL జర్నలింగ్)                                                                |
| డెస్క్టాప్       | **Electron 41** + `electron-builder` 26.10 (`electron/` వద్ద ప్రత్యేక వర్క్స్పేస్)                                            |
| పరీక్షలు         | **Node స్థానిక టెస్ట్ రన్నర్** (యూనిట్/ఇంటిగ్రేషన్), **Vitest** (MCP, autoCombo, cache), **Playwright** (e2e + protocols-e2e) |
| బిల్డ్           | `scripts/build/build-next-isolated.mjs` ద్వారా Next.js స్వతంత్ర బిల్డ్                                                        |
| లింట్/ఫార్మాట్   | ESLint ఫ్లాట్ కాన్ఫిగ్ + Prettier (Husky ప్రీ-కమిట్ ద్వారా `lint-staged`)                                                     |
| మాడ్యూల్ వ్యవస్థ | ప్రతిచోటా ESM (`"type": "module"`)                                                                                            |
| వర్క్స్పేస్లు    | npm వర్క్స్పేస్ — `open-sse` మాత్రమే ఉప-వర్క్స్పేస్                                                                           |

పాత్ అలియాస్లు (`tsconfig.json`):

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

డిఫాల్ట్ HTTP పోర్ట్: **`20128`** (API మరియు డ్యాష్బోర్డ్ ఒకే ప్రాసెస్ను పంచుకుంటాయి). డేటా
డైరెక్టరీ `DATA_DIR` పర్యావరణ వేరియబుల్ ద్వారా నిర్ణయించబడుతుంది; దాని డిఫాల్ట్ విలువ `~/.omniroute/`.

---

## 2. రిపోజిటరీ నిర్మాణం

```
OmniRoute/
├── src/                  Next.js అప్లికేషన్ (App Router, లైబ్రరీలు, డొమైన్, సర్వర్, భాగస్వామ్య అంశాలు)
├── open-sse/             స్ట్రీమింగ్ ఇంజిన్ వర్క్స్పేస్ (@omniroute/open-sse)
├── electron/             డెస్క్టాప్ ర్యాపర్ (Electron 41 మెయిన్ + ప్రీలోడ్)
├── bin/                  CLI ఎంట్రీ పాయింట్లు (omniroute, reset-password)
├── tests/                యూనిట్, ఇంటిగ్రేషన్, e2e, protocols-e2e, ట్రాన్స్లేటర్, సెక్యూరిటీ, ఫిక్చర్లు
├── scripts/              బిల్డ్, సింక్, తనిఖీ, మైగ్రేషన్ మరియు రన్టైమ్ సహాయక స్క్రిప్ట్లు
├── docs/                 పబ్లిక్ డాక్యుమెంటేషన్ (ఈ డైరెక్టరీ)
├── public/               స్టాటిక్ అసెట్లు, PWA మానిఫెస్ట్, సర్వీస్ వర్కర్
├── config/               రన్టైమ్ కాన్ఫిగ్ నమూనాలు
├── images/               మార్కెటింగ్/స్క్రీన్షాట్ అసెట్లు
├── _ideia/, _references/, _mono_repo/, _tasks/   అంతర్గత తాత్కాలిక / ప్రణాళిక అంశాలు (షిప్ చేయబడవు)
├── CLAUDE.md             Claude Code కోసం రిపో నియమాలు
├── AGENTS.md             ఏజెంట్ల కోసం మరింత లోతైన ఆర్కిటెక్చర్ సూచన
├── package.json          v3.8.51, వర్క్స్పేస్ రూట్
└── tsconfig.json         పాత్ అలియాస్లు + ప్రధాన కంపైలర్ ఎంపికలు
```

---

## 3. `src/` — Next.js అప్లికేషన్

```
src/
├── app/                  App Router పేజీలు + API రూట్లు
├── lib/                  ప్రధాన లైబ్రరీలు (DB, auth, OAuth, skills, memory, …)
├── domain/               స్వచ్ఛమైన డొమైన్ లేయర్ (policy, fallback, cost, lockout, …)
├── server/               సర్వర్కు మాత్రమే పరిమితమైన మాడ్యూల్లు (authz, cors, auth)
├── shared/               రకాలు, స్థిరాంకాలు, ధ్రువీకరణ, కాంట్రాక్ట్లు, యుటిలిటీలు (సరిహద్దుల మధ్య సురక్షితం)
├── mitm/                 CLI సమీకరణ కోసం మాన్-ఇన్-ది-మిడిల్ ప్రాక్సీ సహాయకాలు
├── models/               స్థానిక మోడల్ మెటాడేటా / అలియాసింగ్
├── sse/                  ఇప్పటికీ src/ కింద ఉన్న లెగసీ SSE హ్యాండ్లర్లు (open-sse/ కాదు)
├── store/                క్లయింట్-సైడ్ స్థితి స్టోర్లు
├── middleware/           రూట్-స్థాయి మిడిల్వేర్ యుటిలిటీలు (Next.js గ్లోబల్ మిడిల్వేర్ కాదు)
├── scripts/              యాప్ కోడ్ ద్వారా ఇంపోర్ట్ చేయగల ఇన్-ట్రీ స్క్రిప్ట్లు
├── types/                ఆంబియంట్ మరియు షేర్డ్ TS రకాలు
├── i18n/                 లొకేల్ బండిల్లు
├── instrumentation.ts    Next.js ఇన్స్ట్రుమెంటేషన్ హుక్
├── instrumentation-node.ts
└── proxy.ts              అగ్ర-స్థాయి ప్రాక్సీ బూట్స్ట్రాప్ సహాయకం
```

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

App Router డ్యాష్బోర్డ్ UI మరియు పబ్లిక్/మేనేజ్మెంట్ HTTP API రెండింటినీ అందుబాటులో ఉంచుతుంది.
ఇక్కడ **గ్లోబల్ మిడిల్వేర్ లేదు** — ప్రతి రూట్ స్థాయిలో ఇంటర్సెప్షన్ జరుగుతుంది.

`src/app/` కింద ఉన్న అగ్ర-స్థాయి సెగ్మెంట్లు:

| పాత్                                                                          | ఉద్దేశ్యం                                          |
| ----------------------------------------------------------------------------- | -------------------------------------------------- |
| `api/`                                                                        | అన్ని HTTP API రూట్లు (దిగువ విభజనను చూడండి)       |
| `a2a/`                                                                        | A2A JSON-RPC 2.0 ఎండ్పాయింట్ (`POST /a2a`)         |
| `.well-known/agent.json/`                                                     | A2A Agent Card డిస్కవరీ డాక్యుమెంట్                |
| `(dashboard)/`                                                                | డ్యాష్బోర్డ్ UI (రూట్ గ్రూప్, URL ప్రిఫిక్స్ లేదు) |
| `auth/`, `login/`, `forgot-password/`, `callback/`                            | ప్రామాణీకరణ ప్రవాహాలు                              |
| `landing/`                                                                    | మార్కెటింగ్/ల్యాండింగ్ పేజీ                        |
| `docs/`                                                                       | ఎంబెడెడ్ API డాక్యుమెంటేషన్ వ్యూయర్                |
| `status/`, `maintenance/`, `offline/`                                         | కార్యాచరణ పేజీలు                                   |
| `privacy/`, `terms/`                                                          | చట్టపరమైన పేజీలు                                   |
| `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`                | స్టాటిక్ ఎర్రర్ పేజీలు                             |
| `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | ఫ్రేమ్వర్క్ ఎర్రర్/లోడింగ్ బౌండరీలు                |
| `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`                        | రూట్ షెల్                                          |

#### 3.1.1 `src/app/(dashboard)/dashboard/` — UI పేజీలు

`agents`, `analytics`, `api-manager`, `audit`, `auto-combo`, `batch`, `cache`,
`changelog`, `cli-tools`, `cloud-agents`, `combos`, `compression`, `context`,
`costs`, `endpoint`, `health`, `limits`, `logs`, `memory`, `onboarding`,
`playground`, `providers`, `search-tools`, `settings`, `skills`, `system`,
`translator`, `usage`, `webhooks`, అదనంగా రూట్ `page.tsx`, `HomePageClient.tsx`,
`BootstrapBanner.tsx`.

#### 3.1.2 `src/app/api/` — అగ్ర-స్థాయి API గ్రూప్లు

```
src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   ఎంబెడెడ్ సర్వీస్ నిర్వహణ (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI-అనుకూల పబ్లిక్ API
├── v1beta/     Gemini-శైలి అనుకూలత
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — ఎంబెడెడ్ సర్వీస్ల నిర్వహణ

9Router మరియు CLIProxyAPIని ఇన్స్టాల్ చేయడం, ప్రారంభించడం, ఆపడం, పర్యవేక్షించడం కోసం రూట్లు.
అవి `npm install`ని అమలు చేయగలవు మరియు చైల్డ్ ప్రాసెస్లను సృష్టించగలవు కాబట్టి, అన్ని పాత్లు
**LOCAL_ONLY**గా వర్గీకరించబడ్డాయి (లూప్బ్యాక్ మాత్రమే, కఠిన నియమం #17).

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() సహాయకం
│   ├── install/route.ts    POST — execFile ద్వారా npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — కొత్త వెర్షన్ను npm install చేయడం
│   ├── rotate-key/route.ts POST — కొత్త API కీని రూపొందించడం + పునఃప్రారంభించడం
│   ├── status/route.ts     GET  — లైవ్ + DB స్థితి + వెర్షన్ మెటాడేటా
│   └── auto-start/route.ts POST — auto_start ఫ్లాగ్ను మార్చడం
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor() సహాయకం
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — కొత్త వెర్షన్ను npm install చేయడం
│   ├── status/route.ts     GET  — లైవ్ + DB స్థితి + వెర్షన్ మెటాడేటా
│   └── auto-start/route.ts POST — auto_start ఫ్లాగ్ను మార్చడం
└── [name]/
    └── logs/route.ts       GET  — SSE లాగ్ టెయిల్ (అన్ని సర్వీస్లు పంచుకుంటాయి)
```

సంబంధిత డ్యాష్బోర్డ్ UI:
`src/app/(dashboard)/dashboard/providers/services/` — రెండు-ట్యాబ్ల పేజీ (CLIProxyAPI + 9Router).
9Router ఎంబెడెడ్ UI కోసం రివర్స్ ప్రాక్సీ:
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

లోతైన వివరణ: `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — OpenAI-అనుకూల పబ్లిక్ API

```
v1/
├── accounts/[id]/                       ఖాతా శోధన
├── agents/tasks/[id]/, agents/tasks/    A2A-శైలి టాస్క్ ఎండ్పాయింట్లు
├── api/                                 v1/api కింద అందుబాటులో ఉంచిన అంతర్గత API సహాయకాలు
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    చాట్ కంప్లీషన్లు (ప్రధాన ఎండ్పాయింట్)
├── completions/                         పాత టెక్స్ట్ కంప్లీషన్లు
├── embeddings/                          ఎంబెడ్డింగ్లు
├── files/[id]/, files/                  Files API
├── _helpers/                            భాగస్వామ్య రూట్ సహాయకాలు (పబ్లిక్ URL లేదు)
├── images/{edits, generations}/         చిత్రం ఉత్పత్తి + సవరణ
├── issues/                              ట్రయాజ్ సహాయక ఎండ్పాయింట్లు
├── management/{proxies}/                v1 లోపల మేనేజ్మెంట్-స్కోప్డ్ రూట్లు
├── messages/{count_tokens}/             Anthropic-శైలి సందేశాల అనుకూలత
├── models/                              మోడల్ జాబితా (`route.ts`, `catalog.ts`)
├── moderations/                         మోడరేషన్
├── music/                               సంగీత ఉత్పత్తి
├── providers/[provider]/                ప్రతి ప్రొవైడర్కు సంబంధించిన ఆపరేషన్లు
├── quotas/{check}                       కోటా తనిఖీలు
├── registered-keys/                     నమోదైన కీ అడ్మిన్
├── rerank/                              పునఃర్యాంకింగ్
├── responses/[...path]/                 OpenAI Responses API (క్యాచ్-ఆల్)
├── search/                              వెబ్ శోధన
├── videos/                              వీడియో ఉత్పత్తి
├── ws/                                  WebSocket బ్రిడ్జ్
└── route.ts                             ఇండెక్స్ హ్యాండ్లర్
```

ప్రతి రూట్ ఫైల్ ఇదే నమూనాను అనుసరిస్తుంది:

```
రూట్ → CORS ప్రీఫ్లైట్ → Zod బాడీ ధ్రువీకరణ → ఐచ్ఛిక ప్రామాణీకరణ
      → API కీ విధాన అమలు → హ్యాండ్లర్ డెలిగేషన్ (open-sse)
```

`v1beta/` అనేది Gemini-శైలి అనుకూలత ఉపరితలం (అదే `open-sse/handlers/`
పైప్లైన్లోకి అనువదించే పలుచని ర్యాపర్).

### 3.2 `src/lib/` — ప్రధాన లైబ్రరీలు

డేటా, సింక్, OAuth, స్కిల్, మెమరీ మొదలైనవాటిని ఎల్లప్పుడూ ఈ మాడ్యూళ్ల ద్వారా ఇంపోర్ట్ చేయండి. ఈ
పట్టిక వాస్తవ డైరెక్టరీలను మరియు ముఖ్యమైన టాప్-లెవల్ ఫైల్లను సమూహపరుస్తుంది.

| మాడ్యూల్          | ఉద్దేశ్యం                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/`            | A2A ప్రోటోకాల్ సర్వర్: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (6 నైపుణ్యాలు: ఖర్చు విశ్లేషణ, స్థితి నివేదిక, ప్రొవైడర్ అన్వేషణ, కోటా నిర్వహణ, స్మార్ట్ రూటింగ్, సామర్థ్యాల జాబితా)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `acp/`            | ఏజెంట్-కంట్రోల్-ప్రోటోకాల్: `index.ts`, `manager.ts`, `registry.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `api/`            | అంతర్గత API సహాయకాలు: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `auth/`           | `managementPassword.ts` (పాస్వర్డ్ రీసెట్ / హ్యాషింగ్)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `batches/`        | OpenAI Batches API సేవ (`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `catalog/`        | OpenRouter కేటలాగ్ సమకాలీకరణ (`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `cloudAgent/`     | క్లౌడ్ ఏజెంట్ రిజిస్ట్రీ: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `combos/`         | కాంబో పరిష్కార సహాయకాలు                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `compliance/`     | ఆడిట్ + ప్రొవైడర్ ఆడిట్: `index.ts`, `providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `config/`         | రన్టైమ్ కాన్ఫిగరేషన్ అనుసంధానం                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `db/`             | SQLite డొమైన్ మాడ్యూల్స్ (§3.2.1 చూడండి)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `display/`        | API ప్రతిస్పందనలలో ఉపయోగించే UI/ప్రదర్శన సహాయకాలు                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `embeddings/`     | ఎంబెడింగ్ సేవా రిజిస్ట్రీ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `env/`            | ఎన్విరాన్మెంట్ లోడింగ్ + అంతర్దృష్టి                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `evals/`          | మూల్యాంకన రన్టైమ్                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `guardrails/`     | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `jobs/`           | నేపథ్య జాబ్లు (`autoUpdate.ts`, …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `memory/`         | నిరంతర మెమరీ: `store.ts`, `cache.ts`, `retrieval.ts`, `summarization.ts`, `extraction.ts`, `injection.ts`, `qdrant.ts`, `settings.ts`, `verify.ts`, `schemas.ts`, `types.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `monitoring/`     | `observability.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `oauth/`          | OAuth/దిగుమతి ప్రొవైడర్ మాడ్యూల్స్ (22): `agy`, `antigravity`, `claude`, `cline`, `codebuddy-cn`, `codex`, `cursor`, `devin-desktop`, `ghe-copilot`, `github`, `gitlab-duo`, `grok-cli-oauth`, `grok-cli`, `kilocode`, `kimi-coding`, `kiro`, `openference`, `qoder`, `trae`, `xai-oauth`, `zed-hosted`, `zed`, అదనంగా `services/`, `utils/`, మరియు `constants/oauth.ts`                                                                                                                                                                                                                                                                                                                                                                       |
| `plugins/`        | ప్లగిన్ లోడర్ (`index.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `promptCache/`    | `prefixAnalyzer.ts`, `index.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `providerModels/` | నిర్వహిత మోడల్ జీవితచక్రం: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `providers/`      | ప్రొవైడర్ సహాయకాలు: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `resilience/`     | `settings.ts` — సర్క్యూట్ బ్రేకర్, కూల్డౌన్, లాకౌట్ కోసం సెట్టింగ్లు                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `runtime/`        | రన్టైమ్ ఫీచర్ గుర్తింపు                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `services/`       | అంతర్నిర్మిత సేవల ఫ్రేమ్వర్క్: `ServiceSupervisor.ts` (ఆపరేషన్ లాక్, రింగ్ బఫర్, హెల్త్ చెకర్తో కూడిన సాధారణ చైల్డ్-ప్రాసెస్ సూపర్వైజర్), `bootstrap.ts` (ప్రాసెస్-స్థాయి నమోదు మరియు స్వయంచాలక ప్రారంభం), `registry.ts` (టూల్ → సూపర్వైజర్ మ్యాప్), `apiKey.ts` (AES-256-GCM కీ స్టోర్), `modelSync.ts` (ఆవర్తన మోడల్ సమకాలీకరణ), `ringBuffer.ts` (5 MB వృత్తాకార లాగ్ బఫర్), `healthCheck.ts` (HTTP స్థితి ప్రోబ్), `types.ts`, `embedWsProxy.ts` (WebSocket ప్రాక్సీ), `installers/{ninerouter,cliproxy}.ts`. `docs/frameworks/EMBEDDED-SERVICES.md` చూడండి                                                                                                                                                                                 |
| `agentSkills/`    | ఏజెంట్ నైపుణ్యాల కేటలాగ్ + జనరేటర్: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → `skills/{id}/SKILL.md`ను వ్రాస్తుంది), `openapiParser.ts` (OpenAPI స్పెసిఫికేషన్ నుండి REST ఎండ్పాయింట్లను వెలికితీస్తుంది), `cliRegistryParser.ts` (bin/cli-registry నుండి CLI ఉపకమాండ్లను వెలికితీస్తుంది), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). REST రూట్లు (`/api/agent-skills/*`), MCP టూల్స్ (`omniroute_agent_skills_*`), మరియు A2A నైపుణ్యం `list-capabilities` ద్వారా వినియోగించబడుతుంది. [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md) చూడండి. |
| `skills/`         | నైపుణ్య ఫ్రేమ్వర్క్: `registry.ts`, `executor.ts`, `interception.ts`, `injection.ts`, `sandbox.ts`, `custom.ts`, `hybrid.ts`, `builtins.ts`, `a2a.ts`, `providerSettings.ts`, `schemas.ts`, `skillssh.ts`, `types.ts`, అదనంగా `builtin/browser.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `spend/`          | `batchWriter.ts` (వెనుకబడిన వ్రాత బఫర్)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `sync/`           | `bundle.ts`, `tokens.ts` (క్లౌడ్ సమకాలీకరణ)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `system/`         | సిస్టమ్-స్థాయి సహాయకాలు                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `translator/`     | అగ్ర-స్థాయి అనువాదక అనుసంధానం (`open-sse/translator/`లోకి అప్పగిస్తుంది)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `usage/`          | వినియోగ లెక్కింపు: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `versionManager/` | స్వయంచాలక నవీకరణ + వెర్షన్ మానిఫెస్ట్                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `ws/`             | WebSocket బ్రిడ్జ్                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `zed-oauth/`      | Zed ఎడిటర్ OAuth ప్రక్రియ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

`src/lib/`లోని అగ్ర-స్థాయి ఫైళ్లు:

- పాత `localDb.ts` barrel తొలగించబడింది — వినియోగదారులు నిర్దిష్ట `src/lib/db/*` మాడ్యూళ్లను నేరుగా import చేస్తారు.
- `proxyHealth.ts`, `proxyLogger.ts`, `tokenHealthCheck.ts`, `localHealthCheck.ts`
- `apiBridgeServer.ts`, `cacheLayer.ts`, `semanticCache.ts`, `settingsCache.ts`
- `cloudSync.ts`, `initCloudSync.ts`
- `cloudflaredTunnel.ts`, `ngrokTunnel.ts`, `tailscaleTunnel.ts`
- `consoleInterceptor.ts`, `container.ts`, `gracefulShutdown.ts`, `idempotencyLayer.ts`
- `ipUtils.ts`, `logEnv.ts`, `logPayloads.ts`, `logRotation.ts`
- `modelAliasSeed.ts`, `modelCapabilities.ts`, `modelMetadataRegistry.ts`, `modelsDevSync.ts`
- `piiSanitizer.ts`, `pricingSync.ts`
- `apiKeyExposure.ts`, `cacheControlSettings.ts`, `dataPaths.ts`, `toolPolicy.ts`
- `translatorEvents.ts`, `usageDb.ts`, `usageAnalytics.ts`, `webhookDispatcher.ts`

#### 3.2.1 `src/lib/db/`

Singleton SQLite డేటాబేస్ (`core.ts`లో `getDbInstance()`, WAL journaling).
**routes లేదా handlersలో ముడి SQLను ఎప్పుడూ వ్రాయవద్దు** — ఈ మాడ్యూళ్ల ద్వారానే నిర్వహించండి.

![డేటాబేస్ స్కీమా అవలోకనం (ఎంచుకున్న ప్రధాన పట్టికలు)](../diagrams/exported/db-schema-overview.svg)

> మూలం: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd)

డొమైన్ మాడ్యూళ్లు (ప్రతి ఒక్కటి ఒకటి లేదా అంతకంటే ఎక్కువ పట్టికలను నిర్వహిస్తుంది): `apiKeys.ts`, `backup.ts`,
`batches.ts`, `cleanup.ts`, `cliToolState.ts`, `combos.ts`,
`commandCodeAuth.ts`, `compression.ts`, `compressionAnalytics.ts`,
`compressionCacheStats.ts`, `compressionCombos.ts`, `compressionScheduler.ts`,
`contextHandoffs.ts`, `core.ts`, `creditBalance.ts`, `databaseSettings.ts`,
`detailedLogs.ts`, `domainState.ts`, `encryption.ts`, `evals.ts`, `files.ts`,
`healthCheck.ts`, `jsonMigration.ts`, `migrationRunner.ts`,
`modelComboMappings.ts`, `models.ts`, `oneproxy.ts`, `prompts.ts`,
`providers.ts`, `providerLimits.ts`, `proxies.ts`, `quotaSnapshots.ts`,
`readCache.ts`, `reasoningCache.ts`, `registeredKeys.ts`, `secrets.ts`,
`sessionAccountAffinity.ts`, `settings.ts`, `stateReset.ts`, `stats.ts`,
`syncTokens.ts`, `tierConfig.ts`, `upstreamProxy.ts`, `versionManager.ts`,
`webhooks.ts`.

`migrations/`లో 168 సంస్కరణల వారీ `.sql` ఫైళ్లు (idempotent, transactional) ఉంటాయి, ఇవి boot సమయంలో `migrationRunner.ts` ద్వారా అమలు చేయబడతాయి.

migrations అంతటా సృష్టించబడిన పట్టికలు (మొత్తం 123):

`a`, `account_key_limits`, `api_keys`, `batches`, `call_logs`,
`combo_adaptation_state`, `combos`, `command_code_auth_sessions`,
`compression_analytics`, `compression_cache_stats`,
`compression_combo_assignments`, `compression_combos`, `context_handoffs`,
`daily_usage_summary`, `db_meta`, `domain_budgets`, `domain_circuit_breakers`,
`domain_cost_history`, `domain_fallback_chains`, `domain_lockout_state`,
`eval_cases`, `eval_runs`, `eval_suites`, `files`, `hourly_usage_summary`,
`key_value`, `mcp_tool_audit`, `memories`, `model_combo_mappings`,
`provider_connections`, `provider_key_limits`, `provider_nodes`,
`proxy_assignments`, `proxy_logs`, `proxy_registry`, `quota_snapshots`,
`reasoning_cache`, `registered_keys`, `request_detail_logs`,
`routing_decisions`, `semantic_cache`, `session_account_affinity`,
`skill_executions`, `skills`, `sync_tokens`, `tier_assignments`,
`tier_config`, `upstream_proxy_config`, `usage_history`, `version_manager`,
`webhooks` (అదనంగా memory శోధన కోసం FTS5 virtual tables).

### 3.3 `src/domain/` — డొమైన్ లేయర్

I/O లేని స్వచ్ఛమైన వ్యాపార తర్కం. routes మరియు handlers ద్వారా import చేయబడుతుంది.

| ఫైల్                                       | ఉద్దేశ్యం                                                       |
| ------------------------------------------ | --------------------------------------------------------------- |
| `policyEngine.ts`                          | అగ్ర-స్థాయి policy resolver                                     |
| `fallbackPolicy.ts`                        | Fallback నిర్ణయ వృక్షం                                          |
| `costRules.ts`                             | ఖర్చు గణన నియమాలు                                               |
| `lockoutPolicy.ts`                         | Model lockout నిర్ణయాలు                                         |
| `tagRouter.ts`                             | Tag-ఆధారిత routing                                              |
| `comboResolver.ts`                         | request → target జాబితా నుండి combo resolution                  |
| `connectionModelRules.ts`                  | ప్రతి-connection model filters                                  |
| `modelAvailability.ts`                     | Model లభ్యత తనిఖీ                                               |
| `degradation.ts`                           | Degraded-mode పరివర్తనలు                                        |
| `providerExpiration.ts`                    | గడువు ముగిసిన account/key గుర్తింపు                             |
| `quotaCache.ts`                            | Cached quota నిర్ణయాలు                                          |
| `responses.ts`, `omnirouteResponseMeta.ts` | Response ఆకృతి సహాయకాలు                                         |
| `configAudit.ts`                           | Config మార్పు audit                                             |
| `assessment/`                              | Model assessment (ప్రతి RFC ప్రకారం, పాక్షికంగా అమలు చేయబడింది) |
| `types.ts`                                 | భాగస్వామ్య domain types                                         |

### 3.4 `src/server/` — Serverకు మాత్రమే

Client components నుండి import చేయడం సాధ్యం కాదు.

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        routesను public లేదా managementగా వర్గీకరిస్తుంది
│   ├── assertAuth.ts      Assertion సహాయకం
│   ├── context.ts         ప్రతి-request authz context
│   ├── headers.ts
│   ├── pipeline.ts        Authz pipeline
│   ├── policies/          నిర్దిష్ట policies
│   └── types.ts
└── cors/origins.ts        CORS origin అనుమతి జాబితా
```

### 3.5 `src/shared/` — భాగస్వామ్యం చేయడానికి సురక్షితం

నిర్దిష్ట ప్రయోజనాలున్న ఉపడైరెక్టరీలుగా విభజించబడింది:

- `constants/` — `providers.ts` (Zod ద్వారా ధృవీకరించబడిన ప్రొవైడర్ కేటలాగ్), `models.ts`,
  `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`,
  `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`,
  `headers.ts`, `upstreamHeaders.ts` (నిషేధిత జాబితా), `mcpScopes.ts`,
  `errorCodes.ts`, `publicApiRoutes.ts`, `batch.ts`, `batchEndpoints.ts`,
  `bodySize.ts`, `colors.ts`, `appConfig.ts`, `config.ts`,
  `sidebarVisibility.ts`, `visionBridgeDefaults.ts`.
- `validation/` — `schemas.ts` (~80 Zod స్కీమాలు), `compressionConfigSchemas.ts`,
  `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`.
- `contracts/` — npmకు పంపిణీ చేయబడే పబ్లిక్ API కాంట్రాక్ట్లు.
- `types/` — భాగస్వామ్య TS రకాలు.
- `utils/` — `circuitBreaker.ts`, `apiAuth.ts`, `apiKey.ts`, `apiKeyPolicy.ts`,
  `api.ts`, `classify429.ts`, `cliCompat.ts`, `clipboard.ts`, `cloud.ts`, `cn.ts`,
  `cors.ts`, `featureFlags.ts`,
  `fetchTimeout.ts`, `formatting.ts`, `inputSanitizer.ts`, `logger.ts`,
  `machine.ts`, `machineId.ts`, `maskEmail.ts`, `modelCatalogSearch.ts`,
  `nodeRuntimeSupport.ts`, `parseApiKeys.ts`, `providerHints.ts`,
  `providerModelAliases.ts`, `rateLimiter.ts`, `releaseNotes.ts`,
  `a11yAudit.ts`, అలాగే `services/`, `network/`, `middleware/`, `schemas/`,
  `hooks/`, `components/` కింద ఉన్న డ్యాష్బోర్డ్ హుక్స్/కాంపోనెంట్లు.

---

## 4. `open-sse/` — స్ట్రీమింగ్ ఇంజిన్ వర్క్స్పేస్

`@omniroute/open-sse`గా ప్రచురించబడిన ప్రత్యేక npm వర్క్స్పేస్. అభ్యర్థన
ప్రాసెసింగ్, ఎగ్జిక్యూటర్లు, ట్రాన్స్లేటర్లు, సేవలు, ట్రాన్స్ఫార్మర్ మరియు MCP సర్వర్ను నిర్వహిస్తుంది.

```
open-sse/
├── index.ts                పబ్లిక్ ఎక్స్పోర్ట్లు
├── package.json            వర్క్స్పేస్ మానిఫెస్ట్
├── tsconfig.json
├── types.d.ts
├── config/                 ప్రొవైడర్ రిజిస్ట్రీలు, హెడర్ ప్రొఫైల్లు, ఐడెంటిటీ, …
├── handlers/               అభ్యర్థన హ్యాండ్లర్లు (చాట్, ఎంబెడ్డింగ్లు, ఆడియో, చిత్రం, …)
├── executors/              150 ప్రొవైడర్ ఎగ్జిక్యూటర్ మాడ్యూళ్లు (ఎగ్జిక్యూటర్ క్లాస్లు + ప్రతి ప్రొవైడర్కు సహాయకాలు)
├── translator/             ఫార్మాట్ మార్పిడి (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions స్ట్రీమ్ ట్రాన్స్ఫార్మర్
├── services/               80+ సేవా మాడ్యూళ్లు (కాంబోలు, ఫాల్బ్యాక్, కోటాలు, ఐడెంటిటీ, …)
├── utils/                  స్ట్రీమింగ్ సహాయకాలు, TLS క్లయింట్, AWS SigV4, ప్రాక్సీ ఫెచ్, …
└── mcp-server/             MCP సర్వర్ (3 ట్రాన్స్పోర్ట్లు, 33 స్కోప్లు, 110 టూల్స్)
```

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

| హ్యాండ్లర్              | ఉద్దేశ్యం                                                                         |
| ----------------------- | --------------------------------------------------------------------------------- |
| `chatCore.ts`           | ప్రధాన చాట్ పైప్లైన్ (క్యాష్, రేట్ పరిమితి, కాంబో రూటింగ్, ఎగ్జిక్యూటర్ డిస్పాచ్) |
| `responsesHandler.ts`   | OpenAI Responses API ప్రవేశ బిందువు                                               |
| `embeddings.ts`         | ఎంబెడ్డింగ్లు                                                                     |
| `imageGeneration.ts`    | చిత్ర ఉత్పత్తి                                                                    |
| `audioSpeech.ts`        | టెక్స్ట్-టు-స్పీచ్                                                                |
| `audioTranscription.ts` | స్పీచ్-టు-టెక్స్ట్                                                                |
| `videoGeneration.ts`    | వీడియో ఉత్పత్తి                                                                   |
| `musicGeneration.ts`    | సంగీత ఉత్పత్తి                                                                    |
| `rerank.ts`             | పునఃర్యాంకింగ్                                                                    |
| `moderations.ts`        | మోడరేషన్                                                                          |
| `search.ts`             | వెబ్ శోధన                                                                         |
| `sseParser.ts`          | SSE ఈవెంట్ పార్సర్                                                                |
| `usageExtractor.ts`     | అప్స్ట్రీమ్ స్ట్రీమ్ల నుండి టోకెన్ గణనలను వెలికితీయడం                             |
| `responseSanitizer.ts`  | ప్రొవైడర్-నిర్దిష్ట అనవసర సమాచారాన్ని తొలగించడం                                   |
| `responseTranslator.ts` | ప్రొవైడర్ ప్రతిస్పందన మరియు ట్రాన్స్లేటర్ లేయర్ మధ్య అనుసంధానం                    |

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

150 టాప్-లెవల్ ఎగ్జిక్యూటర్ మాడ్యూళ్లు (`*.ts` నుండి `base.ts`, `index.ts` మరియు పరీక్షలను మినహాయించి — ఈ సంఖ్యను
`npm run check:docs-counts` కొలుస్తుంది). ప్రతి ఎగ్జిక్యూటర్ క్లాస్ `BaseExecutor` (`base.ts`)ను,
నేరుగా లేదా `DefaultExecutor` లేదా మరొక ఎగ్జిక్యూటర్ ద్వారా విస్తరిస్తుంది; మిగిలిన మాడ్యూళ్లు ప్రతి ప్రొవైడర్కు
సంబంధించిన సహాయకాలు (టూల్ స్కీమాలు, ఫెచ్/TTS అడాప్టర్లు, ప్రత్యేక ప్రవర్తన హ్యాండ్లర్లు). ఎగ్జిక్యూటర్లలో ఇవి ఉన్నాయి:

`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`,
`chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`,
`muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`,
`pollinations`, `qoder`, `vertex`, `devin-desktop`, అలాగే `claudeIdentity.ts`
(ఉమ్మడి ఐడెంటిటీ సహాయకం) మరియు `index.ts` (రిజిస్ట్రీ).

> గమనిక: ఇక్కడ జాబితా చేయని ప్రొవైడర్లకు సాధారణ
> OpenAI-అనుకూల ఎగ్జిక్యూటర్ను ఉపయోగించే `default.ts` సేవలందిస్తుంది. పూర్తి ప్రొవైడర్ కేటలాగ్ (375 ప్రొవైడర్లు)
> `src/shared/constants/providers.ts`లో ఉంది.

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

హబ్-అండ్-స్పోక్ అనువాదం (OpenAI హబ్గా ఉంటుంది).

- **9 అభ్యర్థన ట్రాన్స్లేటర్లు** (`translator/request/`):
  `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`,
  `gemini-to-openai`, `openai-responses`, `openai-to-claude`,
  `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`.
- **9 ప్రతిస్పందన ట్రాన్స్లేటర్లు** (`translator/response/`):
  `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`,
  `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`,
  `openai-to-claude`.
- **9 సహాయకాలు** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`, అలాగే
  సహాయక పరీక్షలు.
- **చిత్ర సహాయకాలు** (`translator/image/sizeMapper.ts`).
- టాప్-లెవల్: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

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

- `responsesTransformer.ts` — `TransformStream`-ఆధారిత Responses API ↔ Chat
  Completions కన్వర్టర్ (`responses/` రూట్ క్యాచ్-ఆల్ ద్వారా ఉపయోగించబడుతుంది).

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

ముఖ్యాంశాలు (పూర్తి జాబితా `open-sse/services/` కింద ఉంది):

| అంశం                                      | ఫైళ్లు                                                                                                                                                                                                                                                   |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| కాంబో రూటింగ్                             | `combo.ts` (20 వ్యూహాలు), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`                                                                                                                                      |
| ఆటో కాంబో ఇంజిన్                          | `autoCombo/` — `engine.ts`, `scoring.ts`, `taskFitness.ts`, `virtualFactory.ts`, `modePacks.ts`, `autoPrefix.ts`, `persistence.ts`, `providerDiversity.ts`, `providerRegistryAccessor.ts`, `routerStrategy.ts`, `selfHealing.ts`, `index.ts`             |
| ప్రతికూల పరిస్థితులను తట్టుకునే సామర్థ్యం | `accountFallback.ts` (కూల్డౌన్ + లాక్అవుట్), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                                       |
| కోటాలు                                    | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| క్యాషింగ్                                 | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| రూటింగ్ మేధస్సు                           | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| మోడల్ నిర్వహణ                             | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| కుదింపు                                   | `compression/` — పూర్తి కుదింపు ఇంజిన్ వైరింగ్                                                                                                                                                                                                           |
| టోకెన్ + సెషన్                            | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| టైర్ / మానిఫెస్ట్                         | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / నెట్వర్క్                            | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| బ్యాచ్లు                                  | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| వినియోగం                                  | `usage.ts`                                                                                                                                                                                                                                               |

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

- `server.ts`లో **110 ప్రత్యేక టూల్స్** అనుసంధానించబడ్డాయి (`schemas/tools.ts`లో 45 ప్రామాణిక టూల్స్ +
  మెమరీ, స్కిల్స్, GitHub-స్కిల్స్, పూల్, గేమిఫికేషన్, ప్లగిన్, Notion, Obsidian,
  లోకల్-కార్పస్ మరియు కుదింపు మాడ్యూల్స్ — `countUniqueMcpTools` ద్వారా యూనియన్ లెక్కించబడింది).
- **3 ట్రాన్స్పోర్ట్లు**: stdio, HTTP Streamable, SSE.
- రన్టైమ్లో **33 స్కోప్లు** అమలు చేయబడతాయి — ప్రాథమిక జాబితా `src/shared/constants/mcpScopes.ts`లో ఉంది; పూర్తి సమితి ప్రతి టూల్ మాడ్యూల్ ప్రకటించిన స్కోప్ల యూనియన్.
- ఆడిట్ పట్టిక: `mcp_tool_audit` (`audit.ts` ద్వారా నింపబడుతుంది).
- ఫైళ్లు: `server.ts`, `index.ts`, `httpTransport.ts`, `audit.ts`, `scopeEnforcement.ts`,
  `runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`,
  `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`,
  అలాగే `__tests__/` కింద ఉన్న పరీక్షలు.
- పూర్తి టూల్ కేటలాగ్ కోసం [MCP-SERVER.md](../frameworks/MCP-SERVER.md) చూడండి.

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

ప్రొవైడర్ రిజిస్ట్రీలు (`providerRegistry.ts`, `providerModels.ts`,
`providerHeaderProfiles.ts`), ప్రతి ఫార్మాట్కు సంబంధించిన మోడల్ రిజిస్ట్రీలు (`audioRegistry.ts`,
`embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`,
`musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`),
గుర్తింపు సహాయకాలు (`codexIdentity.ts`, `codexInstructions.ts`,
`anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`,
`cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`),
క్రెడెన్షియల్ సహాయకాలు (`credentialLoader.ts`, `codexClient.ts`), మరియు క్లౌడ్
అడాప్టర్లు (`azureAi.ts`, `bedrock.ts`, `datarobot.ts`, `glmProvider.ts`,
`maritalk.ts`, `oci.ts`, `petals.ts`, `runway.ts`, `sap.ts`, `watsonx.ts`,
`ollamaModels.ts`, `errorConfig.ts`, `constants.ts`, `registryUtils.ts`).

### 4.8 `open-sse/utils/`

స్ట్రీమింగ్ ప్రిమిటివ్లు మరియు ప్రొవైడర్ సహాయకాలు: `stream.ts`, `streamHandler.ts`,
`streamHelpers.ts`, `streamPayloadCollector.ts`, `streamReadiness.ts`,
`sseHeartbeat.ts`, `proxyFetch.ts`, `proxyDispatcher.ts`, `tlsClient.ts`,
`networkProxy.ts`, `awsSigV4.ts`, `cacheControlPolicy.ts`,
`cursorChecksum.ts`, `cursorAgentProtobuf.ts`, `cursorVersionDetector.ts`,
`comfyuiClient.ts`, `kieTask.ts`, `bypassHandler.ts`, `aiSdkCompat.ts`,
`thinkTagParser.ts`, `urlSanitize.ts`, `usageTracking.ts`, `requestLogger.ts`,
`progressTracker.ts`, `cors.ts`, `error.ts`, `logger.ts`, `sleep.ts`,
`ollamaTransform.ts`.

---

## 5. `electron/` — డెస్క్టాప్ ర్యాపర్

```
electron/
├── main.js                  Electron ప్రధాన ప్రాసెస్
├── preload.js               ప్రీలోడ్ బ్రిడ్జ్ (contextIsolation ప్రారంభించబడింది)
├── types.d.ts
├── package.json             electron-builder కాన్ఫిగ్, వెర్షన్ 3.8.51
├── README.md
├── assets/                  బిల్డ్ వనరులు (ఐకాన్లు, అర్హతలు, …)
├── node_modules/            ప్రత్యేక node_modules (better-sqlite3, electron-updater)
└── dist-electron/           బిల్డ్ అవుట్పుట్ (కమిట్ చేయబడదు)
```

వర్క్స్పేస్ రూట్లో ఐదు npm స్క్రిప్ట్లు: `electron:dev`, `electron:build`,
`electron:build:{win,mac,linux}`, `electron:smoke:packaged`. స్వయంచాలక అప్డేట్
GitHub విడుదల ఫీడ్ను సూచించే `electron-updater` ద్వారా జరుగుతుంది.

---

## 6. `bin/` — CLI

```
bin/
├── omniroute.mjs           ప్రధాన CLI ఎంట్రీ (Node ESM)
├── reset-password.mjs      CLI నుండి నిర్వహణ పాస్వర్డ్ను రీసెట్ చేయండి
├── mcp-server.mjs          MCP సర్వర్ లాంచర్ (stdio)
├── nodeRuntimeSupport.mjs  Node వెర్షన్ గార్డ్
└── cli/
    ├── program.mjs         Commander ప్రోగ్రామ్ బిల్డర్
    ├── runtime.mjs         withRuntime సహాయకం (మొదట సర్వర్/DB ఫాల్బ్యాక్)
    ├── output.mjs          అవుట్పుట్ ఫార్మాటర్లు (json/jsonl/table/csv)
    ├── i18n.mjs            లోకేల్లతో t() సహాయకం
    ├── api.mjs             API ఫెచ్ సహాయకం
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    కమాండ్ నమోదు
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (ప్రతి కమాండ్/సమూహానికి ఒక ఫైల్)
```

`package.json` → `bin`లో రెండు బైనరీలు అందుబాటులో ఉంచబడ్డాయి:

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

---

## 7. `tests/`

| డైరెక్టరీ                                            | రకం                                                                                                             |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`                                        | Node స్థానిక టెస్ట్ రన్నర్ ద్వారా యూనిట్ పరీక్షలు (1821 ఫైళ్లు, అదనంగా `api/`, `auth/`, `authz/` ఉపడైరెక్టరీలు) |
| `tests/integration/`                                 | క్రాస్-మాడ్యూల్ + DB-స్టేట్ పరీక్షలు                                                                            |
| `tests/e2e/`                                         | Playwright UI పరీక్షలు                                                                                          |
| `tests/e2e/protocol-clients.test.ts`                 | MCP/A2A ప్రోటోకాల్ e2e                                                                                          |
| `tests/translator/`                                  | ట్రాన్స్లేటర్-నిర్దిష్ట పరీక్షలు                                                                                |
| `tests/security/`                                    | భద్రతా రిగ్రెషన్లు                                                                                              |
| `tests/load/`                                        | లోడ్ / స్ట్రెస్ పరీక్షలు                                                                                        |
| `tests/golden-set/`                                  | ట్రాన్స్లేటర్ రిగ్రెషన్ల కోసం రిఫరెన్స్ అవుట్పుట్లు                                                             |
| `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | మద్దతు                                                                                                          |

సాధారణ కమాండ్లు:

| కమాండ్                                                   | ఇది అమలు చేసేది                                                                |
| -------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `npm run test:unit`                                      | Node టెస్ట్ రన్నర్ ద్వారా అన్ని `tests/unit/*.test.ts` పరీక్షలు (కంకరెన్సీ 10) |
| `npm run test:vitest`                                    | Vitest సూట్ (MCP, autoCombo, cache)                                            |
| `npm run test:e2e`                                       | Playwright UI సూట్                                                             |
| `npm run test:protocols:e2e`                             | MCP + A2A ప్రోటోకాల్ e2e                                                       |
| `npm run test:coverage`                                  | కవరేజ్ గేట్ (లైన్లు/స్టేట్మెంట్లు/ఫంక్షన్లు/బ్రాంచ్లు ≥60%)                    |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | ఒకే ఫైల్ను అమలు చేయడం                                                          |

---

## 8. `scripts/`

ప్రయోజనం ఆధారంగా 6 ఉపఫోల్డర్లుగా క్రమబద్ధీకరించబడింది.

- **`scripts/build/`** — `build-next-isolated.mjs`, `prepublish.ts`,
  `prepare-electron-standalone.mjs`, `pack-artifact-policy.ts`,
  `validate-pack-artifact.ts`, `postinstall.mjs`, `postinstallSupport.mjs`,
  `uninstall.mjs`, `bootstrap-env.mjs`, `runtime-env.mjs`,
  `native-binary-compat.mjs`.
- **`scripts/dev/`** — `run-next.mjs`, `run-next-playwright.mjs`,
  `run-standalone.mjs`, `standalone-server-ws.mjs`, `responses-ws-proxy.mjs`,
  `v1-ws-bridge.mjs`, `smoke-electron-packaged.mjs`,
  `run-playwright-tests.mjs`, `run-ecosystem-tests.mjs`,
  `run-protocol-clients-tests.mjs`, `sync-env.mjs`, `healthcheck.mjs`,
  `system-info.mjs`, అలాగే చదవడానికి-మాత్రమే ఉద్దేశించిన PR పర్యవేక్షణ సహాయకాలు
  `ci-discriminate.sh` (ఒక రెఫరెన్స్ PR లేదా base-red ఇష్యూతో పోల్చి, PRలో విఫలమైన తనిఖీల సిగ్నేచర్లను స్వంతం /
  వారసత్వంగా వచ్చినవి / తెలియనివిగా వర్గీకరిస్తుంది) మరియు `audit-worktree.sh`
  (డర్టీ ఫైళ్లు, రక్షిత ఉపరితలాలు, తొలగించబడిన అసర్ట్లు, సప్రెషన్ గణనలు, మిగిలిపోయిన
  తాత్కాలిక tsconfigలు, PR head వర్సెస్ స్థానిక HEAD — ఒక వర్కర్ PR ఆమోదించబడే ముందు).
- **`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. అభ్యర్థన పైప్లైన్ (సారాంశం)

![అభ్యర్థన పైప్లైన్ (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> మూలం: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
క్లయింట్ అభ్యర్థన
  → /v1/chat/completions (route.ts)
     CORS ప్రీఫ్లైట్ తనిఖీ
     Zod ధ్రువీకరణ (shared/validation/schemas.ts లోని chatCompletionsSchema)
     ప్రమాణీకరణ (extractApiKey + isValidApiKey లేదా requireManagementAuth)
     విధాన ఇంజిన్ (src/server/authz/pipeline.ts)
     రక్షణ నియమాలు (PII మాస్కర్, ప్రాంప్ట్ ఇంజెక్షన్, విజన్ బ్రిడ్జ్)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     క్యాష్ తనిఖీ (సెమాంటిక్ + రీడ్ క్యాష్)
     రేట్ పరిమితి (rateLimitManager, accountSemaphore)
     కాంబో రూటింగ్ (మోడల్ ఒక కాంబోకు పరిష్కరించబడితే)
       comboResolver → ప్రతి లక్ష్యానికి లూప్ → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       అప్స్ట్రీమ్ను ఫెచ్ చేయడం → accountFallback ద్వారా మళ్లీ ప్రయత్నించడం/బ్యాక్ఆఫ్
     translateResponse() (open-sse/translator/response/*)
     SSE స్ట్రీమ్ లేదా JSON ప్రతిస్పందన
     Responses API అయితే: open-sse/transformer/responsesTransformer.ts ద్వారా TransformStream
  → అనుపాలన ఆడిట్ (src/lib/compliance/)
  → క్లయింట్కు ప్రతిస్పందన
```

### స్థితిస్థాపకత రన్టైమ్ స్థితి (మూడు యంత్రాంగాలు)

| యంత్రాంగం                   | పరిధి                        | ఎక్కడ                                                                                                                       |
| --------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| ప్రొవైడర్ సర్క్యూట్ బ్రేకర్ | మొత్తం ప్రొవైడర్             | `src/shared/utils/circuitBreaker.ts`, `domain_circuit_breakers`లో నిల్వ చేయబడుతుంది                                         |
| కనెక్షన్ కూల్డౌన్           | ఒక ఖాతా/కీ                   | `src/sse/services/auth.ts`లోని `markAccountUnavailable()`; `accountFallback.checkFallbackError()` ద్వారా వినియోగించబడుతుంది |
| మోడల్ లాకౌట్                | ప్రొవైడర్ + కనెక్షన్ + మోడల్ | `open-sse/services/accountFallback.ts`, `domain_lockout_state`లో నిల్వ చేయబడుతుంది                                          |

[RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) మరియు
[CLAUDE.md](../../CLAUDE.md)లోని ప్రత్యేక విభాగాన్ని చూడండి.

---

## 10. సహకరించడం ఎలా

### కొత్త providerను జోడించడం

1. `src/shared/constants/providers.ts`లో నమోదు చేయండి (లోడ్ సమయంలో Zodతో ధృవీకరించబడుతుంది).
2. అనుకూల లాజిక్ అవసరమైతే `open-sse/executors/`లో executorను జోడించండి
   (`BaseExecutor`ను విస్తరించండి).
3. అది OpenAI ఫార్మాట్ను ఉపయోగించకపోతే `open-sse/translator/`లో translatorను జోడించండి.
4. OAuth ఆధారితమైతే, `src/lib/oauth/providers/` మరియు
   `src/lib/oauth/services/` కింద కాన్ఫిగరేషన్ను జోడించండి.
5. `open-sse/config/providerRegistry.ts`లో (లేదా `open-sse/config/` కింద ఉన్న
   ఫార్మాట్-నిర్దిష్ట registryలో) మోడళ్లను నమోదు చేయండి.
6. `tests/unit/` కింద పరీక్షలను రాయండి.

### కొత్త API routeను జోడించడం

1. `src/app/api/your-route/route.ts`ను సృష్టించండి.
2. ఈ నమూనాను అనుసరించండి: CORS → Zod body ధృవీకరణ → auth → handlerకు అప్పగించడం.
3. కొత్త request ఆకృతి ఉంటే: `src/shared/validation/schemas.ts`లో Zod schemaను జోడించండి.
4. నిర్వహణకు మాత్రమే అయితే: `src/shared/constants/publicApiRoutes.ts`కు pathను జోడించండి
   (public API surface కోసం denylist).
5. `tests/unit/` కింద పరీక్షలను జోడించండి.
6. `docs/reference/API_REFERENCE.md` మరియు `docs/openapi.yaml`ను నవీకరించండి.

### కొత్త DB moduleను జోడించడం

1. `src/lib/db/yourModule.ts`ను సృష్టించి, `./core.ts` నుండి `getDbInstance()`ను import చేయండి.
2. మీ domain కోసం CRUD functionsను export చేయండి.
3. కొత్త tables ఉంటే: `src/lib/db/migrations/` కింద వరుస సంఖ్యతో,
   idempotentగా, transactionalగా ఉండే migrationను జోడించండి.
4. Importers `@/lib/db/yourModule` నుండి నేరుగా importsను ఉపయోగించాలి (barrel వద్దు — పాత `localDb.ts` re-export layer తొలగించబడింది).
5. `tests/unit/` కింద పరీక్షలను జోడించండి.

### కొత్త MCP toolను జోడించడం

1. `open-sse/mcp-server/tools/` కింద tool definitionను జోడించండి (లేదా
   `open-sse/mcp-server/schemas/tools.ts`ను విస్తరించండి).
2. `src/shared/constants/mcpScopes.ts`లో తగిన scope(లు)ను కేటాయించండి.
3. `open-sse/mcp-server/server.ts`లో toolను నమోదు చేయండి.
4. `open-sse/mcp-server/__tests__/` కింద పరీక్షలను జోడించండి.
5. [MCP-SERVER.md](../frameworks/MCP-SERVER.md)ను నవీకరించండి.

### కొత్త A2A skillను జోడించడం

[A2A-SERVER.md § కొత్త Skillను జోడించడం](../frameworks/A2A-SERVER.md) చూడండి. Skills
`src/lib/a2a/skills/`లో ఉంటాయి మరియు A2A task manager ద్వారా నమోదు చేయబడతాయి.

---

## 11. నియమాలు

- **Code style**: 2-space indent, double quotes, 100 char width, semicolons,
  `es5` trailing commas — `lint-staged` ద్వారా Prettier వీటిని అమలు చేస్తుంది.
- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative.
- **Naming**: files `camelCase` లేదా `kebab-case`, components `PascalCase`,
  constants `UPPER_SNAKE`.
- **ESLint**: ప్రతిచోటా `no-eval`, `no-implied-eval`, `no-new-func` = `error`;
  `open-sse/` మరియు `tests/`లో `no-explicit-any` = `warn`, మిగతా చోట్ల error.
- **TypeScript**: `strict: false` (legacy విధానం). Cross-module boundaries కోసం
  inference కంటే explicit typesకు ప్రాధాన్యం ఇవ్వండి.
- **Database**: routes లేదా handlersలో raw SQLను ఎప్పుడూ రాయవద్దు — ఎల్లప్పుడూ
  `src/lib/db/` modules ద్వారానే ఉపయోగించండి. Barrel-import ఎప్పుడూ చేయవద్దు — నిర్దిష్ట `src/lib/db/*` modulesను నేరుగా ఉపయోగించండి.
- **DB-entity typing (#3512)**: DB table యొక్క row ఆకృతిని వ్రాసే లేదా చదివే function,
  call site వద్ద `any` లేదా inline anonymous typeకు బదులుగా, ఆ table యొక్క
  columnsను 1:1గా ప్రతిబింబించే named TS interfaceను స్వీకరించాలి/తిరిగి ఇవ్వాలి.
  Interfaceను function పక్కనే ఉంచండి (ఉదా. `saveRequestUsage`కు పైన
  `src/lib/usage/usageHistory.ts`లో `export interface UsageEntry`), వేర్వేరు
  writers rowను దశలవారీగా పూరించే సందర్భంలో individual fieldsను
  optional/nullableగా ఉంచండి, అలాగే callers మధ్య ఆకృతి మారే field కోసం
  `any` కంటే `unknown`కు ప్రాధాన్యం ఇవ్వండి (fieldపై దీన్ని document చేయండి, ఉదా. `UsageEntry.tokens`
  raw provider ఆకృతిలోని usage మరియు normalized ఆకృతి రెండింటినీ
  అంగీకరిస్తుంది). ఈ విధంగా file యొక్క `any` count సున్నాకు చేరిన తర్వాత,
  అది తిరిగి పెరగకుండా `check:any-budget:t11` allowlistకు
  (`scripts/check/check-t11-any-budget.mjs`, `maxAny: 0`) జోడించండి. ఇది
  first-slice నియమం — విస్తృతమైన "anonymous `any` వద్దు" cleanup మిగిలిన
  codebase అంతటా దశలవారీగా జరుగుతుంది.
- **Errors**: నిర్దిష్ట error typesతో try/catch ఉపయోగించండి, pino contextతో log చేయండి. SSE streamsలో
  errorsను ఎప్పుడూ నిశ్శబ్దంగా విస్మరించవద్దు; cleanup కోసం abort signalsను ఉపయోగించండి.
- **Security**: `eval()` / `new Function()` / implied evalను ఎప్పుడూ ఉపయోగించవద్దు. అన్ని
  inputsను Zodతో ధృవీకరించండి. నిల్వలో ఉన్న credentialsను encrypt చేయండి (AES-256-GCM).
  `src/shared/constants/upstreamHeaders.ts` denylistను sanitize/validation
  layerతో సమలేఖనంలో ఉంచండి.
- **Commits**: Conventional Commits — `feat(scope): subject`. అనుమతించబడిన scopes:
  `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
  `a2a`, `memory`, `skills`.
- **Branches**: prefixes `feat/`, `fix/`, `refactor/`, `docs/`, `test/`,
  `chore/`. `main`కు ఎప్పుడూ నేరుగా commit చేయవద్దు.
- **Husky**: pre-commitలో `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11` అమలవుతాయి; pre-pushలో `check:any-budget:t11` + `check:tracked-artifacts` అమలవుతాయి (వేగవంతమైన gates; `test:unit`ను మినహాయిస్తాయి).

---

## 12. కఠిన నియమాలు (`CLAUDE.md` నుండి)

1. రహస్యాలు లేదా క్రెడెన్షియల్స్ను ఎప్పుడూ కమిట్ చేయవద్దు.
2. బ్యారెల్-ఇంపోర్ట్ను ఎప్పుడూ ఉపయోగించవద్దు — నిర్దిష్ట `src/lib/db/*` మాడ్యూళ్లను నేరుగా ఉపయోగించండి.
3. `eval()` / `new Function()` / పరోక్ష evalను ఎప్పుడూ ఉపయోగించవద్దు.
4. నేరుగా `main`కు ఎప్పుడూ కమిట్ చేయవద్దు.
5. రూట్లలో ముడి SQLను ఎప్పుడూ వ్రాయవద్దు — ఎల్లప్పుడూ `src/lib/db/` మాడ్యూళ్ల ద్వారానే నిర్వహించండి.
6. SSE స్ట్రీమ్లలో లోపాలను ఎప్పుడూ నిశ్శబ్దంగా విస్మరించవద్దు.
7. ఇన్పుట్లను ఎల్లప్పుడూ Zod స్కీమాలతో ధ్రువీకరించండి.
8. ప్రొడక్షన్ కోడ్ను మార్చేటప్పుడు ఎల్లప్పుడూ పరీక్షలను చేర్చండి.
9. కవరేజ్ తప్పనిసరిగా ≥ 60%గా ఉండాలి (స్టేట్మెంట్లు, లైన్లు, ఫంక్షన్లు, బ్రాంచ్లు).

---

## 13. ఇవి కూడా చూడండి

- [ARCHITECTURE.md](./ARCHITECTURE.md) — ఉన్నత-స్థాయి ఆర్కిటెక్చర్ మరియు మాడ్యూల్
  బాధ్యతలు.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — పబ్లిక్ + మేనేజ్మెంట్ API రిఫరెన్స్.
- [FEATURES.md](../guides/FEATURES.md) — ఫీచర్ మ్యాట్రిక్స్ మరియు వెర్షన్ ముఖ్యాంశాలు.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — సర్క్యూట్ బ్రేకర్, కూల్డౌన్,
  లాకౌట్పై లోతైన వివరణ.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — Auto Combo స్కోరింగ్ మరియు వ్యూహాలు.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — పూర్తి MCP టూల్ కేటలాగ్ + ట్రాన్స్పోర్ట్లు.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — A2A ప్రోటోకాల్ నైపుణ్యాలు మరియు డిస్కవరీ.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK + Caveman కంప్రెషన్.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI ఇంటిగ్రేషన్లు.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (ఉంటే), [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) — డిప్లాయ్మెంట్ లక్ష్యాలు.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — సాధారణ నిర్వహణ సమస్యలు.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — కంట్రిబ్యూటర్ వర్క్ఫ్లో.
- [CLAUDE.md](../../CLAUDE.md) — Claude Code కోసం రిపో నియమాలు (పైన పేర్కొన్న అనేక సంప్రదాయాలకు
  మూలాధారం).
- [AGENTS.md](../../AGENTS.md) — ఏజెంట్లు ఉపయోగించే మరింత లోతైన ఆర్కిటెక్చర్ రిఫరెన్స్.