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

OmniRoute Codebase Documentation (తెలుగు)

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

---

వెర్షన్: v3.8.51 చివరిగా నవీకరించబడింది: 2026-06-28 లక్ష్య పాఠకులు: OmniRouteకు సహకరిస్తున్న లేదా దాని పైన ఇంటిగ్రేషన్లను నిర్మిస్తున్న ఇంజినీర్లు.

ఉన్నత-స్థాయి ఆర్కిటెక్చర్ రేఖాచిత్రాలు మరియు ప్రతి ఉపవ్యవస్థ వెనుక ఉన్న తార్కికత కోసం, 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 చూడండి.
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/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/              108 ప్రొవైడర్-నిర్దిష్ట HTTP ఎగ్జిక్యూటర్లు
├── 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/

108 ప్రొవైడర్ ఎగ్జిక్యూటర్లు, ప్రతి ఒక్కటి 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, అదనంగా claudeIdentity.ts (భాగస్వామ్య ఐడెంటిటీ సహాయకం) మరియు index.ts (రిజిస్ట్రీ).

గమనిక: ఇక్కడ జాబితా చేయని ప్రొవైడర్లను సాధారణ OpenAI-అనుకూల ఎగ్జిక్యూటర్ను ఉపయోగించే default.ts అందిస్తుంది. పూర్తి ప్రొవైడర్ కేటలాగ్ (355 ప్రొవైడర్లు) 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 (19 వ్యూహాలు), 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, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
కోటాలు	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.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 చూడండి.

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.
• 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. అభ్యర్థన పైప్లైన్ (సారాంశం)

మూలం: 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 మరియు 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ను నవీకరించండి.

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

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