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

OmniRoute Codebase Documentation (ខ្មែរ)

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

---

កំណែ៖ v3.8.51 បានធ្វើបច្ចុប្បន្នភាពចុងក្រោយ៖ 2026-06-28 អ្នកអានគោលដៅ៖ វិស្វករដែលរួមចំណែកដល់ OmniRoute ឬបង្កើតការរួមបញ្ចូលនៅលើវា។

សម្រាប់ដ្យាក្រាមស្ថាបត្យកម្មកម្រិតខ្ពស់ និងហេតុផលនៅពីក្រោយប្រព័ន្ធរងនីមួយៗ សូមអាន ARCHITECTURE.md។ សម្រាប់ការសិក្សាស៊ីជម្រៅលើប្រព័ន្ធរងនីមួយៗ (Auto Combo, ម៉ាស៊ីនមេ MCP, ម៉ាស៊ីនមេ A2A, Skills, Memory, Cloud Agents, Resilience, Compression ជាដើម) សូមមើលឯកសារដែលផ្តោតជាក់លាក់លើប្រធានបទទាំងនោះនៅក្នុងថត docs/ នេះ។

ឯកសារនេះពិពណ៌នាអំពី អ្វីដែលមាននៅក្នុងឃ្លាំងកូដនាពេលបច្ចុប្បន្ន ដើម្បីឱ្យវិស្វករថ្មី អាចស្វែងយល់ពីរចនាសម្ព័ន្ធថត យល់ពីការរៀបចំជាស្រទាប់នៅពេលដំណើរការ និងដឹងពីកន្លែងដែលត្រូវបន្ថែមកូដ ដោយមិនចាំបាច់បង្កើតម៉ូឌុលថ្មី។

---

1. ជង់បច្ចេកវិទ្យា

ផ្នែកពាក់ព័ន្ធ	ជម្រើស
ក្របខណ្ឌវេប	Next.js 16 (App Router, លទ្ធផល 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។
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 ឱ្យសោះ — ត្រូវប្រើម៉ូឌុលទាំងនេះ។

ប្រភព៖ 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/ — Workspace សម្រាប់ម៉ាស៊ីន Streaming

Workspace npm ដាច់ដោយឡែកដែលត្រូវបានចេញផ្សាយជា @omniroute/open-sse។ វាគ្រប់គ្រងការដំណើរការ request, executors, translators, services, transformer និង MCP server។

open-sse/
├── index.ts                ការនាំចេញសាធារណៈ
├── package.json            Manifest របស់ workspace
├── tsconfig.json
├── types.d.ts
├── config/                 បញ្ជីចុះឈ្មោះ provider, profile របស់ header, identity, …
├── handlers/               Handler សម្រាប់ request (chat, embeddings, audio, image, …)
├── executors/              HTTP executor ជាក់លាក់តាម provider ចំនួន 108
├── translator/             ការបម្លែង format (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformer សម្រាប់ stream នៃ Responses API ↔ Chat Completions
├── services/               ម៉ូឌុល service ជាង 80 (combos, fallback, quotas, identity, …)
├── utils/                  ជំនួយការ streaming, TLS client, AWS SigV4, proxy fetch, …
└── mcp-server/             MCP server (transport 3, scope 33, tool 110)

4.1 open-sse/handlers/

Handler	គោលបំណង
chatCore.ts	Pipeline សំខាន់សម្រាប់ chat (cache, rate limit, combo routing, ការបញ្ជូនទៅ executor)
responsesHandler.ts	ចំណុចចូលរបស់ OpenAI Responses API
embeddings.ts	Embeddings
imageGeneration.ts	ការបង្កើតរូបភាព
audioSpeech.ts	ការបម្លែងអត្ថបទទៅជាសំឡេង
audioTranscription.ts	ការបម្លែងសំឡេងទៅជាអត្ថបទ
videoGeneration.ts	ការបង្កើតវីដេអូ
musicGeneration.ts	ការបង្កើតតន្ត្រី
rerank.ts	ការរៀបចំណាត់ថ្នាក់ឡើងវិញ
moderations.ts	ការត្រួតពិនិត្យមាតិកា
search.ts	ការស្វែងរកលើបណ្ដាញ
sseParser.ts	Parser សម្រាប់ event របស់ SSE
usageExtractor.ts	ទាញយកចំនួន token ពី stream ខាង upstream
responseSanitizer.ts	ដក noise ដែលជាក់លាក់ចំពោះ provider ចេញ
responseTranslator.ts	ស្រទាប់តភ្ជាប់រវាង response របស់ provider និងស្រទាប់ translator

4.2 open-sse/executors/

មាន executor របស់ provider ចំនួន 108 ដែលនីមួយៗ extend ពី BaseExecutor (base.ts)៖

antigravity, azure-openai, blackbox-web, cliproxyapi, chatgpt-web-codex, cloudflare-ai, codex, commandCode, cursor, default, devin-cli, muse-spark-web, nlpcloud, opencode, perplexity-web, petals, pollinations, qoder, vertex, devin-desktop រួមទាំង claudeIdentity.ts (ជំនួយការ identity ដែលប្រើរួមគ្នា) និង index.ts (បញ្ជីចុះឈ្មោះ)។

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

4.3 open-sse/translator/

ការបកប្រែបែប hub-and-spoke (OpenAI គឺជា hub)។

• Translator សម្រាប់ request ចំនួន 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។
• Translator សម្រាប់ response ចំនួន 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 ព្រមទាំង test សម្រាប់ជំនួយការ។
• ជំនួយការសម្រាប់រូបភាព (translator/image/sizeMapper.ts)។
• កម្រិតកំពូល៖ bootstrap.ts, formats.ts, registry.ts, index.ts។

4.4 open-sse/transformer/

• responsesTransformer.ts — កម្មវិធីបម្លែង Responses API ↔ Chat Completions ដែលផ្អែកលើ TransformStream (ប្រើដោយ catch-all របស់ route responses/)។

4.5 open-sse/services/

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

ចំណុចពាក់ព័ន្ធ	ឯកសារ
ការកំណត់ផ្លូវ Combo	combo.ts (យុទ្ធសាស្ត្រ 19), 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, 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
កម្រិត / manifest	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 ក្រុមធនធាន gamification កម្មវិធីបន្ថែម 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 សម្រាប់កាតាឡុកឧបករណ៍ពេញលេញ។

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។
• scripts/check/ — check-cycles.mjs, check-docs-sync.mjs, check-docs-counts-sync.mjs, check-env-doc-sync.mjs, check-deprecated-versions.mjs, check-route-validation.mjs, check-t11-any-budget.mjs, check-pr-test-policy.mjs, check-supported-node-runtime.ts, test-report-summary.mjs។
• scripts/docs/ — generate-docs-index.mjs, gen-provider-reference.ts។
• scripts/i18n/ — generate-multilang.mjs, run-visual-qa.mjs, generate-qa-checklist.mjs, apply-priority-overrides.mjs, validate_translation.py, check_translations.py, i18n_autotranslate.py, untranslatable-keys.json។
• scripts/ad-hoc/ — cursor-tap.cjs, sync-cursor-models.mjs, migrate-env.mjs, dbsetup.js។

---

9. បំពង់ដំណើរការសំណើ (សេចក្ដីសង្ខេប)

ប្រភព៖ diagrams/request-pipeline.mmd

សំណើរបស់ម៉ាស៊ីនភ្ញៀវ
  → /v1/chat/completions (route.ts)
     ការត្រួតពិនិត្យ CORS 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 និងផ្នែកពិសេសនៅក្នុង 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។

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

សូមមើល 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 — ស្ថាបត្យកម្មកម្រិតខ្ពស់ និងការទទួលខុសត្រូវរបស់ម៉ូឌុល។
• API_REFERENCE.md — ឯកសារយោង public + management API។
• FEATURES.md — តារាងលក្ខណៈពិសេស និងចំណុចសំខាន់ៗតាមកំណែ។
• RESILIENCE_GUIDE.md — ការពន្យល់ស៊ីជម្រៅអំពី circuit breaker, cooldown និង lockout។
• AUTO-COMBO.md — ការដាក់ពិន្ទុ និងយុទ្ធសាស្ត្រ Auto Combo។
• MCP-SERVER.md — កាតាឡុកឧបករណ៍ MCP ពេញលេញ + transports។
• A2A-SERVER.md — ជំនាញ និងការស្វែងរករបស់ពិធីការ A2A។
• COMPRESSION_GUIDE.md — ការបង្ហាប់ RTK + Caveman។
• CLI-TOOLS.md — ការរួមបញ្ចូល CLI។
• ELECTRON_GUIDE.md (ប្រសិនបើមាន), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — គោលដៅដាក់ឱ្យដំណើរការ។
• TROUBLESHOOTING.md — បញ្ហាប្រតិបត្តិការទូទៅ។
• CONTRIBUTING.md — លំហូរការងាររបស់អ្នករួមចំណែក។
• CLAUDE.md — ច្បាប់ repo សម្រាប់ Claude Code (ប្រភពពិតប្រាកដ សម្រាប់អនុសញ្ញាជាច្រើនខាងលើ)។
• AGENTS.md — ឯកសារយោងស្ថាបត្យកម្មកាន់តែស៊ីជម្រៅ ដែលត្រូវបានប្រើដោយ agents។