OmniRoute/docs/i18n/ur/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 · 🇰🇭 km · 🇮🇳 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 · 🇺🇿 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، اسٹینڈ الون آؤٹ پٹ، کوئی عالمی مڈل ویئر نہیں)
زبان	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 پری کمیٹ کے ذریعے 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/               صرف سرور کے ماڈیولز (authz، cors، تصدیق)
├── shared/               اقسام، مستقلات، توثیق، معاہدے، یوٹیلٹیز (حدود کے پار محفوظ)
├── mitm/                 CLI انضمام کے لیے مین-اِن-دی-مڈل پراکسی معاونین
├── models/               مقامی ماڈل میٹا ڈیٹا / عرف سازی
├── sse/                  وراثتی SSE ہینڈلرز جو اب بھی src/ کے تحت موجود ہیں (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/ (6 مہارتیں: لاگت کا تجزیہ، صحت کی رپورٹ، فراہم کنندہ کی دریافت، کوٹا مینجمنٹ، اسمارٹ روٹنگ، صلاحیتوں کی فہرست)
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/	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/	پلگ اِن لوڈر (index.ts)
promptCache/	prefixAnalyzer.ts، index.ts
providerModels/	منظم ماڈل لائف سائیکل: modelDiscovery.ts، managedModelImport.ts، managedAvailableModels.ts، cursorAgent.ts
providers/	فراہم کنندہ کے معاون اجزا: catalog.ts، validation.ts، imageValidation.ts، claudeExtraUsage.ts، codexConnectionDefaults.ts، codexFastTier.ts، webCookieAuth.ts، managedAvailableModels.ts، requestDefaults.ts
resilience/	settings.ts — سرکٹ بریکر، کول ڈاؤن، لاک آؤٹ کی ترتیبات
runtime/	رن ٹائم فیچر کی شناخت
search/	executeWebSearch.ts
services/	ایمبیڈڈ سروسز فریم ورک: ServiceSupervisor.ts (آپریشن لاک، رِنگ بفر، اور ہیلتھ چیکر کے ساتھ عمومی چائلڈ پروسیس سپروائزر)، bootstrap.ts (پروسیس سطح کی رجسٹریشن اور خودکار آغاز)، registry.ts (ٹول → سپروائزر میپ)، apiKey.ts (AES-256-GCM کلید اسٹور)، modelSync.ts (وقفے وقفے سے ماڈل سنک)، ringBuffer.ts (5 MB دائروی لاگ بفر)، healthCheck.ts (HTTP ہیلتھ پروب)، types.ts، embedWsProxy.ts (WebSocket پراکسی)، installers/{ninerouter,cliproxy}.ts۔ docs/frameworks/EMBEDDED-SERVICES.md دیکھیں
agentSkills/	Agent Skills کیٹلاگ + جنریٹر: 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 دیکھیں۔
skills/	مہارت کا فریم ورک: registry.ts، executor.ts، interception.ts، injection.ts، sandbox.ts، custom.ts، hybrid.ts، builtins.ts، a2a.ts، providerSettings.ts، schemas.ts، skillssh.ts، types.ts، نیز builtin/browser.ts
spend/	batchWriter.ts (رائٹ بی ہائنڈ بفر)
sync/	bundle.ts، tokens.ts (Cloud Sync)
system/	سسٹم سطح کے معاون اجزا
translator/	اعلیٰ سطح کا ٹرانسلیٹر رابطہ (open-sse/translator/ کو تفویض کرتا ہے)
usage/	استعمال کا حساب کتاب: costCalculator.ts، tokenAccounting.ts، usageHistory.ts، aggregateHistory.ts، usageStats.ts، callLogs.ts، callLogArtifacts.ts، fetcher.ts، providerLimits.ts، migrations.ts
versionManager/	خودکار اپ ڈیٹ + ورژن مینی فیسٹ
ws/	WebSocket برج
zed-oauth/	Zed ایڈیٹر کا OAuth فلو

src/lib/ میں اعلیٰ سطح کی فائلیں:

• پرانا localDb.ts بیرل ہٹا دیا گیا — صارفین مخصوص 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 ڈیٹابیس (core.ts میں getDbInstance()، WAL جرنلنگ)۔ روٹس یا ہینڈلرز میں کبھی خام SQL نہ لکھیں — ان ماڈیولز کے ذریعے کام کریں۔

ماخذ: diagrams/db-schema-overview.mmd

ڈومین ماڈیولز (ہر ایک ایک یا زیادہ ٹیبلز کا ذمہ دار ہے): 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 فائلیں (آئیڈیم پوٹنٹ، ٹرانزیکشنل) موجود ہیں اور بوٹ کے وقت migrationRunner.ts کے ذریعے چلائی جاتی ہیں۔

مائیگریشنز میں بنائے گئے ٹیبلز (کل 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 ورچوئل ٹیبلز)۔

3.3 src/domain/ — ڈومین تہہ

خالص کاروباری منطق، کوئی I/O نہیں۔ روٹس اور ہینڈلرز کے ذریعے درآمد کی جاتی ہے۔

فائل	مقصد
policyEngine.ts	اعلیٰ سطح کا پالیسی ریزالور
fallbackPolicy.ts	فال بیک فیصلوں کا شجرہ
costRules.ts	لاگت کے حساب کے قواعد
lockoutPolicy.ts	ماڈل لاک آؤٹ کے فیصلے
tagRouter.ts	ٹیگ پر مبنی روٹنگ
comboResolver.ts	درخواست → ہدف فہرست سے کومبو ریزولیوشن
connectionModelRules.ts	ہر کنکشن کے لیے ماڈل فلٹرز
modelAvailability.ts	ماڈل کی دستیابی کی جانچ
degradation.ts	تنزلی شدہ موڈ کی منتقلیاں
providerExpiration.ts	زائد المیعاد اکاؤنٹ/کلید کی شناخت
quotaCache.ts	کیش شدہ کوٹا فیصلے
responses.ts, omnirouteResponseMeta.ts	رسپانس کی ساخت کے معاونین
configAudit.ts	کنفیگ تبدیلی کا آڈٹ
assessment/	ماڈل کی جانچ (RFC کے مطابق، جزوی طور پر نافذ شدہ)
types.ts	مشترکہ ڈومین اقسام

3.4 src/server/ — صرف سرور کے لیے

کلائنٹ کمپوننٹس سے درآمد نہیں کیا جا سکتا۔

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        روٹس کو عوامی یا انتظامی کے طور پر درجہ بند کرتا ہے
│   ├── assertAuth.ts      تصدیقی معاون
│   ├── context.ts         ہر درخواست کے لیے authz سیاق
│   ├── headers.ts
│   ├── pipeline.ts        Authz پائپ لائن
│   ├── policies/          ٹھوس پالیسیاں
│   └── types.ts
└── cors/origins.ts        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 (تقریباً 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/ — اسٹریمنگ انجن ورک اسپیس

ایک علیحدہ npm ورک اسپیس جو @omniroute/open-sse کے نام سے شائع کی گئی ہے۔ یہ درخواستوں کی پروسیسنگ، ایگزیکیوٹرز، ٹرانسلیٹرز، سروسز، ٹرانسفارمر، اور MCP سرور کی ذمہ دار ہے۔

open-sse/
├── index.ts                عوامی ایکسپورٹس
├── package.json            ورک اسپیس مینی فیسٹ
├── tsconfig.json
├── types.d.ts
├── config/                 فراہم کنندہ رجسٹریاں، ہیڈر پروفائلز، شناخت، …
├── handlers/               درخواست ہینڈلرز (چیٹ، ایمبیڈنگز، آڈیو، تصویر، …)
├── executors/              فراہم کنندہ کے لیے مخصوص 108 HTTP ایگزیکیوٹرز
├── 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/

فراہم کنندگان کے 108 ایگزیکیوٹرز، جن میں سے ہر ایک 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 (مشترکہ شناختی ہیلپر) اور index.ts (رجسٹری)۔

نوٹ: یہاں درج نہ کیے گئے فراہم کنندگان کو عمومی OpenAI-مطابق ایگزیکیوٹر استعمال کرتے ہوئے default.ts فراہم کرتا ہے۔ فراہم کنندگان کا مکمل کیٹلاگ (355 فراہم کنندگان) 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 (19 حکمتِ عملیاں)، 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، 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
ٹیئر / مینی فیسٹ	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 میں منسلک ہیں (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 دیکھیں۔

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۔ خودکار اپ ڈیٹ electron-updater کے ذریعے ہوتی ہے، جو GitHub ریلیز فیڈ کی جانب اشارہ کرتا ہے۔

---

6. bin/ — CLI

bin/
├── omniroute.mjs           مرکزی CLI انٹری (Node ESM)
├── reset-password.mjs      CLI سے مینجمنٹ پاس ورڈ ری سیٹ کریں
├── mcp-server.mjs          MCP سرور لانچر (stdio)
├── nodeRuntimeSupport.mjs  Node ورژن گارڈ
└── cli/
    ├── program.mjs         Commander پروگرام بلڈر
    ├── runtime.mjs         withRuntime معاون (سرور-اول/db-فال بیک)
    ├── output.mjs          آؤٹ پٹ فارمیٹرز (json/jsonl/table/csv)
    ├── i18n.mjs            لوکیلز کے ساتھ t() معاون
    ├── api.mjs             API fetch معاون
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    کمانڈ رجسٹریشن
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (ہر کمانڈ/گروپ کے لیے ایک فائل)

package.json → bin میں دو بائنریز دستیاب کرائی گئی ہیں:

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

---

7. tests/

ڈائریکٹری	قسم
tests/unit/	Node کے مقامی ٹیسٹ رنر کے ذریعے یونٹ ٹیسٹس (1821 فائلیں، نیز api/، auth/، authz/ ذیلی ڈائریکٹریز)
tests/integration/	متعدد ماڈیولز + DB-اسٹیٹ ٹیسٹس
tests/e2e/	Playwright UI ٹیسٹس
tests/e2e/protocol-clients.test.ts	MCP/A2A پروٹوکول e2e
tests/translator/	مترجم سے مخصوص ٹیسٹس
tests/security/	سیکیورٹی ریگریشنز
tests/load/	لوڈ / اسٹریس ٹیسٹس
tests/golden-set/	مترجم کی ریگریشنز کے لیے حوالہ جاتی آؤٹ پٹس
tests/helpers/، tests/fixtures/، tests/manual/	معاون مواد

عام کمانڈز:

کمانڈ	یہ کیا چلاتی ہے
npm run test:unit	Node ٹیسٹ رنر کے ذریعے تمام tests/unit/*.test.ts (کنکرنسی 10)
npm run test:vitest	Vitest سوٹ (MCP، autoCombo، cache)
npm run test:e2e	Playwright UI سوٹ
npm run test:protocols:e2e	MCP + A2A پروٹوکول e2e
npm run test:coverage	کوریج گیٹ (≥60% لائنیں/اسٹیٹمنٹس/فنکشنز/برانچز)
node --import tsx/esm --test tests/unit/<file>.test.ts	ایک فائل کا رن

---

8. scripts/

مقصد کے لحاظ سے 6 ذیلی فولڈرز میں منظم ہے۔

• scripts/build/ — build-next-isolated.mjs, prepublish.ts, prepare-electron-standalone.mjs, pack-artifact-policy.ts, validate-pack-artifact.ts, postinstall.mjs, postinstallSupport.mjs, uninstall.mjs, bootstrap-env.mjs, runtime-env.mjs, native-binary-compat.mjs.
• scripts/dev/ — run-next.mjs, run-next-playwright.mjs, run-standalone.mjs, standalone-server-ws.mjs, responses-ws-proxy.mjs, v1-ws-bridge.mjs, smoke-electron-packaged.mjs, run-playwright-tests.mjs, run-ecosystem-tests.mjs, run-protocol-clients-tests.mjs, sync-env.mjs, healthcheck.mjs, system-info.mjs.
• 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 پری فلائٹ جانچ
     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/*)
       اپ اسٹریم fetch → 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 اور CLAUDE.md میں مختص حصے کو دیکھیں۔

---

10. شراکت کیسے کریں

نیا provider شامل کریں

1. src/shared/constants/providers.ts میں رجسٹر کریں (لوڈ کے وقت Zod کے ذریعے توثیق شدہ)۔
2. اگر حسبِ ضرورت منطق درکار ہو تو open-sse/executors/ میں executor شامل کریں (BaseExecutor کو extend کریں)۔
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/ کے تحت tests لکھیں۔

نیا API route شامل کریں

1. src/app/api/your-route/route.ts بنائیں۔
2. اس طرز کی پیروی کریں: CORS → Zod body validation → auth → handler delegation۔
3. اگر request کی ساخت نئی ہو تو Zod schema کو src/shared/validation/schemas.ts میں شامل کریں۔
4. اگر صرف انتظامی استعمال کے لیے ہو تو path کو src/shared/constants/publicApiRoutes.ts میں شامل کریں (عوامی API سطح کے لیے denylist)۔
5. tests/unit/ کے تحت tests شامل کریں۔
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/ کے تحت ایک migration شامل کریں، جو ترتیب وار نمبر شدہ، idempotent، اور transactional ہو۔
4. درآمد کنندگان @/lib/db/yourModule سے براہِ راست imports استعمال کریں (کوئی barrel نہیں — پرانی localDb.ts re-export layer ہٹا دی گئی ہے)۔
5. tests/unit/ کے تحت tests شامل کریں۔

نیا MCP tool شامل کریں

1. tool کی تعریف open-sse/mcp-server/tools/ کے تحت شامل کریں (یا open-sse/mcp-server/schemas/tools.ts کو extend کریں)۔
2. src/shared/constants/mcpScopes.ts میں مناسب scope(s) تفویض کریں۔
3. tool کو open-sse/mcp-server/server.ts میں رجسٹر کریں۔
4. open-sse/mcp-server/__tests__/ کے تحت tests شامل کریں۔
5. MCP-SERVER.md کو اپ ڈیٹ کریں۔

نئی A2A skill شامل کریں

A2A-SERVER.md § نئی Skill شامل کرنا دیکھیں۔ Skills src/lib/a2a/skills/ میں موجود ہوتی ہیں اور A2A task manager کے ذریعے رجسٹر کی جاتی ہیں۔

---

11. روایات

• Code style: 2-space indent، double quotes، 100 حروف کی چوڑائی، semicolons، es5 trailing commas — lint-staged کے ذریعے Prettier ان کا نفاذ کرتا ہے۔
• Imports: بیرونی → اندرونی (@/، @omniroute/open-sse) → نسبتی۔
• Naming: فائلیں 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 (وراثتی طرزِ عمل)۔ modules کے درمیان حدود کے لیے 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 کو ایک نام زدہ TS interface لینا/لوٹانا چاہیے جو اس table کے columns کی 1:1 عکاسی کرے، نہ کہ call site پر any یا inline anonymous type۔ interface کو function کے ساتھ رکھیں (مثلاً saveRequestUsage کے اوپر src/lib/usage/usageHistory.ts میں export interface UsageEntry)، جب مختلف writers row کو بتدریج پُر کرتے ہوں تو انفرادی fields کو optional/nullable رکھیں، اور جس field کی shape callers کے لحاظ سے مختلف ہو اس کے لیے any کے بجائے unknown کو ترجیح دیں (field پر دستاویزی وضاحت کے ساتھ، مثلاً UsageEntry.tokens خام provider-shaped usage اور normalized shape دونوں قبول کرتا ہے)۔ جب اس طریقے سے کسی فائل میں any کی تعداد صفر ہو جائے تو اسے check:any-budget:t11 allowlist (scripts/check/check-t11-any-budget.mjs، maxAny: 0) میں شامل کریں تاکہ یہ دوبارہ خراب نہ ہو سکے۔ یہ first-slice convention ہے — زیادہ وسیع "کوئی anonymous any نہیں" صفائی باقی 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. کبھی بیرل امپورٹ نہ کریں — مخصوص src/lib/db/* ماڈیولز براہِ راست استعمال کریں۔
3. کبھی eval() / new Function() / ضمنی eval استعمال نہ کریں۔
4. کبھی براہِ راست main میں کمٹ نہ کریں۔
5. روٹس میں کبھی خام SQL نہ لکھیں — ہمیشہ src/lib/db/ ماڈیولز کے ذریعے کام کریں۔
6. SSE اسٹریمز میں خرابیوں کو کبھی خاموشی سے نظر انداز نہ کریں۔
7. ان پٹس کی ہمیشہ Zod اسکیماؤں کے ذریعے توثیق کریں۔
8. پروڈکشن کوڈ تبدیل کرتے وقت ہمیشہ ٹیسٹس شامل کریں۔
9. کوریج ≥ 60% (اسٹیٹمنٹس، لائنز، فنکشنز، برانچز) برقرار رہنی چاہیے۔

---

13. مزید دیکھیے

• ARCHITECTURE.md — اعلیٰ سطحی آرکیٹیکچر اور ماڈیولز کی ذمہ داریاں۔
• API_REFERENCE.md — عوامی + انتظامی API حوالہ۔
• FEATURES.md — فیچر میٹرکس اور ورژن کی نمایاں خصوصیات۔
• RESILIENCE_GUIDE.md — سرکٹ بریکر، کول ڈاؤن، اور لاک آؤٹ کا گہرائی سے جائزہ۔
• AUTO-COMBO.md — Auto Combo اسکورنگ اور حکمتِ عملیاں۔
• MCP-SERVER.md — مکمل MCP ٹول کیٹلاگ + ٹرانسپورٹس۔
• 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 — Claude Code کے لیے ریپوزٹری کے قواعد (اوپر دیے گئے بہت سے ضوابط کا مستند ماخذ)۔
• AGENTS.md — ایجنٹس کے زیرِ استعمال مزید گہرا آرکیٹیکچر حوالہ۔