# 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) · 🇸🇰 [sk](../../../sk/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇮 [sl](../../../sl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇸 [sr](../../../sr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../../sv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../../sw/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../../ta/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../../te/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../../th/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../../tr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../../ur/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇿 [uz](../../../uz/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../../vi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [yo](../../../yo/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md)

---

> **අනුවාදය:** 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, ස්වාධීන ප්රතිදානය, ගෝලීය 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** (singleton, WAL journaling)                                                                 |
| ඩෙස්ක්ටොප්      | **Electron 41** + `electron-builder` 26.10 (`electron/` හි වෙනම workspace එකක්)                                              |
| පරීක්ෂණ         | **Node ස්වදේශීය test runner** (ඒකක/ඒකාබද්ධ), **Vitest** (MCP, autoCombo, cache), **Playwright** (e2e + protocols-e2e)        |
| ගොඩනැගීම        | `scripts/build/build-next-isolated.mjs` හරහා Next.js ස්වාධීන ගොඩනැගීම                                                        |
| Lint/ආකෘතිය     | ESLint flat config + Prettier (Husky pre-commit හරහා `lint-staged`)                                                          |
| මොඩියුල පද්ධතිය | සෑම තැනකම ESM (`"type": "module"`)                                                                                           |
| Dashboard UI    | **Tailwind CSS 4** + ව්යාපෘතිය සමඟ ඇතුළත් කළ **Keak CI UI Kit** (`packages/ui-kit`), Lucide icons — `DESIGN_SYSTEM.md` බලන්න |
| Workspaces      | npm workspaces — `open-sse`, `packages/browser-pool`, `packages/ui-kit`                                                      |

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

- `@/*` → `src/*`
- `@omniroute/open-sse` → `open-sse/index.ts`
- `@omniroute/open-sse/*` → `open-sse/*`
- `@omniroute/ui-kit` → `packages/ui-kit/src`, `@omniroute/ui-kit/*` → `packages/ui-kit/src/*`

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

---

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

```
OmniRoute/
├── src/                  Next.js යෙදුම (App Router, libs, domain, server, shared)
├── open-sse/             ප්රවාහ එන්ජින් වැඩබිම (@omniroute/open-sse)
├── packages/             වැඩබිම්: ui-kit (ඇතුළත් කළ Keak CI UI Kit), browser-pool
├── electron/             ඩෙස්ක්ටොප් ආවරණය (Electron 41 main + preload)
├── bin/                  CLI පිවිසුම් ස්ථාන (omniroute, reset-password)
├── tests/                ඒකක, ඒකාබද්ධතා, e2e, protocols-e2e, පරිවර්තක, ආරක්ෂක, සහ fixtures පරීක්ෂණ
├── scripts/              ගොඩනැගීම, සමමුහුර්ත කිරීම, පරීක්ෂා කිරීම, සංක්රමණය, සහ ධාවනකාල සහායක ස්ක්රිප්ට්
├── docs/                 පොදු ලේඛන (මෙම නාමාවලිය)
├── public/               ස්ථිතික වත්කම්, PWA manifest, service worker
├── 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, සත්යාපනය, 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/`            | නියෝජිත-පාලන-ප්රොටෝකෝලය: `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/`     | Cloud agent රෙජිස්ට්රිය: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `combos/`         | Combo නිරාකරණ සහායක                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `compliance/`     | විගණනය + provider විගණනය: `index.ts`, `providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `config/`         | Runtime වින්යාස සම්බන්ධකය                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `db/`             | SQLite domain මොඩියුල (§3.2.1 බලන්න)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `display/`        | API ප්රතිචාර සඳහා භාවිත කරන UI/display සහායක                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `embeddings/`     | Embedding සේවා රෙජිස්ට්රිය                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `env/`            | 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` (Cloud Sync)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `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/*` මොඩියුල සෘජුවම ආයාත කරයි.
- `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 නොලියන්න** — මෙම මොඩියුල හරහා ක්රියා කරන්න.

![දත්ත සමුදා schema දළ විශ්ලේෂණය (තෝරාගත් මූලික වගු)](../diagrams/exported/db-schema-overview.svg)

> මූලාශ්රය: [diagrams/db-schema-overview.mmd](../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) අඩංගු වන අතර, ආරම්භයේදී
`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 tables ද ඇතුළුව).

### 3.3 `src/domain/` — Domain ස්තරය

I/O නොමැති පිරිසිදු ව්යාපාරික තර්කනය. routes සහ handlers මඟින් ආයාත කරයි.

| ගොනුව                                      | අරමුණ                                               |
| ------------------------------------------ | --------------------------------------------------- |
| `policyEngine.ts`                          | ඉහළම මට්ටමේ policy resolver                         |
| `fallbackPolicy.ts`                        | Fallback තීරණ වෘක්ෂය                                |
| `costRules.ts`                             | පිරිවැය ගණනය කිරීමේ රීති                            |
| `lockoutPolicy.ts`                         | Model lockout තීරණ                                  |
| `tagRouter.ts`                             | Tag මත පදනම් වූ routing                             |
| `comboResolver.ts`                         | ඉල්ලීමෙන් → ඉලක්ක ලැයිස්තුවට combo resolution       |
| `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 වෙනස්කම් විගණනය                              |
| `assessment/`                              | Model තක්සේරුව (RFC අනුව, අර්ධ වශයෙන් ක්රියාත්මකයි) |
| `types.ts`                                 | හවුල් domain වර්ග                                   |

### 3.4 `src/server/` — Server සඳහා පමණි

Client components වෙතින් ආයාත කළ නොහැක.

```
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` (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/` යටතේ ඇති උපකරණ පුවරු හුක්/සංරචක.
- `components/` — උපකරණ පුවරු සංරචක API එක (`index.tsx` බැරලය: `Button`, `Input`,
  `Select`, `Modal`, `Card`, `DataTable`, …). මූලික සංරචක, ව්යාපෘතියට ඇතුළත් කළ
  කට්ටලය මත ඇති ඇඩැප්ටර වේ (`packages/ui-kit`, `@omniroute/ui-kit/button` වැනි
  සංරචක උපමාර්ගයක් මඟින් ආයාත කෙරේ), එබැවින් තිර ඒවායේ ආයාත පවත්වා ගන්නා අතර
  සලකුණුකරණය කට්ටලයට අයත් වේ. ෂෙල් එක `layouts/DashboardLayout.tsx` → `layouts/DashboardShell.tsx`
  (කට්ටලයේ `SidebarProvider`/`SidebarInset`) වන අතර එයට `Sidebar.tsx` සහ `Header.tsx` ඇතුළත් වේ;
  අයිකන `Icon.tsx` සහ `constants/iconMap.ts` හරහා ගමන් කරයි. `docs/architecture/DESIGN_SYSTEM.md` බලන්න.

---

## 4. `open-sse/` — ප්‍රවාහ එන්ජිම වැඩබිම

`@omniroute/open-sse` ලෙස ප්‍රකාශයට පත් කරන ලද වෙනම npm වැඩ ඉඩක්. ඉල්ලීම් සැකසීම, ක්‍රියාත්මක කරන්නන්, පරිවර්තකයන්, සේවා, ට්‍රාන්ස්ෆෝමරය සහ MCP සේවාදායකය සතුය.

```
open-sse/
├── index.ts                Public exports
├── package.json            Workspace manifest
├── tsconfig.json
├── types.d.ts
├── config/                 Provider registries, header profiles, identity, …
├── handlers/               Request handlers (chat, embeddings, audio, image, …)
├── executors/              159 provider executor modules (executor classes + per-provider helpers)
├── translator/             Format conversion (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions stream transformer
├── services/               80+ service modules (combos, fallback, quotas, identity, …)
├── utils/                  Streaming helpers, TLS client, AWS SigV4, proxy fetch, …
└── mcp-server/             MCP server (3 transports, 33 scopes, 110 tools)
```

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

| හසුරුවන්නා              | අරමුණ                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| `chatCore.ts`           | ප්‍රධාන කතාබස් නල මාර්ගය (හැඹිලිය, අනුපාත සීමාව, සංයුක්ත මාර්ගගත කිරීම, ක්‍රියාත්මක කරන්නා යැවීම) |
| `responsesHandler.ts`   | OpenAI ප්‍රතිචාර 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/`

ඉහළ මට්ටමේ විධායක මොඩියුල 159 (`*.ts` minus `base.ts`, `index.ts` සහ පරීක්ෂණ — ගණන් කිරීමේ `npm run check:docs-counts` මිනුම්). සෑම විධායක පන්තියක්ම `BaseExecutor` (`base.ts`) සෘජුව හෝ `DefaultExecutor` හරහා හෝ වෙනත් ක්‍රියාත්මක කරන්නෙකු හරහා දිගු කරයි; ඉතිරි මොඩියුලයන් එක්-සැපයුම්කරුට සහායකයින් වේ (මෙවලම් ක්‍රම, fetch/TTS ඇඩප්ටර, quirk හසුරුවන්න). විධායකයින්ට ඇතුළත් වන්නේ:

`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`, `chatgpt-web-codex`, `cloudflare-ai`, `codex` `vertex` `commandCode`, `cursor`, `default`, `devin-cli`, `muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `pollinations`, `qoder`, plus `devin-desktop` `petals` බෙදාගත් අනන්‍යතා සහායකයා) සහ `claudeIdentity.ts` (රෙජිස්ට්‍රිය) `index.ts`

> සටහන: මෙහි ලැයිස්තුගත කර නොමැති සපයන්නන් සඳහා සාමාන්‍ය OpenAI-අනුකූල ක්‍රියාකාරකය භාවිතයෙන් `default.ts` විසින් සේවය කරනු ලැබේ. සම්පූර්ණ සැපයුම්කරුවන්ගේ නාමාවලිය (සපයන්නන් 381) `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`, plus helper tests.
- **රූප සහායකයින්** (`translator/image/sizeMapper.ts`).
- ඉහළම මට්ටම: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

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

- `responsesTransformer.ts` — `TransformStream` -based ප්‍රතිචාර API ↔ Chat Completions Converter ( `responses/` route catch-all විසින් භාවිතා කරනු ලැබේ).

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

විශේෂ අවස්ථා ( `open-sse/services/` යටතේ සම්පූර්ණ ලැයිස්තුව):

| කනස්සල්ල             | ගොනු                                                                                                                                                                                                                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Combo routing        | `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` (cooldown + lockout), `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/`

- **අද්විතීය මෙවලම් 110 ක්** `server.ts` හි රැහැන්ගත (45 canonical in `schemas/tools.ts` + memory, skills, GitHub-skills, pool, gamification, plugin, Notion, Obsidian, local-corpus and compression modules — Union by `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`, plus tests under `__tests__/`.
- සම්පූර්ණ මෙවලම් නාමාවලිය සඳහා [MCP-SERVER.md](../frameworks/MCP-SERVER.md) බලන්න.

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

Provider registries (`providerRegistry.ts`, `providerModels.ts`, `providerHeaderProfiles.ts`), per-format model registries (`audioRegistry.ts`, `embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`, `musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`), identity helpers (`codexIdentity.ts`, `codexInstructions.ts`, `anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`, `cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`), credential helpers (`credentialLoader.ts`, `codexClient.ts`), and cloud adapters (`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` `ollamaTransform.ts` `aiSdkCompat.ts`, `thinkTagParser.ts`, `urlSanitize.ts`, `usageTracking.ts`, `progressTracker.ts` `error.ts` `cors.ts` `logger.ts` `requestLogger.ts`, `sleep.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`, සහ කියවීමට පමණක් ඇති PR අධීක්ෂණ සහායක
  `ci-discriminate.sh` (යොමු PR එකකට හෝ base-red ගැටලුවට සාපේක්ෂව PR එකක අසාර්ථක පරීක්ෂණවල අත්සන් තමන්ගේ / උරුම වූ /
  නොදන්නා ලෙස වර්ග කරයි) සහ `audit-worktree.sh`
  (වෙනස්කම් සහිත ගොනු, ආරක්ෂිත පෘෂ්ඨ, ඉවත් කළ asserts, මර්දන ගණන්, ඉතිරිව ඇති
  තාවකාලික tsconfigs, 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. දායක වන ආකාරය

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

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](../frameworks/MCP-SERVER.md) යාවත්කාලීන කරන්න.

### නව A2A skill එකක් එක් කිරීම

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