# 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) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../../ms/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇵 [ne](../../../ne/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../../nl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../../no/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [or](../../../or/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [pa](../../../pa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../../phi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../../pl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../../pt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../../ro/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../../ru/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇰 [si](../../../si/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../../sk/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇮 [sl](../../../sl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇸 [sr](../../../sr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../../sv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../../sw/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../../ta/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../../te/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../../th/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../../tr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../../ur/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇿 [uz](../../../uz/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../../vi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [yo](../../../yo/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md)

---

> **កំណែ៖** 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, លទ្ធផល standalone, គ្មាន 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`)                            |
| មូលដ្ឋានទិន្នន័យ           | **SQLite** តាមរយៈ `better-sqlite3` (singleton, ការកត់ត្រាបែប WAL)                                                                  |
| ផ្ទៃតុ                     | **Electron 41** + `electron-builder` 26.10 (workspace ដាច់ដោយឡែកនៅ `electron/`)                                                    |
| ការធ្វើតេស្ត               | **កម្មវិធីដំណើរការតេស្តដើមរបស់ Node** (unit/integration), **Vitest** (MCP, autoCombo, cache), **Playwright** (e2e + protocols-e2e) |
| ការបង្កើត                  | Next.js standalone តាមរយៈ `scripts/build/build-next-isolated.mjs`                                                                  |
| ការត្រួតពិនិត្យ/ទ្រង់ទ្រាយ | ការកំណត់រចនាសម្ព័ន្ធ ESLint flat + Prettier (`lint-staged` តាមរយៈ Husky pre-commit)                                                |
| ប្រព័ន្ធម៉ូឌុល             | ESM គ្រប់ទីកន្លែង (`"type": "module"`)                                                                                             |
| Workspaces                 | npm workspace — `open-sse` គឺជា workspace រងតែមួយគត់                                                                               |

ឈ្មោះក្លែងកាត់ផ្លូវ (`tsconfig.json`):

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

ច្រក HTTP លំនាំដើម៖ **`20128`** (API និង dashboard ប្រើដំណើរការតែមួយ)។ ថតទិន្នន័យ
គឺជាអថេរបរិស្ថាន `DATA_DIR` ដែលតាមលំនាំដើមកំណត់ទៅ `~/.omniroute/`។

---

## 2. រចនាសម្ព័ន្ធឃ្លាំងកូដ

```
OmniRoute/
├── src/                  កម្មវិធី Next.js (App Router, បណ្ណាល័យ, domain, server, ធាតុប្រើរួម)
├── open-sse/             workspace ម៉ាស៊ីន streaming (@omniroute/open-sse)
├── electron/             ស្រទាប់ផ្ទៃតុ (Electron 41 main + preload)
├── bin/                  ចំណុចចូល CLI (omniroute, reset-password)
├── tests/                Unit, integration, e2e, protocols-e2e, translator, security, fixtures
├── scripts/              ស្គ្រីបជំនួយសម្រាប់ build, sync, check, migration និង runtime
├── docs/                 ឯកសារសាធារណៈ (ថតនេះ)
├── public/               ទ្រព្យសកម្មឋិតិវន្ត, PWA manifest, service worker
├── config/               គំរូការកំណត់រចនាសម្ព័ន្ធ runtime
├── images/               ទ្រព្យសកម្មទីផ្សារ/រូបថតអេក្រង់
├── _ideia/, _references/, _mono_repo/, _tasks/   ឯកសារព្រាង / ផែនការផ្ទៃក្នុង (មិនត្រូវបានចែកចាយ)
├── CLAUDE.md             ច្បាប់ឃ្លាំងកូដសម្រាប់ Claude Code
├── AGENTS.md             ឯកសារយោងស្ថាបត្យកម្មស៊ីជម្រៅសម្រាប់ភ្នាក់ងារ
├── package.json          v3.8.51, ឫស workspace
└── tsconfig.json         ឈ្មោះក្លែងកាត់ផ្លូវ + ជម្រើសចម្បងរបស់ compiler
```

---

## 3. `src/` — កម្មវិធី Next.js

```
src/
├── app/                  ទំព័រ App Router + ផ្លូវ API
├── lib/                  បណ្ណាល័យស្នូល (DB, ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណ, OAuth, ជំនាញ, អង្គចងចាំ, …)
├── domain/               ស្រទាប់ដែនសុទ្ធ (គោលការណ៍, ជម្រើសបម្រុង, ចំណាយ, ការចាក់សោ, …)
├── server/               ម៉ូឌុលសម្រាប់តែម៉ាស៊ីនមេ (authz, cors, auth)
├── shared/               ប្រភេទ, តម្លៃថេរ, សុពលកម្ម, កិច្ចសន្យា, ឧបករណ៍ប្រើប្រាស់ (មានសុវត្ថិភាពសម្រាប់ឆ្លងព្រំដែន)
├── mitm/                 កម្មវិធីជំនួយប្រូកស៊ី Man-in-the-middle សម្រាប់ការរួមបញ្ចូល CLI
├── models/               ទិន្នន័យមេតាម៉ូដែលមូលដ្ឋាន / ការកំណត់ឈ្មោះក្លែងក្លាយ
├── sse/                  កម្មវិធីដោះស្រាយ SSE ចាស់ៗដែលនៅតែស្ថិតក្រោម src/ (មិនមែន open-sse/)
├── store/                ឃ្លាំងស្ថានភាពខាងម៉ាស៊ីនភ្ញៀវ
├── middleware/           ឧបករណ៍ប្រើប្រាស់ middleware កម្រិតផ្លូវ (មិនមែន middleware សកលរបស់ Next.js)
├── scripts/              ស្គ្រីបក្នុងមែកធាងដែលអាចនាំចូលដោយកូដកម្មវិធី
├── types/                ប្រភេទ TS បរិបទ និងរួម
├── i18n/                 បណ្តុំភាសាតំបន់
├── instrumentation.ts    hook សម្រាប់ instrumentation របស់ Next.js
├── instrumentation-node.ts
└── proxy.ts              កម្មវិធីជំនួយចាប់ផ្ដើមប្រូកស៊ីកម្រិតកំពូល
```

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

App Router ផ្ដល់ទាំង UI ផ្ទាំងគ្រប់គ្រង និង HTTP API សាធារណៈ/សម្រាប់ការគ្រប់គ្រង។
**មិនមាន middleware សកលទេ** — ការស្ទាក់ចាប់ត្រូវបានធ្វើឡើងតាមផ្លូវនីមួយៗ។

ផ្នែកកម្រិតកំពូលក្រោម `src/app/`៖

| ផ្លូវ                                                                         | គោលបំណង                                          |
| ----------------------------------------------------------------------------- | ------------------------------------------------ |
| `api/`                                                                        | ផ្លូវ HTTP API ទាំងអស់ (សូមមើលការបែងចែកខាងក្រោម) |
| `a2a/`                                                                        | ចំណុចចុង JSON-RPC 2.0 របស់ A2A (`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` | ព្រំដែនកំហុស/ការផ្ទុករបស់ framework              |
| `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/         API សាធារណៈដែលឆបគ្នាជាមួយ OpenAI
├── v1beta/     ភាពឆបគ្នាតាមបែប Gemini
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — ការគ្រប់គ្រងសេវាកម្មដែលបានបង្កប់

ផ្លូវសម្រាប់ដំឡើង ចាប់ផ្ដើម បញ្ឈប់ និងត្រួតពិនិត្យ 9Router និង CLIProxyAPI។
ផ្លូវទាំងអស់ត្រូវបានចាត់ថ្នាក់ជា **LOCAL_ONLY** (សម្រាប់តែ loopback, វិធានតឹងរ៉ឹង #17) ពីព្រោះពួកវា
អាចហៅ `npm install` និងបង្កើតដំណើរការរង។

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             មុខងារជំនួយ getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install តាមរយៈ execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install កំណែថ្មីជាង
│   ├── rotate-key/route.ts POST — បង្កើត API key ថ្មី + ចាប់ផ្ដើមឡើងវិញ
│   ├── 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)។
ប្រូកស៊ីបញ្ច្រាសសម្រាប់ UI ដែលបានបង្កប់របស់ 9Router៖
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

ការពន្យល់ស៊ីជម្រៅ៖ `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — API សាធារណៈដែលឆបគ្នាជាមួយ OpenAI

```
v1/
├── accounts/[id]/                       ស្វែងរកគណនី
├── agents/tasks/[id]/, agents/tasks/    ចំណុចបញ្ចប់កិច្ចការបែប A2A
├── api/                                 មុខងារជំនួយ API ខាងក្នុងដែលបង្ហាញក្រោម v1/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/                            មុខងារជំនួយ route ដែលប្រើរួមគ្នា (គ្មាន URL សាធារណៈ)
├── images/{edits, generations}/         បង្កើត + កែសម្រួលរូបភាព
├── issues/                              ចំណុចបញ្ចប់ជំនួយសម្រាប់ការចាត់ថ្នាក់បញ្ហា
├── management/{proxies}/                route វិសាលភាពគ្រប់គ្រងនៅក្នុង v1
├── messages/{count_tokens}/             ភាពឆបគ្នានៃសារបែប Anthropic
├── models/                              បញ្ជីម៉ូដែល (`route.ts`, `catalog.ts`)
├── moderations/                         ការត្រួតពិនិត្យមាតិកា
├── music/                               បង្កើតតន្ត្រី
├── providers/[provider]/                ប្រតិបត្តិការតាម provider នីមួយៗ
├── quotas/{check}                       ការស្ទង់កូតា
├── registered-keys/                     ការគ្រប់គ្រង key ដែលបានចុះឈ្មោះ
├── rerank/                              ការរៀបចំណាត់ថ្នាក់ឡើងវិញ
├── responses/[...path]/                 OpenAI Responses API (ចាប់យកទាំងអស់)
├── search/                              ស្វែងរកលើបណ្ដាញ
├── videos/                              បង្កើតវីដេអូ
├── ws/                                  ស្ពាន WebSocket
└── route.ts                             កម្មវិធីដោះស្រាយលិបិក្រម
```

ឯកសារ route នីមួយៗអនុវត្តតាមលំនាំដូចគ្នា៖

```
Route → ការត្រួតពិនិត្យជាមុន CORS → ការផ្ទៀងផ្ទាត់ body ដោយ Zod → ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណជាជម្រើស
      → ការអនុវត្តគោលការណ៍ API key → ការផ្ទេរការដោះស្រាយទៅ handler (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` (ការកំណត់ពាក្យសម្ងាត់ឡើងវិញ / ការធ្វើ hashing)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `batches/`        | សេវា OpenAI Batches API (`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `catalog/`        | ការធ្វើសមកាលកម្មកាតាឡុក OpenRouter (`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `cloudAgent/`     | បញ្ជីឈ្មោះភ្នាក់ងារ cloud៖ `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/`        | ឧបករណ៍ជំនួយ UI/ការបង្ហាញ ដែលប្រើដោយការឆ្លើយតប API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `embeddings/`     | បញ្ជីឈ្មោះសេវា embedding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `env/`            | ការផ្ទុក Env + ការត្រួតពិនិត្យខាងក្នុង                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `evals/`          | បរិស្ថានដំណើរការ eval                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `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/`        | កម្មវិធីផ្ទុក plugin (`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` — ការកំណត់សម្រាប់ circuit breaker, cooldown និង lockout                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `runtime/`        | ការរកឃើញមុខងារពេលដំណើរការ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `services/`       | ក្របខណ្ឌសេវាបង្កប់៖ `ServiceSupervisor.ts` (កម្មវិធីគ្រប់គ្រងដំណើរការរងទូទៅ ដែលមានសោប្រតិបត្តិការ ring buffer និងកម្មវិធីត្រួតពិនិត្យស្ថានភាព), `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/`    | កាតាឡុក + កម្មវិធីបង្កើត Agent Skills៖ `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → សរសេរទៅ `skills/{id}/SKILL.md`), `openapiParser.ts` (ស្រង់ endpoint REST ពីលក្ខណៈបច្ចេកទេស OpenAPI), `cliRegistryParser.ts` (ស្រង់ពាក្យបញ្ជារង CLI ពី bin/cli-registry), `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` (សតិបណ្ដោះអាសន្ន write-behind)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `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/`      | លំហូរ OAuth របស់កម្មវិធីកែសម្រួល Zed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

ឯកសារថ្នាក់កំពូលនៅក្នុង `src/lib/`៖

- Barrel ចាស់ `localDb.ts` ត្រូវបានលុបចេញ — អ្នកប្រើប្រាស់ import ម៉ូឌុល `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/`

មូលដ្ឋានទិន្នន័យ SQLite បែប Singleton (`getDbInstance()` នៅក្នុង `core.ts`, ការកត់ត្រា journal តាម WAL)។
**កុំសរសេរ SQL ឆៅនៅក្នុង routes ឬ handlers ឱ្យសោះ** — ត្រូវប្រើម៉ូឌុលទាំងនេះ។

![ទិដ្ឋភាពទូទៅនៃ 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 (អាចប្រតិបត្តិម្ដងហើយម្ដងទៀតដោយគ្មានផលប៉ះពាល់បន្ថែម និងមានលក្ខណៈ 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 សម្រាប់ការស្វែងរក memory)។

### 3.3 `src/domain/` — ស្រទាប់ Domain

តក្កវិជ្ជាអាជីវកម្មសុទ្ធសាធ ដោយគ្មាន I/O។ ត្រូវបាន import ដោយ routes និង handlers។

| ឯកសារ                                      | គោលបំណង                                         |
| ------------------------------------------ | ----------------------------------------------- |
| `policyEngine.ts`                          | កម្មវិធីដោះស្រាយ policy ថ្នាក់កំពូល             |
| `fallbackPolicy.ts`                        | មែកធាងសម្រេចចិត្ត fallback                      |
| `costRules.ts`                             | ច្បាប់គណនាថ្លៃចំណាយ                             |
| `lockoutPolicy.ts`                         | ការសម្រេចចិត្ត lockout របស់ model               |
| `tagRouter.ts`                             | ការកំណត់ផ្លូវដោយផ្អែកលើ tag                     |
| `comboResolver.ts`                         | ការដោះស្រាយ combo ពី request → បញ្ជីគោលដៅ       |
| `connectionModelRules.ts`                  | តម្រង model សម្រាប់ connection នីមួយៗ           |
| `modelAvailability.ts`                     | ការត្រួតពិនិត្យភាពអាចប្រើបានរបស់ model          |
| `degradation.ts`                           | ការផ្លាស់ប្ដូរទៅកាន់ degraded-mode              |
| `providerExpiration.ts`                    | ការរកឃើញ account/key ដែលផុតកំណត់                |
| `quotaCache.ts`                            | ការសម្រេចចិត្តលើ quota ដែលបាន cache             |
| `responses.ts`, `omnirouteResponseMeta.ts` | ឧបករណ៍ជំនួយសម្រាប់ទម្រង់ response               |
| `configAudit.ts`                           | ការធ្វើសវនកម្មលើការផ្លាស់ប្ដូរ config           |
| `assessment/`                              | ការវាយតម្លៃ model (តាម RFC, បានអនុវត្តមួយផ្នែក) |
| `types.ts`                                 | ប្រភេទ domain ដែលប្រើរួមគ្នា                    |

### 3.4 `src/server/` — សម្រាប់ Server តែប៉ុណ្ណោះ

មិនអាច import ពី client components បានទេ។

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        ចាត់ថ្នាក់ routes ថាជា public ឬ management
│   ├── assertAuth.ts      ឧបករណ៍ជំនួយសម្រាប់ assertion
│   ├── context.ts         context នៃ authz សម្រាប់ request នីមួយៗ
│   ├── headers.ts
│   ├── pipeline.ts        pipeline របស់ authz
│   ├── policies/          policies ជាក់លាក់
│   └── types.ts
└── cors/origins.ts        បញ្ជីអនុញ្ញាត origin របស់ CORS
```

### 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/` — កិច្ចសន្យា API សាធារណៈដែលចេញផ្សាយទៅ npm។
- `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` ព្រមទាំង hooks/components នៃ dashboard នៅក្រោម `services/`, `network/`,
  `middleware/`, `schemas/`, `hooks/`, `components/`។

---

## 4. `open-sse/` — កន្លែងធ្វើការរបស់ម៉ាស៊ីនស្ទ្រីម

កន្លែងធ្វើការ npm ដាច់ដោយឡែក ដែលត្រូវបានចេញផ្សាយជា `@omniroute/open-sse`។ វាគ្រប់គ្រងការដំណើរការសំណើ ម៉ូឌុលប្រតិបត្តិ អ្នកបកប្រែ សេវាកម្ម ម៉ូឌុលបម្លែង និងម៉ាស៊ីនមេ MCP។

```
open-sse/
├── index.ts                ការនាំចេញសាធារណៈ
├── package.json            បញ្ជីកំណត់រចនាសម្ព័ន្ធកន្លែងធ្វើការ
├── tsconfig.json
├── types.d.ts
├── config/                 បញ្ជីអ្នកផ្តល់សេវា ទម្រង់បឋមកថា អត្តសញ្ញាណ …
├── handlers/               កម្មវិធីដោះស្រាយសំណើ (ការជជែក embedding អូឌីយ៉ូ រូបភាព …)
├── executors/              ម៉ូឌុលប្រតិបត្តិរបស់អ្នកផ្តល់សេវាចំនួន 156 (ថ្នាក់ប្រតិបត្តិ + មុខងារជំនួយតាមអ្នកផ្តល់សេវា)
├── translator/             ការបម្លែងទម្រង់ (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            ម៉ូឌុលបម្លែងស្ទ្រីម Responses API ↔ Chat Completions
├── services/               ម៉ូឌុលសេវាកម្មជាង 80 (បន្សំ fallback កូតា អត្តសញ្ញាណ …)
├── utils/                  មុខងារជំនួយស្ទ្រីម ម៉ាស៊ីនភ្ញៀវ TLS, AWS SigV4, proxy fetch, …
└── mcp-server/             ម៉ាស៊ីនមេ MCP (មធ្យោបាយបញ្ជូន 3 វិសាលភាព 33 ឧបករណ៍ 110)
```

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

| កម្មវិធីដោះស្រាយ        | គោលបំណង                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `chatCore.ts`           | ខ្សែដំណើរការជជែកចម្បង (ឃ្លាំងសម្ងាត់ កម្រិតអត្រា ការកំណត់ផ្លូវបន្សំ ការបញ្ជូនទៅម៉ូឌុលប្រតិបត្តិ) |
| `responsesHandler.ts`   | ចំណុចចូល OpenAI Responses API                                                                    |
| `embeddings.ts`         | Embedding                                                                                        |
| `imageGeneration.ts`    | ការបង្កើតរូបភាព                                                                                  |
| `audioSpeech.ts`        | ការបម្លែងអត្ថបទទៅជាសំឡេង                                                                         |
| `audioTranscription.ts` | ការបម្លែងសំឡេងទៅជាអត្ថបទ                                                                         |
| `videoGeneration.ts`    | ការបង្កើតវីដេអូ                                                                                  |
| `musicGeneration.ts`    | ការបង្កើតតន្ត្រី                                                                                 |
| `rerank.ts`             | ការរៀបចំណាត់ថ្នាក់ឡើងវិញ                                                                         |
| `moderations.ts`        | ការត្រួតពិនិត្យមាតិកា                                                                            |
| `search.ts`             | ការស្វែងរកលើបណ្ដាញ                                                                               |
| `sseParser.ts`          | ឧបករណ៍ញែកព្រឹត្តិការណ៍ SSE                                                                       |
| `usageExtractor.ts`     | ទាញយកចំនួន token ចេញពីស្ទ្រីមខាងដើម                                                              |
| `responseSanitizer.ts`  | ដកទិន្នន័យរំខានជាក់លាក់របស់អ្នកផ្តល់សេវាចេញ                                                      |
| `responseTranslator.ts` | ស្រទាប់ភ្ជាប់រវាងការឆ្លើយតបរបស់អ្នកផ្តល់សេវា និងស្រទាប់អ្នកបកប្រែ                                |

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

ម៉ូឌុលប្រតិបត្តិកម្រិតកំពូលចំនួន 156 (`*.ts` ដក `base.ts`, `index.ts` និងតេស្តចេញ — ចំនួននេះត្រូវបានវាស់ដោយ
`npm run check:docs-counts`)។ ថ្នាក់ប្រតិបត្តិនីមួយៗពង្រីកពី `BaseExecutor` (`base.ts`)
ដោយផ្ទាល់ ឬតាមរយៈ `DefaultExecutor` ឬម៉ូឌុលប្រតិបត្តិផ្សេងទៀត។ ម៉ូឌុលដែលនៅសល់គឺជា
មុខងារជំនួយតាមអ្នកផ្តល់សេវា (ស្គីមាឧបករណ៍ អាដាប់ទ័រ fetch/TTS និងកម្មវិធីដោះស្រាយលក្ខណៈពិសេស)។ ម៉ូឌុលប្រតិបត្តិរួមមាន៖

`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`,
`chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`,
`muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`,
`pollinations`, `qoder`, `vertex`, `devin-desktop` ព្រមទាំង `claudeIdentity.ts`
(មុខងារជំនួយអត្តសញ្ញាណរួម) និង `index.ts` (បញ្ជីចុះឈ្មោះ)។

> ចំណាំ៖ អ្នកផ្តល់សេវាដែលមិនបានរាយនៅទីនេះ ត្រូវបានបម្រើដោយ `default.ts` តាមរយៈម៉ូឌុលប្រតិបត្តិទូទៅ
> ដែលឆបគ្នាជាមួយ OpenAI។ កាតាឡុកអ្នកផ្តល់សេវាពេញលេញ (អ្នកផ្តល់សេវា 375) ស្ថិតនៅក្នុង
> `src/shared/constants/providers.ts`។

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

ការបកប្រែតាមរចនាសម្ព័ន្ធមជ្ឈមណ្ឌល និងកាំ (OpenAI ជាមជ្ឈមណ្ឌល)។

- **អ្នកបកប្រែសំណើ 9** (`translator/request/`)៖
  `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`,
  `gemini-to-openai`, `openai-responses`, `openai-to-claude`,
  `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`។
- **អ្នកបកប្រែការឆ្លើយតប 9** (`translator/response/`)៖
  `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`,
  `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`,
  `openai-to-claude`។
- **មុខងារជំនួយ 9** (`translator/helpers/`)៖
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper` ព្រមទាំង
  តេស្តមុខងារជំនួយ។
- **មុខងារជំនួយរូបភាព** (`translator/image/sizeMapper.ts`)។
- កម្រិតកំពូល៖ `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`។

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

- `responsesTransformer.ts` — កម្មវិធីបម្លែង Responses API ↔ Chat Completions ដែលផ្អែកលើ `TransformStream`
  (ប្រើដោយផ្លូវ `responses/` ដែលទទួលសំណើទាំងអស់ដែលមិនត្រូវនឹងផ្លូវផ្សេង)។

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

ផ្នែកសំខាន់ៗ (បញ្ជីពេញលេញនៅក្រោម `open-sse/services/`)៖

| កង្វល់                    | ឯកសារ                                                                                                                                                                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ការកំណត់ផ្លូវ Combo       | `combo.ts` (យុទ្ធសាស្ត្រ 20), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`                                                                                                                                  |
| ម៉ាស៊ីន Auto Combo        | `autoCombo/` — `engine.ts`, `scoring.ts`, `taskFitness.ts`, `virtualFactory.ts`, `modePacks.ts`, `autoPrefix.ts`, `persistence.ts`, `providerDiversity.ts`, `providerRegistryAccessor.ts`, `routerStrategy.ts`, `selfHealing.ts`, `index.ts`             |
| ភាពធន់នឹងបញ្ហា            | `accountFallback.ts` (រយៈពេលរង់ចាំ + ការចាក់សោ), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                                   |
| កូតា                      | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| ឃ្លាំងសម្ងាត់             | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| ភាពឆ្លាតវៃនៃការកំណត់ផ្លូវ | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| ការគ្រប់គ្រងម៉ូដែល        | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| ការបង្ហាប់                | `compression/` — ការតភ្ជាប់ម៉ាស៊ីនបង្ហាប់ពេញលេញ                                                                                                                                                                                                          |
| ថូខឹន + សម័យ              | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| កម្រិត / ម៉ានីហ្វេស       | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / បណ្តាញ               | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| បាច់                      | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| ការប្រើប្រាស់             | `usage.ts`                                                                                                                                                                                                                                               |

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

- **ឧបករណ៍មិនស្ទួនចំនួន 110** ត្រូវបានតភ្ជាប់ក្នុង `server.ts` (ឧបករណ៍ស្តង់ដារចំនួន 45 ក្នុង `schemas/tools.ts` +
  ម៉ូឌុលអង្គចងចាំ ជំនាញ GitHub-skills អាងធនធាន ហ្គេមមីហ្វិកាស្យុង កម្មវិធីជំនួយ Notion, Obsidian,
  local-corpus និងការបង្ហាប់ — ចំនួនសហភាពត្រូវបានរាប់ដោយ `countUniqueMcpTools`)។
- **មធ្យោបាយដឹកជញ្ជូន 3**៖ stdio, HTTP Streamable, SSE។
- **វិសាលភាពចំនួន 33** ត្រូវបានអនុវត្តនៅពេលដំណើរការ — បញ្ជីមូលដ្ឋាននៅក្នុង `src/shared/constants/mcpScopes.ts` ហើយសំណុំពេញលេញគឺជាសហភាពនៃវិសាលភាពដែលបានប្រកាសដោយម៉ូឌុលឧបករណ៍នីមួយៗ។
- តារាងសវនកម្ម៖ `mcp_tool_audit` (បញ្ចូលទិន្នន័យដោយ `audit.ts`)។
- ឯកសារ៖ `server.ts`, `index.ts`, `httpTransport.ts`, `audit.ts`, `scopeEnforcement.ts`,
  `runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`,
  `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`,
  ព្រមទាំងការធ្វើតេស្តនៅក្រោម `__tests__/`។
- សូមមើល [MCP-SERVER.md](../frameworks/MCP-SERVER.md) សម្រាប់កាតាឡុកឧបករណ៍ពេញលេញ។

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

បញ្ជីចុះឈ្មោះអ្នកផ្តល់សេវា (`providerRegistry.ts`, `providerModels.ts`,
`providerHeaderProfiles.ts`), បញ្ជីចុះឈ្មោះម៉ូដែលតាមទម្រង់នីមួយៗ (`audioRegistry.ts`,
`embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`,
`musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`),
ឧបករណ៍ជំនួយអត្តសញ្ញាណ (`codexIdentity.ts`, `codexInstructions.ts`,
`anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`,
`cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`),
ឧបករណ៍ជំនួយព័ត៌មានសម្ងាត់ (`credentialLoader.ts`, `codexClient.ts`) និងអាដាប់ទ័រ
ក្លោដ (`azureAi.ts`, `bedrock.ts`, `datarobot.ts`, `glmProvider.ts`,
`maritalk.ts`, `oci.ts`, `petals.ts`, `runway.ts`, `sap.ts`, `watsonx.ts`,
`ollamaModels.ts`, `errorConfig.ts`, `constants.ts`, `registryUtils.ts`)។

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

ព្រីមីទីវសម្រាប់ស្ទ្រីម និងមុខងារជំនួយរបស់អ្នកផ្តល់សេវា៖ `stream.ts`, `streamHandler.ts`,
`streamHelpers.ts`, `streamPayloadCollector.ts`, `streamReadiness.ts`,
`sseHeartbeat.ts`, `proxyFetch.ts`, `proxyDispatcher.ts`, `tlsClient.ts`,
`networkProxy.ts`, `awsSigV4.ts`, `cacheControlPolicy.ts`,
`cursorChecksum.ts`, `cursorAgentProtobuf.ts`, `cursorVersionDetector.ts`,
`comfyuiClient.ts`, `kieTask.ts`, `bypassHandler.ts`, `aiSdkCompat.ts`,
`thinkTagParser.ts`, `urlSanitize.ts`, `usageTracking.ts`, `requestLogger.ts`,
`progressTracker.ts`, `cors.ts`, `error.ts`, `logger.ts`, `sleep.ts`,
`ollamaTransform.ts`.

---

## 5. `electron/` — កម្មវិធីស្រោបសម្រាប់ Desktop

```
electron/
├── main.js                  ដំណើរការមេរបស់ Electron
├── preload.js               ស្ពាន Preload (បានបើក contextIsolation)
├── types.d.ts
├── package.json             ការកំណត់រចនាសម្ព័ន្ធ electron-builder, កំណែ 3.8.51
├── README.md
├── assets/                  ធនធានសម្រាប់ Build (រូបតំណាង, entitlements, …)
├── node_modules/            node_modules ដាច់ដោយឡែក (better-sqlite3, electron-updater)
└── dist-electron/           លទ្ធផល Build (មិនបាន commit)
```

មានស្គ្រីប npm ចំនួនប្រាំនៅ root របស់ workspace៖ `electron:dev`, `electron:build`,
`electron:build:{win,mac,linux}`, `electron:smoke:packaged`។ ការធ្វើបច្ចុប្បន្នភាពដោយស្វ័យប្រវត្តិធ្វើឡើងតាមរយៈ
`electron-updater` ដែលចង្អុលទៅកាន់ feed នៃ release របស់ GitHub។

---

## 6. `bin/` — CLI

```
bin/
├── omniroute.mjs           ចំណុចចូល CLI មេ (Node ESM)
├── reset-password.mjs      កំណត់ពាក្យសម្ងាត់គ្រប់គ្រងឡើងវិញពី CLI
├── mcp-server.mjs          កម្មវិធីបើកដំណើរការ MCP server (stdio)
├── nodeRuntimeSupport.mjs  ឧបករណ៍ត្រួតពិនិត្យកំណែ Node
└── cli/
    ├── program.mjs         កម្មវិធីបង្កើត Commander program
    ├── runtime.mjs         helper withRuntime (server-first/db-fallback)
    ├── output.mjs          កម្មវិធីកំណត់ទ្រង់ទ្រាយលទ្ធផល (json/jsonl/table/csv)
    ├── i18n.mjs            helper t() ជាមួយ locales
    ├── api.mjs             helper សម្រាប់ API fetch
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    ការចុះឈ្មោះ command
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (មួយឯកសារក្នុងមួយ command/group)
```

Binary ចំនួនពីរត្រូវបានបង្ហាញនៅក្នុង `package.json` → `bin`៖

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

---

## 7. `tests/`

| ថត                                                   | ប្រភេទ                                                                                                       |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `tests/unit/`                                        | ការធ្វើតេស្ត Unit តាមរយៈកម្មវិធីដំណើរការតេស្តដើមរបស់ Node (1821 ឯកសារ រួមទាំងថតរង `api/`, `auth/`, `authz/`) |
| `tests/integration/`                                 | ការធ្វើតេស្តឆ្លងម៉ូឌុល + ស្ថានភាព DB                                                                         |
| `tests/e2e/`                                         | ការធ្វើតេស្ត UI ដោយ Playwright                                                                               |
| `tests/e2e/protocol-clients.test.ts`                 | ការធ្វើតេស្ត e2e សម្រាប់ពិធីការ MCP/A2A                                                                      |
| `tests/translator/`                                  | ការធ្វើតេស្តជាក់លាក់សម្រាប់កម្មវិធីបកប្រែ                                                                    |
| `tests/security/`                                    | ការធ្វើតេស្តបញ្ហាថយក្រោយផ្នែកសុវត្ថិភាព                                                                      |
| `tests/load/`                                        | ការធ្វើតេស្តបន្ទុក / សម្ពាធ                                                                                  |
| `tests/golden-set/`                                  | លទ្ធផលយោងសម្រាប់បញ្ហាថយក្រោយរបស់កម្មវិធីបកប្រែ                                                               |
| `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | ការគាំទ្រ                                                                                                    |

Command ដែលប្រើជាទូទៅ៖

| Command                                                  | អ្វីដែលវាដំណើរការ                                                                 |
| -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `npm run test:unit`                                      | រាល់ `tests/unit/*.test.ts` តាមរយៈកម្មវិធីដំណើរការតេស្តរបស់ Node (concurrency 10) |
| `npm run test:vitest`                                    | សំណុំតេស្ត Vitest (MCP, autoCombo, cache)                                         |
| `npm run test:e2e`                                       | សំណុំតេស្ត UI របស់ Playwright                                                     |
| `npm run test:protocols:e2e`                             | ការធ្វើតេស្ត e2e សម្រាប់ពិធីការ MCP + A2A                                         |
| `npm run test:coverage`                                  | កម្រិត Coverage (≥60% នៃ lines/statements/functions/branches)                     |
| `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 ទៅជា របស់ខ្លួន / ទទួលមរតក /
  មិនស្គាល់ ដោយប្រៀបធៀបនឹង PR យោង ឬបញ្ហា base-red) និង `audit-worktree.sh`
  (ឯកសារដែលបានកែប្រែមិនទាន់រក្សាទុក, ផ្នែកដែលបានការពារ, assert ដែលបានលុប, ចំនួនការទប់ស្កាត់, tsconfig បណ្ដោះអាសន្ន
  ដែលនៅសេសសល់, ក្បាល PR ធៀបនឹង HEAD មូលដ្ឋាន — មុនពេល PR របស់ worker ត្រូវបានទទួលយក)។
- **`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 preflight
     ការផ្ទៀងផ្ទាត់ Zod (chatCompletionsSchema នៅក្នុង shared/validation/schemas.ts)
     ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណ (extractApiKey + isValidApiKey ឬ requireManagementAuth)
     ម៉ាស៊ីនគោលការណ៍ (src/server/authz/pipeline.ts)
     របាំងការពារ (ឧបករណ៍បិទបាំង PII, ការបញ្ចូល prompt, ស្ពាន vision)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     ការត្រួតពិនិត្យឃ្លាំងសម្ងាត់ (ឃ្លាំងសម្ងាត់ semantic + read)
     ដែនកំណត់អត្រា (rateLimitManager, accountSemaphore)
     ការកំណត់ផ្លូវ combo (ប្រសិនបើម៉ូដែលត្រូវបានដោះស្រាយទៅជា combo)
       comboResolver → រង្វិលជុំតាមគោលដៅនីមួយៗ → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       ទាញយកពី upstream → ព្យាយាមម្ដងទៀត/ពន្យារពេលថយក្រោយតាមរយៈ accountFallback
     translateResponse() (open-sse/translator/response/*)
     ស្ទ្រីម SSE ឬការឆ្លើយតប JSON
     ប្រសិនបើជា Responses API៖ TransformStream តាមរយៈ open-sse/transformer/responsesTransformer.ts
  → សវនកម្មអនុលោមភាព (src/lib/compliance/)
  → ការឆ្លើយតបទៅម៉ាស៊ីនភ្ញៀវ
```

### ស្ថានភាព runtime សម្រាប់ភាពធន់ (យន្តការបី)

| យន្តការ                         | វិសាលភាព                            | ទីតាំង                                                                                                            |
| ------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| ឧបករណ៍ផ្ដាច់សៀគ្វីអ្នកផ្ដល់សេវា | អ្នកផ្ដល់សេវាទាំងមូល                | `src/shared/utils/circuitBreaker.ts`, រក្សាទុកក្នុង `domain_circuit_breakers`                                     |
| រយៈពេលរង់ចាំនៃការតភ្ជាប់        | គណនី/សោមួយ                          | `markAccountUnavailable()` ក្នុង `src/sse/services/auth.ts`; ប្រើប្រាស់ដោយ `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. បន្ថែម executor មួយក្នុង `open-sse/executors/` ប្រសិនបើត្រូវការតក្កវិជ្ជាផ្ទាល់ខ្លួន
   (ពង្រីក `BaseExecutor`)។
3. បន្ថែម translator មួយក្នុង `open-sse/translator/` ប្រសិនបើវាមិនប្រើទម្រង់ OpenAI។
4. ប្រសិនបើផ្អែកលើ OAuth សូមបន្ថែមការកំណត់រចនាសម្ព័ន្ធក្រោម `src/lib/oauth/providers/` និង
   `src/lib/oauth/services/`។
5. ចុះឈ្មោះម៉ូដែលក្នុង `open-sse/config/providerRegistry.ts` (ឬ registry សម្រាប់ទម្រង់ជាក់លាក់
   ក្រោម `open-sse/config/`)។
6. សរសេរការធ្វើតេស្តក្រោម `tests/unit/`។

### បន្ថែម API route ថ្មី

1. បង្កើត `src/app/api/your-route/route.ts`។
2. អនុវត្តតាមលំនាំ៖ CORS → ការផ្ទៀងផ្ទាត់ body ដោយ Zod → ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណ → ការប្រគល់ការងារទៅ handler។
3. ប្រសិនបើមានទម្រង់ request ថ្មី៖ បន្ថែម Zod schema ក្នុង `src/shared/validation/schemas.ts`។
4. ប្រសិនបើសម្រាប់តែការគ្រប់គ្រង៖ បន្ថែម path ទៅ `src/shared/constants/publicApiRoutes.ts`
   (denylist សម្រាប់ផ្ទៃ API សាធារណៈ)។
5. បន្ថែមការធ្វើតេស្តក្រោម `tests/unit/`។
6. ធ្វើបច្ចុប្បន្នភាព `docs/reference/API_REFERENCE.md` និង `docs/openapi.yaml`។

### បន្ថែមម៉ូឌុល DB ថ្មី

1. បង្កើត `src/lib/db/yourModule.ts` ហើយ import `getDbInstance()` ពី `./core.ts`។
2. Export អនុគមន៍ CRUD សម្រាប់ដែនរបស់អ្នក។
3. ប្រសិនបើមានតារាងថ្មី៖ បន្ថែម migration មួយក្រោម `src/lib/db/migrations/` ដោយដាក់លេខ
   តាមលំដាប់ អាចដំណើរការម្តងហើយម្តងទៀតដោយគ្មានផលប៉ះពាល់ និងស្ថិតក្នុង transaction។
4. អ្នក import ត្រូវប្រើ direct imports ពី `@/lib/db/yourModule` (គ្មាន barrel — ស្រទាប់ re-export ចាស់ `localDb.ts` ត្រូវបានដកចេញហើយ)។
5. បន្ថែមការធ្វើតេស្តក្រោម `tests/unit/`។

### បន្ថែមឧបករណ៍ MCP ថ្មី

1. បន្ថែមនិយមន័យឧបករណ៍ក្រោម `open-sse/mcp-server/tools/` (ឬពង្រីក
   `open-sse/mcp-server/schemas/tools.ts`)។
2. កំណត់ scope ដែលសមស្របក្នុង `src/shared/constants/mcpScopes.ts`។
3. ចុះឈ្មោះឧបករណ៍ក្នុង `open-sse/mcp-server/server.ts`។
4. បន្ថែមការធ្វើតេស្តក្រោម `open-sse/mcp-server/__tests__/`។
5. ធ្វើបច្ចុប្បន្នភាព [MCP-SERVER.md](../frameworks/MCP-SERVER.md)។

### បន្ថែមជំនាញ A2A ថ្មី

សូមមើល [A2A-SERVER.md § ការបន្ថែមជំនាញថ្មី](../frameworks/A2A-SERVER.md)។ ជំនាញស្ថិតនៅក្នុង
`src/lib/a2a/skills/` ហើយត្រូវបានចុះឈ្មោះតាមរយៈកម្មវិធីគ្រប់គ្រងកិច្ចការ A2A។

---

## 11. អនុសញ្ញា

- **រចនាប័ទ្មកូដ**៖ ចូលបន្ទាត់ដោយ 2 space, ប្រើ double quotes, ទទឹង 100 តួអក្សរ, ប្រើ semicolons,
  និង `es5` trailing commas — ត្រូវបានអនុវត្តដោយ Prettier តាមរយៈ `lint-staged`។
- **Imports**៖ ខាងក្រៅ → ខាងក្នុង (`@/`, `@omniroute/open-sse`) → relative។
- **ការដាក់ឈ្មោះ**៖ ឯកសារប្រើ `camelCase` ឬ `kebab-case`, components ប្រើ `PascalCase`,
  constants ប្រើ `UPPER_SNAKE`។
- **ESLint**៖ `no-eval`, `no-implied-eval`, `no-new-func` = `error` គ្រប់ទីកន្លែង;
  `no-explicit-any` = `warn` ក្នុង `open-sse/` និង `tests/`, ជា error នៅកន្លែងផ្សេង។
- **TypeScript**៖ `strict: false` (ជំហរដើម្បីគាំទ្រប្រព័ន្ធចាស់)។ គួរប្រើ types ដែលបញ្ជាក់ច្បាស់លាស់ជំនួស
  inference សម្រាប់ព្រំដែនឆ្លងម៉ូឌុល។
- **មូលដ្ឋានទិន្នន័យ**៖ មិនត្រូវសរសេរ SQL ដើមក្នុង routes ឬ handlers ឡើយ — ត្រូវឆ្លងកាត់
  ម៉ូឌុល `src/lib/db/` ជានិច្ច។ មិនត្រូវ barrel-import ឡើយ — ប្រើម៉ូឌុល `src/lib/db/*` ជាក់លាក់ដោយផ្ទាល់។
- **ការកំណត់ type សម្រាប់ DB-entity (#3512)**៖ អនុគមន៍ដែលសរសេរ ឬអានទម្រង់ row
  របស់តារាង DB គួរទទួល/ត្រឡប់ TS interface ដែលមានឈ្មោះ និងឆ្លុះបញ្ចាំង columns
  របស់តារាងនោះក្នុងសមាមាត្រ 1:1 មិនមែន `any` ឬ inline anonymous type នៅ call site ទេ។ ដាក់
  interface នៅក្បែរអនុគមន៍ (ឧ. `export interface UsageEntry` ក្នុង
  `src/lib/usage/usageHistory.ts` នៅខាងលើ `saveRequestUsage`) រក្សា fields នីមួយៗឱ្យជា
  optional/nullable នៅពេល writers ផ្សេងៗបញ្ចូលទិន្នន័យទៅក្នុង row
  ជាបន្តបន្ទាប់ ហើយគួរប្រើ `unknown` ជំនួស `any` សម្រាប់ field ដែលទម្រង់របស់វា
  ប្រែប្រួលតាម callers (ត្រូវកត់ត្រានៅលើ field ឧ. `UsageEntry.tokens`
  ទទួលយកទាំង usage ដែលមានទម្រង់ដើមរបស់ provider និងទម្រង់ដែលបានធ្វើឱ្យស្តង់ដារ)។ នៅពេលចំនួន
  `any` របស់ឯកសារមួយថយដល់សូន្យតាមវិធីនេះ សូមបន្ថែមវាទៅក្នុង allowlist
  `check:any-budget:t11` (`scripts/check/check-t11-any-budget.mjs`,
  `maxAny: 0`) ដើម្បីកុំឱ្យវាត្រឡប់ថយក្រោយ។ នេះជាអនុសញ្ញាសម្រាប់ផ្នែកដំបូង — ការសម្អាត
  "គ្មាន anonymous `any`" ទូលំទូលាយជាងនេះ ត្រូវបានអនុវត្តជាបន្តបន្ទាប់លើផ្នែកដែលនៅសល់នៃ
  codebase។
- **កំហុស**៖ ប្រើ try/catch ជាមួយ error types ជាក់លាក់ ហើយកត់ត្រា log ជាមួយ pino context។ មិនត្រូវ
  លាក់កំហុសដោយស្ងៀមស្ងាត់ក្នុង SSE streams ឡើយ; ប្រើ abort signals សម្រាប់ការសម្អាត។
- **សុវត្ថិភាព**៖ មិនត្រូវប្រើ `eval()` / `new Function()` / implied eval ឡើយ។ ផ្ទៀងផ្ទាត់
  inputs ទាំងអស់ដោយ Zod។ អ៊ិនគ្រីប credentials ពេលរក្សាទុក (AES-256-GCM)។ រក្សា
  denylist `src/shared/constants/upstreamHeaders.ts` ឱ្យស្របគ្នាជាមួយស្រទាប់
  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/`។ មិនត្រូវ commit ដោយផ្ទាល់ទៅ `main` ឡើយ។
- **Husky**៖ pre-commit ដំណើរការ `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11`; pre-push ដំណើរការ `check:any-budget:t11` + `check:tracked-artifacts` (ការត្រួតពិនិត្យរហ័ស; មិនរាប់បញ្ចូល `test:unit`)។

---

## 12. ច្បាប់តឹងរ៉ឹង (ពី CLAUDE.md)

1. កុំ commit ព័ត៌មានសម្ងាត់ ឬព័ត៌មានបញ្ជាក់អត្តសញ្ញាណជាដាច់ខាត។
2. កុំធ្វើ barrel-import ជាដាច់ខាត — ត្រូវប្រើម៉ូឌុល `src/lib/db/*` ជាក់លាក់ដោយផ្ទាល់។
3. កុំប្រើ `eval()` / `new Function()` / eval ដោយប្រយោលជាដាច់ខាត។
4. កុំ commit ដោយផ្ទាល់ទៅ `main` ជាដាច់ខាត។
5. កុំសរសេរ SQL ដើមនៅក្នុង routes ជាដាច់ខាត — ត្រូវឆ្លងកាត់ម៉ូឌុល `src/lib/db/` ជានិច្ច។
6. កុំមិនអើពើចំពោះកំហុសដោយស្ងៀមស្ងាត់នៅក្នុង SSE streams ជាដាច់ខាត។
7. ត្រូវផ្ទៀងផ្ទាត់ inputs ជាមួយ Zod schemas ជានិច្ច។
8. ត្រូវបញ្ចូល tests ជានិច្ច នៅពេលផ្លាស់ប្ដូរ production code។
9. Coverage ត្រូវរក្សាឱ្យនៅ ≥ 60% (statements, lines, functions, branches)។

---

## 13. សូមមើលផងដែរ

- [ARCHITECTURE.md](./ARCHITECTURE.md) — ស្ថាបត្យកម្មកម្រិតខ្ពស់ និងការទទួលខុសត្រូវរបស់ម៉ូឌុល។
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — ឯកសារយោង public + management 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 ពេញលេញ + transports។
- [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) — ច្បាប់ repo សម្រាប់ Claude Code (ប្រភពពិតប្រាកដ
  សម្រាប់អនុសញ្ញាជាច្រើនខាងលើ)។
- [AGENTS.md](../../AGENTS.md) — ឯកសារយោងស្ថាបត្យកម្មកាន់តែស៊ីជម្រៅ ដែលត្រូវបានប្រើដោយ agents។