mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-18 04:42:30 +03:00

Files

Diego Rodrigues de Sa e Souza b637350680 fix(docs): re-sync the 65 documentation mirror sets; section-level docs pipeline; drift gate blocking (#13940 )

1,104 mirrors rewritten over five passes of run-translation on the 22-source core set: the 14 sources edited since their translation, the 322 mirrors that were still English copies, and the frontmatter the old extractor leaked into the newer locales' bodies. The pipeline now caches per-`## `-section hashes and retranslates only changed sections, never reuses a section that is still English, rebuilds English-copy / leaked mirrors even when the source is unchanged, merges the state on save (parallel runs), and the drift gate (scoped to the core set) is blocking. Final audit: 0 stale, 0 English copies, 0 leaked frontmatter across 1,430 core mirrors.

⚠️ base-red inherited: #12732

2026-09-17 02:55:31 -03:00

83 KiB

Raw Blame History

OmniRoute Codebase Documentation (Filipino)

🌐 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 · 🇵🇱 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

Bersyon: v3.8.51 Huling na-update: 2026-06-28 Para kanino: Mga engineer na nag-aambag sa OmniRoute o gumagawa ng mga integration sa ibabaw nito.

Para sa mga high-level na diagram ng arkitektura at pangangatwiran sa likod ng bawat subsystem, basahin ang ARCHITECTURE.md. Para sa mas malalalim na talakayan tungkol sa mga indibidwal na subsystem (Auto Combo, MCP server, A2A server, Skills, Memory, Cloud Agents, Resilience, Compression, atbp.), tingnan ang kanilang mga nakalaang file sa direktoryong docs/ na ito.

Inilalarawan ng file na ito kung ano ang kasalukuyang nasa repository upang madaling malibot ng isang bagong engineer ang tree, maunawaan ang runtime layering, at malaman kung saan magdaragdag ng code nang hindi gumagawa ng mga bagong module.

1. Tech Stack

Aspeto	Pinili
Web framework	Next.js 16 (App Router, standalone output, walang global middleware)
Wika	TypeScript 6.0+ — target na `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`
Runtime	Node.js `>=22.22.2 <23` o `>=24.0.0 <27` (ipinapatupad sa pamamagitan ng `engines` + `SUPPORTED_NODE_RANGE`)
Database	SQLite sa pamamagitan ng `better-sqlite3` (singleton, WAL journaling)
Desktop	Electron 41 + `electron-builder` 26.10 (hiwalay na workspace sa `electron/`)
Mga test	Node native test runner (unit/integration), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Build	Next.js standalone sa pamamagitan ng `scripts/build/build-next-isolated.mjs`
Lint/format	ESLint flat config + Prettier (`lint-staged` sa pamamagitan ng Husky pre-commit)
Module system	ESM sa lahat ng bahagi (`"type": "module"`)
Mga workspace	npm workspace — `open-sse` ang tanging sub-workspace

Mga path alias (tsconfig.json):

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

Default na HTTP port: 20128 (magkapareho ng process ang API at dashboard). Ang data directory ay ang DATA_DIR env var, na may default na ~/.omniroute/.

2. Ayos ng Repository

OmniRoute/
├── src/                  Next.js application (App Router, mga library, domain, server, shared)
├── open-sse/             Workspace ng streaming engine (@omniroute/open-sse)
├── electron/             Desktop wrapper (Electron 41 main + preload)
├── bin/                  Mga CLI entry point (omniroute, reset-password)
├── tests/                Unit, integration, e2e, protocols-e2e, translator, security, mga fixture
├── scripts/              Mga helper script para sa build, sync, check, migration, at runtime
├── docs/                 Pampublikong dokumentasyon (ang direktoryong ito)
├── public/               Mga static asset, PWA manifest, service worker
├── config/               Mga sample ng runtime config
├── images/               Mga asset para sa marketing/screenshot
├── _ideia/, _references/, _mono_repo/, _tasks/   Internal na scratch / pagpaplano (hindi isinasama sa release)
├── CLAUDE.md             Mga panuntunan ng repo para sa Claude Code
├── AGENTS.md             Mas malalim na sanggunian sa arkitektura para sa mga agent
├── package.json          v3.8.51, workspace root
└── tsconfig.json         Mga path alias + pangunahing compiler option

3. `src/` — Next.js Application

src/
├── app/                  Mga page ng App Router + mga API route
├── lib/                  Mga pangunahing library (DB, auth, OAuth, skills, memory, …)
├── domain/               Purong domain layer (policy, fallback, cost, lockout, …)
├── server/               Mga module na para lamang sa server (authz, cors, auth)
├── shared/               Mga type, constant, validation, contract, utility (ligtas gamitin sa iba’t ibang boundary)
├── mitm/                 Mga helper ng man-in-the-middle proxy para sa integrasyon ng CLI
├── models/               Metadata / aliasing ng lokal na model
├── sse/                  Mga legacy SSE handler na nasa ilalim pa rin ng src/ (hindi open-sse/)
├── store/                Mga client-side state store
├── middleware/           Mga route-level middleware utility (hindi global middleware ng Next.js)
├── scripts/              Mga in-tree script na maaaring i-import ng app code
├── types/                Mga ambient at shared TS type
├── i18n/                 Mga locale bundle
├── instrumentation.ts    Instrumentation hook ng Next.js
├── instrumentation-node.ts
└── proxy.ts              Top-level helper para sa pag-bootstrap ng proxy

3.1 `src/app/` — App Router

Inilalantad ng App Router ang dashboard UI at ang pampubliko/pampamahalaang HTTP API. Walang global middleware — isinasagawa ang interception sa bawat route.

Mga top-level segment sa ilalim ng src/app/:

Path	Layunin
`api/`	Lahat ng HTTP API route (tingnan ang detalye sa ibaba)
`a2a/`	A2A JSON-RPC 2.0 endpoint (`POST /a2a`)
`.well-known/agent.json/`	Dokumento sa pagtuklas ng A2A Agent Card
`(dashboard)/`	Dashboard UI (route group, walang URL prefix)
`auth/`, `login/`, `forgot-password/`, `callback/`	Mga daloy ng auth
`landing/`	Marketing/landing page
`docs/`	Naka-embed na viewer ng dokumentasyon ng API
`status/`, `maintenance/`, `offline/`	Mga page para sa operasyon
`privacy/`, `terms/`	Mga legal na page
`400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`	Mga static na error page
`error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx`	Mga boundary ng framework para sa error/pag-load
`layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`	Root shell

3.1.1 `src/app/(dashboard)/dashboard/` — Mga page ng 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, kasama ang root na page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 `src/app/api/` — Mga top-level API group

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/   Pamamahala ng mga naka-embed na serbisyo (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         Pampublikong API na compatible sa OpenAI
├── v1beta/     Compatibility na Gemini-style
├── version-manager/
└── webhooks/

3.1.2a `src/app/api/services/` — Pamamahala ng Mga Naka-embed na Serbisyo

Mga route para sa pag-install, pagsisimula, paghinto, at pagsubaybay sa 9Router at CLIProxyAPI. Ang lahat ng path ay inuuri bilang LOCAL_ONLY (loopback lamang, mahigpit na panuntunan #17) dahil maaari nilang patakbuhin ang npm install at gumawa ng mga child process.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             pantulong na getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install sa pamamagitan ng 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 ng mas bagong bersyon
│   ├── rotate-key/route.ts POST — bumuo ng bagong API key + i-restart
│   ├── status/route.ts     GET  — live + katayuan sa DB + metadata ng bersyon
│   └── auto-start/route.ts POST — i-toggle ang flag na auto_start
├── cliproxy/
│   ├── _lib.ts             pantulong na 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 ng mas bagong bersyon
│   ├── status/route.ts     GET  — live + katayuan sa DB + metadata ng bersyon
│   └── auto-start/route.ts POST — i-toggle ang flag na auto_start
└── [name]/
    └── logs/route.ts       GET  — hulihan ng SSE log (ginagamit ng lahat ng serbisyo)

Kaukulang UI ng dashboard: src/app/(dashboard)/dashboard/providers/services/ — pahinang may dalawang tab (CLIProxyAPI + 9Router). Reverse proxy para sa naka-embed na UI ng 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Masusing pagtalakay: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 `src/app/api/v1/` — Pampublikong API na compatible sa OpenAI

v1/
├── accounts/[id]/                       paghahanap ng account
├── agents/tasks/[id]/, agents/tasks/    mga endpoint ng gawain na istilong A2A
├── api/                                 mga panloob na pantulong ng API na inilalantad sa ilalim ng v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (ang pangunahing endpoint)
├── completions/                         mga legacy na text completion
├── embeddings/                          mga embedding
├── files/[id]/, files/                  Files API
├── _helpers/                            mga pinagsasaluhang pantulong ng route (walang pampublikong URL)
├── images/{edits, generations}/         pagbuo + pag-edit ng larawan
├── issues/                              mga endpoint na pantulong sa pag-uuri
├── management/{proxies}/                mga route na saklaw ng pamamahala sa loob ng v1
├── messages/{count_tokens}/             compatibility sa mga mensaheng istilong Anthropic
├── models/                              listahan ng modelo (`route.ts`, `catalog.ts`)
├── moderations/                         moderasyon
├── music/                               pagbuo ng musika
├── providers/[provider]/                mga operasyon para sa bawat provider
├── quotas/{check}                       mga probe ng quota
├── registered-keys/                     pangangasiwa ng nakarehistrong key
├── rerank/                              muling pagraranggo
├── responses/[...path]/                 OpenAI Responses API (catch-all)
├── search/                              paghahanap sa web
├── videos/                              pagbuo ng video
├── ws/                                  tulay ng WebSocket
└── route.ts                             handler ng index

Sinusunod ng bawat route file ang parehong pattern:

Route → CORS preflight → pagpapatunay ng body gamit ang Zod → opsyonal na auth
      → pagpapatupad ng patakaran sa API key → pagtatalaga sa handler (open-sse)

Ang v1beta/ ay ang compatibility surface na istilong Gemini (isang manipis na wrapper na nagsasalin patungo sa parehong pipeline na open-sse/handlers/).

3.2 `src/lib/` — Mga pangunahing library

Palaging i-import ang data, sync, OAuth, skill, memory, atbp. sa pamamagitan ng mga module na ito. Pinapangkat ng talahanayan ang mga aktuwal na directory at mahahalagang file sa pinakamataas na antas.

Module	Layunin
`a2a/`	Server ng A2A protocol: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (6 na skill: pagsusuri ng gastos, ulat sa kalagayan, pagtuklas ng provider, pamamahala ng quota, matalinong pagruruta, list-capabilities)
`acp/`	Agent-Control-Protocol: `index.ts`, `manager.ts`, `registry.ts`
`api/`	Mga internal na API helper: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`
`auth/`	`managementPassword.ts` (pag-reset / pag-hash ng password)
`batches/`	Serbisyo ng OpenAI Batches API (`service.ts`)
`catalog/`	Pag-sync ng catalog ng OpenRouter (`openrouterCatalog.ts`)
`cloudAgent/`	Registry ng cloud agent: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`
`combos/`	Mga helper sa pagresolba ng combo
`compliance/`	Audit + audit ng provider: `index.ts`, `providerAudit.ts`
`config/`	Pandugtong para sa runtime config
`db/`	Mga domain module ng SQLite (tingnan ang §3.2.1)
`display/`	Mga UI/display helper na ginagamit ng mga tugon ng API
`embeddings/`	Registry ng serbisyo sa embedding
`env/`	Pag-load + introspection ng env
`evals/`	Runtime ng eval
`guardrails/`	`piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`
`jobs/`	Mga background job (`autoUpdate.ts`, …)
`memory/`	Persistent na 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/`	Mga module ng OAuth/import provider (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`, kasama ang `services/`, `utils/`, at `constants/oauth.ts`
`plugins/`	Loader ng plugin (`index.ts`)
`promptCache/`	`prefixAnalyzer.ts`, `index.ts`
`providerModels/`	Lifecycle ng pinamamahalaang modelo: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`
`providers/`	Mga helper ng provider: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`
`resilience/`	`settings.ts` — mga setting para sa circuit breaker, cooldown, at lockout
`runtime/`	Pagtukoy ng mga runtime feature
`search/`	`executeWebSearch.ts`
`services/`	Framework ng mga naka-embed na serbisyo: `ServiceSupervisor.ts` (generic na supervisor ng child process na may operation lock, ring buffer, at health checker), `bootstrap.ts` (pagpaparehistro sa antas ng proseso at awtomatikong pagsisimula), `registry.ts` (mapa ng tool → supervisor), `apiKey.ts` (key store na AES-256-GCM), `modelSync.ts` (pana-panahong pag-sync ng modelo), `ringBuffer.ts` (5 MB na circular log buffer), `healthCheck.ts` (HTTP health probe), `types.ts`, `embedWsProxy.ts` (WebSocket proxy), `installers/{ninerouter,cliproxy}.ts`. Tingnan ang `docs/frameworks/EMBEDDED-SERVICES.md`
`agentSkills/`	Catalog + generator ng Agent Skills: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → nagsusulat sa `skills/{id}/SKILL.md`), `openapiParser.ts` (kumukuha ng mga REST endpoint mula sa OpenAPI spec), `cliRegistryParser.ts` (kumukuha ng mga CLI subcommand mula sa bin/cli-registry), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Ginagamit ng mga REST route (`/api/agent-skills/`), MCP tool (`omniroute_agent_skills_`), at A2A skill na `list-capabilities`. Tingnan ang AGENT-SKILLS.md.
`skills/`	Framework ng skill: `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`, kasama ang `builtin/browser.ts`
`spend/`	`batchWriter.ts` (write-behind buffer)
`sync/`	`bundle.ts`, `tokens.ts` (Cloud Sync)
`system/`	Mga helper sa antas ng system
`translator/`	Pangunahing pandugtong ng translator (idinidelega sa `open-sse/translator/`)
`usage/`	Pagtutuos ng paggamit: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`
`versionManager/`	Awtomatikong pag-update + manifest ng bersyon
`ws/`	WebSocket bridge
`zed-oauth/`	Daloy ng OAuth para sa Zed editor

Mga top-level na file sa src/lib/:

Inalis ang lumang localDb.ts barrel — direktang ini-import ng mga consumer ang mga partikular na module ng src/lib/db/*.
proxyHealth.ts, proxyLogger.ts, tokenHealthCheck.ts, localHealthCheck.ts
apiBridgeServer.ts, cacheLayer.ts, semanticCache.ts, settingsCache.ts
cloudSync.ts, initCloudSync.ts
cloudflaredTunnel.ts, ngrokTunnel.ts, tailscaleTunnel.ts
consoleInterceptor.ts, container.ts, gracefulShutdown.ts, idempotencyLayer.ts
ipUtils.ts, logEnv.ts, logPayloads.ts, logRotation.ts
modelAliasSeed.ts, modelCapabilities.ts, modelMetadataRegistry.ts, modelsDevSync.ts
piiSanitizer.ts, pricingSync.ts
apiKeyExposure.ts, cacheControlSettings.ts, dataPaths.ts, toolPolicy.ts
translatorEvents.ts, usageDb.ts, usageAnalytics.ts, webhookDispatcher.ts

3.2.1 `src/lib/db/`

Singleton na SQLite database (getDbInstance() sa core.ts, WAL journaling). Huwag kailanman magsulat ng raw SQL sa mga route o handler — dumaan sa mga module na ito.

Pinagmulan: diagrams/db-schema-overview.mmd

Mga module ng domain (bawat isa ay namamahala sa isa o higit pang table): 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.

Naglalaman ang migrations/ ng 168 may-bersyong .sql file (idempotent, transactional) at isinasagawa ito ng migrationRunner.ts sa pag-boot.

Mga table na nilikha sa lahat ng migration (123 sa kabuuan):

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 (kasama ang mga FTS5 virtual table para sa paghahanap ng memory).

3.3 `src/domain/` — Layer ng domain

Purong business logic, walang I/O. Ini-import ng mga route at handler.

File	Layunin
`policyEngine.ts`	Top-level na tagalutas ng policy
`fallbackPolicy.ts`	Decision tree para sa fallback
`costRules.ts`	Mga panuntunan sa pagkalkula ng gastos
`lockoutPolicy.ts`	Mga pagpapasya sa pag-lockout ng model
`tagRouter.ts`	Routing batay sa tag
`comboResolver.ts`	Paglutas ng combo mula request → target list
`connectionModelRules.ts`	Mga filter ng model para sa bawat connection
`modelAvailability.ts`	Pagsusuri sa availability ng model
`degradation.ts`	Mga transition ng degraded mode
`providerExpiration.ts`	Pagtukoy sa nag-expire na account/key
`quotaCache.ts`	Mga naka-cache na pagpapasya sa quota
`responses.ts`, `omnirouteResponseMeta.ts`	Mga helper para sa hugis ng response
`configAudit.ts`	Audit ng pagbabago sa config
`assessment/`	Pagtatasa ng model (ayon sa RFC, bahagyang ipinatupad)
`types.ts`	Mga nakabahaging uri ng domain

3.4 `src/server/` — Para lamang sa server

Hindi maaaring i-import mula sa mga client component.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Inuuri ang mga route bilang pampubliko o pang-management
│   ├── assertAuth.ts      Helper para sa assertion
│   ├── context.ts         Authz context para sa bawat request
│   ├── headers.ts
│   ├── pipeline.ts        Authz pipeline
│   ├── policies/          Mga konkretong policy
│   └── types.ts
└── cors/origins.ts        Allowlist ng CORS origin

3.5 `src/shared/` — Ligtas ibahagi

Hinati sa mga nakatuong subdirectory:

constants/ — providers.ts (catalog ng provider na bina-validate ng Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (denylist), 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 schema), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
contracts/ — mga pampublikong kontrata ng API na ipinapamahagi sa npm.
types/ — mga pinagsasaluhang uri ng 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, kasama ang mga dashboard hook/component sa ilalim ng services/, network/, middleware/, schemas/, hooks/, components/.

4. `open-sse/` — Workspace ng streaming engine

Hiwalay na npm workspace na inilalathala bilang @omniroute/open-sse. Pinangangasiwaan nito ang pagproseso ng request, mga executor, translator, serbisyo, transformer, at ang MCP server.

open-sse/
├── index.ts                Mga pampublikong export
├── package.json            Manifest ng workspace
├── tsconfig.json
├── types.d.ts
├── config/                 Mga registry ng provider, profile ng header, identity, …
├── handlers/               Mga handler ng request (chat, embedding, audio, image, …)
├── executors/              108 HTTP executor na partikular sa provider
├── translator/             Pag-convert ng format (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformer ng stream mula Responses API ↔ Chat Completions
├── services/               80+ module ng serbisyo (combo, fallback, quota, identity, …)
├── utils/                  Mga helper sa streaming, TLS client, AWS SigV4, proxy fetch, …
└── mcp-server/             MCP server (3 transport, 33 scope, 110 tool)

4.1 `open-sse/handlers/`

Handler	Layunin
`chatCore.ts`	Pangunahing pipeline ng chat (cache, rate limit, combo routing, pagpapadala sa executor)
`responsesHandler.ts`	Entry point ng OpenAI Responses API
`embeddings.ts`	Mga embedding
`imageGeneration.ts`	Pagbuo ng image
`audioSpeech.ts`	Text-to-speech
`audioTranscription.ts`	Speech-to-text
`videoGeneration.ts`	Pagbuo ng video
`musicGeneration.ts`	Pagbuo ng musika
`rerank.ts`	Muling pagraranggo
`moderations.ts`	Moderation
`search.ts`	Paghahanap sa web
`sseParser.ts`	Parser ng SSE event
`usageExtractor.ts`	Kinukuha ang bilang ng mga token mula sa mga upstream stream
`responseSanitizer.ts`	Inaalis ang ingay na partikular sa provider
`responseTranslator.ts`	Tagapag-ugnay sa pagitan ng tugon ng provider at translator layer

4.2 `open-sse/executors/`

108 executor ng provider, na bawat isa ay nag-e-extend sa 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, kasama ang claudeIdentity.ts (nakabahaging helper para sa identity) at index.ts (registry).

Paalala: ang mga provider na hindi nakalista rito ay sinisilbihan ng default.ts gamit ang generic na OpenAI-compatible executor. Makikita ang buong catalog ng provider (355 provider) sa src/shared/constants/providers.ts.

4.3 `open-sse/translator/`

Hub-and-spoke na pagsasalin (OpenAI ang hub).

9 na translator ng request (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 na translator ng response (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 na helper (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, kasama ang mga test ng helper.
Mga helper para sa image (translator/image/sizeMapper.ts).
Nangungunang antas: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 `open-sse/transformer/`

responsesTransformer.ts — Converter na nakabatay sa TransformStream para sa Responses API ↔ Chat Completions (ginagamit ng catch-all na route na responses/).

4.5 `open-sse/services/`

Mga tampok (ang buong listahan ay nasa open-sse/services/):

Usapin	Mga file
Pag-route ng combo	`combo.ts` (19 na estratehiya), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`
Auto Combo engine	`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`
Katatagan	`accountFallback.ts` (cooldown + lockout), `errorClassifier.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`
Mga quota	`quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts`
Pag-cache	`reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`
Katalinuhan sa pag-route	`intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`
Pangangasiwa ng modelo	`modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`
Compression	`compression/` — kumpletong pagkaka-wire ng compression engine
Token + session	`tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`
Tier / manifest	`tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`
IP / network	`ipFilter.ts`, `webSearchFallback.ts`
Mga batch	`batchProcessor.ts`
Paggamit	`usage.ts`

4.6 `open-sse/mcp-server/`

110 natatanging tool na naka-wire sa server.ts (45 canonical sa schemas/tools.ts + mga module ng memory, skills, GitHub-skills, pool, gamification, plugin, Notion, Obsidian, local-corpus at compression — binilang ang union gamit ang countUniqueMcpTools).
3 transport: stdio, HTTP Streamable, SSE.
33 scope na ipinapatupad sa runtime — ang batayang listahan ay nasa src/shared/constants/mcpScopes.ts, at ang kumpletong set ay ang union ng mga scope na idineklara ng bawat tool module.
Talahanayan ng audit: mcp_tool_audit (nilalagyan ng data ng audit.ts).
Mga file: 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, pati na rin ang mga test sa ilalim ng __tests__/.
Tingnan ang MCP-SERVER.md para sa kumpletong katalogo ng mga tool.

4.7 `open-sse/config/`

Mga registry ng provider (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), mga registry ng modelo ayon sa format (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), mga helper ng identity (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), mga helper ng credential (credentialLoader.ts, codexClient.ts), at mga cloud adapter (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/`

Mga primitive sa streaming at mga helper ng provider: 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/` — Desktop wrapper

electron/
├── main.js                  Pangunahing proseso ng Electron
├── preload.js               Preload bridge (naka-enable ang contextIsolation)
├── types.d.ts
├── package.json             Config ng electron-builder, bersyon 3.8.51
├── README.md
├── assets/                  Mga resource sa build (mga icon, entitlement, …)
├── node_modules/            Nakalaang node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Output ng build (hindi naka-commit)

Limang npm script sa root ng workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Isinasagawa ang awtomatikong pag-update sa pamamagitan ng electron-updater na nakaturo sa feed ng release sa GitHub.

6. `bin/` — CLI

bin/
├── omniroute.mjs           Pangunahing CLI entry (Node ESM)
├── reset-password.mjs      I-reset ang password sa pamamahala mula sa CLI
├── mcp-server.mjs          Launcher ng MCP server (stdio)
├── nodeRuntimeSupport.mjs  Pagsusuri sa bersyon ng Node
└── cli/
    ├── program.mjs         Tagabuo ng Commander program
    ├── runtime.mjs         withRuntime helper (server-first/db-fallback)
    ├── output.mjs          Mga formatter ng output (json/jsonl/table/csv)
    ├── i18n.mjs            t() helper na may mga locale
    ├── api.mjs             Helper sa pag-fetch ng API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Pagpaparehistro ng command
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (isang file bawat command/group)

Dalawang binary ang inilalantad sa package.json → bin:

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

7. `tests/`

Direktoryo	Uri
`tests/unit/`	Mga unit test gamit ang native test runner ng Node (1821 file, kasama ang mga subdir na `api/`, `auth/`, `authz/`)
`tests/integration/`	Mga test sa iba’t ibang module + estado ng DB
`tests/e2e/`	Mga Playwright UI test
`tests/e2e/protocol-clients.test.ts`	MCP/A2A protocol e2e
`tests/translator/`	Mga test na partikular sa translator
`tests/security/`	Mga regression sa seguridad
`tests/load/`	Mga load / stress test
`tests/golden-set/`	Mga reperensiyang output para sa mga regression ng translator
`tests/helpers/`, `tests/fixtures/`, `tests/manual/`	Suporta

Mga karaniwang command:

Command	Kung ano ang pinapatakbo nito
`npm run test:unit`	Lahat ng `tests/unit/*.test.ts` gamit ang Node test runner (concurrency 10)
`npm run test:vitest`	Vitest suite (MCP, autoCombo, cache)
`npm run test:e2e`	Playwright UI suite
`npm run test:protocols:e2e`	MCP + A2A protocol e2e
`npm run test:coverage`	Coverage gate (≥60% ng mga line/statement/function/branch)
`node --import tsx/esm --test tests/unit/<file>.test.ts`	Pagpapatakbo ng isang file

8. `scripts/`

Inayos sa 6 na subfolder ayon sa layunin.

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. Pipeline ng Kahilingan (Buod)

Pinagmulan: diagrams/request-pipeline.mmd

Kahilingan ng client
  → /v1/chat/completions (route.ts)
     Paunang pagsusuri ng CORS
     Pag-validate gamit ang Zod (chatCompletionsSchema sa shared/validation/schemas.ts)
     Awtorisasyon (extractApiKey + isValidApiKey O requireManagementAuth)
     Engine ng patakaran (src/server/authz/pipeline.ts)
     Mga guardrail (PII masker, prompt injection, vision bridge)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Pagsusuri ng cache (semantic + read cache)
     Limitasyon sa rate (rateLimitManager, accountSemaphore)
     Combo routing (kung ang model ay malulutas bilang combo)
       comboResolver → pag-loop sa bawat target → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       pag-fetch sa upstream → muling pagsubok/backoff sa pamamagitan ng accountFallback
     translateResponse() (open-sse/translator/response/*)
     SSE stream O JSON response
     Kung Responses API: TransformStream sa pamamagitan ng open-sse/transformer/responsesTransformer.ts
  → Audit sa pagsunod (src/lib/compliance/)
  → Tugon sa client

Runtime state ng katatagan (tatlong mekanismo)

Mekanismo	Saklaw	Saan
Circuit breaker ng provider	Buong provider	`src/shared/utils/circuitBreaker.ts`, iniimbak sa `domain_circuit_breakers`
Cooldown ng koneksyon	Isang account/key	`markAccountUnavailable()` sa `src/sse/services/auth.ts`; ginagamit ng `accountFallback.checkFallbackError()`
Lockout ng model	Provider + koneksyon + model	`open-sse/services/accountFallback.ts`, iniimbak sa `domain_lockout_state`

Tingnan ang RESILIENCE_GUIDE.md at ang nakalaang seksyon sa CLAUDE.md.

10. Paano Mag-ambag

Magdagdag ng bagong provider

Irehistro sa src/shared/constants/providers.ts (vina-validate ng Zod sa pag-load).
Magdagdag ng executor sa open-sse/executors/ kung kinakailangan ang custom na lohika (i-extend ang BaseExecutor).
Magdagdag ng translator sa open-sse/translator/ kung hindi nito ginagamit ang format ng OpenAI.
Kung nakabatay sa OAuth, magdagdag ng config sa ilalim ng src/lib/oauth/providers/ at src/lib/oauth/services/.
Irehistro ang mga model sa open-sse/config/providerRegistry.ts (o sa registry na partikular sa format sa ilalim ng open-sse/config/).
Sumulat ng mga test sa ilalim ng tests/unit/.

Magdagdag ng bagong API route

Gumawa ng src/app/api/your-route/route.ts.
Sundin ang pattern: CORS → pag-validate ng body gamit ang Zod → auth → pagtatalaga sa handler.
Kung bagong anyo ng request: idagdag ang Zod schema sa src/shared/validation/schemas.ts.
Kung para lamang sa pamamahala: idagdag ang path sa src/shared/constants/publicApiRoutes.ts (denylist para sa pampublikong API surface).
Magdagdag ng mga test sa ilalim ng tests/unit/.
I-update ang docs/reference/API_REFERENCE.md at docs/openapi.yaml.

Magdagdag ng bagong DB module

Gumawa ng src/lib/db/yourModule.ts at i-import ang getDbInstance() mula sa ./core.ts.
I-export ang mga CRUD function para sa iyong domain.
Kung may mga bagong table: magdagdag ng migration sa ilalim ng src/lib/db/migrations/, na may sunod-sunod na numero, idempotent, at transactional.
Gumagamit ang mga importer ng mga direktang import mula sa @/lib/db/yourModule (walang barrel — inalis na ang lumang re-export layer na localDb.ts).
Magdagdag ng mga test sa ilalim ng tests/unit/.

Magdagdag ng bagong MCP tool

Idagdag ang depinisyon ng tool sa ilalim ng open-sse/mcp-server/tools/ (o i-extend ang open-sse/mcp-server/schemas/tools.ts).
Italaga ang naaangkop na (mga) scope sa src/shared/constants/mcpScopes.ts.
Irehistro ang tool sa open-sse/mcp-server/server.ts.
Magdagdag ng mga test sa ilalim ng open-sse/mcp-server/__tests__/.
I-update ang MCP-SERVER.md.

Magdagdag ng bagong A2A skill

Tingnan ang A2A-SERVER.md § Pagdaragdag ng Bagong Skill. Matatagpuan ang mga skill sa src/lib/a2a/skills/ at inirerehistro ang mga ito sa pamamagitan ng A2A task manager.

11. Mga Kumbensiyon

Estilo ng code: 2-space na indent, mga double quote, lapad na 100 character, mga semicolon, es5 trailing comma — ipinapatupad ng Prettier sa pamamagitan ng lint-staged.
Mga import: external → internal (@/, @omniroute/open-sse) → relative.
Pagpapangalan: mga file na camelCase o kebab-case, mga component na PascalCase, mga constant na UPPER_SNAKE.
ESLint: no-eval, no-implied-eval, no-new-func = error sa lahat ng lugar; no-explicit-any = warn sa open-sse/ at tests/, error sa ibang lugar.
TypeScript: strict: false (legacy na postura). Mas piliin ang mga tahasang type kaysa inference para sa mga hangganan sa pagitan ng mga module.
Database: huwag kailanman magsulat ng raw SQL sa mga route o handler — palaging dumaan sa mga module ng src/lib/db/. Huwag kailanman gumamit ng barrel import — direktang gamitin ang mga partikular na module ng src/lib/db/*.
Pag-type ng DB entity (#3512): ang isang function na nagsusulat o nagbabasa ng row shape ng isang DB table ay dapat tumanggap/magbalik ng pinangalanang TS interface na eksaktong tumutugma sa mga column ng table nang 1:1, hindi any o isang inline na anonymous type sa call site. Ilagay ang interface katabi ng function (hal. export interface UsageEntry sa src/lib/usage/usageHistory.ts sa itaas ng saveRequestUsage), panatilihing optional/nullable ang mga indibidwal na field kapag paunti-unting pinupunan ng iba't ibang writer ang row, at mas piliin ang unknown kaysa any para sa isang field na ang anyo ay nag-iiba depende sa caller (nakadokumento sa field, hal. tumatanggap ang UsageEntry.tokens ng raw na usage na ayon sa anyo ng provider at ng normalized na anyo). Kapag naging zero na ang bilang ng any sa isang file sa ganitong paraan, idagdag ito sa allowlist ng check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) upang hindi ito bumalik sa dating kalagayan. Isa itong kumbensiyon para sa unang bahagi — ang mas malawak na paglilinis ng "walang anonymous na any" ay isinasagawa nang paunti-unti sa natitirang bahagi ng codebase.
Mga error: gumamit ng try/catch na may mga partikular na uri ng error, at mag-log gamit ang pino context. Huwag kailanman tahimik na balewalain ang mga error sa mga SSE stream; gumamit ng mga abort signal para sa cleanup.
Seguridad: huwag kailanman gumamit ng eval() / new Function() / implied eval. I-validate ang lahat ng input gamit ang Zod. I-encrypt ang mga credential habang nakaimbak (AES-256-GCM). Panatilihing nakaayon ang denylist ng src/shared/constants/upstreamHeaders.ts sa layer ng sanitization/validation.
Mga commit: Conventional Commits — feat(scope): subject. Mga pinapayagang scope: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
Mga branch: mga prefix na feat/, fix/, refactor/, docs/, test/, chore/. Huwag kailanman direktang mag-commit sa main.
Husky: pinapatakbo ng pre-commit ang lint-staged + check:docs-sync + check:any-budget:t11; pinapatakbo ng pre-push ang check:any-budget:t11 + check:tracked-artifacts (mabilis na mga gate; hindi kasama ang test:unit).

12. Mahihigpit na Panuntunan (mula sa CLAUDE.md)

Huwag kailanman mag-commit ng mga secret o credential.
Huwag kailanman gumamit ng barrel import — direktang gamitin ang mga partikular na module ng src/lib/db/*.
Huwag kailanman gumamit ng eval() / new Function() / ipinahiwatig na eval.
Huwag kailanman direktang mag-commit sa main.
Huwag kailanman magsulat ng raw SQL sa mga route — palaging dumaan sa mga module ng src/lib/db/.
Huwag kailanman tahimik na balewalain ang mga error sa mga SSE stream.
Palaging i-validate ang mga input gamit ang mga Zod schema.
Palaging magsama ng mga test kapag binabago ang production code.
Dapat manatiling ≥ 60% ang coverage (mga statement, linya, function, at branch).

13. Tingnan Din

ARCHITECTURE.md — pangkalahatang arkitektura at mga responsibilidad ng module.
API_REFERENCE.md — sanggunian para sa pampubliko at management API.
FEATURES.md — matrix ng mga feature at mahahalagang pagbabago sa bawat bersyon.
RESILIENCE_GUIDE.md — masusing pagtalakay sa circuit breaker, cooldown, at lockout.
AUTO-COMBO.md — pagmamarka at mga estratehiya ng Auto Combo.
MCP-SERVER.md — kumpletong katalogo ng mga MCP tool at mga transport.
A2A-SERVER.md — mga kasanayan at discovery ng A2A protocol.
COMPRESSION_GUIDE.md — RTK + Caveman compression.
CLI-TOOLS.md — mga integrasyon ng CLI.
ELECTRON_GUIDE.md (kung mayroon), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — mga target ng deployment.
TROUBLESHOOTING.md — mga karaniwang isyu sa operasyon.
CONTRIBUTING.md — daloy ng trabaho ng contributor.
CLAUDE.md — mga panuntunan ng repo para sa Claude Code (ang pangunahing batayan para sa marami sa mga convention sa itaas).
AGENTS.md — mas malalim na sanggunian sa arkitektura na ginagamit ng mga agent.

83 KiB Raw Blame History Unescape Escape

OmniRoute Codebase Documentation (Filipino)

1. Tech Stack

2. Ayos ng Repository

3. src/ — Next.js Application

3.1 src/app/ — App Router

3.1.1 src/app/(dashboard)/dashboard/ — Mga page ng UI

3.1.2 src/app/api/ — Mga top-level API group

3.1.2a src/app/api/services/ — Pamamahala ng Mga Naka-embed na Serbisyo

3.1.3 src/app/api/v1/ — Pampublikong API na compatible sa OpenAI

3.2 src/lib/ — Mga pangunahing library

3.2.1 src/lib/db/

3.3 src/domain/ — Layer ng domain

3.4 src/server/ — Para lamang sa server

3.5 src/shared/ — Ligtas ibahagi

4. open-sse/ — Workspace ng streaming engine

4.1 open-sse/handlers/

4.2 open-sse/executors/

4.3 open-sse/translator/

4.4 open-sse/transformer/

4.5 open-sse/services/

4.6 open-sse/mcp-server/

4.7 open-sse/config/

4.8 open-sse/utils/

5. electron/ — Desktop wrapper

6. bin/ — CLI

7. tests/

8. scripts/