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

OmniRoute Codebase Documentation (বাংলা)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇨🇿 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 · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

সংস্করণ: v3.8.51 সর্বশেষ হালনাগাদ: 2026-06-28 পাঠক: OmniRoute-এ অবদান রাখা বা এর ওপর ইন্টিগ্রেশন তৈরি করা প্রকৌশলীরা।

উচ্চ-স্তরের আর্কিটেকচার ডায়াগ্রাম এবং প্রতিটি সাবসিস্টেমের পেছনের যুক্তি জানতে ARCHITECTURE.md পড়ুন। পৃথক সাবসিস্টেমগুলো সম্পর্কে বিস্তারিত জানতে (Auto Combo, MCP server, A2A server, 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, cache), 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 env var, যার ডিফল্ট মান ~/.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, auth, OAuth, skills, memory, …)
├── domain/               বিশুদ্ধ ডোমেইন স্তর (policy, fallback, cost, lockout, …)
├── server/               শুধু-সার্ভার মডিউল (authz, cors, auth)
├── 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/ (৬টি স্কিল: খরচ বিশ্লেষণ, স্বাস্থ্য প্রতিবেদন, প্রোভাইডার অনুসন্ধান, কোটা ব্যবস্থাপনা, স্মার্ট রাউটিং, সক্ষমতা তালিকাভুক্তকরণ)
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 দেখুন।
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 ব্যারেলটি সরিয়ে ফেলা হয়েছে — ব্যবহারকারীরা নির্দিষ্ট 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/ — স্ট্রিমিং ইঞ্জিন ওয়ার্কস্পেস

@omniroute/open-sse নামে প্রকাশিত পৃথক npm ওয়ার্কস্পেস। এটি অনুরোধ প্রক্রিয়াকরণ, এক্সিকিউটর, ট্রান্সলেটর, সার্ভিস, ট্রান্সফর্মার এবং 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 সহায়ক (সার্ভার-প্রথম/ডেটাবেস-ফলব্যাক)
    ├── 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/*)
       আপস্ট্রিম ফেচ → 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 এক্সটেন্ড করুন)।
3. এটি OpenAI ফরম্যাটে যোগাযোগ না করলে open-sse/translator/-এ একটি translator যোগ করুন।
4. OAuth-ভিত্তিক হলে, src/lib/oauth/providers/ এবং src/lib/oauth/services/-এর অধীনে কনফিগ যোগ করুন।
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 validation → auth → handler delegation।
3. নতুন request shape হলে: src/shared/validation/schemas.ts-এ Zod schema যোগ করুন।
4. কেবল management-এর জন্য হলে: src/shared/constants/publicApiRoutes.ts-এ path যোগ করুন (public API surface-এর denylist)।
5. tests/unit/-এর অধীনে টেস্ট যোগ করুন।
6. docs/reference/API_REFERENCE.md এবং docs/openapi.yaml আপডেট করুন।

একটি নতুন DB module যোগ করুন

1. src/lib/db/yourModule.ts তৈরি করুন এবং ./core.ts থেকে getDbInstance() import করুন।
2. আপনার domain-এর জন্য CRUD function export করুন।
3. নতুন table থাকলে: src/lib/db/migrations/-এর অধীনে একটি migration যোগ করুন, যা ধারাবাহিকভাবে নম্বরযুক্ত, idempotent এবং transactional।
4. Importer-গুলো @/lib/db/yourModule থেকে সরাসরি import ব্যবহার করবে (কোনো barrel নয় — পুরোনো localDb.ts re-export layer সরিয়ে দেওয়া হয়েছে)।
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 নির্ধারণ করুন।
3. open-sse/mcp-server/server.ts-এ tool-টি নিবন্ধন করুন।
4. open-sse/mcp-server/__tests__/-এর অধীনে টেস্ট যোগ করুন।
5. MCP-SERVER.md আপডেট করুন।

একটি নতুন A2A skill যোগ করুন

A2A-SERVER.md § একটি নতুন Skill যোগ করা দেখুন। Skill-গুলো src/lib/a2a/skills/-এ থাকে এবং A2A task manager-এর মাধ্যমে নিবন্ধিত হয়।

---

11. রীতিনীতি

• কোড স্টাইল: 2-space indent, double quotes, 100 char width, semicolons, es5 trailing commas — lint-staged-এর মাধ্যমে Prettier দ্বারা প্রয়োগ করা হয়।
• Import: external → internal (@/, @omniroute/open-sse) → relative।
• নামকরণ: file-এর জন্য camelCase বা kebab-case, component-এর জন্য PascalCase, constant-এর জন্য UPPER_SNAKE।
• ESLint: no-eval, no-implied-eval, no-new-func = সর্বত্র error; no-explicit-any = open-sse/ এবং tests/-এ warn, অন্যত্র error।
• TypeScript: strict: false (legacy অবস্থান)। Cross-module boundary-তে inference-এর বদলে explicit type পছন্দ করুন।
• Database: route বা handler-এ কখনো raw SQL লিখবেন না — সবসময় src/lib/db/ module-এর মাধ্যমে কাজ করুন। কখনো barrel-import করবেন না — নির্দিষ্ট src/lib/db/* module সরাসরি ব্যবহার করুন।
• DB-entity typing (#3512): DB table-এর row shape লেখে বা পড়ে—এমন function-এর উচিত সেই table-এর column-গুলোর সঙ্গে 1:1 সামঞ্জস্যপূর্ণ একটি named TS interface গ্রহণ/ফেরত দেওয়া; call site-এ any বা inline anonymous type নয়। Interface-টি function-এর পাশে রাখুন (যেমন saveRequestUsage-এর ওপরে src/lib/usage/usageHistory.ts-এ export interface UsageEntry), বিভিন্ন writer যখন ক্রমান্বয়ে row পূরণ করে তখন পৃথক field-গুলো optional/nullable রাখুন, এবং যে field-এর shape caller-ভেদে পরিবর্তিত হয় তার জন্য any-এর বদলে unknown ব্যবহার করুন (field-টিতে নথিবদ্ধ করুন; যেমন UsageEntry.tokens raw provider-shaped usage এবং normalized shape—উভয়ই গ্রহণ করে)। এভাবে কোনো file-এর any সংখ্যা শূন্যে পৌঁছালে, সেটিকে check:any-budget:t11 allowlist-এ (scripts/check/check-t11-any-budget.mjs, maxAny: 0) যোগ করুন, যাতে এটি আবার আগের অবস্থায় ফিরে যেতে না পারে। এটি একটি প্রথম-পর্যায়ের রীতি — বিস্তৃত "no anonymous any" cleanup বাকি codebase জুড়ে ধাপে ধাপে করা হয়।
• Error: নির্দিষ্ট error type-সহ try/catch ব্যবহার করুন, pino context দিয়ে log করুন। SSE stream-এ কখনো নীরবে error উপেক্ষা করবেন না; cleanup-এর জন্য abort signal ব্যবহার করুন।
• Security: কখনো eval() / new Function() / implied eval ব্যবহার করবেন না। সব input Zod দিয়ে যাচাই করুন। সংরক্ষিত credential encrypt করুন (AES-256-GCM)। src/shared/constants/upstreamHeaders.ts denylist-কে sanitize/validation layer-এর সঙ্গে সামঞ্জস্যপূর্ণ রাখুন।
• Commit: Conventional Commits — feat(scope): subject। অনুমোদিত scope: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills।
• Branch: prefix হিসেবে 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 চলে (দ্রুত gate; 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 — এজেন্টদের ব্যবহৃত আরও বিস্তারিত আর্কিটেকচার রেফারেন্স।