# ओमनीरूट आर्किटेक्चर

🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md)

_अंतिम अद्यतन: 2026-02-18_

## कार्यकारी सारांश

ओमनीरूट एक स्थानीय एआई रूटिंग गेटवे और नेक्स्ट.जेएस पर निर्मित डैशबोर्ड है।
यह एक एकल OpenAI-संगत एंडपॉइंट (`/v1/*`) प्रदान करता है और अनुवाद, फ़ॉलबैक, टोकन रिफ्रेश और उपयोग ट्रैकिंग के साथ कई अपस्ट्रीम प्रदाताओं के बीच ट्रैफ़िक को रूट करता है।

मुख्य क्षमताएं:

- सीएलआई/टूल्स के लिए ओपनएआई-संगत एपीआई सतह (28 प्रदाता)
- प्रदाता प्रारूपों में अनुरोध/प्रतिक्रिया अनुवाद
- मॉडल कॉम्बो फ़ॉलबैक (मल्टी-मॉडल अनुक्रम)
- खाता-स्तरीय फ़ॉलबैक (प्रति प्रदाता बहु-खाता)
- OAuth + एपीआई-कुंजी प्रदाता कनेक्शन प्रबंधन
- `/v1/embeddings` के माध्यम से एम्बेडिंग पीढ़ी (6 प्रदाता, 9 मॉडल)
- `/v1/images/generations` के माध्यम से छवि निर्माण (4 प्रदाता, 9 मॉडल)
- तर्क मॉडल के लिए टैग पार्सिंग (`<think>...</think>`) के बारे में सोचें
- सख्त ओपनएआई एसडीके संगतता के लिए प्रतिक्रिया स्वच्छता
- क्रॉस-प्रदाता अनुकूलता के लिए भूमिका सामान्यीकरण (डेवलपर→सिस्टम, सिस्टम→उपयोगकर्ता)।
- संरचित आउटपुट रूपांतरण (json_schema → जेमिनी रिस्पॉन्सस्कीमा)
- प्रदाताओं, चाबियाँ, उपनाम, कॉम्बो, सेटिंग्स, मूल्य निर्धारण के लिए स्थानीय दृढ़ता
- उपयोग/लागत ट्रैकिंग और अनुरोध लॉगिंग
- मल्टी-डिवाइस/स्टेट सिंक के लिए वैकल्पिक क्लाउड सिंक
- एपीआई एक्सेस नियंत्रण के लिए आईपी अनुमति सूची/ब्लॉकलिस्ट
- सोच बजट प्रबंधन (पासथ्रू/ऑटो/कस्टम/अनुकूली)
- वैश्विक प्रणाली शीघ्र इंजेक्शन
- सत्र ट्रैकिंग और फ़िंगरप्रिंटिंग
- प्रदाता-विशिष्ट प्रोफाइल के साथ प्रति-खाता बढ़ी हुई दर सीमित करना
- प्रदाता लचीलेपन के लिए सर्किट ब्रेकर पैटर्न
- म्यूटेक्स लॉकिंग के साथ एंटी-थंडरिंग झुंड सुरक्षा
- हस्ताक्षर-आधारित अनुरोध डिडुप्लीकेशन कैश
- डोमेन परत: मॉडल उपलब्धता, लागत नियम, फ़ॉलबैक नीति, लॉकआउट नीति
- डोमेन स्थिति दृढ़ता (फ़ॉलबैक, बजट, लॉकआउट, सर्किट ब्रेकर के लिए SQLite राइट-थ्रू कैश)
- केंद्रीकृत अनुरोध मूल्यांकन के लिए नीति इंजन (लॉकआउट → बजट → फ़ॉलबैक)
- p50/p95/p99 विलंबता एकत्रीकरण के साथ टेलीमेट्री का अनुरोध करें
- एंड-टू-एंड ट्रेसिंग के लिए सहसंबंध आईडी (एक्स-रिक्वेस्ट-आईडी)।
- एपीआई कुंजी के अनुसार ऑप्ट-आउट के साथ अनुपालन ऑडिट लॉगिंग
- एलएलएम गुणवत्ता आश्वासन के लिए इवल फ्रेमवर्क
- वास्तविक समय सर्किट ब्रेकर स्थिति के साथ लचीलापन यूआई डैशबोर्ड
- मॉड्यूलर OAuth प्रदाता (`src/lib/oauth/providers/` के अंतर्गत 12 व्यक्तिगत मॉड्यूल)

प्राथमिक रनटाइम मॉडल:

- `src/app/api/*` के अंतर्गत Next.js ऐप रूट डैशबोर्ड एपीआई और संगतता एपीआई दोनों को लागू करते हैं
- `src/sse/*` + `open-sse/*` में एक साझा SSE/रूटिंग कोर प्रदाता निष्पादन, अनुवाद, स्ट्रीमिंग, फ़ॉलबैक और उपयोग को संभालता है

## दायरा और सीमाएँ

### दायरे में

- स्थानीय गेटवे रनटाइम
- डैशबोर्ड प्रबंधन एपीआई
- प्रदाता प्रमाणीकरण और टोकन ताज़ा करें
- अनुवाद और एसएसई स्ट्रीमिंग का अनुरोध करें
- स्थानीय स्थिति + उपयोग की दृढ़ता
- वैकल्पिक क्लाउड सिंक ऑर्केस्ट्रेशन

### दायरे से बाहर

- `NEXT_PUBLIC_CLOUD_URL` के पीछे क्लाउड सेवा कार्यान्वयन
- स्थानीय प्रक्रिया के बाहर प्रदाता एसएलए/नियंत्रण विमान
- बाहरी सीएलआई बायनेरिज़ स्वयं (क्लाउड सीएलआई, कोडेक्स सीएलआई, आदि)

## उच्च स्तरीय सिस्टम संदर्भ

```mermaid
flowchart LR
    subgraph Clients[Developer Clients]
        C1[Claude Code]
        C2[Codex CLI]
        C3[OpenClaw / Droid / Cline / Continue / Roo]
        C4[Custom OpenAI-compatible clients]
        BROWSER[Browser Dashboard]
    end

    subgraph Router[OmniRoute Local Process]
        API[V1 Compatibility API\n/v1/*]
        DASH[Dashboard + Management API\n/api/*]
        CORE[SSE + Translation Core\nopen-sse + src/sse]
        DB[(db.json)]
        UDB[(usage.json + log.txt)]
    end

    subgraph Upstreams[Upstream Providers]
        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
    end

    subgraph Cloud[Optional Cloud Sync]
        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
    end

    C1 --> API
    C2 --> API
    C3 --> API
    C4 --> API
    BROWSER --> DASH

    API --> CORE
    DASH --> DB
    CORE --> DB
    CORE --> UDB

    CORE --> P1
    CORE --> P2
    CORE --> P3

    DASH --> CLOUD
```

## कोर रनटाइम घटक

## 1) एपीआई और रूटिंग लेयर (नेक्स्ट.जेएस ऐप रूट्स)

मुख्य निर्देशिकाएँ:

- अनुकूलता एपीआई के लिए `src/app/api/v1/*` और `src/app/api/v1beta/*`
- प्रबंधन/कॉन्फ़िगरेशन एपीआई के लिए `src/app/api/*`
- अगला `next.config.mjs` मानचित्र `/v1/*` से `/api/v1/*` में पुनः लिखता है

महत्वपूर्ण अनुकूलता मार्ग:

-
- `src/app/api/v1/messages/route.ts`
- `src/app/api/v1/responses/route.ts`
- `src/app/api/v1/models/route.ts` - `custom: true` के साथ कस्टम मॉडल शामिल हैं
- `src/app/api/v1/embeddings/route.ts` - एम्बेडिंग जेनरेशन (6 प्रदाता)
- `src/app/api/v1/images/generations/route.ts` - छवि निर्माण (एंटीग्रेविटी/नेबियस सहित 4+ प्रदाता)
- `src/app/api/v1/messages/count_tokens/route.ts`
- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` - प्रति-प्रदाता समर्पित चैट
- `src/app/api/v1/providers/[provider]/embeddings/route.ts` - प्रति-प्रदाता समर्पित एम्बेडिंग
- `src/app/api/v1/providers/[provider]/images/generations/route.ts` - प्रति-प्रदाता समर्पित छवियां
- `src/app/api/v1beta/models/route.ts`
- `src/app/api/v1beta/models/[...path]/route.ts`

प्रबंधन डोमेन:

- प्रमाणीकरण/सेटिंग्स: `src/app/api/auth/*`, `src/app/api/settings/*`
- प्रदाता/कनेक्शन: `src/app/api/providers*`
- प्रदाता नोड: `src/app/api/provider-nodes*`
- कस्टम मॉडल: `src/app/api/provider-models` (प्राप्त करें/पोस्ट करें/हटाएं)
- मॉडल कैटलॉग: `src/app/api/models/catalog` (प्राप्त करें)
- प्रॉक्सी कॉन्फ़िगरेशन: `src/app/api/settings/proxy` (प्राप्त/पुट/डिलीट) + `src/app/api/settings/proxy/test` (पोस्ट)
- OAuth: `src/app/api/oauth/*`
- कुंजी/उपनाम/कॉम्बोस/मूल्य निर्धारण: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
- उपयोग: `src/app/api/usage/*`
- सिंक/क्लाउड: `src/app/api/sync/*`, `src/app/api/cloud/*`
- सीएलआई टूलींग सहायक: `src/app/api/cli-tools/*`
- आईपी फ़िल्टर: `src/app/api/settings/ip-filter` (प्राप्त/पुट)
- सोच बजट: `src/app/api/settings/thinking-budget` (प्राप्त/पुट)
- सिस्टम प्रॉम्प्ट: `src/app/api/settings/system-prompt` (प्राप्त/पुट)
- सत्र: `src/app/api/sessions` (प्राप्त करें)
- दर सीमा: `src/app/api/rate-limits` (प्राप्त करें)
- लचीलापन: `src/app/api/resilience` (प्राप्त/पैच) - प्रदाता प्रोफ़ाइल, सर्किट ब्रेकर, दर सीमा स्थिति
- लचीलापन रीसेट: `src/app/api/resilience/reset` (पोस्ट) - ब्रेकर रीसेट करें + कूलडाउन
- कैश आँकड़े: `src/app/api/cache/stats` (प्राप्त करें/हटाएँ)
- मॉडल उपलब्धता: `src/app/api/models/availability` (प्राप्त करें/पोस्ट करें)
- टेलीमेट्री: `src/app/api/telemetry/summary` (प्राप्त करें)
- बजट: `src/app/api/usage/budget` (प्राप्त/पोस्ट करें)
- फ़ॉलबैक चेन: `src/app/api/fallback/chains` (प्राप्त करें/पोस्ट करें/हटाएँ)
- अनुपालन लेखापरीक्षा: `src/app/api/compliance/audit-log` (प्राप्त करें)
- मूल्यांकन: `src/app/api/evals` (प्राप्त/पोस्ट), `src/app/api/evals/[suiteId]` (प्राप्त करें)
- नीतियां: `src/app/api/policies` (प्राप्त/पोस्ट करें)

## 2) एसएसई + अनुवाद कोर

मुख्य प्रवाह मॉड्यूल:

- प्रवेश: `src/sse/handlers/chat.ts`
- कोर ऑर्केस्ट्रेशन: `open-sse/handlers/chatCore.ts`
- प्रदाता निष्पादन एडाप्टर: `open-sse/executors/*`
- प्रारूप पहचान/प्रदाता कॉन्फिगरेशन: `open-sse/services/provider.ts`
- मॉडल पार्स/रिज़ॉल्यूशन: `src/sse/services/model.ts`, `open-sse/services/model.ts`
- खाता फ़ॉलबैक तर्क: `open-sse/services/accountFallback.ts`
- अनुवाद रजिस्ट्री: `open-sse/translator/index.ts`
- स्ट्रीम परिवर्तन: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
- उपयोग निष्कर्षण/सामान्यीकरण: `open-sse/utils/usageTracking.ts`
- टैग पार्सर सोचें: `open-sse/utils/thinkTagParser.ts`
- एंबेडिंग हैंडलर: `open-sse/handlers/embeddings.ts`
- एंबेडिंग प्रदाता रजिस्ट्री: `open-sse/config/embeddingRegistry.ts`
- छवि निर्माण हैंडलर: `open-sse/handlers/imageGeneration.ts`
- छवि प्रदाता रजिस्ट्री: `open-sse/config/imageRegistry.ts`
- प्रतिक्रिया स्वच्छता: `open-sse/handlers/responseSanitizer.ts`
- भूमिका सामान्यीकरण: `open-sse/services/roleNormalizer.ts`

सेवाएँ (व्यावसायिक तर्क):

- खाता चयन/स्कोरिंग: `open-sse/services/accountSelector.ts`
- संदर्भ जीवनचक्र प्रबंधन: `open-sse/services/contextManager.ts`
- आईपी फ़िल्टर प्रवर्तन: `open-sse/services/ipFilter.ts`
- सत्र ट्रैकिंग: `open-sse/services/sessionManager.ts`
- डुप्लिकेशन अनुरोध: `open-sse/services/signatureCache.ts`
- सिस्टम प्रॉम्प्ट इंजेक्शन: `open-sse/services/systemPrompt.ts`
- सोच बजट प्रबंधन: `open-sse/services/thinkingBudget.ts`
- वाइल्डकार्ड मॉडल रूटिंग: `open-sse/services/wildcardRouter.ts`
- दर सीमा प्रबंधन: `open-sse/services/rateLimitManager.ts`
- सर्किट ब्रेकर: `open-sse/services/circuitBreaker.ts`

डोमेन परत मॉड्यूल:

- मॉडल उपलब्धता: `src/lib/domain/modelAvailability.ts`
- लागत नियम/बजट: `src/lib/domain/costRules.ts`
- फ़ॉलबैक नीति: `src/lib/domain/fallbackPolicy.ts`
- कॉम्बो रिज़ॉल्वर: `src/lib/domain/comboResolver.ts`
- तालाबंदी नीति: `src/lib/domain/lockoutPolicy.ts`
- नीति इंजन: `src/domain/policyEngine.ts` - केंद्रीकृत तालाबंदी → बजट → फ़ॉलबैक मूल्यांकन
- त्रुटि कोड सूची: `src/lib/domain/errorCodes.ts`
- अनुरोध आईडी: `src/lib/domain/requestId.ts`
- फ़ेच टाइमआउट: `src/lib/domain/fetchTimeout.ts`
- अनुरोध टेलीमेट्री: `src/lib/domain/requestTelemetry.ts`
- अनुपालन/ऑडिट: `src/lib/domain/compliance/index.ts`
- इवल धावक: `src/lib/domain/evalRunner.ts`
- डोमेन स्थिति दृढ़ता: `src/lib/db/domainState.ts` - फ़ॉलबैक चेन, बजट, लागत इतिहास, लॉकआउट स्थिति, सर्किट ब्रेकर के लिए SQLite CRUD

OAuth प्रदाता मॉड्यूल (`src/lib/oauth/providers/` के अंतर्गत 12 व्यक्तिगत फ़ाइलें):

- रजिस्ट्री सूचकांक: `src/lib/oauth/providers/index.ts`
- व्यक्तिगत प्रदाता: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
- पतला आवरण: `src/lib/oauth/providers.ts` - अलग-अलग मॉड्यूल से पुनः निर्यात

## 3) दृढ़ता परत

प्राथमिक स्थिति डीबी:

-
- फ़ाइल: `${DATA_DIR}/db.json` (या सेट होने पर `$XDG_CONFIG_HOME/omniroute/db.json`, अन्यथा `~/.omniroute/db.json`)
- संस्थाएँ: प्रदाता कनेक्शन, प्रदाता नोड्स, मॉडल उपनाम, कॉम्बो, एपीकीज़, सेटिंग्स, मूल्य निर्धारण, **कस्टम मॉडल**, **प्रॉक्सी कॉन्फिग**, **आईपीफिल्टर**, **थिंकिंगबजट**, **सिस्टमप्रॉम्प्ट**

उपयोग डीबी:

- `src/lib/usageDb.ts`
- फ़ाइलें: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
- `localDb` के समान मूल निर्देशिका नीति का पालन करता है (`DATA_DIR`, फिर सेट होने पर `XDG_CONFIG_HOME/omniroute`)
- केंद्रित उप-मॉड्यूल में विघटित: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts`

डोमेन स्थिति DB (SQLite):

- `src/lib/db/domainState.ts` - डोमेन स्थिति के लिए CRUD संचालन
- तालिकाएँ (`src/lib/db/core.ts` में निर्मित): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
- राइट-थ्रू कैश पैटर्न: इन-मेमोरी मैप्स रनटाइम पर आधिकारिक होते हैं; उत्परिवर्तन SQLite के साथ समकालिक रूप से लिखे जाते हैं; कोल्ड स्टार्ट पर राज्य को डीबी से बहाल किया जाता है

## 4) प्रामाणिक + सुरक्षा सतहें

- डैशबोर्ड कुकी प्रमाणीकरण: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
- एपीआई कुंजी निर्माण/सत्यापन: `src/shared/utils/apiKey.ts`
- प्रदाता रहस्य `providerConnections` प्रविष्टियों में बने रहे
- `open-sse/utils/proxyFetch.ts` (env vars) और `open-sse/utils/networkProxy.ts` (प्रति-प्रदाता या वैश्विक रूप से कॉन्फ़िगर करने योग्य) के माध्यम से आउटबाउंड प्रॉक्सी समर्थन

## 5) क्लाउड सिंक

- शेड्यूलर init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
- आवधिक कार्य: `src/shared/services/cloudSyncScheduler.ts`
- नियंत्रण मार्ग: `src/app/api/sync/cloud/route.ts`

## अनुरोध जीवनचक्र (`/v1/chat/completions`)

## कॉम्बो + अकाउंट फ़ॉलबैक फ़्लो

```mermaid
flowchart TD
    A[Incoming model string] --> B{Is combo name?}
    B -- Yes --> C[Load combo models sequence]
    B -- No --> D[Single model path]

    C --> E[Try model N]
    E --> F[Resolve provider/model]
    D --> F

    F --> G[Select account credentials]
    G --> H{Credentials available?}
    H -- No --> I[Return provider unavailable]
    H -- Yes --> J[Execute request]

    J --> K{Success?}
    K -- Yes --> L[Return response]
    K -- No --> M{Fallback-eligible error?}

    M -- No --> N[Return error]
    M -- Yes --> O[Mark account unavailable cooldown]
    O --> P{Another account for provider?}
    P -- Yes --> G
    P -- No --> Q{In combo with next model?}
    Q -- Yes --> E
    Q -- No --> R[Return all unavailable]
```

फ़ॉलबैक निर्णय स्थिति कोड और त्रुटि-संदेश अनुमानों का उपयोग करके `open-sse/services/accountFallback.ts` द्वारा संचालित होते हैं।

## OAuth ऑनबोर्डिंग और टोकन रिफ्रेश जीवनचक्र

```mermaid
sequenceDiagram
    autonumber
    participant UI as Dashboard UI
    participant OAuth as /api/oauth/[provider]/[action]
    participant ProvAuth as Provider Auth Server
    participant DB as localDb
    participant Test as /api/providers/[id]/test
    participant Exec as Provider Executor

    UI->>OAuth: GET authorize or device-code
    OAuth->>ProvAuth: create auth/device flow
    ProvAuth-->>OAuth: auth URL or device code payload
    OAuth-->>UI: flow data

    UI->>OAuth: POST exchange or poll
    OAuth->>ProvAuth: token exchange/poll
    ProvAuth-->>OAuth: access/refresh tokens
    OAuth->>DB: createProviderConnection(oauth data)
    OAuth-->>UI: success + connection id

    UI->>Test: POST /api/providers/[id]/test
    Test->>Exec: validate credentials / optional refresh
    Exec-->>Test: valid or refreshed token info
    Test->>DB: update status/tokens/errors
    Test-->>UI: validation result
```

लाइव ट्रैफ़िक के दौरान रिफ्रेश को निष्पादक `refreshCredentials()` के माध्यम से `open-sse/handlers/chatCore.ts` के अंदर निष्पादित किया जाता है।

## क्लाउड सिंक जीवनचक्र (सक्षम/सिंक/अक्षम)

```mermaid
sequenceDiagram
    autonumber
    participant UI as Endpoint Page UI
    participant Sync as /api/sync/cloud
    participant DB as localDb
    participant Cloud as External Cloud Sync
    participant Claude as ~/.claude/settings.json

    UI->>Sync: POST action=enable
    Sync->>DB: set cloudEnabled=true
    Sync->>DB: ensure API key exists
    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
    Cloud-->>Sync: sync result
    Sync->>Cloud: GET /{machineId}/v1/verify
    Sync-->>UI: enabled + verification status

    UI->>Sync: POST action=sync
    Sync->>Cloud: POST /sync/{machineId}
    Cloud-->>Sync: remote data
    Sync->>DB: update newer local tokens/status
    Sync-->>UI: synced

    UI->>Sync: POST action=disable
    Sync->>DB: set cloudEnabled=false
    Sync->>Cloud: DELETE /sync/{machineId}
    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
    Sync-->>UI: disabled
```

क्लाउड सक्षम होने पर आवधिक सिंक `CloudSyncScheduler` द्वारा ट्रिगर किया जाता है।

## डेटा मॉडल और स्टोरेज मैप

भौतिक भंडारण फ़ाइलें:

- मुख्य स्थिति: `${DATA_DIR}/db.json` (या सेट होने पर `$XDG_CONFIG_HOME/omniroute/db.json`, अन्यथा `~/.omniroute/db.json`)
- उपयोग आँकड़े: `${DATA_DIR}/usage.json`
- अनुरोध लॉग लाइनें: `${DATA_DIR}/log.txt`
- वैकल्पिक अनुवादक/अनुरोध डिबग सत्र: `<repo>/logs/...`

## परिनियोजन टोपोलॉजी

## मॉड्यूल मैपिंग (निर्णय-महत्वपूर्ण)

### रूट और एपीआई मॉड्यूल

- `src/app/api/v1/*`, `src/app/api/v1beta/*`: अनुकूलता एपीआई
- `src/app/api/v1/providers/[provider]/*`: प्रति-प्रदाता समर्पित मार्ग (चैट, एम्बेडिंग, चित्र)
- `src/app/api/providers*`: प्रदाता CRUD, सत्यापन, परीक्षण
- `src/app/api/provider-nodes*`: कस्टम संगत नोड प्रबंधन
- `src/app/api/provider-models`: कस्टम मॉडल प्रबंधन (CRUD)
- `src/app/api/models/catalog`: पूर्ण मॉडल कैटलॉग एपीआई (प्रदाता द्वारा समूहीकृत सभी प्रकार)
- `src/app/api/oauth/*`: OAuth/डिवाइस-कोड प्रवाह
- `src/app/api/keys*`: स्थानीय एपीआई कुंजी जीवनचक्र
- `src/app/api/models/alias`: उपनाम प्रबंधन
- `src/app/api/combos*`: फ़ॉलबैक कॉम्बो प्रबंधन
- `src/app/api/pricing`: लागत गणना के लिए मूल्य निर्धारण ओवरराइड होता है
- `src/app/api/settings/proxy`: प्रॉक्सी कॉन्फ़िगरेशन (प्राप्त/पुट/हटाएं)
- `src/app/api/settings/proxy/test`: आउटबाउंड प्रॉक्सी कनेक्टिविटी टेस्ट (POST)
- `src/app/api/usage/*`: एपीआई का उपयोग और लॉग
- `src/app/api/sync/*` + `src/app/api/cloud/*`: क्लाउड सिंक और क्लाउड-फेसिंग सहायक
- `src/app/api/cli-tools/*`: स्थानीय सीएलआई कॉन्फ़िगरेशन लेखक/चेकर्स
- `src/app/api/settings/ip-filter`: आईपी अनुमति सूची/ब्लॉकलिस्ट (प्राप्त/पुट)
- `src/app/api/settings/thinking-budget`: सोच टोकन बजट कॉन्फ़िगरेशन (प्राप्त/पुट)
- `src/app/api/settings/system-prompt`: ग्लोबल सिस्टम प्रॉम्प्ट (प्राप्त/पुट)
- `src/app/api/sessions`: सक्रिय सत्र सूची (प्राप्त करें)
- `src/app/api/rate-limits`: प्रति खाता दर सीमा स्थिति (GET)

### रूटिंग और निष्पादन कोर

- `src/sse/handlers/chat.ts`: अनुरोध पार्स, कॉम्बो हैंडलिंग, खाता चयन लूप
- `open-sse/handlers/chatCore.ts`: अनुवाद, निष्पादक प्रेषण, पुनः प्रयास/रीफ्रेश हैंडलिंग, स्ट्रीम सेटअप
- `open-sse/executors/*`: प्रदाता-विशिष्ट नेटवर्क और प्रारूप व्यवहार

### अनुवाद रजिस्ट्री और प्रारूप परिवर्तक

- `open-sse/translator/index.ts`: अनुवादक रजिस्ट्री और ऑर्केस्ट्रेशन
- अनुवादकों के लिए अनुरोध: `open-sse/translator/request/*`
- प्रतिक्रिया अनुवादक: `open-sse/translator/response/*`
- प्रारूप स्थिरांक: `open-sse/translator/formats.ts`

### दृढ़ता

- `src/lib/localDb.ts`: लगातार कॉन्फ़िगरेशन/स्थिति
- `src/lib/usageDb.ts`: उपयोग इतिहास और रोलिंग अनुरोध लॉग

## प्रदाता निष्पादक कवरेज (रणनीति पैटर्न)

प्रत्येक प्रदाता के पास `BaseExecutor` (`open-sse/executors/base.ts` में) का विस्तार करने वाला एक विशेष निष्पादक होता है, जो URL निर्माण, हेडर निर्माण, घातीय बैकऑफ़ के साथ पुनः प्रयास, क्रेडेंशियल रिफ्रेश हुक और `execute()` ऑर्केस्ट्रेशन विधि प्रदान करता है।

| निष्पादक              | प्रदाता(ओं)                                                                                                                                                                  | विशेष हैंडलिंग                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `DefaultExecutor`     | ओपनएआई, क्लाउड, जेमिनी, क्वेन, आईफ्लो, ओपनराउटर, जीएलएम, किमी, मिनीमैक्स, डीपसीक, ग्रोक, एक्सएआई, मिस्ट्रल, पर्प्लेक्सिटी, टुगेदर, फायरवर्क्स, सेरेब्रा, कोहेरे, एनवीआईडीआईए | प्रति प्रदाता डायनामिक यूआरएल/हेडर कॉन्फिगरेशन                                          |
| `AntigravityExecutor` | गूगल एंटीग्रेविटी                                                                                                                                                            | कस्टम प्रोजेक्ट/सत्र आईडी, पुनः प्रयास करें-पार्सिंग के बाद                             |
| `CodexExecutor`       | ओपनएआई कोडेक्स                                                                                                                                                               | सिस्टम निर्देश इंजेक्ट करता है, तर्क करने का प्रयास करता है                             |
| `CursorExecutor`      | कर्सर आईडीई                                                                                                                                                                  | कनेक्टआरपीसी प्रोटोकॉल, प्रोटोबफ एन्कोडिंग, चेकसम के माध्यम से हस्ताक्षर करने का अनुरोध |
| `GithubExecutor`      | गिटहब कोपायलट                                                                                                                                                                | कोपायलट टोकन ताज़ा करें, VSCode-नकल हेडर                                                |
| `KiroExecutor`        | एडब्ल्यूएस कोडव्हिस्परर/किरो                                                                                                                                                 | एडब्ल्यूएस इवेंटस्ट्रीम बाइनरी प्रारूप → एसएसई रूपांतरण                                 |
| `GeminiCLIExecutor`   | जेमिनी सीएलआई                                                                                                                                                                | Google OAuth टोकन ताज़ा चक्र                                                            |

अन्य सभी प्रदाता (कस्टम संगत नोड्स सहित) `DefaultExecutor` का उपयोग करते हैं।

## प्रदाता संगतता मैट्रिक्स

| प्रदाता               | प्रारूप              | प्रामाणिक                | स्ट्रीम           | नॉन-स्ट्रीम | टोकन ताज़ा करें | उपयोग एपीआई         |
| --------------------- | -------------------- | ------------------------ | ----------------- | ----------- | --------------- | ------------------- |
| क्लाउड                | क्लाउड               | एपीआई कुंजी / OAuth      | ✅                | ✅          | ✅              | ⚠️ केवल एडमिन       |
| मिथुन                 | मिथुन                | एपीआई कुंजी / OAuth      | ✅                | ✅          | ✅              | ⚠️ क्लाउड कंसोल     |
| जेमिनी सीएलआई         | मिथुन-क्ली           | OAuth                    | ✅                | ✅          | ✅              | ⚠️ क्लाउड कंसोल     |
| प्रतिगुरुत्वाकर्षण    | प्रतिगुरुत्वाकर्षण   | OAuth                    | ✅                | ✅          | ✅              | ✅ पूर्ण कोटा एपीआई |
| ओपनएआई                | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| कोडेक्स               | openai-प्रतिक्रियाएं | OAuth                    | ✅ मजबूर          | ❌          | ✅              | ✅ दर सीमा          |
| गिटहब कोपायलट         | ओपनाई                | OAuth + सहपायलट टोकन     | ✅                | ✅          | ✅              | ✅ कोटा स्नैपशॉट    |
| कर्सर                 | कर्सर                | कस्टम चेकसम              | ✅                | ✅          | ❌              | ❌                  |
| किरो                  | किरो                 | एडब्ल्यूएस एसएसओ ओआईडीसी | ✅ (इवेंटस्ट्रीम) | ❌          | ✅              | ✅ उपयोग सीमा       |
| क्वेन                 | ओपनाई                | OAuth                    | ✅                | ✅          | ✅              | ⚠️ प्रति अनुरोध     |
| आईफ्लो                | ओपनाई                | OAuth (बेसिक)            | ✅                | ✅          | ✅              | ⚠️ प्रति अनुरोध     |
| ओपनराउटर              | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| जीएलएम/किमी/मिनीमैक्स | क्लाउड               | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| डीपसीक                | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| ग्रोक                 | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| एक्सएआई (ग्रोक)       | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| मिस्ट्रल              | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| उलझन                  | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| एक साथ एआई            | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| आतिशबाजी एआई          | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| सेरेब्रस              | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| सहभागी                | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |
| एनवीडिया एनआईएम       | ओपनाई                | एपीआई कुंजी              | ✅                | ✅          | ❌              | ❌                  |

## प्रारूप अनुवाद कवरेज

पता लगाए गए स्रोत प्रारूपों में शामिल हैं:

- `openai`
- `openai-responses`
- `claude`
- `gemini`

लक्ष्य प्रारूपों में शामिल हैं:

- ओपनएआई चैट/प्रतिक्रियाएं
  -क्लाउड
- मिथुन/मिथुन-सीएलआई/एंटीग्रेविटी लिफाफा
- किरो
- कर्सर

अनुवाद **हब प्रारूप के रूप में ओपनएआई** का उपयोग करते हैं - सभी रूपांतरण मध्यवर्ती के रूप में ओपनएआई से गुजरते हैं:

```
Source Format → OpenAI (hub) → Target Format
```

स्रोत पेलोड आकार और प्रदाता लक्ष्य प्रारूप के आधार पर अनुवादों का चयन गतिशील रूप से किया जाता है।

अनुवाद पाइपलाइन में अतिरिक्त प्रसंस्करण परतें:

- **प्रतिक्रिया स्वच्छता** - सख्त एसडीके अनुपालन सुनिश्चित करने के लिए ओपनएआई-प्रारूप प्रतिक्रियाओं (स्ट्रीमिंग और गैर-स्ट्रीमिंग दोनों) से गैर-मानक फ़ील्ड हटा देता है
- **भूमिका सामान्यीकरण** - गैर-ओपनएआई लक्ष्यों के लिए `developer` → `system` परिवर्तित करता है; सिस्टम भूमिका को अस्वीकार करने वाले मॉडलों के लिए `system` → `user` का विलय (GLM, ERNIE)
- **टैग निष्कर्षण के बारे में सोचें** - पार्स `<think>...</think>` सामग्री को `reasoning_content` फ़ील्ड में ब्लॉक करता है
- **संरचित आउटपुट** - OpenAI `response_format.json_schema` को मिथुन के `responseMimeType` + `responseSchema` में परिवर्तित करता है

## समर्थित एपीआई समापन बिंदु

| समापन बिंदु                                        | प्रारूप              | हैंडलर                                             |
| -------------------------------------------------- | -------------------- | -------------------------------------------------- | ------------------------ |
| `POST /v1/chat/completions`                        | ओपनएआई चैट           | `src/sse/handlers/chat.ts`                         |
| `POST /v1/messages`                                | क्लाउड संदेश         | वही हैंडलर (स्वतः पता चला)                         |
| `POST /v1/responses`                               | ओपनएआई प्रतिक्रियाएँ | `open-sse/handlers/responsesHandler.ts`            |
| `POST /v1/embeddings`                              | ओपनएआई एंबेडिंग्स    | `open-sse/handlers/embeddings.ts`                  |
| `GET /v1/embeddings`                               | मॉडल सूची            | एपीआई मार्ग                                        |
| `POST /v1/images/generations`                      | OpenAI छवियाँ        |                                                    |
| `GET /v1/images/generations`                       | मॉडल सूची            | एपीआई मार्ग                                        |
| `POST /v1/providers/{provider}/chat/completions`   | ओपनएआई चैट           | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित          |
|                                                    | ओपनएआई एंबेडिंग्स    | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित          |
| `POST /v1/providers/{provider}/images/generations` | OpenAI छवियाँ        | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित          |
| `POST /v1/messages/count_tokens`                   | क्लाउड टोकन गिनती    | एपीआई मार्ग                                        |
|                                                    | OpenAI मॉडल सूची     | एपीआई मार्ग (चैट + एम्बेडिंग + छवि + कस्टम मॉडल)   |
| `GET /api/models/catalog`                          | कैटलॉग               | प्रदाता + प्रकार                                   | द्वारा समूहीकृत सभी मॉडल |
| `POST /v1beta/models/*:streamGenerateContent`      | मिथुन राशि के जातक   | एपीआई मार्ग                                        |
|                                                    | प्रॉक्सी कॉन्फिग     | नेटवर्क प्रॉक्सी कॉन्फ़िगरेशन                      |
|                                                    | प्रॉक्सी कनेक्टिविटी | प्रॉक्सी स्वास्थ्य/कनेक्टिविटी परीक्षण समापन बिंदु |
|                                                    | कस्टम मॉडल           | प्रति प्रदाता कस्टम मॉडल प्रबंधन                   |

## बायपास हैंडलर

बाईपास हैंडलर (`open-sse/utils/bypassHandler.ts`) क्लाउड सीएलआई से ज्ञात "थ्रोअवे" अनुरोधों को रोकता है - वार्मअप पिंग, शीर्षक निष्कर्षण, और टोकन गिनती - और अपस्ट्रीम प्रदाता टोकन का उपभोग किए बिना **नकली प्रतिक्रिया** लौटाता है। यह तभी ट्रिगर होता है जब `User-Agent` में `claude-cli` होता है।

## लॉगर पाइपलाइन का अनुरोध करें

अनुरोध लकड़हारा (`open-sse/utils/requestLogger.ts`) एक 7-चरण डीबग लॉगिंग पाइपलाइन प्रदान करता है, जो डिफ़ॉल्ट रूप से अक्षम है, `ENABLE_REQUEST_LOGS=true` के माध्यम से सक्षम है:

प्रत्येक अनुरोध सत्र के लिए फ़ाइलें `<repo>/logs/<session>/` पर लिखी जाती हैं।

## विफलता के तरीके और लचीलापन

## 1) खाता/प्रदाता उपलब्धता

- क्षणिक/दर/प्रामाणिक त्रुटियों पर प्रदाता खाता ठंडा हो गया
- अनुरोध विफल होने से पहले खाता फ़ॉलबैक
- वर्तमान मॉडल/प्रदाता पथ समाप्त होने पर कॉम्बो मॉडल फ़ॉलबैक

## 2) टोकन समाप्ति

- ताज़ा करने योग्य प्रदाताओं के लिए पुनः प्रयास के साथ पूर्व-जांच और ताज़ा करें
- कोर पथ में ताज़ा प्रयास के बाद 401/403 पुनः प्रयास करें

## 3) स्ट्रीम सुरक्षा

- डिस्कनेक्ट-अवेयर स्ट्रीम नियंत्रक
- एंड-ऑफ-स्ट्रीम फ्लश और `[DONE]` हैंडलिंग के साथ अनुवाद स्ट्रीम
- प्रदाता उपयोग मेटाडेटा अनुपलब्ध होने पर उपयोग अनुमान फ़ॉलबैक

## 4) क्लाउड सिंक गिरावट

- समन्वयन त्रुटियाँ सामने आती हैं लेकिन स्थानीय रनटाइम जारी रहता है
- शेड्यूलर में पुनः प्रयास-सक्षम तर्क है, लेकिन आवधिक निष्पादन वर्तमान में डिफ़ॉल्ट रूप से एकल-प्रयास सिंक को कॉल करता है

## 5) डेटा इंटीग्रिटी

- गुम चाबियों के लिए डीबी आकार माइग्रेशन/मरम्मत
- लोकलडीबी और यूज़डीबी के लिए भ्रष्ट JSON रीसेट सुरक्षा उपाय

## अवलोकनशीलता और परिचालन संकेत

रनटाइम दृश्यता स्रोत:

- `src/sse/utils/logger.ts` से कंसोल लॉग
- `usage.json` में प्रति-अनुरोध उपयोग समुच्चय
- पाठ्य अनुरोध स्थिति लॉग इन `log.txt`
- `logs/` के अंतर्गत वैकल्पिक गहन अनुरोध/अनुवाद लॉग जब `ENABLE_REQUEST_LOGS=true`
- यूआई खपत के लिए डैशबोर्ड उपयोग समापन बिंदु (`/api/usage/*`)।

## सुरक्षा-संवेदनशील सीमाएँ

- JWT सीक्रेट (`JWT_SECRET`) डैशबोर्ड सत्र कुकी सत्यापन/हस्ताक्षर को सुरक्षित करता है
- प्रारंभिक पासवर्ड फ़ॉलबैक (`INITIAL_PASSWORD`, डिफ़ॉल्ट `123456`) को वास्तविक परिनियोजन में ओवरराइड किया जाना चाहिए
- एपीआई कुंजी एचएमएसी रहस्य (`API_KEY_SECRET`) उत्पन्न स्थानीय एपीआई कुंजी प्रारूप को सुरक्षित करता है
- प्रदाता रहस्य (एपीआई कुंजी/टोकन) स्थानीय डीबी में बने रहते हैं और उन्हें फ़ाइल सिस्टम स्तर पर संरक्षित किया जाना चाहिए
- क्लाउड सिंक एंडपॉइंट एपीआई कुंजी ऑथ + मशीन आईडी सेमेन्टिक्स पर निर्भर करते हैं

## पर्यावरण और रनटाइम मैट्रिक्स

कोड द्वारा सक्रिय रूप से उपयोग किए जाने वाले पर्यावरण चर:

- ऐप/ऑथ: `JWT_SECRET`, `INITIAL_PASSWORD`
- भंडारण: `DATA_DIR`
- संगत नोड व्यवहार: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
- वैकल्पिक स्टोरेज बेस ओवरराइड (लिनक्स/मैकओएस जब `DATA_DIR` सेट न हो): `XDG_CONFIG_HOME`
- सुरक्षा हैशिंग: `API_KEY_SECRET`, `MACHINE_ID_SALT`
- लॉगिंग: `ENABLE_REQUEST_LOGS`
- सिंक/क्लाउड यूआरएल: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
- आउटबाउंड प्रॉक्सी: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` और लोअरकेस वेरिएंट
- SOCKS5 फ़ीचर फ़्लैग: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
- प्लेटफ़ॉर्म/रनटाइम सहायक (ऐप-विशिष्ट कॉन्फ़िगरेशन नहीं): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`

## ज्ञात वास्तुशिल्प नोट्स

1. `usageDb` और `localDb` अब लीगेसी फ़ाइल माइग्रेशन के साथ समान आधार निर्देशिका नीति (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) साझा करते हैं।
2. `/api/v1/route.ts` एक स्थिर मॉडल सूची लौटाता है और यह `/v1/models` द्वारा उपयोग किया जाने वाला मुख्य मॉडल स्रोत नहीं है।
3. अनुरोध लकड़हारा सक्षम होने पर पूर्ण हेडर/बॉडी लिखता है; लॉग निर्देशिका को संवेदनशील मानें।
4. क्लाउड व्यवहार सही `NEXT_PUBLIC_BASE_URL` और क्लाउड एंडपॉइंट रीचैबिलिटी पर निर्भर करता है।
5. `open-sse/` निर्देशिका को `@omniroute/open-sse` **npm कार्यक्षेत्र पैकेज** के रूप में प्रकाशित किया गया है। स्रोत कोड इसे `@omniroute/open-sse/...` के माध्यम से आयात करता है (Next.js `transpilePackages` द्वारा हल किया गया)। इस दस्तावेज़ में फ़ाइल पथ अभी भी स्थिरता के लिए निर्देशिका नाम `open-sse/` का उपयोग करते हैं।
6. डैशबोर्ड में चार्ट सुलभ, इंटरैक्टिव एनालिटिक्स विज़ुअलाइज़ेशन (मॉडल उपयोग बार चार्ट, सफलता दर के साथ प्रदाता ब्रेकडाउन टेबल) के लिए **रिचार्ट्स** (एसवीजी-आधारित) का उपयोग करते हैं।
7. E2E परीक्षण **Playwright** (`tests/e2e/`) का उपयोग करते हैं, `npm run test:e2e` के माध्यम से चलते हैं। यूनिट परीक्षण **Node.js टेस्ट रनर** (`tests/unit/`) का उपयोग करते हैं, जो `npm run test:plan3` के माध्यम से चलते हैं। `src/` के अंतर्गत स्रोत कोड **टाइपस्क्रिप्ट** (`.ts`/`.tsx`) है; `open-sse/` कार्यस्थान जावास्क्रिप्ट (`.js`) बना हुआ है।
8. सेटिंग्स पृष्ठ को 5 टैब में व्यवस्थित किया गया है: सुरक्षा, रूटिंग (6 वैश्विक रणनीतियाँ: भरण-प्रथम, राउंड-रॉबिन, पी2सी, यादृच्छिक, कम से कम उपयोग किया गया, लागत-अनुकूलित), लचीलापन (संपादन योग्य दर सीमा, सर्किट ब्रेकर, नीतियां), एआई (सोच बजट, सिस्टम प्रॉम्प्ट, प्रॉम्प्ट कैश), उन्नत (प्रॉक्सी)।

## परिचालन सत्यापन चेकलिस्ट

- स्रोत से निर्मित: `npm run build`
- डॉकर छवि बनाएं: `docker build -t omniroute .`
- सेवा प्रारंभ करें और सत्यापित करें:
- `GET /api/settings`
- `GET /api/v1/models`
- जब `PORT=20128` हो तो CLI लक्ष्य आधार URL `http://<host>:20128/v1` होना चाहिए
