OmniRoute/docs/i18n/si/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 · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 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, ස්වාධීන ප්රතිදානය, ගෝලීය middleware නොමැත)
භාෂාව	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/ හි වෙනම workspace එකක්)
පරීක්ෂණ	Node ස්වදේශීය පරීක්ෂණ ධාවකය (ඒකක/අනුකලන), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
ගොඩනැඟීම	scripts/build/build-next-isolated.mjs හරහා Next.js ස්වාධීන ගොඩනැඟීම
Lint/ආකෘතිය	ESLint පැතලි වින්යාසය + Prettier (Husky pre-commit හරහා lint-staged)
මොඩියුල පද්ධතිය	සෑම තැනකම ESM ("type": "module")
Workspaces	npm workspace — එකම උප-workspace එක open-sse වේ

මාර්ග අන්වර්ථ (tsconfig.json):

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

පෙරනිමි HTTP port එක: 20128 (API සහ dashboard එකම ක්රියාවලිය බෙදා ගනී). දත්ත නාමාවලිය DATA_DIR පරිසර විචල්යය වන අතර, එහි පෙරනිමි අගය ~/.omniroute/ වේ.

---

2. ගබඩා ව්යුහය

OmniRoute/
├── src/                  Next.js යෙදුම (App Router, පුස්තකාල, domain, server, බෙදාගත් සංරචක)
├── open-sse/             Streaming engine workspace (@omniroute/open-sse)
├── electron/             ඩෙස්ක්ටොප් ආවරණය (Electron 41 main + preload)
├── bin/                  CLI ප්රවේශ ස්ථාන (omniroute, reset-password)
├── tests/                ඒකක, අනුකලන, e2e, protocols-e2e, translator, security, fixtures
├── scripts/              ගොඩනැඟීමේ, සමමුහුර්ත කිරීමේ, පරීක්ෂා කිරීමේ, migration සහ ධාවනකාල සහායක scripts
├── docs/                 පොදු ප්රලේඛනය (මෙම නාමාවලිය)
├── public/               ස්ථිතික සම්පත්, PWA manifest, service worker
├── config/               ධාවනකාල වින්යාස සාම්පල
├── images/               අලෙවිකරණ/තිරරූප සම්පත්
├── _ideia/, _references/, _mono_repo/, _tasks/   අභ්යන්තර අත්හදාබැලීම් / සැලසුම් (නිකුත් නොකෙරේ)
├── CLAUDE.md             Claude Code සඳහා ගබඩා නීති
├── AGENTS.md             agents සඳහා වඩාත් ගැඹුරු ගෘහනිර්මාණ යොමුව
├── package.json          v3.8.51, workspace මූලය
└── tsconfig.json         මාර්ග අන්වර්ථ + මූලික compiler විකල්ප

---

3. src/ — Next.js යෙදුම

src/
├── app/                  App Router පිටු + API මාර්ග
├── lib/                  මූලික පුස්තකාල (DB, සත්යාපනය, OAuth, කුසලතා, මතකය, …)
├── domain/               පිරිසිදු වසම් ස්තරය (ප්රතිපත්ති, විකල්ප යාන්ත්රණ, පිරිවැය, අගුලු දැමීම, …)
├── server/               සේවාදායකයට පමණක් සීමා වූ මොඩියුල (අවසර පාලනය, cors, සත්යාපනය)
├── 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/                    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/	Agent-Control-Protocol: 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 තුළ කිසිවිටෙක raw SQL නොලියන්න — මෙම මොඩියුල හරහා ක්රියා කරන්න.

මූලාශ්රය: diagrams/db-schema-overview.mmd

Domain මොඩියුල (එක් එක් මොඩියුලය වගු එකක් හෝ කිහිපයක් භාරව පවතී): 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/ තුළ අනුවාදගත .sql ගොනු 168ක් (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 (මතක සෙවීම සඳහා FTS5 virtual වගු ද ඇතුළුව).

3.3 src/domain/ — 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 → ඉලක්ක ලැයිස්තුව ලෙස combo විසඳීම
connectionModelRules.ts	එක් එක් connection සඳහා model filters
modelAvailability.ts	Model ලබාගත හැකි බව පරීක්ෂා කිරීම
degradation.ts	Degraded-mode සංක්රාන්ති
providerExpiration.ts	කල් ඉකුත් වූ account/key හඳුනාගැනීම
quotaCache.ts	Cache කළ quota තීරණ
responses.ts, omnirouteResponseMeta.ts	Response හැඩතල සඳහා උපකාරක
configAudit.ts	Config වෙනස්කම් පිළිබඳ audit එක
assessment/	Model ඇගයීම (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 allowlist එක

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 (Zod ස්කීමා ~80ක්), 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/              සැපයුම්කරු-විශේෂිත HTTP ක්රියාත්මක කරන්නන් 108ක්
├── 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/

BaseExecutor (base.ts) විස්තාරණය කරන සැපයුම්කරු ක්රියාත්මක කරන්නන් 108ක්:

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/

• අනන්ය මෙවලම් 110ක් server.ts තුළ සම්බන්ධ කර ඇත (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/           ගොඩනැගීමේ ප්රතිදානය (commit කර නැත)

වැඩබිම් මූලයේ 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 fetch සහායකය
    ├── 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. දායක වන ආකාරය

නව සපයන්නෙකු එක් කිරීම

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 එක තුළ) models ලියාපදිංචි කරන්න.
6. tests/unit/ යටතේ පරීක්ෂණ ලියන්න.

නව API route එකක් එක් කිරීම

1. src/app/api/your-route/route.ts සාදන්න.
2. මෙම රටාව අනුගමනය කරන්න: CORS → Zod body වලංගුකරණය → සත්යාපනය → handler වෙත පැවරීම.
3. නව request ආකෘතියක් නම්: src/shared/validation/schemas.ts තුළ Zod schema එක එක් කරන්න.
4. එය කළමනාකරණයට පමණක් නම්: src/shared/constants/publicApiRoutes.ts වෙත path එක එක් කරන්න (පොදු API පෘෂ්ඨය සඳහා denylist එක).
5. tests/unit/ යටතේ පරීක්ෂණ එක් කරන්න.
6. docs/reference/API_REFERENCE.md සහ docs/openapi.yaml යාවත්කාලීන කරන්න.

නව DB module එකක් එක් කිරීම

1. src/lib/db/yourModule.ts සාදා ./core.ts වෙතින් getDbInstance() ආයාත කරන්න.
2. ඔබේ domain එක සඳහා CRUD functions නිර්යාත කරන්න.
3. නව tables තිබේ නම්: src/lib/db/migrations/ යටතේ අනුක්රමිකව අංකනය කළ, idempotent සහ transactional migration එකක් එක් කරන්න.
4. Importers විසින් @/lib/db/yourModule වෙතින් සෘජු imports භාවිත කරයි (barrel එකක් නොවේ — පැරණි localDb.ts නැවත-නිර්යාත ස්තරය ඉවත් කර ඇත).
5. tests/unit/ යටතේ පරීක්ෂණ එක් කරන්න.

නව MCP tool එකක් එක් කිරීම

1. open-sse/mcp-server/tools/ යටතේ tool නිර්වචනය එක් කරන්න (හෝ open-sse/mcp-server/schemas/tools.ts විස්තාරණය කරන්න).
2. src/shared/constants/mcpScopes.ts තුළ සුදුසු scope එක හෝ scopes පවරන්න.
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. සම්මුතීන්

• කේත ශෛලිය: හිස්තැන් 2ක indent කිරීම, ද්විත්ව උද්ධෘත ලකුණු, අක්ෂර 100ක පළල, semicolons, es5 trailing commas — lint-staged හරහා Prettier මඟින් බලාත්මක කෙරේ.
• Imports: බාහිර → අභ්යන්තර (@/, @omniroute/open-sse) → සාපේක්ෂ.
• නාමකරණය: 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 (පැරණි ස්ථාවරය). modules අතර සීමා සඳහා inference වෙනුවට පැහැදිලි types භාවිත කිරීමට ප්රමුඛත්වය දෙන්න.
• දත්ත සමුදාය: 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 ලෙස පිළිබිඹු කරන නම් කළ TS interface එකක් ලබාගෙන/ආපසු ලබා දිය යුතුය. interface එක function එක අසල තබන්න (උදා. saveRequestUsage ට ඉහළින් src/lib/usage/usageHistory.ts තුළ export interface UsageEntry), විවිධ writers විසින් row එක ක්රමයෙන් පුරවන විට එක් එක් fields optional/nullable ලෙස තබන්න, සහ callers අතර ආකෘතිය වෙනස් වන field එකක් සඳහා any වෙනුවට unknown භාවිත කිරීමට ප්රමුඛත්වය දෙන්න (field එක මත එය ලේඛනගත කරන්න, උදා. UsageEntry.tokens raw provider-shaped usage සහ normalized shape යන දෙකම පිළිගනී). මේ ආකාරයෙන් file එකක any ගණන ශුන්යයට ළඟා වූ පසු, එය නැවත පිරිහිය නොහැකි වන සේ check:any-budget:t11 allowlist එකට (scripts/check/check-t11-any-budget.mjs, maxAny: 0) එක් කරන්න. මෙය first-slice සම්මුතියකි — පුළුල් "anonymous any නැත" පිරිසිදු කිරීම අනෙකුත් codebase එක පුරා පුනරාවර්තනීයව සිදු කෙරේ.
• දෝෂ: නිශ්චිත error types සමඟ try/catch භාවිත කර, pino context සමඟ log කරන්න. SSE streams තුළ කිසිවිටෙක දෝෂ නිහඬව නොසලකා හරින්න; cleanup සඳහා abort signals භාවිත කරන්න.
• ආරක්ෂාව: කිසිවිටෙක eval() / new Function() / implied eval භාවිත නොකරන්න. සියලු inputs Zod සමඟ වලංගු කරන්න. නිෂ්ක්රීයව ඇති credentials සංකේතනය කරන්න (AES-256-GCM). src/shared/constants/upstreamHeaders.ts denylist එක sanitize/validation ස්තරය සමඟ සමපාතව තබා ගන්න.
• 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. කිසිවිටෙකත් රහස් හෝ අක්තපත්ර commit නොකරන්න.
2. කිසිවිටෙකත් barrel-import නොකරන්න — නිශ්චිත src/lib/db/* මොඩියුල සෘජුවම භාවිත කරන්න.
3. කිසිවිටෙකත් eval() / new Function() / ව්යංග eval භාවිත නොකරන්න.
4. කිසිවිටෙකත් main වෙත සෘජුවම commit නොකරන්න.
5. කිසිවිටෙකත් routes තුළ raw SQL නොලියන්න — සැමවිටම src/lib/db/ මොඩියුල හරහා යන්න.
6. SSE streams තුළ දෝෂ නිහඬව නොසලකා නොහරින්න.
7. සැමවිටම Zod schemas මඟින් ආදාන වලංගු කරන්න.
8. production code වෙනස් කරන විට සැමවිටම පරීක්ෂණ ඇතුළත් කරන්න.
9. ආවරණය (statements, lines, functions, branches) ≥ 60% මට්ටමේ පවත්වාගත යුතුය.

---

13. තවද බලන්න

• ARCHITECTURE.md — ඉහළ මට්ටමේ ගෘහනිර්මාණය සහ මොඩියුල වගකීම්.
• API_REFERENCE.md — පොදු + කළමනාකරණ API යොමුව.
• FEATURES.md — විශේෂාංග න්යාසය සහ අනුවාද විශේෂතා.
• RESILIENCE_GUIDE.md — circuit breaker, cooldown සහ lockout පිළිබඳ ගැඹුරු විග්රහය.
• 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 සඳහා repo නීති (ඉහත සම්මුතීන් බොහොමයක සත්ය මූලාශ්රය).
• AGENTS.md — agents විසින් භාවිත කරන වඩාත් ගැඹුරු ගෘහනිර්මාණ යොමුව.