# OmniRoute Codebase Documentation (नेपाली) 🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../../ar/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇿 [az](../../../az/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../../bg/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../../bn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇦 [bs](../../../bs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../../cs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../../da/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../../de/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇷 [el](../../../el/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../../es/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇪 [et](../../../et/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../../fa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../../fi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../../fr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇪 [ga](../../../ga/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../../gu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ha](../../../ha/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../../he/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../../hi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇷 [hr](../../../hr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../../hu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇲 [hy](../../../hy/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../../id/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ig](../../../ig/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../../it/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../../ja/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇪 [ka](../../../ka/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇭 [km](../../../km/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../../ms/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [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, स्ट्यान्डअलोन आउटपुट, कुनै ग्लोबल मिडलवेयर छैन) | | भाषा | **TypeScript 6.0+** — लक्ष्य `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false` | | रनटाइम | **Node.js** `>=22.22.2 <23` वा `>=24.0.0 <27` (`engines` + `SUPPORTED_NODE_RANGE` मार्फत लागू गरिएको) | | डेटाबेस | `better-sqlite3` मार्फत **SQLite** (सिङ्गलटन, WAL जर्नलिङ) | | डेस्कटप | **Electron 41** + `electron-builder` 26.10 (`electron/` मा छुट्टै वर्कस्पेस) | | परीक्षणहरू | **Node नेटिभ टेस्ट रनर** (युनिट/इन्टिग्रेसन), **Vitest** (MCP, autoCombo, क्यास), **Playwright** (e2e + protocols-e2e) | | बिल्ड | `scripts/build/build-next-isolated.mjs` मार्फत Next.js स्ट्यान्डअलोन | | लिन्ट/ढाँचा | ESLint फ्ल्याट कन्फिग + Prettier (Husky pre-commit मार्फत `lint-staged`) | | मोड्युल प्रणाली | सबै ठाउँमा ESM (`"type": "module"`) | | वर्कस्पेसहरू | npm वर्कस्पेस — `open-sse` एकमात्र सब-वर्कस्पेस हो | पाथ एलियासहरू (`tsconfig.json`): - `@/*` → `src/*` - `@omniroute/open-sse` → `open-sse/index.ts` - `@omniroute/open-sse/*` → `open-sse/*` पूर्वनिर्धारित HTTP पोर्ट: **`20128`** (API र ड्यासबोर्डले एउटै प्रोसेस साझा गर्छन्)। डेटा डाइरेक्टरी `DATA_DIR` वातावरण चर हो, जसको पूर्वनिर्धारित मान `~/.omniroute/` हो। --- ## 2. रिपोजिटरी संरचना ``` OmniRoute/ ├── src/ Next.js अनुप्रयोग (App Router, लाइब्रेरीहरू, डोमेन, सर्भर, साझा) ├── open-sse/ स्ट्रिमिङ इन्जिन वर्कस्पेस (@omniroute/open-sse) ├── electron/ डेस्कटप र्यापर (Electron 41 मुख्य + प्रिलोड) ├── bin/ CLI प्रवेश बिन्दुहरू (omniroute, reset-password) ├── tests/ युनिट, इन्टिग्रेसन, e2e, protocols-e2e, अनुवादक, सुरक्षा, फिक्स्चरहरू ├── scripts/ बिल्ड, सिङ्क, जाँच, माइग्रेसन, र रनटाइम सहायक स्क्रिप्टहरू ├── docs/ सार्वजनिक दस्तावेजीकरण (यो डाइरेक्टरी) ├── public/ स्थिर एसेटहरू, PWA म्यानिफेस्ट, सर्भिस वर्कर ├── config/ रनटाइम कन्फिग नमुनाहरू ├── images/ मार्केटिङ/स्क्रिनसट एसेटहरू ├── _ideia/, _references/, _mono_repo/, _tasks/ आन्तरिक मस्यौदा / योजना (वितरण गरिँदैन) ├── CLAUDE.md Claude Code का लागि रिपो नियमहरू ├── AGENTS.md एजेन्टहरूका लागि अझ विस्तृत आर्किटेक्चर सन्दर्भ ├── package.json v3.8.51, वर्कस्पेस रुट └── tsconfig.json पाथ एलियासहरू + मुख्य कम्पाइलर विकल्पहरू ``` --- ## 3. `src/` — Next.js अनुप्रयोग ``` src/ ├── app/ App Router पृष्ठहरू + API रुटहरू ├── lib/ मुख्य लाइब्रेरीहरू (DB, प्रमाणीकरण, OAuth, सीपहरू, मेमोरी, …) ├── domain/ शुद्ध डोमेन तह (नीति, फलब्याक, लागत, लकआउट, …) ├── server/ सर्भरमा मात्र प्रयोग हुने मोड्युलहरू (प्राधिकरण, cors, प्रमाणीकरण) ├── shared/ प्रकारहरू, स्थिरांकहरू, प्रमाणीकरण, सम्झौताहरू, उपयोगिताहरू (सीमा-पार सुरक्षित) ├── mitm/ CLI एकीकरणका लागि म्यान-इन-द-मिडल प्रोक्सी सहायकहरू ├── models/ स्थानीय मोडेल मेटाडेटा / उपनामकरण ├── sse/ अझै src/ अन्तर्गत रहेका लिगेसी SSE ह्यान्डलरहरू (open-sse/ होइन) ├── store/ क्लाइन्ट-साइड अवस्था स्टोरहरू ├── middleware/ रुट-स्तरीय मिडलवेयर उपयोगिताहरू (Next.js को ग्लोबल मिडलवेयर होइन) ├── scripts/ एप कोडद्वारा आयात गर्न मिल्ने इन-ट्री स्क्रिप्टहरू ├── types/ एम्बियन्ट र साझा TS प्रकारहरू ├── i18n/ लोकेल बन्डलहरू ├── instrumentation.ts Next.js इन्स्ट्रुमेन्टेसन हुक ├── instrumentation-node.ts └── proxy.ts शीर्ष-स्तरीय प्रोक्सी बुटस्ट्र्याप सहायक ``` ### 3.1 `src/app/` — App Router App Router ले ड्यासबोर्ड UI र सार्वजनिक/व्यवस्थापन HTTP API दुवै उपलब्ध गराउँछ। यहाँ **कुनै ग्लोबल मिडलवेयर छैन** — इन्टरसेप्सन प्रत्येक रुटमा छुट्टाछुट्टै गरिन्छ। `src/app/` अन्तर्गतका शीर्ष-स्तरीय खण्डहरू: | पथ | उद्देश्य | | ----------------------------------------------------------------------------- | ------------------------------------------- | | `api/` | सबै HTTP API रुटहरू (तलको विवरण हेर्नुहोस्) | | `a2a/` | A2A JSON-RPC 2.0 एन्डपोइन्ट (`POST /a2a`) | | `.well-known/agent.json/` | A2A Agent Card खोज दस्तावेज | | `(dashboard)/` | ड्यासबोर्ड UI (रुट समूह, URL उपसर्ग छैन) | | `auth/`, `login/`, `forgot-password/`, `callback/` | प्रमाणीकरण प्रवाहहरू | | `landing/` | मार्केटिङ/ल्यान्डिङ पृष्ठ | | `docs/` | एम्बेड गरिएको API दस्तावेज दर्शक | | `status/`, `maintenance/`, `offline/` | सञ्चालनसम्बन्धी पृष्ठहरू | | `privacy/`, `terms/` | कानुनी पृष्ठहरू | | `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/` | स्थिर त्रुटि पृष्ठहरू | | `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | फ्रेमवर्कका त्रुटि/लोडिङ सीमाहरू | | `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts` | मूल शेल | #### 3.1.1 `src/app/(dashboard)/dashboard/` — UI पृष्ठहरू `agents`, `analytics`, `api-manager`, `audit`, `auto-combo`, `batch`, `cache`, `changelog`, `cli-tools`, `cloud-agents`, `combos`, `compression`, `context`, `costs`, `endpoint`, `health`, `limits`, `logs`, `memory`, `onboarding`, `playground`, `providers`, `search-tools`, `settings`, `skills`, `system`, `translator`, `usage`, `webhooks`, साथै मूल `page.tsx`, `HomePageClient.tsx`, `BootstrapBanner.tsx`। #### 3.1.2 `src/app/api/` — शीर्ष-स्तरीय API समूहहरू ``` src/app/api/ ├── a2a/{status, tasks} ├── acp/ ├── admin/ ├── analytics/ ├── assess/ ├── auth/ ├── batches/ ├── cache/ ├── cli-tools/ ├── cloud/{codex-responses-ws} ├── combos/ ├── compliance/ ├── compression/ ├── context/ ├── db/, db-backups/ ├── evals/ ├── fallback/ ├── files/ ├── health/ ├── init/ ├── internal/{concurrency} ├── keys/ ├── logs/ ├── mcp/{audit, sse, status, stream, tools} ├── memory/{health, [id]/, route.ts} ├── model-combo-mappings/ ├── models/ ├── monitoring/ ├── oauth/ ├── openapi/ ├── policies/ ├── pricing/ ├── provider-metrics/, provider-models/, provider-nodes/ ├── providers/ ├── rate-limit/, rate-limits/ ├── resilience/ ├── restart/, shutdown/ ├── search/ ├── sessions/ ├── settings/ ├── skills/{executions, [id], install, marketplace, route.ts, skillssh} ├── storage/ ├── sync/, synced-available-models/ ├── system/ ├── tags/ ├── telemetry/ ├── token-health/ ├── translator/ ├── tunnels/ ├── services/ एम्बेड गरिएका सेवाहरूको व्यवस्थापन (9router, cliproxy) — LOCAL_ONLY ├── upstream-proxy/ ├── usage/ ├── v1/ OpenAI-सङ्गत सार्वजनिक API ├── v1beta/ Gemini-शैलीको अनुकूलता ├── version-manager/ └── webhooks/ ``` #### 3.1.2a `src/app/api/services/` — एम्बेड गरिएका सेवाहरूको व्यवस्थापन 9Router र CLIProxyAPI स्थापना गर्ने, सुरु गर्ने, रोक्ने र अनुगमन गर्ने रुटहरू। सबै पथहरूलाई **LOCAL_ONLY** (लुपब्याकमा मात्र, कठोर नियम #17) का रूपमा वर्गीकृत गरिएको छ, किनभने तिनले `npm install` आह्वान गर्न र चाइल्ड प्रोसेसहरू सुरु गर्न सक्छन्। ``` src/app/api/services/ ├── 9router/ │ ├── _lib.ts getOrInitSupervisor() सहायक │ ├── install/route.ts POST — execFile मार्फत npm install │ ├── start/route.ts POST — supervisor.start() │ ├── stop/route.ts POST — supervisor.stop() │ ├── restart/route.ts POST — supervisor.restart() │ ├── update/route.ts POST — नयाँ संस्करण npm install गर्ने │ ├── rotate-key/route.ts POST — नयाँ API कुञ्जी उत्पन्न गर्ने + पुनः सुरु गर्ने │ ├── status/route.ts GET — प्रत्यक्ष + DB स्थिति + संस्करण मेटाडेटा │ └── auto-start/route.ts POST — auto_start फ्ल्याग टगल गर्ने ├── cliproxy/ │ ├── _lib.ts getOrInitSupervisor() सहायक │ ├── install/route.ts POST — npm install │ ├── start/route.ts POST — supervisor.start() │ ├── stop/route.ts POST — supervisor.stop() │ ├── restart/route.ts POST — supervisor.restart() │ ├── update/route.ts POST — नयाँ संस्करण npm install गर्ने │ ├── status/route.ts GET — प्रत्यक्ष + DB स्थिति + संस्करण मेटाडेटा │ └── auto-start/route.ts POST — auto_start फ्ल्याग टगल गर्ने └── [name]/ └── logs/route.ts GET — SSE लगको पछिल्लो भाग (सबै सेवाहरूद्वारा साझा) ``` सम्बन्धित ड्यासबोर्ड UI: `src/app/(dashboard)/dashboard/providers/services/` — दुई-ट्याबको पृष्ठ (CLIProxyAPI + 9Router)। 9Router मा अन्तःस्थापित UI का लागि रिभर्स प्रोक्सी: `src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts` विस्तृत अध्ययन: `docs/frameworks/EMBEDDED-SERVICES.md` #### 3.1.3 `src/app/api/v1/` — OpenAI-सङ्गत सार्वजनिक API ``` v1/ ├── accounts/[id]/ खाता खोज ├── agents/tasks/[id]/, agents/tasks/ A2A-शैलीका कार्य अन्त्यबिन्दुहरू ├── api/ v1/api अन्तर्गत उपलब्ध गराइएका आन्तरिक API सहायकहरू ├── audio/{speech, transcriptions}/ TTS + STT ├── batches/[id]/{cancel}, batches/ OpenAI Batches API ├── chat/completions/ Chat Completions (मुख्य अन्त्यबिन्दु) ├── completions/ पुरानो पाठ पूर्णता ├── embeddings/ एम्बेडिङहरू ├── files/[id]/, files/ Files API ├── _helpers/ साझा रुट सहायकहरू (सार्वजनिक URL छैन) ├── images/{edits, generations}/ छवि उत्पादन + सम्पादन ├── issues/ ट्रायाज सहायक अन्त्यबिन्दुहरू ├── management/{proxies}/ v1 भित्रका व्यवस्थापन-क्षेत्रका रुटहरू ├── messages/{count_tokens}/ Anthropic-शैलीको सन्देश अनुकूलता ├── models/ मोडेल सूचीकरण (`route.ts`, `catalog.ts`) ├── moderations/ मोडरेसन ├── music/ सङ्गीत उत्पादन ├── providers/[provider]/ प्रत्येक प्रदायकका सञ्चालनहरू ├── quotas/{check} कोटा परीक्षणहरू ├── registered-keys/ दर्ता गरिएका कुञ्जीहरूको प्रशासन ├── rerank/ पुनःक्रमाङ्कन ├── responses/[...path]/ OpenAI Responses API (सबै समेट्ने) ├── search/ वेब खोज ├── videos/ भिडियो उत्पादन ├── ws/ WebSocket ब्रिज └── route.ts अनुक्रमणिका ह्यान्डलर ``` हरेक रुट फाइलले एउटै ढाँचा पालना गर्छ: ``` रुट → CORS प्रिफ्लाइट → Zod बडी प्रमाणीकरण → वैकल्पिक प्रमाणीकरण → API कुञ्जी नीति कार्यान्वयन → ह्यान्डलर प्रत्यायोजन (open-sse) ``` `v1beta/` Gemini-शैलीको अनुकूलता सतह हो (उही `open-sse/handlers/` पाइपलाइनमा रूपान्तरण गर्ने पातलो र्यापर)। ### 3.2 `src/lib/` — मूल लाइब्रेरीहरू डेटा, सिङ्क, OAuth, सीप, मेमोरी आदि सधैँ यी मोड्युलहरूमार्फत आयात गर्नुहोस्। तालिकाले वास्तविक डाइरेक्टरीहरू र उल्लेखनीय शीर्ष-स्तरीय फाइलहरूलाई समूहबद्ध गर्छ। | मोड्युल | उद्देश्य | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `a2a/` | A2A प्रोटोकल सर्भर: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (६ वटा स्किल: लागत विश्लेषण, स्वास्थ्य प्रतिवेदन, प्रदायक खोज, कोटा व्यवस्थापन, स्मार्ट राउटिङ, क्षमताहरूको सूची) | | `acp/` | Agent-Control-Protocol: `index.ts`, `manager.ts`, `registry.ts` | | `api/` | आन्तरिक API सहायकहरू: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts` | | `auth/` | `managementPassword.ts` (पासवर्ड रिसेट / ह्यासिङ) | | `batches/` | OpenAI Batches API सेवा (`service.ts`) | | `catalog/` | OpenRouter क्याटलग सिङ्क (`openrouterCatalog.ts`) | | `cloudAgent/` | क्लाउड एजेन्ट रजिस्ट्री: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts` | | `combos/` | कम्बो रिजोल्युसन सहायकहरू | | `compliance/` | अडिट + प्रदायक अडिट: `index.ts`, `providerAudit.ts` | | `config/` | रनटाइम कन्फिग संयोजन | | `db/` | SQLite डोमेन मोड्युलहरू (§3.2.1 हेर्नुहोस्) | | `display/` | API प्रतिक्रियाहरूले प्रयोग गर्ने UI/डिस्प्ले सहायकहरू | | `embeddings/` | एम्बेडिङ सेवा रजिस्ट्री | | `env/` | वातावरण लोडिङ + निरीक्षण | | `evals/` | मूल्याङ्कन रनटाइम | | `guardrails/` | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts` | | `jobs/` | पृष्ठभूमि कार्यहरू (`autoUpdate.ts`, …) | | `memory/` | स्थायी मेमोरी: `store.ts`, `cache.ts`, `retrieval.ts`, `summarization.ts`, `extraction.ts`, `injection.ts`, `qdrant.ts`, `settings.ts`, `verify.ts`, `schemas.ts`, `types.ts` | | `monitoring/` | `observability.ts` | | `oauth/` | OAuth/आयात प्रदायक मोड्युलहरू (२२): `agy`, `antigravity`, `claude`, `cline`, `codebuddy-cn`, `codex`, `cursor`, `devin-desktop`, `ghe-copilot`, `github`, `gitlab-duo`, `grok-cli-oauth`, `grok-cli`, `kilocode`, `kimi-coding`, `kiro`, `openference`, `qoder`, `trae`, `xai-oauth`, `zed-hosted`, `zed`, साथै `services/`, `utils/`, र `constants/oauth.ts` | | `plugins/` | प्लगइन लोडर (`index.ts`) | | `promptCache/` | `prefixAnalyzer.ts`, `index.ts` | | `providerModels/` | व्यवस्थित मोडेल जीवनचक्र: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts` | | `providers/` | प्रदायक सहायकहरू: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts` | | `resilience/` | `settings.ts` — सर्किट ब्रेकर, कूलडाउन र लकआउटका सेटिङहरू | | `runtime/` | रनटाइम सुविधा पहिचान | | `search/` | `executeWebSearch.ts` | | `services/` | अन्तर्निहित सेवा फ्रेमवर्क: `ServiceSupervisor.ts` (अपरेसन लक, रिङ बफर र स्वास्थ्य जाँचकर्तासहितको सामान्य चाइल्ड-प्रोसेस सुपरभाइजर), `bootstrap.ts` (प्रक्रिया-स्तरीय दर्ता र स्वतः-सुरुवात), `registry.ts` (उपकरण → सुपरभाइजर म्याप), `apiKey.ts` (AES-256-GCM कुञ्जी भण्डार), `modelSync.ts` (आवधिक मोडेल सिङ्क), `ringBuffer.ts` (५ MB चक्रीय लग बफर), `healthCheck.ts` (HTTP स्वास्थ्य प्रोब), `types.ts`, `embedWsProxy.ts` (WebSocket प्रोक्सी), `installers/{ninerouter,cliproxy}.ts`। `docs/frameworks/EMBEDDED-SERVICES.md` हेर्नुहोस् | | `agentSkills/` | एजेन्ट स्किल्स क्याटलग + जेनेरेटर: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → `skills/{id}/SKILL.md` मा लेख्छ), `openapiParser.ts` (OpenAPI स्पेकबाट REST एन्डपोइन्टहरू निकाल्छ), `cliRegistryParser.ts` (bin/cli-registry बाट CLI उपकमान्डहरू निकाल्छ), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport)। REST रुटहरू (`/api/agent-skills/*`), MCP उपकरणहरू (`omniroute_agent_skills_*`), र A2A स्किल `list-capabilities` द्वारा प्रयोग गरिन्छ। [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md) हेर्नुहोस्। | | `skills/` | स्किल फ्रेमवर्क: `registry.ts`, `executor.ts`, `interception.ts`, `injection.ts`, `sandbox.ts`, `custom.ts`, `hybrid.ts`, `builtins.ts`, `a2a.ts`, `providerSettings.ts`, `schemas.ts`, `skillssh.ts`, `types.ts`, साथै `builtin/browser.ts` | | `spend/` | `batchWriter.ts` (राइट-बिहाइन्ड बफर) | | `sync/` | `bundle.ts`, `tokens.ts` (क्लाउड सिङ्क) | | `system/` | प्रणाली-स्तरीय सहायकहरू | | `translator/` | शीर्ष-स्तरीय अनुवादक संयोजन (`open-sse/translator/` मा प्रत्यायोजन गर्छ) | | `usage/` | प्रयोग लेखाङ्कन: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts` | | `versionManager/` | स्वतः-अद्यावधिक + संस्करण म्यानिफेस्ट | | `ws/` | WebSocket ब्रिज | | `zed-oauth/` | Zed सम्पादक OAuth प्रवाह | `src/lib/` मा शीर्ष-स्तरीय फाइलहरू: - पुरानो `localDb.ts` barrel हटाइएको छ — उपभोक्ताहरूले विशिष्ट `src/lib/db/*` मोड्युलहरू सीधै आयात गर्छन्। - `proxyHealth.ts`, `proxyLogger.ts`, `tokenHealthCheck.ts`, `localHealthCheck.ts` - `apiBridgeServer.ts`, `cacheLayer.ts`, `semanticCache.ts`, `settingsCache.ts` - `cloudSync.ts`, `initCloudSync.ts` - `cloudflaredTunnel.ts`, `ngrokTunnel.ts`, `tailscaleTunnel.ts` - `consoleInterceptor.ts`, `container.ts`, `gracefulShutdown.ts`, `idempotencyLayer.ts` - `ipUtils.ts`, `logEnv.ts`, `logPayloads.ts`, `logRotation.ts` - `modelAliasSeed.ts`, `modelCapabilities.ts`, `modelMetadataRegistry.ts`, `modelsDevSync.ts` - `piiSanitizer.ts`, `pricingSync.ts` - `apiKeyExposure.ts`, `cacheControlSettings.ts`, `dataPaths.ts`, `toolPolicy.ts` - `translatorEvents.ts`, `usageDb.ts`, `usageAnalytics.ts`, `webhookDispatcher.ts` #### 3.2.1 `src/lib/db/` Singleton SQLite डेटाबेस (`core.ts` मा `getDbInstance()`, WAL journaling)। **routes वा handlers मा कहिल्यै raw SQL नलेख्नुहोस्** — यी मोड्युलहरूमार्फत जानुहोस्। ![डेटाबेस schema को सिंहावलोकन (चयन गरिएका मुख्य tables)](../diagrams/exported/db-schema-overview.svg) > स्रोत: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd) डोमेन मोड्युलहरू (प्रत्येकले एक वा बढी tables को स्वामित्व लिन्छ): `apiKeys.ts`, `backup.ts`, `batches.ts`, `cleanup.ts`, `cliToolState.ts`, `combos.ts`, `commandCodeAuth.ts`, `compression.ts`, `compressionAnalytics.ts`, `compressionCacheStats.ts`, `compressionCombos.ts`, `compressionScheduler.ts`, `contextHandoffs.ts`, `core.ts`, `creditBalance.ts`, `databaseSettings.ts`, `detailedLogs.ts`, `domainState.ts`, `encryption.ts`, `evals.ts`, `files.ts`, `healthCheck.ts`, `jsonMigration.ts`, `migrationRunner.ts`, `modelComboMappings.ts`, `models.ts`, `oneproxy.ts`, `prompts.ts`, `providers.ts`, `providerLimits.ts`, `proxies.ts`, `quotaSnapshots.ts`, `readCache.ts`, `reasoningCache.ts`, `registeredKeys.ts`, `secrets.ts`, `sessionAccountAffinity.ts`, `settings.ts`, `stateReset.ts`, `stats.ts`, `syncTokens.ts`, `tierConfig.ts`, `upstreamProxy.ts`, `versionManager.ts`, `webhooks.ts`। `migrations/` मा 168 वटा संस्करणयुक्त `.sql` फाइलहरू (idempotent, transactional) छन् र तिनलाई boot हुँदा `migrationRunner.ts` द्वारा कार्यान्वयन गरिन्छ। migrations भरि सिर्जना गरिएका tables (जम्मा 123): `a`, `account_key_limits`, `api_keys`, `batches`, `call_logs`, `combo_adaptation_state`, `combos`, `command_code_auth_sessions`, `compression_analytics`, `compression_cache_stats`, `compression_combo_assignments`, `compression_combos`, `context_handoffs`, `daily_usage_summary`, `db_meta`, `domain_budgets`, `domain_circuit_breakers`, `domain_cost_history`, `domain_fallback_chains`, `domain_lockout_state`, `eval_cases`, `eval_runs`, `eval_suites`, `files`, `hourly_usage_summary`, `key_value`, `mcp_tool_audit`, `memories`, `model_combo_mappings`, `provider_connections`, `provider_key_limits`, `provider_nodes`, `proxy_assignments`, `proxy_logs`, `proxy_registry`, `quota_snapshots`, `reasoning_cache`, `registered_keys`, `request_detail_logs`, `routing_decisions`, `semantic_cache`, `session_account_affinity`, `skill_executions`, `skills`, `sync_tokens`, `tier_assignments`, `tier_config`, `upstream_proxy_config`, `usage_history`, `version_manager`, `webhooks` (साथै memory search का लागि FTS5 virtual tables)। ### 3.3 `src/domain/` — डोमेन तह शुद्ध व्यावसायिक तर्क, कुनै I/O छैन। routes र handlers द्वारा आयात गरिन्छ। | फाइल | उद्देश्य | | ------------------------------------------ | ------------------------------------------------------------- | | `policyEngine.ts` | शीर्ष-स्तरीय policy resolver | | `fallbackPolicy.ts` | Fallback निर्णय tree | | `costRules.ts` | लागत गणनाका नियमहरू | | `lockoutPolicy.ts` | Model lockout सम्बन्धी निर्णयहरू | | `tagRouter.ts` | Tag-आधारित routing | | `comboResolver.ts` | request → target सूचीबाट Combo resolution | | `connectionModelRules.ts` | प्रत्येक connection का model filters | | `modelAvailability.ts` | Model उपलब्धता जाँच | | `degradation.ts` | Degraded-mode अवस्थान्तरणहरू | | `providerExpiration.ts` | म्याद सकिएको account/key पत्ता लगाउने कार्य | | `quotaCache.ts` | Cache गरिएका quota सम्बन्धी निर्णयहरू | | `responses.ts`, `omnirouteResponseMeta.ts` | Response को आकारसम्बन्धी सहायकहरू | | `configAudit.ts` | Config परिवर्तन audit | | `assessment/` | Model मूल्याङ्कन (RFC अनुसार, आंशिक रूपमा कार्यान्वयन गरिएको) | | `types.ts` | साझा domain types | ### 3.4 `src/server/` — Server-मात्र Client components बाट आयात गर्न सकिँदैन। ``` server/ ├── auth/loginGuard.ts ├── authz/ │ ├── classify.ts routes लाई public वा management का रूपमा वर्गीकरण गर्छ │ ├── assertAuth.ts Assertion सहायक │ ├── context.ts प्रत्येक request को authz context │ ├── headers.ts │ ├── pipeline.ts Authz pipeline │ ├── policies/ ठोस policies │ └── types.ts └── cors/origins.ts CORS origin allowlist ``` ### 3.5 `src/shared/` — साझा गर्न सुरक्षित केन्द्रित subdirectories मा विभाजित: - `constants/` — `providers.ts` (Zod द्वारा प्रमाणीकरण गरिएको प्रदायक सूची), `models.ts`, `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`, `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`, `headers.ts`, `upstreamHeaders.ts` (निषेध सूची), `mcpScopes.ts`, `errorCodes.ts`, `publicApiRoutes.ts`, `batch.ts`, `batchEndpoints.ts`, `bodySize.ts`, `colors.ts`, `appConfig.ts`, `config.ts`, `sidebarVisibility.ts`, `visionBridgeDefaults.ts`। - `validation/` — `schemas.ts` (~80 Zod स्किमा), `compressionConfigSchemas.ts`, `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`। - `contracts/` — npm मा उपलब्ध गराइएका सार्वजनिक API अनुबन्धहरू। - `types/` — साझा TS प्रकारहरू। - `utils/` — `circuitBreaker.ts`, `apiAuth.ts`, `apiKey.ts`, `apiKeyPolicy.ts`, `api.ts`, `classify429.ts`, `cliCompat.ts`, `clipboard.ts`, `cloud.ts`, `cn.ts`, `cors.ts`, `featureFlags.ts`, `fetchTimeout.ts`, `formatting.ts`, `inputSanitizer.ts`, `logger.ts`, `machine.ts`, `machineId.ts`, `maskEmail.ts`, `modelCatalogSearch.ts`, `nodeRuntimeSupport.ts`, `parseApiKeys.ts`, `providerHints.ts`, `providerModelAliases.ts`, `rateLimiter.ts`, `releaseNotes.ts`, `a11yAudit.ts`, साथै `services/`, `network/`, `middleware/`, `schemas/`, `hooks/`, `components/` अन्तर्गतका ड्यासबोर्ड हुक/कम्पोनेन्टहरू। --- ## 4. `open-sse/` — स्ट्रिमिङ इन्जिन कार्यक्षेत्र `@omniroute/open-sse` को रूपमा प्रकाशित छुट्टै npm कार्यक्षेत्र। यसले अनुरोध प्रशोधन, एक्जिक्युटरहरू, ट्रान्सलेटरहरू, सेवाहरू, ट्रान्सफर्मर र MCP सर्भर व्यवस्थापन गर्छ। ``` open-sse/ ├── index.ts सार्वजनिक निर्यातहरू ├── package.json कार्यक्षेत्र म्यानिफेस्ट ├── tsconfig.json ├── types.d.ts ├── config/ प्रदायक रजिस्ट्रीहरू, हेडर प्रोफाइलहरू, पहिचान, … ├── handlers/ अनुरोध ह्यान्डलरहरू (च्याट, एम्बेडिङ, अडियो, छवि, …) ├── executors/ 156 प्रदायक एक्जिक्युटर मोड्युलहरू (एक्जिक्युटर क्लासहरू + प्रत्येक प्रदायकका सहायकहरू) ├── translator/ ढाँचा रूपान्तरण (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro) ├── transformer/ Responses API ↔ Chat Completions स्ट्रिम ट्रान्सफर्मर ├── services/ 80+ सेवा मोड्युलहरू (कम्बोहरू, फलब्याक, कोटाहरू, पहिचान, …) ├── utils/ स्ट्रिमिङ सहायकहरू, TLS क्लाइन्ट, AWS SigV4, प्रोक्सी फेच, … └── mcp-server/ MCP सर्भर (3 ट्रान्सपोर्टहरू, 33 स्कोपहरू, 110 उपकरणहरू) ``` ### 4.1 `open-sse/handlers/` | ह्यान्डलर | उद्देश्य | | ----------------------- | -------------------------------------------------------------------------- | | `chatCore.ts` | मुख्य च्याट पाइपलाइन (क्यास, दर सीमा, कम्बो राउटिङ, एक्जिक्युटर डिस्प्याच) | | `responsesHandler.ts` | OpenAI Responses API प्रवेश बिन्दु | | `embeddings.ts` | एम्बेडिङहरू | | `imageGeneration.ts` | छवि उत्पादन | | `audioSpeech.ts` | टेक्स्ट-टु-स्पिच | | `audioTranscription.ts` | स्पिच-टु-टेक्स्ट | | `videoGeneration.ts` | भिडियो उत्पादन | | `musicGeneration.ts` | सङ्गीत उत्पादन | | `rerank.ts` | पुनःक्रमाङ्कन | | `moderations.ts` | मोडरेसन | | `search.ts` | वेब खोज | | `sseParser.ts` | SSE घटना पार्सर | | `usageExtractor.ts` | अपस्ट्रिम स्ट्रिमहरूबाट टोकन सङ्ख्या निकाल्छ | | `responseSanitizer.ts` | प्रदायक-विशिष्ट अनावश्यक सामग्री हटाउँछ | | `responseTranslator.ts` | प्रदायक प्रतिक्रिया र ट्रान्सलेटर तहबीचको संयोजक | ### 4.2 `open-sse/executors/` 156 शीर्ष-स्तरीय एक्जिक्युटर मोड्युलहरू (`*.ts` बाट `base.ts`, `index.ts` र परीक्षणहरू घटाएर — यो सङ्ख्या `npm run check:docs-counts` ले मापन गर्छ)। प्रत्येक एक्जिक्युटर क्लासले `BaseExecutor` (`base.ts`) विस्तार गर्छ, प्रत्यक्ष रूपमा वा `DefaultExecutor` अथवा अर्को एक्जिक्युटरमार्फत; बाँकी मोड्युलहरू प्रत्येक प्रदायकका सहायकहरू हुन् (उपकरण स्किमाहरू, फेच/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` (रजिस्ट्री)। > नोट: यहाँ सूचीबद्ध नगरिएका प्रदायकहरूलाई जेनेरिक OpenAI-सङ्गत > एक्जिक्युटर प्रयोग गरेर `default.ts` ले सेवा दिन्छ। पूर्ण प्रदायक सूची (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` — `TransformStream`-आधारित Responses API ↔ Chat Completions रूपान्तरणकर्ता (`responses/` रुट क्याच-अलद्वारा प्रयोग गरिने)। ### 4.5 `open-sse/services/` मुख्य अंशहरू (पूर्ण सूची `open-sse/services/` अन्तर्गत): | सरोकार | फाइलहरू | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | कम्बो राउटिङ | `combo.ts` (20 रणनीतिहरू), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts` | | अटो कम्बो इन्जिन | `autoCombo/` — `engine.ts`, `scoring.ts`, `taskFitness.ts`, `virtualFactory.ts`, `modePacks.ts`, `autoPrefix.ts`, `persistence.ts`, `providerDiversity.ts`, `providerRegistryAccessor.ts`, `routerStrategy.ts`, `selfHealing.ts`, `index.ts` | | प्रतिरोधक्षमता | `accountFallback.ts` (कुलडाउन + लकआउट), `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/` - `server.ts` मा **110 अद्वितीय उपकरणहरू** वायर गरिएका छन् (`schemas/tools.ts` मा 45 क्यानोनिकल + मेमोरी, सीपहरू, GitHub-सीपहरू, पूल, गेमिफिकेसन, प्लगइन, Notion, Obsidian, स्थानीय-कर्पस र सङ्कुचन मोड्युलहरू — युनियनलाई `countUniqueMcpTools` द्वारा गणना गरिएको)। - **3 ट्रान्सपोर्टहरू**: stdio, HTTP Streamable, SSE। - रनटाइममा **33 स्कोपहरू** लागू गरिएका छन् — आधार सूची `src/shared/constants/mcpScopes.ts` मा छ, पूर्ण सेट प्रत्येक उपकरण मोड्युलद्वारा घोषित स्कोपहरूको युनियन हो। - अडिट तालिका: `mcp_tool_audit` (`audit.ts` द्वारा भरिने)। - फाइलहरू: `server.ts`, `index.ts`, `httpTransport.ts`, `audit.ts`, `scopeEnforcement.ts`, `runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`, `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`, साथै `__tests__/` अन्तर्गतका परीक्षणहरू। - पूर्ण उपकरण क्याटलगका लागि [MCP-SERVER.md](../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/` — डेस्कटप र्यापर ``` electron/ ├── main.js Electron मुख्य प्रक्रिया ├── preload.js प्रिलोड ब्रिज (contextIsolation सक्षम) ├── types.d.ts ├── package.json electron-builder कन्फिगरेसन, संस्करण 3.8.51 ├── README.md ├── assets/ बिल्ड स्रोतहरू (आइकन, इन्टाइटलमेन्ट, …) ├── node_modules/ समर्पित node_modules (better-sqlite3, electron-updater) └── dist-electron/ बिल्ड आउटपुट (कमिट नगरिएको) ``` वर्कस्पेस रुटमा पाँचवटा npm स्क्रिप्ट छन्: `electron:dev`, `electron:build`, `electron:build:{win,mac,linux}`, `electron:smoke:packaged`। स्वतः-अपडेट GitHub रिलिज फिडतर्फ औँल्याइएको `electron-updater` मार्फत हुन्छ। --- ## 6. `bin/` — CLI ``` bin/ ├── omniroute.mjs मुख्य CLI प्रवेशबिन्दु (Node ESM) ├── reset-password.mjs CLI बाट व्यवस्थापन पासवर्ड रिसेट गर्छ ├── mcp-server.mjs MCP सर्भर लन्चर (stdio) ├── nodeRuntimeSupport.mjs Node संस्करण गार्ड └── cli/ ├── program.mjs Commander प्रोग्राम बिल्डर ├── runtime.mjs withRuntime सहायक (पहिले-सर्भर/DB-फल्ब्याक) ├── output.mjs आउटपुट फर्म्याटरहरू (json/jsonl/table/csv) ├── i18n.mjs लोकेलसहितको t() सहायक ├── api.mjs API fetch सहायक ├── data-dir.mjs ├── encryption.mjs ├── sqlite.mjs └── commands/ ├── registry.mjs कमान्ड दर्ता ├── setup.mjs ├── doctor.mjs ├── providers.mjs └── ... (प्रत्येक कमान्ड/समूहका लागि एउटा फाइल) ``` `package.json` → `bin` मा दुईवटा बाइनरी उपलब्ध गराइएका छन्: - `omniroute` → `bin/omniroute.mjs` - `omniroute-reset-password` → `bin/reset-password.mjs` --- ## 7. `tests/` | डाइरेक्टरी | प्रकार | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `tests/unit/` | Node को नेटिभ टेस्ट रनरमार्फत युनिट टेस्टहरू (१८२१ फाइल, साथै `api/`, `auth/`, `authz/` उपडाइरेक्टरीहरू) | | `tests/integration/` | क्रस-मोड्युल + DB-स्थिति टेस्टहरू | | `tests/e2e/` | Playwright UI टेस्टहरू | | `tests/e2e/protocol-clients.test.ts` | MCP/A2A प्रोटोकल e2e | | `tests/translator/` | अनुवादक-विशिष्ट टेस्टहरू | | `tests/security/` | सुरक्षा रिग्रेसनहरू | | `tests/load/` | लोड / स्ट्रेस टेस्टहरू | | `tests/golden-set/` | अनुवादक रिग्रेसनहरूका लागि सन्दर्भ आउटपुटहरू | | `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | सहायक सामग्री | सामान्य कमान्डहरू: | कमान्ड | यसले के चलाउँछ | | -------------------------------------------------------- | --------------------------------------------------------------- | | `npm run test:unit` | Node टेस्ट रनरमार्फत सबै `tests/unit/*.test.ts` (कन्करेन्सी १०) | | `npm run test:vitest` | Vitest सुइट (MCP, autoCombo, cache) | | `npm run test:e2e` | Playwright UI सुइट | | `npm run test:protocols:e2e` | MCP + A2A प्रोटोकल e2e | | `npm run test:coverage` | कभरेज गेट (लाइन/स्टेटमेन्ट/फङ्सन/ब्रान्च ≥६०%) | | `node --import tsx/esm --test tests/unit/.test.ts` | एकल फाइल सञ्चालन | --- ## 8. `scripts/` उद्देश्यअनुसार 6 वटा उपफोल्डरमा व्यवस्थित गरिएको छ। - **`scripts/build/`** — `build-next-isolated.mjs`, `prepublish.ts`, `prepare-electron-standalone.mjs`, `pack-artifact-policy.ts`, `validate-pack-artifact.ts`, `postinstall.mjs`, `postinstallSupport.mjs`, `uninstall.mjs`, `bootstrap-env.mjs`, `runtime-env.mjs`, `native-binary-compat.mjs`। - **`scripts/dev/`** — `run-next.mjs`, `run-next-playwright.mjs`, `run-standalone.mjs`, `standalone-server-ws.mjs`, `responses-ws-proxy.mjs`, `v1-ws-bridge.mjs`, `smoke-electron-packaged.mjs`, `run-playwright-tests.mjs`, `run-ecosystem-tests.mjs`, `run-protocol-clients-tests.mjs`, `sync-env.mjs`, `healthcheck.mjs`, `system-info.mjs`, साथै पढ्न मात्र मिल्ने PR निगरानी सहायकहरू `ci-discriminate.sh` (सन्दर्भ PR वा base-red issue सँग तुलना गरी PR का असफल जाँच सङ्केतहरूलाई आफ्नै / वंशानुगत / अज्ञातमा वर्गीकरण गर्छ) र `audit-worktree.sh` (फोहोर फाइलहरू, संरक्षित सतहहरू, हटाइएका assert हरू, suppression गणनाहरू, बाँकी रहेका अस्थायी tsconfig हरू, PR head विरुद्ध स्थानीय HEAD — worker को PR स्वीकार गर्नुअघि)। - **`scripts/check/`** — `check-cycles.mjs`, `check-docs-sync.mjs`, `check-docs-counts-sync.mjs`, `check-env-doc-sync.mjs`, `check-deprecated-versions.mjs`, `check-route-validation.mjs`, `check-t11-any-budget.mjs`, `check-pr-test-policy.mjs`, `check-supported-node-runtime.ts`, `test-report-summary.mjs`। - **`scripts/docs/`** — `generate-docs-index.mjs`, `gen-provider-reference.ts`। - **`scripts/i18n/`** — `generate-multilang.mjs`, `run-visual-qa.mjs`, `generate-qa-checklist.mjs`, `apply-priority-overrides.mjs`, `validate_translation.py`, `check_translations.py`, `i18n_autotranslate.py`, `untranslatable-keys.json`। - **`scripts/ad-hoc/`** — `cursor-tap.cjs`, `sync-cursor-models.mjs`, `migrate-env.mjs`, `dbsetup.js`। --- ## 9. अनुरोध पाइपलाइन (सारांश) ![अनुरोध पाइपलाइन (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg) > स्रोत: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd) ``` क्लाइन्ट अनुरोध → /v1/chat/completions (route.ts) CORS प्रिफ्लाइट जाँच Zod प्रमाणीकरण (shared/validation/schemas.ts मा chatCompletionsSchema) प्रमाणीकरण (extractApiKey + isValidApiKey वा requireManagementAuth) नीति इन्जिन (src/server/authz/pipeline.ts) सुरक्षा नियन्त्रणहरू (PII मास्कर, प्रम्प्ट इन्जेक्सन, भिजन ब्रिज) → handleChatCore() (open-sse/handlers/chatCore.ts) क्यास जाँच (सिम्यान्टिक + रिड क्यास) दर सीमा (rateLimitManager, accountSemaphore) कम्बो राउटिङ (यदि मोडेल कम्बोमा रिजल्भ हुन्छ भने) comboResolver → प्रत्येक लक्ष्यका लागि लुप → handleSingleModel() translateRequest() (open-sse/translator/request/*) getExecutor(providerId).execute() (open-sse/executors/*) अपस्ट्रिम फेच → accountFallback मार्फत पुनःप्रयास/ब्याकअफ translateResponse() (open-sse/translator/response/*) SSE स्ट्रिम वा JSON प्रतिक्रिया यदि Responses API भएमा: open-sse/transformer/responsesTransformer.ts मार्फत TransformStream → अनुपालन अडिट (src/lib/compliance/) → क्लाइन्टलाई प्रतिक्रिया ``` ### पुनःस्थापनशीलता रनटाइम अवस्था (तीन संयन्त्र) | संयन्त्र | दायरा | स्थान | | --------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | प्रदायक सर्किट ब्रेकर | सम्पूर्ण प्रदायक | `src/shared/utils/circuitBreaker.ts`, `domain_circuit_breakers` मा स्थायी रूपमा भण्डारित | | जडान कुलडाउन | एउटा खाता/कुञ्जी | `src/sse/services/auth.ts` मा `markAccountUnavailable()`; `accountFallback.checkFallbackError()` द्वारा प्रयोग | | मोडेल लकआउट | प्रदायक + जडान + मोडेल | `open-sse/services/accountFallback.ts`, `domain_lockout_state` मा स्थायी रूपमा भण्डारित | [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) र [CLAUDE.md](../../CLAUDE.md) को समर्पित खण्ड हेर्नुहोस्। --- ## 10. योगदान कसरी गर्ने ### नयाँ प्रदायक थप्ने 1. `src/shared/constants/providers.ts` मा दर्ता गर्नुहोस् (लोड हुँदा Zod द्वारा प्रमाणीकरण गरिन्छ)। 2. अनुकूलित तर्क आवश्यक भएमा `open-sse/executors/` मा executor थप्नुहोस् (`BaseExecutor` लाई विस्तार गर्नुहोस्)। 3. यदि त्यसले OpenAI ढाँचा प्रयोग गर्दैन भने `open-sse/translator/` मा translator थप्नुहोस्। 4. यदि OAuth-आधारित हो भने, `src/lib/oauth/providers/` र `src/lib/oauth/services/` अन्तर्गत config थप्नुहोस्। 5. मोडेलहरू `open-sse/config/providerRegistry.ts` मा (वा `open-sse/config/` अन्तर्गतको ढाँचा-विशिष्ट registry मा) दर्ता गर्नुहोस्। 6. `tests/unit/` अन्तर्गत परीक्षणहरू लेख्नुहोस्। ### नयाँ API route थप्ने 1. `src/app/api/your-route/route.ts` सिर्जना गर्नुहोस्। 2. यो ढाँचा पालना गर्नुहोस्: CORS → Zod body प्रमाणीकरण → प्रमाणीकरण → handler प्रत्यायोजन। 3. नयाँ request shape भएमा: `src/shared/validation/schemas.ts` मा Zod schema थप्नुहोस्। 4. व्यवस्थापनका लागि मात्र हो भने: path लाई `src/shared/constants/publicApiRoutes.ts` मा थप्नुहोस् (सार्वजनिक API सतहका लागि denylist)। 5. `tests/unit/` अन्तर्गत परीक्षणहरू थप्नुहोस्। 6. `docs/reference/API_REFERENCE.md` र `docs/openapi.yaml` अद्यावधिक गर्नुहोस्। ### नयाँ DB module थप्ने 1. `src/lib/db/yourModule.ts` सिर्जना गर्नुहोस् र `./core.ts` बाट `getDbInstance()` आयात गर्नुहोस्। 2. आफ्नो domain का लागि CRUD functions निर्यात गर्नुहोस्। 3. नयाँ tables भएमा: `src/lib/db/migrations/` अन्तर्गत क्रमिक रूपमा नम्बर दिइएको, idempotent र transactional migration थप्नुहोस्। 4. Importers ले `@/lib/db/yourModule` बाट प्रत्यक्ष imports प्रयोग गर्छन् (barrel होइन — पुरानो `localDb.ts` पुनः-निर्यात तह हटाइएको छ)। 5. `tests/unit/` अन्तर्गत परीक्षणहरू थप्नुहोस्। ### नयाँ MCP tool थप्ने 1. `open-sse/mcp-server/tools/` अन्तर्गत tool definition थप्नुहोस् (वा `open-sse/mcp-server/schemas/tools.ts` विस्तार गर्नुहोस्)। 2. `src/shared/constants/mcpScopes.ts` मा उपयुक्त scope(s) तोक्नुहोस्। 3. `open-sse/mcp-server/server.ts` मा tool दर्ता गर्नुहोस्। 4. `open-sse/mcp-server/__tests__/` अन्तर्गत परीक्षणहरू थप्नुहोस्। 5. [MCP-SERVER.md](../frameworks/MCP-SERVER.md) अद्यावधिक गर्नुहोस्। ### नयाँ A2A skill थप्ने [A2A-SERVER.md § नयाँ Skill थप्ने](../frameworks/A2A-SERVER.md) हेर्नुहोस्। Skills `src/lib/a2a/skills/` मा रहन्छन् र A2A task manager मार्फत दर्ता गरिन्छन्। --- ## 11. प्रचलनहरू - **Code style**: 2-space indent, double quotes, 100 char width, semicolons, `es5` trailing commas — `lint-staged` मार्फत Prettier द्वारा लागू गरिन्छ। - **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative। - **Naming**: files `camelCase` वा `kebab-case`, components `PascalCase`, constants `UPPER_SNAKE`। - **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = सबै ठाउँमा `error`; `no-explicit-any` = `open-sse/` र `tests/` मा `warn`, अन्यत्र error। - **TypeScript**: `strict: false` (legacy posture)। Cross-module boundaries का लागि inference भन्दा explicit types लाई प्राथमिकता दिनुहोस्। - **Database**: routes वा handlers मा कहिल्यै raw SQL नलेख्नुहोस् — सधैं `src/lib/db/` modules मार्फत जानुहोस्। कहिल्यै barrel-import नगर्नुहोस् — निश्चित `src/lib/db/*` modules प्रत्यक्ष प्रयोग गर्नुहोस्। - **DB-entity typing (#3512)**: DB table को row shape लेख्ने वा पढ्ने function ले call site मा `any` वा inline anonymous type होइन, त्यस table का columns सँग 1:1 मेल खाने नाम दिइएको TS interface लिनु/फिर्ता गर्नुपर्छ। Interface लाई function को छेउमै राख्नुहोस् (जस्तै `saveRequestUsage` माथि `src/lib/usage/usageHistory.ts` मा `export interface UsageEntry`), फरक writers ले row लाई क्रमिक रूपमा populate गर्दा individual fields लाई optional/nullable राख्नुहोस्, र callers अनुसार shape फरक पर्ने field का लागि `any` भन्दा `unknown` लाई प्राथमिकता दिनुहोस् (field मै दस्तावेजीकरण गरिएको, जस्तै `UsageEntry.tokens` ले raw provider-shaped usage र normalized shape दुवै स्वीकार गर्छ)। यसरी कुनै file को `any` count शून्य पुगेपछि, त्यसलाई `check:any-budget:t11` allowlist (`scripts/check/check-t11-any-budget.mjs`, `maxAny: 0`) मा थप्नुहोस् ताकि regression हुन नसकोस्। यो first-slice convention हो — व्यापक "no anonymous `any`" cleanup बाँकी codebase भरि पुनरावृत्तिमूलक रूपमा गरिन्छ। - **Errors**: विशिष्ट error types सहित try/catch प्रयोग गर्नुहोस्, pino context सहित log गर्नुहोस्। SSE streams मा errors लाई कहिल्यै चुपचाप नदबाउनुहोस्; cleanup का लागि abort signals प्रयोग गर्नुहोस्। - **Security**: `eval()` / `new Function()` / implied eval कहिल्यै प्रयोग नगर्नुहोस्। सबै inputs लाई Zod मार्फत validate गर्नुहोस्। भण्डारणमा credentials encrypt गर्नुहोस् (AES-256-GCM)। `src/shared/constants/upstreamHeaders.ts` denylist लाई sanitize/validation layer सँग मिलाएर राख्नुहोस्। - **Commits**: Conventional Commits — `feat(scope): subject`। अनुमत scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`। - **Branches**: prefixes `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`। `main` मा कहिल्यै प्रत्यक्ष commit नगर्नुहोस्। - **Husky**: pre-commit ले `lint-staged` + `check:docs-sync` + `check:any-budget:t11` चलाउँछ; pre-push ले `check:any-budget:t11` + `check:tracked-artifacts` चलाउँछ (छिटो gates; `test:unit` समावेश हुँदैन)। --- ## 12. कडा नियमहरू (CLAUDE.md बाट) 1. गोप्य जानकारी वा प्रमाणहरू कहिल्यै कमिट नगर्नुहोस्। 2. कहिल्यै barrel-import नगर्नुहोस् — निश्चित `src/lib/db/*` मोड्युलहरू सीधै प्रयोग गर्नुहोस्। 3. `eval()` / `new Function()` / निहित eval कहिल्यै प्रयोग नगर्नुहोस्। 4. `main` मा कहिल्यै सीधै कमिट नगर्नुहोस्। 5. रुटहरूमा कहिल्यै raw SQL नलेख्नुहोस् — सधैं `src/lib/db/` मोड्युलहरूबाट जानुहोस्। 6. SSE स्ट्रिमहरूमा त्रुटिहरूलाई कहिल्यै चुपचाप बेवास्ता नगर्नुहोस्। 7. इनपुटहरूलाई सधैं Zod स्किमाहरूद्वारा प्रमाणीकरण गर्नुहोस्। 8. उत्पादन कोड परिवर्तन गर्दा सधैं परीक्षणहरू समावेश गर्नुहोस्। 9. कभरेज ≥ 60% कायम रहनुपर्छ (स्टेटमेन्टहरू, लाइनहरू, फङ्सनहरू, ब्रान्चहरू)। --- ## 13. यो पनि हेर्नुहोस् - [ARCHITECTURE.md](./ARCHITECTURE.md) — उच्च-स्तरीय आर्किटेक्चर र मोड्युलका जिम्मेवारीहरू। - [API_REFERENCE.md](../reference/API_REFERENCE.md) — सार्वजनिक + व्यवस्थापन API सन्दर्भ। - [FEATURES.md](../guides/FEATURES.md) — फिचर म्याट्रिक्स र संस्करणका मुख्य विशेषताहरू। - [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — circuit breaker, cooldown, र lockout को गहन विवरण। - [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — Auto Combo स्कोरिङ र रणनीतिहरू। - [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — पूर्ण MCP टुल सूची + ट्रान्सपोर्टहरू। - [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — A2A प्रोटोकलका सीपहरू र डिस्कभरी। - [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK + Caveman कम्प्रेसन। - [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI एकीकरणहरू। - [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (उपलब्ध भएमा), [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md), [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — डिप्लोयमेन्ट लक्ष्यहरू। - [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — सञ्चालनसम्बन्धी सामान्य समस्याहरू। - [CONTRIBUTING.md](../../CONTRIBUTING.md) — योगदानकर्ताको कार्यप्रवाह। - [CLAUDE.md](../../CLAUDE.md) — Claude Code का लागि रिपोजिटरी नियमहरू (माथिका धेरै परिपाटीहरूको आधिकारिक स्रोत)। - [AGENTS.md](../../AGENTS.md) — एजेन्टहरूले प्रयोग गर्ने थप गहन आर्किटेक्चर सन्दर्भ।