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

OmniRoute Codebase Documentation (Kiswahili)

🌐 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 · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Toleo: v3.8.51 Ilisasishwa mwisho: 2026-06-28 Hadhira: Wahandisi wanaochangia OmniRoute au wanaounda miunganisho juu yake.

Kwa michoro ya usanifu wa kiwango cha juu na maelezo ya mantiki ya kila mfumo mdogo, soma ARCHITECTURE.md. Kwa uchambuzi wa kina wa mifumo midogo mahususi (Auto Combo, seva ya MCP, seva ya A2A, Ujuzi, Kumbukumbu, Mawakala wa Wingu, Ustahimilivu, Mfinyazo, n.k.) angalia faili zao mahususi katika saraka hii ya docs/.

Faili hii inaeleza kilichopo kwenye hazina kwa sasa ili mhandisi mpya aweze kuvinjari muundo wa saraka, kuelewa mpangilio wa tabaka wakati wa utekelezaji, na kujua mahali pa kuongeza msimbo bila kubuni moduli mpya.

---

1. Teknolojia Zinazotumika

Eneo	Chaguo
Mfumo wa wavuti	Next.js 16 (App Router, towe linalojitegemea, bila middleware ya kimataifa)
Lugha	TypeScript 6.0+ — lengo ES2022, module: esnext, moduleResolution: bundler, strict: false
Mazingira ya utekelezaji	Node.js >=22.22.2 <23 au >=24.0.0 <27 (inatekelezwa kupitia engines + SUPPORTED_NODE_RANGE)
Hifadhidata	SQLite kupitia better-sqlite3 (nakala moja, uhifadhi wa kumbukumbu wa WAL)
Kompyuta ya mezani	Electron 41 + electron-builder 26.10 (eneo tofauti la kazi katika electron/)
Majaribio	Kiendesha majaribio asilia cha Node (vitengo/ujumuishaji), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Uundaji	Next.js inayojitegemea kupitia scripts/build/build-next-isolated.mjs
Ukaguzi/uumbizaji	Usanidi tambarare wa ESLint + Prettier (lint-staged kupitia Husky pre-commit)
Mfumo wa moduli	ESM kila mahali ("type": "module")
Maeneo ya kazi	Eneo la kazi la npm — open-sse ndilo eneo pekee la kazi dogo

Majina mbadala ya njia (tsconfig.json):

• @/* → src/*
• @omniroute/open-sse → open-sse/index.ts
• @omniroute/open-sse/* → open-sse/*

Mlango chaguo-msingi wa HTTP: 20128 (API na dashibodi hutumia mchakato mmoja). Saraka ya data ni kigezo cha mazingira cha DATA_DIR, ambacho kwa chaguo-msingi ni ~/.omniroute/.

---

2. Mpangilio wa Hazina

OmniRoute/
├── src/                  Programu ya Next.js (App Router, maktaba, kikoa, seva, vipengele vya pamoja)
├── open-sse/             Eneo la kazi la injini ya utiririshaji (@omniroute/open-sse)
├── electron/             Kifuniko cha kompyuta ya mezani (mchakato mkuu wa Electron 41 + upakiaji wa awali)
├── bin/                  Vituo vya kuingilia vya CLI (omniroute, reset-password)
├── tests/                Majaribio ya vitengo, ujumuishaji, e2e, protocols-e2e, kitafsiri, usalama, data za majaribio
├── scripts/              Hati saidizi za uundaji, ulandanishaji, ukaguzi, uhamishaji na utekelezaji
├── docs/                 Nyaraka za umma (saraka hii)
├── public/               Rasilimali tuli, manifesti ya PWA, service worker
├── config/               Sampuli za usanidi wa wakati wa utekelezaji
├── images/               Rasilimali za masoko/picha za skrini
├── _ideia/, _references/, _mono_repo/, _tasks/   Rasimu za ndani / mipango (hazisambazwi)
├── CLAUDE.md             Kanuni za hazina kwa Claude Code
├── AGENTS.md             Rejeleo la kina la usanifu kwa mawakala
├── package.json          v3.8.51, mzizi wa eneo la kazi
└── tsconfig.json         Majina mbadala ya njia + chaguo kuu za kikusanyaji

---

3. src/ — Programu ya Next.js

src/
├── app/                  Kurasa za App Router + njia za API
├── lib/                  Maktaba za msingi (DB, auth, OAuth, skills, memory, …)
├── domain/               Safu halisi ya domain (policy, fallback, cost, lockout, …)
├── server/               Moduli za upande wa seva pekee (authz, cors, auth)
├── shared/               Aina, konstanti, uthibitishaji, mikataba, zana saidizi (salama kuvuka mipaka)
├── mitm/                 Zana saidizi za proksi ya mtu-katikati kwa ujumuishaji wa CLI
├── models/               Metadata / majina mbadala ya modeli za ndani
├── sse/                  Vishughulikiaji vya zamani vya SSE ambavyo bado vipo chini ya src/ (si open-sse/)
├── store/                Hifadhi za hali za upande wa mteja
├── middleware/           Zana za middleware za kiwango cha njia (si middleware ya kimataifa ya Next.js)
├── scripts/              Skripti za ndani ya mti zinazoweza kuletwa na msimbo wa programu
├── types/                Aina za TS za mazingira na zinazoshirikiwa
├── i18n/                 Vifurushi vya lugha
├── instrumentation.ts    Hook ya instrumentation ya Next.js
├── instrumentation-node.ts
└── proxy.ts              Kisaidizi cha kiwango cha juu cha kuanzisha proksi

3.1 src/app/ — App Router

App Router hufichua UI ya dashibodi pamoja na API ya HTTP ya umma/usimamizi. Hakuna middleware ya kimataifa — uzuiaji hufanywa kwa kila njia.

Sehemu za kiwango cha juu chini ya src/app/:

Njia	Madhumuni
api/	Njia zote za API ya HTTP (tazama uchanganuzi hapa chini)
a2a/	Endpoint ya A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Hati ya ugunduzi ya A2A Agent Card
(dashboard)/	UI ya dashibodi (kundi la njia, hakuna kiambishi awali cha URL)
auth/, login/, forgot-password/, callback/	Mitiririko ya uthibitishaji
landing/	Ukurasa wa uuzaji/utangulizi
docs/	Kitazamaji kilichopachikwa cha nyaraka za API
status/, maintenance/, offline/	Kurasa za uendeshaji
privacy/, terms/	Kurasa za kisheria
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Kurasa tuli za hitilafu
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Mipaka ya hitilafu/upakiaji ya mfumo
layout.tsx, page.tsx, globals.css, manifest.ts	Gamba la msingi

3.1.1 src/app/(dashboard)/dashboard/ — Kurasa za 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, pamoja na page.tsx, HomePageClient.tsx, BootstrapBanner.tsx za msingi.

3.1.2 src/app/api/ — Makundi ya API ya kiwango cha juu

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/   Usimamizi wa huduma zilizopachikwa (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API ya umma inayooana na OpenAI
├── v1beta/     Uoanifu wa mtindo wa Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Usimamizi wa Huduma Zilizopachikwa

Njia za kusakinisha, kuanzisha, kusimamisha na kufuatilia 9Router na CLIProxyAPI. Njia zote zimeainishwa kuwa LOCAL_ONLY (loopback pekee, kanuni thabiti #17) kwa sababu zinaweza kutekeleza npm install na kuanzisha michakato tanzu.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             kisaidizi cha getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install kupitia execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install toleo jipya zaidi
│   ├── rotate-key/route.ts POST — zalisha ufunguo mpya wa API + anzisha upya
│   ├── status/route.ts     GET  — hali ya moja kwa moja + hali ya DB + metadata ya toleo
│   └── auto-start/route.ts POST — badilisha hali ya alama ya auto_start
├── cliproxy/
│   ├── _lib.ts             kisaidizi cha 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 toleo jipya zaidi
│   ├── status/route.ts     GET  — hali ya moja kwa moja + hali ya DB + metadata ya toleo
│   └── auto-start/route.ts POST — badilisha hali ya alama ya auto_start
└── [name]/
    └── logs/route.ts       GET  — mkia wa kumbukumbu za SSE (unashirikiwa na huduma zote)

UI inayolingana ya dashibodi: src/app/(dashboard)/dashboard/providers/services/ — ukurasa wenye vichupo viwili (CLIProxyAPI + 9Router). Proksi ya kinyume kwa UI iliyopachikwa ya 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Ufafanuzi wa kina: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API ya umma inayooana na OpenAI

v1/
├── accounts/[id]/                       utafutaji wa akaunti
├── agents/tasks/[id]/, agents/tasks/    ncha za kazi zenye mtindo wa A2A
├── api/                                 visaidizi vya ndani vya API vinavyofichuliwa chini ya v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API ya OpenAI Batches
├── chat/completions/                    Chat Completions (ncha kuu)
├── completions/                         ukamilishaji wa maandishi wa zamani
├── embeddings/                          upachikaji
├── files/[id]/, files/                  API ya Files
├── _helpers/                            visaidizi vya pamoja vya njia (hakuna URL ya umma)
├── images/{edits, generations}/         uzalishaji + uhariri wa picha
├── issues/                              ncha saidizi za uchambuzi wa awali
├── management/{proxies}/                njia zenye upeo wa usimamizi ndani ya v1
├── messages/{count_tokens}/             uoanifu wa ujumbe wenye mtindo wa Anthropic
├── models/                              orodha ya modeli (`route.ts`, `catalog.ts`)
├── moderations/                         udhibiti
├── music/                               uzalishaji wa muziki
├── providers/[provider]/                operesheni za kila mtoa huduma
├── quotas/{check}                       uchunguzi wa mgao
├── registered-keys/                     usimamizi wa funguo zilizosajiliwa
├── rerank/                              upangaji upya wa nafasi
├── responses/[...path]/                 API ya OpenAI Responses (inayonasa zote)
├── search/                              utafutaji wa wavuti
├── videos/                              uzalishaji wa video
├── ws/                                  daraja la WebSocket
└── route.ts                             kishughulikiaji cha faharasa

Kila faili ya njia hufuata muundo uleule:

Njia → ukaguzi wa awali wa CORS → uthibitishaji wa mwili kwa Zod → uthibitishaji wa hiari
     → utekelezaji wa sera ya ufunguo wa API → ukabidhi kwa kishughulikiaji (open-sse)

v1beta/ ni kiolesura cha uoanifu chenye mtindo wa Gemini (kifungashio chepesi kinachotafsiri kwenda kwenye mchakato uleule wa open-sse/handlers/).

3.2 src/lib/ — Maktaba msingi

Daima leta data, usawazishaji, OAuth, ujuzi, kumbukumbu, n.k. kupitia moduli hizi. Jedwali linaweka pamoja saraka halisi na faili muhimu za kiwango cha juu.

Moduli	Madhumuni
a2a/	Seva ya itifaki ya A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (ujuzi 6: uchanganuzi wa gharama, ripoti ya afya, ugunduzi wa watoa huduma, usimamizi wa mgao, uelekezaji mahiri, kuorodhesha uwezo)
acp/	Itifaki ya Udhibiti wa Ajenti: index.ts, manager.ts, registry.ts
api/	Visaidizi vya ndani vya API: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (uwekaji upya wa nenosiri / uwekaji hashi)
batches/	Huduma ya API ya OpenAI Batches (service.ts)
catalog/	Ulandanishaji wa katalogi ya OpenRouter (openrouterCatalog.ts)
cloudAgent/	Sajili ya ajenti za wingu: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Visaidizi vya utatuzi wa mikusanyiko
compliance/	Ukaguzi + ukaguzi wa mtoa huduma: index.ts, providerAudit.ts
config/	Kiunganishi cha usanidi wa wakati wa utekelezaji
db/	Moduli za kikoa za SQLite (tazama §3.2.1)
display/	Visaidizi vya UI/onyesho vinavyotumiwa na majibu ya API
embeddings/	Sajili ya huduma za upachikaji
env/	Upakiaji + uchunguzi wa mazingira
evals/	Mazingira ya utekelezaji wa tathmini
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Kazi za usuli (autoUpdate.ts, …)
memory/	Kumbukumbu endelevu: 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/	Moduli za OAuth/uagizaji wa watoa huduma (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, pamoja na services/, utils/, na constants/oauth.ts
plugins/	Kipakiaji cha programu-jalizi (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Mzunguko wa maisha wa modeli zinazosimamiwa: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Visaidizi vya watoa huduma: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — mipangilio ya kivunja mzunguko, kipindi cha kupoa, na uzuiaji
runtime/	Ugunduzi wa vipengele wakati wa utekelezaji
search/	executeWebSearch.ts
services/	Mfumo wa huduma zilizopachikwa: ServiceSupervisor.ts (msimamizi wa jumla wa michakato-toto mwenye kufuli ya operesheni, bafa ya mzunguko, na kikagua afya), bootstrap.ts (usajili katika kiwango cha mchakato na uanzishaji wa kiotomatiki), registry.ts (ramani ya zana → msimamizi), apiKey.ts (hifadhi ya funguo ya AES-256-GCM), modelSync.ts (ulandanishaji wa modeli wa mara kwa mara), ringBuffer.ts (bafa ya kumbukumbu ya mzunguko ya MB 5), healthCheck.ts (uchunguzi wa afya wa HTTP), types.ts, embedWsProxy.ts (proksi ya WebSocket), installers/{ninerouter,cliproxy}.ts. Tazama docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Katalogi + jenereta ya Ujuzi wa Ajenti: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → huandika skills/{id}/SKILL.md), openapiParser.ts (hutoa ncha za REST kutoka kwa vipimo vya OpenAPI), cliRegistryParser.ts (hutoa amri ndogo za CLI kutoka bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Hutumiwa na njia za REST (/api/agent-skills/*), zana za MCP (omniroute_agent_skills_*), na ujuzi wa A2A list-capabilities. Tazama AGENT-SKILLS.md.
skills/	Mfumo wa ujuzi: 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, pamoja na builtin/browser.ts
spend/	batchWriter.ts (bafa ya uandishi ulioahirishwa)
sync/	bundle.ts, tokens.ts (Ulandanishaji wa Wingu)
system/	Visaidizi vya kiwango cha mfumo
translator/	Kiunganishi cha kiwango cha juu cha kitafsiri (hukabidhi kwa open-sse/translator/)
usage/	Uhasibu wa matumizi: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Usasishaji wa kiotomatiki + faili bainishi ya toleo
ws/	Daraja la WebSocket
zed-oauth/	Mtiririko wa OAuth wa kihariri cha Zed

Faili za kiwango cha juu katika src/lib/:

• Faili ya zamani ya mkusanyo localDb.ts iliondolewa — watumiaji huleta moduli mahususi za src/lib/db/* moja kwa moja.
• 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/

Hifadhidata moja ya SQLite (getDbInstance() katika core.ts, uandishi wa kumbukumbu wa WAL). Kamwe usiandike SQL ghafi katika njia au vishughulikiaji — tumia moduli hizi.

Chanzo: diagrams/db-schema-overview.mmd

Moduli za kikoa (kila moja inamiliki jedwali moja au zaidi): 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/ ina faili 168 za .sql zenye matoleo (zinazoweza kutekelezwa tena bila kubadilisha matokeo, na za kimiamala) na hutekelezwa na migrationRunner.ts wakati wa kuwasha.

Majedwali yaliyoundwa katika uhamishaji wote (jumla ya 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 (pamoja na majedwali pepe ya FTS5 kwa ajili ya utafutaji wa kumbukumbu).

3.3 src/domain/ — Tabaka la kikoa

Mantiki safi ya biashara, bila I/O. Huletwa na njia na vishughulikiaji.

Faili	Madhumuni
policyEngine.ts	Kitatuzi cha kiwango cha juu cha sera
fallbackPolicy.ts	Mti wa maamuzi ya mbadala
costRules.ts	Kanuni za ukokotoaji wa gharama
lockoutPolicy.ts	Maamuzi ya kufungia modeli
tagRouter.ts	Uelekezaji kulingana na lebo
comboResolver.ts	Utatuzi wa mchanganyiko kutoka ombi → orodha lengwa
connectionModelRules.ts	Vichujio vya modeli kwa kila muunganisho
modelAvailability.ts	Ukaguzi wa upatikanaji wa modeli
degradation.ts	Mabadiliko ya hali iliyodhoofishwa
providerExpiration.ts	Utambuzi wa akaunti/ufunguo uliokwisha muda
quotaCache.ts	Maamuzi ya mgao yaliyohifadhiwa kwenye kache
responses.ts, omnirouteResponseMeta.ts	Visaidizi vya muundo wa jibu
configAudit.ts	Ukaguzi wa mabadiliko ya usanidi
assessment/	Tathmini ya modeli (kwa mujibu wa RFC, imetekelezwa kwa sehemu)
types.ts	Aina za kikoa zinazoshirikiwa

3.4 src/server/ — Seva pekee

Haiwezi kuletwa kutoka kwa vijenzi vya mteja.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Huainisha njia kuwa za umma au za usimamizi
│   ├── assertAuth.ts      Kisaidizi cha uthibitisho
│   ├── context.ts         Muktadha wa authz kwa kila ombi
│   ├── headers.ts
│   ├── pipeline.ts        Mtiririko wa authz
│   ├── policies/          Sera mahususi
│   └── types.ts
└── cors/origins.ts        Orodha ya asili za CORS zinazoruhusiwa

3.5 src/shared/ — Salama kushirikiwa

Imegawanywa katika saraka ndogo zilizolenga majukumu mahususi:

• constants/ — providers.ts (katalogi ya watoa huduma iliyothibitishwa kwa Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (orodha ya kukataa), 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 (takriban schema 80 za Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — mikataba ya API ya umma inayosambazwa kupitia npm.
• types/ — aina za TS zinazoshirikiwa.
• 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, pamoja na hooks/vijenzi vya dashibodi chini ya services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Nafasi ya kazi ya injini ya utiririshaji

Nafasi tofauti ya kazi ya npm iliyochapishwa kama @omniroute/open-sse. Inamiliki uchakataji wa maombi, vitekelezaji, vitafsiri, huduma, kigeuzi, na seva ya MCP.

open-sse/
├── index.ts                Vipengele vinavyohamishwa hadharani
├── package.json            Manifesti ya nafasi ya kazi
├── tsconfig.json
├── types.d.ts
├── config/                 Sajili za watoa huduma, wasifu wa vichwa, utambulisho, …
├── handlers/               Vishughulikiaji vya maombi (gumzo, embeddings, sauti, picha, …)
├── executors/              Vitekelezaji 108 vya HTTP mahususi kwa watoa huduma
├── translator/             Ubadilishaji wa miundo (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Kigeuzi cha mtiririko wa Responses API ↔ Chat Completions
├── services/               Moduli 80+ za huduma (michanganyiko, mbadala, vikomo, utambulisho, …)
├── utils/                  Visaidizi vya utiririshaji, kiteja cha TLS, AWS SigV4, uletaji kupitia proksi, …
└── mcp-server/             Seva ya MCP (njia 3 za usafirishaji, mawanda 33, zana 110)

4.1 open-sse/handlers/

Kishughulikiaji	Madhumuni
chatCore.ts	Mchakato mkuu wa gumzo (akiba, kikomo cha kasi, uelekezaji wa mchanganyiko, uanzishaji wa kitekelezaji)
responsesHandler.ts	Sehemu ya kuingilia ya OpenAI Responses API
embeddings.ts	Embeddings
imageGeneration.ts	Uzalishaji wa picha
audioSpeech.ts	Maandishi kwenda usemi
audioTranscription.ts	Usemi kwenda maandishi
videoGeneration.ts	Uzalishaji wa video
musicGeneration.ts	Uzalishaji wa muziki
rerank.ts	Upangaji upya
moderations.ts	Udhibiti wa maudhui
search.ts	Utafutaji wa wavuti
sseParser.ts	Kichanganuzi cha matukio ya SSE
usageExtractor.ts	Hutoa idadi ya tokeni kutoka kwenye mitiririko ya huduma za juu
responseSanitizer.ts	Huondoa kelele mahususi kwa mtoa huduma
responseTranslator.ts	Kiunganishi kati ya jibu la mtoa huduma na safu ya kitafsiri

4.2 open-sse/executors/

Vitekelezaji 108 vya watoa huduma, kila kimoja kikitanua 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, pamoja na claudeIdentity.ts (kisaidizi cha pamoja cha utambulisho) na index.ts (sajili).

Kumbuka: watoa huduma ambao hawajaorodheshwa hapa huhudumiwa na default.ts kwa kutumia kitekelezaji cha jumla kinachooana na OpenAI. Katalogi kamili ya watoa huduma (watoa huduma 355) ipo katika src/shared/constants/providers.ts.

4.3 open-sse/translator/

Tafsiri ya kitovu-na-miale (OpenAI ndicho kitovu).

• Vitafsiri 9 vya maombi (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.
• Vitafsiri 9 vya majibu (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.
• Visaidizi 9 (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, pamoja na majaribio ya visaidizi.
• Visaidizi vya picha (translator/image/sizeMapper.ts).
• Kiwango cha juu: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — Kigeuzi kinachotegemea TransformStream cha Responses API ↔ Chat Completions (kinachotumiwa na kishika-maombi-yote cha njia ya responses/).

4.5 open-sse/services/

Vipengele muhimu (orodha kamili chini ya open-sse/services/):

Jambo linalohusika	Faili
Uelekezaji wa Combo	combo.ts (mikakati 19), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Injini ya Auto Combo	autoCombo/ — engine.ts, scoring.ts, taskFitness.ts, virtualFactory.ts, modePacks.ts, autoPrefix.ts, persistence.ts, providerDiversity.ts, providerRegistryAccessor.ts, routerStrategy.ts, selfHealing.ts, index.ts
Ustahimilivu	accountFallback.ts (kipindi cha kusubiri + kufungiwa), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Vikomo	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Uakibishaji	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Uelewa wa uelekezaji	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Ushughulikiaji wa modeli	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Mfinyazo	compression/ — uunganishaji kamili wa injini ya mfinyazo
Tokeni + kipindi	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Daraja / manifesti	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / mtandao	ipFilter.ts, webSearchFallback.ts
Mafungu	batchProcessor.ts
Matumizi	usage.ts

4.6 open-sse/mcp-server/

• Zana 110 za kipekee zilizounganishwa katika server.ts (45 za msingi katika schemas/tools.ts + moduli za kumbukumbu, ujuzi, ujuzi wa GitHub, mkusanyiko, uchezeshaji, programu-jalizi, Notion, Obsidian, hazina ya ndani na mfinyazo — muungano umehesabiwa na countUniqueMcpTools).
• Njia 3 za usafirishaji: stdio, HTTP Streamable, SSE.
• Mawanda 33 yanatekelezwa wakati wa utekelezaji — orodha ya msingi katika src/shared/constants/mcpScopes.ts, seti kamili ni muungano wa mawanda yaliyotangazwa na kila moduli ya zana.
• Jedwali la ukaguzi: mcp_tool_audit (hujazwa na audit.ts).
• Faili: 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, pamoja na majaribio yaliyo chini ya __tests__/.
• Tazama MCP-SERVER.md kwa katalogi kamili ya zana.

4.7 open-sse/config/

Masajili ya watoa huduma (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), masajili ya modeli kwa kila umbizo (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), visaidizi vya utambulisho (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), visaidizi vya vitambulisho (credentialLoader.ts, codexClient.ts), na adapta za wingu (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/

Vipengele vya msingi vya utiririshaji na visaidizi vya watoa huduma: 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/ — Kifungashio cha eneo-kazi

electron/
├── main.js                  Mchakato mkuu wa Electron
├── preload.js               Daraja la upakiaji wa awali (contextIsolation imewezeshwa)
├── types.d.ts
├── package.json             Usanidi wa electron-builder, toleo la 3.8.51
├── README.md
├── assets/                  Rasilimali za uundaji (ikoni, ruhusa, …)
├── node_modules/            node_modules mahususi (better-sqlite3, electron-updater)
└── dist-electron/           Matokeo ya uundaji (hayajawekwa kwenye hazina)

Hati tano za npm kwenye mzizi wa workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Usasishaji kiotomatiki hufanywa kupitia electron-updater inayoelekezwa kwenye mkondo wa matoleo wa GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Kiingilio kikuu cha CLI (Node ESM)
├── reset-password.mjs      Weka upya nenosiri la usimamizi kupitia CLI
├── mcp-server.mjs          Kianzishaji cha seva ya MCP (stdio)
├── nodeRuntimeSupport.mjs  Kikagua toleo la Node
└── cli/
    ├── program.mjs         Kiunda programu cha Commander
    ├── runtime.mjs         Kisaidizi cha withRuntime (server-first/db-fallback)
    ├── output.mjs          Viumbizaji vya matokeo (json/jsonl/table/csv)
    ├── i18n.mjs            Kisaidizi cha t() chenye lugha za eneo
    ├── api.mjs             Kisaidizi cha uchotaji wa API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Usajili wa amri
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (faili moja kwa kila amri/kikundi)

Faili mbili tekelezi zinafichuliwa katika package.json → bin:

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

---

7. tests/

Saraka	Aina
tests/unit/	Majaribio ya kitengo kupitia kiendesha majaribio asilia cha Node (faili 1821, pamoja na saraka ndogo za api/, auth/, authz/)
tests/integration/	Majaribio yanayohusisha moduli mbalimbali pamoja na hali ya DB
tests/e2e/	Majaribio ya UI ya Playwright
tests/e2e/protocol-clients.test.ts	Majaribio ya e2e ya itifaki za MCP/A2A
tests/translator/	Majaribio mahususi ya kitafsiri
tests/security/	Majaribio ya kurudi nyuma kwa usalama
tests/load/	Majaribio ya mzigo / msongo
tests/golden-set/	Matokeo ya marejeleo kwa ajili ya majaribio ya kurudi nyuma ya kitafsiri
tests/helpers/, tests/fixtures/, tests/manual/	Usaidizi

Amri za kawaida:

Amri	Kinachoendeshwa
npm run test:unit	Majaribio yote ya tests/unit/*.test.ts kupitia kiendesha majaribio cha Node (utekelezaji sambamba 10)
npm run test:vitest	Kifurushi cha majaribio cha Vitest (MCP, autoCombo, cache)
npm run test:e2e	Kifurushi cha majaribio ya UI cha Playwright
npm run test:protocols:e2e	Majaribio ya e2e ya itifaki za MCP + A2A
npm run test:coverage	Kizingiti cha ufunikaji (≥60% ya mistari/kauli/vitendakazi/matawi)
node --import tsx/esm --test tests/unit/<file>.test.ts	Uendeshaji wa faili moja

---

8. scripts/

Imepangwa katika folda ndogo 6 kulingana na madhumuni.

• 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. Mfululizo wa Ombi (Muhtasari)

Chanzo: diagrams/request-pipeline.mmd

Ombi la mteja
  → /v1/chat/completions (route.ts)
     Ukaguzi wa awali wa CORS
     Uthibitishaji wa Zod (chatCompletionsSchema katika shared/validation/schemas.ts)
     Uthibitishaji wa utambulisho (extractApiKey + isValidApiKey AU requireManagementAuth)
     Injini ya sera (src/server/authz/pipeline.ts)
     Hatua za ulinzi (kificha PII, udungaji wa kidokezo, daraja la kuona)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Ukaguzi wa akiba (akiba ya kisemantiki + akiba ya usomaji)
     Kikomo cha kasi (rateLimitManager, accountSemaphore)
     Uelekezaji wa mchanganyiko (ikiwa modeli inalingana na mchanganyiko)
       comboResolver → kitanzi kwa kila lengo → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       leta kutoka kwa huduma ya juu → jaribu tena/ongeza muda wa kusubiri kupitia accountFallback
     translateResponse() (open-sse/translator/response/*)
     Mtiririko wa SSE AU jibu la JSON
     Ikiwa ni Responses API: TransformStream kupitia open-sse/transformer/responsesTransformer.ts
  → Ukaguzi wa utiifu (src/lib/compliance/)
  → Jibu kwa mteja

Hali ya wakati wa utekelezaji ya ustahimilivu (mbinu tatu)

Mbinu	Upeo	Mahali
Kivunja mzunguko cha mtoa huduma	Mtoa huduma mzima	src/shared/utils/circuitBreaker.ts, imehifadhiwa katika domain_circuit_breakers
Kipindi cha kusubiri cha muunganisho	Akaunti/ufunguo mmoja	markAccountUnavailable() katika src/sse/services/auth.ts; inatumiwa na accountFallback.checkFallbackError()
Uzuiaji wa modeli	Mtoa huduma + muunganisho + modeli	open-sse/services/accountFallback.ts, imehifadhiwa katika domain_lockout_state

Angalia RESILIENCE_GUIDE.md na sehemu maalumu katika CLAUDE.md.

---

10. Jinsi ya Kuchangia

Ongeza mtoa huduma mpya

1. Sajili katika src/shared/constants/providers.ts (inathibitishwa na Zod wakati wa kupakia).
2. Ongeza kitekelezaji katika open-sse/executors/ ikiwa mantiki maalum inahitajika (panua BaseExecutor).
3. Ongeza kitafsiri katika open-sse/translator/ ikiwa haitumii umbizo la OpenAI.
4. Ikiwa inategemea OAuth, ongeza usanidi chini ya src/lib/oauth/providers/ na src/lib/oauth/services/.
5. Sajili modeli katika open-sse/config/providerRegistry.ts (au sajili mahususi ya umbizo chini ya open-sse/config/).
6. Andika majaribio chini ya tests/unit/.

Ongeza njia mpya ya API

1. Unda src/app/api/your-route/route.ts.
2. Fuata mpangilio huu: CORS → uthibitishaji wa body kwa Zod → uthibitishaji wa utambulisho → ukabidhi kwa handler.
3. Ikiwa ni muundo mpya wa ombi: ongeza schema ya Zod katika src/shared/validation/schemas.ts.
4. Ikiwa ni ya usimamizi pekee: ongeza path kwenye src/shared/constants/publicApiRoutes.ts (orodha ya kukataa kwa sehemu ya API ya umma).
5. Ongeza majaribio chini ya tests/unit/.
6. Sasisha docs/reference/API_REFERENCE.md na docs/openapi.yaml.

Ongeza moduli mpya ya DB

1. Unda src/lib/db/yourModule.ts na uingize getDbInstance() kutoka ./core.ts.
2. Hamisha vitendakazi vya CRUD kwa ajili ya kikoa chako.
3. Ikiwa kuna majedwali mapya: ongeza uhamishaji chini ya src/lib/db/migrations/, uliowekewa nambari kwa mfuatano, unaoweza kurudiwa bila athari za ziada, na wa kimuamala.
4. Waingizaji watumie uingizaji wa moja kwa moja kutoka @/lib/db/yourModule (bila barrel — safu ya zamani ya kusafirisha upya ya localDb.ts iliondolewa).
5. Ongeza majaribio chini ya tests/unit/.

Ongeza zana mpya ya MCP

1. Ongeza ufafanuzi wa zana chini ya open-sse/mcp-server/tools/ (au panua open-sse/mcp-server/schemas/tools.ts).
2. Weka scope husika katika src/shared/constants/mcpScopes.ts.
3. Sajili zana katika open-sse/mcp-server/server.ts.
4. Ongeza majaribio chini ya open-sse/mcp-server/__tests__/.
5. Sasisha MCP-SERVER.md.

Ongeza ujuzi mpya wa A2A

Tazama A2A-SERVER.md § Kuongeza Ujuzi Mpya. Ujuzi hupatikana katika src/lib/a2a/skills/ na husajiliwa kupitia kidhibiti cha kazi cha A2A.

---

11. Kanuni

• Mtindo wa msimbo: ujongezaji wa nafasi 2, alama mbili za kunukuu, upana wa herufi 100, semikoni, koma za mwisho za es5 — hutekelezwa na Prettier kupitia lint-staged.
• Uingizaji: wa nje → wa ndani (@/, @omniroute/open-sse) → wa jamaa.
• Utoaji majina: faili camelCase au kebab-case, vijenzi PascalCase, konstanti UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error kila mahali; no-explicit-any = warn katika open-sse/ na tests/, error kwingineko.
• TypeScript: strict: false (msimamo wa mifumo ya zamani). Pendelea aina zilizobainishwa wazi kuliko uainishaji wa kiotomatiki katika mipaka ya moduli.
• Hifadhidata: kamwe usiandike SQL ghafi katika njia au handler — kila mara pitia moduli za src/lib/db/. Kamwe usiingize kupitia barrel — tumia moja kwa moja moduli mahususi za src/lib/db/*.
• Uainishaji wa huluki za DB (#3512): kitendakazi kinachoandika au kusoma muundo wa safu ya jedwali la DB kinapaswa kupokea/kurejesha interface ya TS yenye jina inayoakisi safu wima za jedwali hilo 1:1, si any au aina isiyo na jina iliyoandikwa moja kwa moja mahali pa kuitwa. Weka interface karibu na kitendakazi (k.m. export interface UsageEntry katika src/lib/usage/usageHistory.ts juu ya saveRequestUsage), acha sehemu binafsi ziwe za hiari/zinazokubali null wakati waandishi tofauti hujaza safu hatua kwa hatua, na pendelea unknown kuliko any kwa sehemu ambayo muundo wake hutofautiana kulingana na mwitaji (imeandikwa katika sehemu hiyo, k.m. UsageEntry.tokens inakubali matumizi ghafi yenye muundo wa mtoa huduma na pia muundo uliosanifishwa). Mara tu idadi ya any katika faili inapofikia sifuri kwa njia hii, iongeze kwenye orodha ya kuruhusu ya check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) ili hali hiyo isirudi nyuma. Hii ni kanuni ya sehemu ya kwanza — usafishaji mpana zaidi wa "hakuna any isiyo na jina" unafanywa kwa hatua katika sehemu nyingine za codebase.
• Hitilafu: tumia try/catch yenye aina mahususi za hitilafu, na urekodi kwa muktadha wa pino. Kamwe usipuuze hitilafu kimya kimya katika mitiririko ya SSE; tumia ishara za kusitisha kwa ajili ya usafishaji.
• Usalama: kamwe usitumie eval() / new Function() / eval isiyo ya moja kwa moja. Thibitisha ingizo zote kwa Zod. Simba vitambulisho vinapohifadhiwa (AES-256-GCM). Weka orodha ya kukataa ya src/shared/constants/upstreamHeaders.ts ikiwa imelandanishwa na safu ya usafishaji/uthibitishaji.
• Commit: Conventional Commits — feat(scope): subject. Scope zinazoruhusiwa: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branch: viambishi awali feat/, fix/, refactor/, docs/, test/, chore/. Kamwe usifanye commit moja kwa moja kwenye main.
• Husky: pre-commit huendesha lint-staged + check:docs-sync + check:any-budget:t11; pre-push huendesha check:any-budget:t11 + check:tracked-artifacts (vizuizi vya haraka; haijumuishi test:unit).

---

12. Kanuni Madhubuti (kutoka CLAUDE.md)

1. Kamwe usiweke siri au vitambulisho kwenye commit.
2. Kamwe usifanye barrel-import — tumia moduli mahususi za src/lib/db/* moja kwa moja.
3. Kamwe usitumie eval() / new Function() / eval iliyodokezwa.
4. Kamwe usifanye commit moja kwa moja kwenye main.
5. Kamwe usiandike SQL ghafi katika routes — kila mara pitia moduli za src/lib/db/.
6. Kamwe usipuuze kimyakimya hitilafu katika mitiririko ya SSE.
7. Kila mara thibitisha ingizo kwa kutumia schemas za Zod.
8. Kila mara jumuisha majaribio unapobadilisha msimbo wa uzalishaji.
9. Coverage lazima ibaki ≥ 60% (statements, lines, functions, branches).

---

13. Tazama Pia

• ARCHITECTURE.md — usanifu wa kiwango cha juu na majukumu ya moduli.
• API_REFERENCE.md — rejeleo la API ya umma + usimamizi.
• FEATURES.md — matriki ya vipengele na mambo muhimu ya matoleo.
• RESILIENCE_GUIDE.md — uchambuzi wa kina wa circuit breaker, cooldown, na lockout.
• AUTO-COMBO.md — uwekaji alama na mikakati ya Auto Combo.
• MCP-SERVER.md — katalogi kamili ya zana za MCP + njia za usafirishaji.
• A2A-SERVER.md — ujuzi na ugunduzi wa itifaki ya A2A.
• COMPRESSION_GUIDE.md — ubanaji wa RTK + Caveman.
• CLI-TOOLS.md — miunganisho ya CLI.
• ELECTRON_GUIDE.md (ikiwa ipo), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — mazingira lengwa ya usambazaji.
• TROUBLESHOOTING.md — matatizo ya kawaida ya uendeshaji.
• CONTRIBUTING.md — mtiririko wa kazi wa wachangiaji.
• CLAUDE.md — kanuni za repo kwa Claude Code (chanzo cha ukweli kwa kanuni nyingi zilizo hapo juu).
• AGENTS.md — rejeleo la kina zaidi la usanifu linalotumiwa na mawakala.