docs/architecture/REPOSITORY_MAP.md
One-line description for every directory and root file. Last updated: 2026-06-28 — OmniRoute v3.8.40
Use this map to navigate the codebase quickly. For deep dives, follow links to dedicated docs.
OmniRoute/
├── src/ # Next.js 16 application (UI + API routes + libs + domain + server)
├── open-sse/ # Streaming engine workspace (handlers, executors, translator, MCP server)
├── electron/ # Desktop wrapper (Electron 41 + electron-builder 26.10)
├── bin/ # CLI entry point and command handlers
├── scripts/ # Build, check, sync, and one-off scripts
├── docs/ # Public documentation (you are here)
├── tests/ # All test suites (unit, integration, e2e, protocols-e2e)
├── public/ # Next.js static assets, PWA manifest, service worker, icons
├── config/ # Static config + quality-gate state (i18n, payloadRules, quality/)
├── images/ # Marketing / README image assets
├── @omniroute/ # Publishable companion packages (opencode-plugin, opencode-provider)
├── skills/ # CLI/agent skill packs (cli-* + omni-* + config-codex-cli)
├── examples/ # Sample plugins + omniroute-cmd-hello starter
├── contrib/ # Community contributions (podman/)
├── .source/ # Fumadocs source config (source.config.mjs + server/browser/dynamic)
├── .github/ # GitHub Actions workflows + issue templates + PR template
├── .husky/ # Git hooks (pre-commit, pre-push)
├── .claude/ # Claude Code slash commands (project-scoped)
├── .agents/ # Codex / generic agent workflows + skills (mirror of .claude/)
├── .vscode/ # VS Code workspace settings
├── _ideia/ # Planning notes (informal; not shipped)
├── _mono_repo/ # Historic subprojects (cloud, site, vscode-extension)
├── _references/ # Read-only reference clones from related OSS projects
├── _tasks/ # Per-release task tracking files (informal)
├── .build/ .worktrees/ dist/ # local build / git-worktree / build-output scratch (gitignored)
├── .issues/ # Local issue cache (gitignored)
├── .playwright-mcp/ # Playwright MCP test artifacts
├── coverage/ # c8 coverage output (gitignored)
├── logs/ # Runtime logs (gitignored)
├── node_modules/ # Dependencies (gitignored)
├── package/ # npm pack staging area (build artifact)
├── .next/ # Next.js build output (gitignored)
└── (root files — see below)
| File | Purpose |
|---|---|
| README.md | Marketing landing page + quick start + feature matrix (see also llm.txt) |
| CHANGELOG.md | Per-release changelog (auto-generated by /version-bump-cc skill) |
| LICENSE | MIT license text |
| CLAUDE.md | Project rules for Claude Code agents (hard rules, conventions, scenarios) |
| AGENTS.md | Same as CLAUDE.md but for non-Claude AI agents (Codex, Cursor, etc.) |
| GEMINI.md | Concise rules for Gemini-based agents (subset of CLAUDE.md) |
| CONTRIBUTING.md | Contributor guide: setup, conventional commits, testing, PR flow |
| SECURITY.md | Vulnerability reporting policy, supported versions, threat model |
| CODE_OF_CONDUCT.md | Contributor Covenant — community behavior expectations |
| llm.txt | Plain-text landing optimized for LLM crawlers (SEO for AI assistants) |
| package.json | npm manifest, scripts, dependencies, engines, c8 coverage gate |
| package-lock.json | Locked dependency tree |
| tsconfig.json | Root TypeScript config |
| tsconfig.typecheck-core.json | Typecheck config for src/ core |
| tsconfig.typecheck-noimplicit-core.json | Strict (noImplicitAny) typecheck |
| tsconfig.tsbuildinfo | TS incremental build cache (gitignored) |
| next.config.mjs | Next.js 16 build configuration (standalone output) |
| next-env.d.ts | Next.js auto-generated env types |
| eslint.config.mjs | ESLint flat config (rules per project area) |
| prettier.config.mjs | Prettier formatting rules |
| postcss.config.mjs | PostCSS config for Tailwind/CSS pipeline |
| playwright.config.ts | Playwright E2E test config |
| vitest.config.ts | Vitest config (default suite) |
| vitest.mcp.config.ts | Vitest config for MCP server / autoCombo / cache suites |
| sonar-project.properties | SonarQube/SonarCloud config (code quality) |
| Dockerfile | Multi-stage Docker build (builder → runner-base → runner-cli) |
| docker-compose.yml | Dev compose with 4 profiles (base, cli, host, cliproxyapi) + redis sidecar |
| docker-compose.prod.yml | Production compose (port 20130, redis, named volumes) |
| .dockerignore | Files excluded from Docker context |
| fly.toml | Fly.io deployment config (region sin, port 20128, /data volume) |
| .env.example | Template env file (auto-copied to .env on first install) |
| .gitignore | Git ignore patterns |
| .npmignore | npm publish exclusion list |
| .npmrc | npm config (registry, lockfile policy) |
| .node-version | Node version pin (used by nvm-compatible tools) |
| .nvmrc | Node version pin for nvm |
| eslint.complexity.config.mjs | ESLint config for the complexity ratchet (scripts/check/check-complexity.mjs --config) |
| eslint.sonarjs.config.mjs | ESLint config for SonarJS rules (cognitive complexity / duplication) |
| source.config.ts | Fumadocs defineDocs source config (feeds .source/) |
| knip.json | Knip config — unused files/exports/deps (feeds the dead-code gate) |
| stryker.conf.json | Stryker mutation-testing config |
| .size-limit.json | size-limit bundle budget config |
| promptfooconfig.yaml | promptfoo eval config |
| .gitleaks.toml | gitleaks secret-scan ruleset |
| .zizmor.yml | zizmor GitHub-Actions security-lint config |
| socket.yml | Socket.dev supply-chain config |
| news.json | In-app release-notes feed (read by src/shared/utils/releaseNotes.ts) |
| flake.nix / flake.lock | Nix dev-shell definition + lock |
| .env | Local secrets (gitignored — generated from .env.example) |
Moved out of the root in v3.8.26 (declutter):
- →
config/quality/:quality-baseline.json,complexity-baseline.json,duplication-baseline.json,file-size-baseline.json,test-discovery-baseline.json,dependency-allowlist.json,.license-allowlist.json, and the generatedquality-metrics.json(gitignored). See## config/.
src/ — Next.js applicationsrc/
├── app/ # App Router (pages + API routes + status pages + landing)
├── lib/ # Core libraries / domain modules (~50 subdirs + ~30 top-level files)
├── domain/ # Pure domain logic (policy engine, fallback, cost, lockout, comboResolver, assessment)
├── server/ # Server-only modules (authz pipeline, cors, auth middleware) — cannot import from client
├── shared/ # Shared between server and client where safe (constants, types, validation, contracts, utils)
├── i18n/ # next-intl config + per-locale message JSON (30+ locales)
├── middleware/ # Next.js middleware (request enrichment, locale detection)
├── mitm/ # MITM proxy core: cert gen/install, handlers, targets, inspector, masks, passthrough
│ ├── handlers/ # 9 IDE-agent handler classes extending MitmHandlerBase (antigravity, kiro, copilot, codex, cursor, zed, claudeCode, openCode, trae)
│ └── inspector/ # Traffic capture layer: buffer (in-memory ring), sseMerger, conversationNormalizer, kindDetector, contextKey, httpProxyServer, systemProxyConfig
├── models/ # Model adapter glue (legacy shim)
├── scripts/ # In-tree maintenance scripts (e.g., backfillAggregation)
├── sse/ # Legacy SSE handlers/services (chat.ts, chatHelpers.ts, services/auth.ts)
├── store/ # Legacy in-memory store (being phased out for src/lib/db)
├── types/ # Shared TS type files
├── instrumentation.ts # Next.js telemetry hook (browser + edge)
├── instrumentation-node.ts # Node-only instrumentation
├── server-init.ts # Server bootstrap (DB migrations, jobs, cleanup)
└── proxy.ts # HTTP-proxy entry shim
src/app/ — App Router (Next.js 16)| Path | Purpose |
|---|---|
app/api/v1/ | Public OpenAI-compat API (~25 sub-routes: chat, completions, embeddings, files, batches, audio, images, videos, music, rerank, moderations, search, ws, agents, accounts, providers, etc.) |
app/api/v1beta/ | Gemini-style API endpoints |
app/api/playground/ | Playground Studio routes: improve-prompt/ (POST — LLM prompt rewriter), presets/ (GET list / POST create), presets/[id]/ (GET / PUT / DELETE) — see docs/frameworks/PLAYGROUND_STUDIO.md |
app/api/ (non-v1) | Management/admin routes (~60 directories: providers, combos, settings, mcp, a2a, evals, memory, skills, webhooks, compliance, resilience, monitoring, tunnels, cli-tools, etc.) |
app/api/tools/agent-bridge/ | AgentBridge REST API — 12 routes (server control, agent state/DNS/mappings, bypass, cert, upstream-CA). LOCAL_ONLY + SPAWN_CAPABLE. See docs/frameworks/AGENTBRIDGE.md §7. |
app/api/tools/traffic-inspector/ | Traffic Inspector REST + WS API — 16+ routes (requests, sessions, hosts, capture-modes, export, ws). LOCAL_ONLY + SPAWN_CAPABLE. See docs/frameworks/TRAFFIC_INSPECTOR.md §8. |
app/a2a/ | A2A JSON-RPC 2.0 entry point (POST /a2a) |
app/.well-known/agent.json/ | A2A Agent Card (discovery) |
app/(dashboard)/dashboard/ | Dashboard UI pages (~35 pages: providers, combos, settings, memory, skills, webhooks, evals, audit, batch, cache, costs, health, system, activity, etc.) |
app/(dashboard)/dashboard/search-tools/ | Search Tools Studio UI (3 tabs: Search/Scrape/Compare + SearchConceptCard + ProviderCatalog) — see docs/frameworks/SEARCH_TOOLS_STUDIO.md |
app/(dashboard)/dashboard/ | Dashboard UI pages (~30 pages: providers, combos, settings, memory, skills, webhooks, evals, audit, batch, cache, costs, health, system, etc.) |
app/(dashboard)/dashboard/memory/ | Memory Studio (plan 21): page.tsx (3-tab shell), components/ (MemoryConceptCard, MemoryEngineStatus, EmbeddingSourceSelector, EditMemoryModal, RetrievePreview, QdrantConfigCard, RerankConfigCard), components/tabs/ (MemoriesTab, PlaygroundTab, EngineTab), hooks/ (useEngineStatus, useMemorySettings) |
app/(dashboard)/dashboard/tools/agent-bridge/ | AgentBridge dashboard page — server card, 9 agent cards, setup wizard, model mapping, bypass list. i18n PT-BR + EN. See docs/frameworks/AGENTBRIDGE.md. |
app/(dashboard)/dashboard/tools/traffic-inspector/ | Traffic Inspector dashboard page — DevTools split, 7 detail tabs, 4 capture mode toggles, session recorder, context colorization. i18n PT-BR + EN. See docs/frameworks/TRAFFIC_INSPECTOR.md. |
app/(dashboard)/dashboard/activity/ | Activity feed page (Group B): page.tsx (server) + ActivityFeedClient.tsx + components/{ActivityFeed,ActivityItem,DayHeader,EventTypeFilter}.tsx — see docs/architecture/MONITORING_SECTIONS.md |
app/(dashboard)/dashboard/costs/quota-share/ | Quota Sharing page (Group B): QuotaSharePageClient.tsx + components/{PoolCard,DimensionBar,AllocationTable,BurnRateChart,QuotaConceptCard,CreatePoolModal,EditAllocationsModal}.tsx + hooks/{usePools,usePoolUsage,useLocalStoragePoolMigration}.ts |
app/(dashboard)/dashboard/costs/quota-share/plans/ | Provider plan config page (Group B): page.tsx + ProviderPlanConfigClient.tsx — quota dimensions per connection override |
app/docs/ | Embedded documentation viewer (renders docs/*.md) |
app/landing/ | Marketing landing page |
app/login/, forgot-password/, forbidden/ | Auth-related pages |
app/{400,401,403,408,429,500,502,503}/ | HTTP error pages |
app/maintenance/, offline/, status/, privacy/, terms/, callback/ | Static/status pages |
app/layout.tsx, page.tsx, manifest.ts, globals.css | Root layout, home, PWA manifest, global CSS |
app/error.tsx, global-error.tsx, not-found.tsx, loading.tsx | Error boundaries |
src/lib/ — Core libraries (~50 modules)| Module | Purpose |
|---|---|
a2a/ | A2A protocol task manager, skills (5), streaming |
acp/ | CLI Agent Registry (local CLI discovery — see docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) |
api/ | Shared API helpers (requireManagementAuth, validation) |
auth/ | Session, password hashing, token validation |
batches/ | OpenAI Batches API handlers |
catalog/ | Provider catalog Zod validation + capability resolution |
cloudAgent/ | Cloud Agents (Codex Cloud, Devin, Jules) — see docs/frameworks/CLOUD_AGENT.md |
combos/ | Combo resolution + reorder helpers |
audit/ | Activity feed helpers: highLevelActions.ts (allowlist + isHighLevelAction()), activityIcons.ts (action → icon/verb map), timeline.ts (groupByDay/relativeTime) — see docs/architecture/MONITORING_SECTIONS.md |
compliance/ | Audit log + provider audit — see docs/security/COMPLIANCE.md |
compression/ | Compression engine glue (engines live in open-sse/services/compression/) |
config/ | Runtime config helpers |
db/ | 95+ domain DB modules + 144 migrations (always go through here for SQLite) |
quota/ | Quota Sharing Engine: dimensions.ts (types/Zod), types.ts (QuotaStore interface), sqliteQuotaStore.ts, redisQuotaStore.ts, storeFactory.ts, fairShare.ts, burnRate.ts, planResolver.ts, planRegistry.ts, saturationSignals.ts, enforce.ts, spendRecorder.ts — see docs/routing/QUOTA_SHARE.md |
radar/ | Radar free-model catalog client: feedSchema.ts, pinnedKeys.ts, verify.ts, sync.ts, applyFeed.ts, index.ts (getRadarCatalog()) — see docs/frameworks/RADAR.md |
display/ | UI formatting helpers (cost, latency, etc.) |
embeddings/ | Embeddings service helpers |
env/ | Env variable parsing + validation |
evals/ | Eval framework (suites, runner, runtime) — see docs/frameworks/EVALS.md |
guardrails/ | PII masker, prompt injection, vision bridge — see docs/security/GUARDRAILS.md |
jobs/ | Background jobs (cron-like) |
memory/ | Conversational memory (SQLite FTS5 + sqlite-vec hybrid RRF + Qdrant tier 2) — see docs/frameworks/MEMORY.md |
memory/embedding/ | Multi-source embedding layer: index.ts (resolver), remote.ts, staticPotion.ts, transformersLocal.ts, cache.ts, types.ts (plan 21) |
memory/vectorStore.ts | sqlite-vec v0.1.9 wrapper — KNN brute-force + hybrid RRF (FTS5 + vector, k=60). Lazy-init, degrades gracefully when sqlite-vec unavailable. (plan 21) |
memory/reindex.ts | runReindexBatch() — processes memories with needs_reindex=1 in background; called by POST /api/memory/reindex and lazy-backfill path. (plan 21) |
monitoring/ | Health checks, metrics emission |
oauth/ | OAuth/import flows for 22 provider modules (agy, antigravity, claude, cline, codebuddy-cn, codex, cursor, devin-desktop, ghe-copilot, github, gitlab-duo, grok-cli-oauth, grok-cli, kilocode, kimi-coding, kiro, qoder, raycast, trae, xai-oauth, zed-hosted, zed) |
plugins/ | Plugin registry |
promptCache/ | Anthropic-style prompt cache breakpoints |
skills/ | Skills framework (built-in + marketplace + SkillsSH) — see docs/frameworks/SKILLS.md |
playground/ | Playground Studio shared helpers: codeExport.ts (curl/Python/TS generator), promptImprover.ts (meta-prompt builder), streamMetrics.ts (pure TTFT/TPS), types.ts (pricing table) — see docs/frameworks/PLAYGROUND_STUDIO.md |
webhookDispatcher.ts | HMAC webhook delivery — see docs/frameworks/WEBHOOKS.md |
cloudflaredTunnel.ts, ngrokTunnel.ts | Tunnel managers — see docs/ops/TUNNELS_GUIDE.md |
oneproxySync.ts, oneproxyRotator.ts | 1proxy free proxy marketplace — see docs/ops/PROXY_GUIDE.md |
cloudSync.ts, initCloudSync.ts | Optional cloud sync of state |
localDb.ts | Re-export barrel for db modules (no logic — re-exports only) |
cacheLayer.ts, idempotencyLayer.ts | Request caching + idempotency |
| (~30 more top-level files) | Specialized helpers (logEnv, modelsDevSync, piiSanitizer, etc.) |
src/db/ — Database (117 modules + 144 migrations)| Subdir | Purpose |
|---|---|
db/core.ts | getDbInstance() singleton with WAL journaling |
db/migrations/ | Versioned SQL files (idempotent, transactional). 073_memory_vec.sql adds memory_vec_meta + needs_reindex column (plan 21). |
db/playgroundPresets.ts | CRUD module for Playground Studio presets (listPlaygroundPresets, getPlaygroundPreset, createPlaygroundPreset, updatePlaygroundPreset, deletePlaygroundPreset) |
db/memoryVec.ts | CRUD for memory_vec_meta (active_dim, embedding_signature, last_reset_at, vec_loaded) + markMemoryNeedsReindex, getMemoryReindexQueue, etc. (plan 21) |
db/<domain>.ts | One module per domain: providers, combos, apiKeys, users, sessions, usage, auditlog, webhooks, skills, memory_entries, cloud_agent_tasks, evals*, reasoning_cache, etc. |
src/domain/| Module | Purpose |
|---|---|
policy.ts | Policy engine |
fallbackPolicy.ts | Fallback decision tree |
costRules.ts | Cost calculation rules |
lockoutPolicy.ts | Model/connection lockout policy |
tagRouter.ts | Tag-based routing |
comboResolver.ts | Combo resolution (used by combo engine) |
modelAvailability.ts | Per-model availability check |
assessment/ | Model assessment (Phase 1 of RFC-AUTO-ASSESSMENT — see docs/archive/) |
src/server/| Module | Purpose |
|---|---|
authz/ | Authorization pipeline: classify → policies → enforce — see docs/architecture/AUTHZ_GUIDE.md |
cors/ | CORS configuration |
auth/ | Session middleware |
src/shared/| Module | Purpose |
|---|---|
constants/providers.ts | 338 providers with Zod validation (source of truth) |
constants/cliTools.ts | External CLI tool registry |
constants/routingStrategies.ts | 19 routing strategies with priorities |
constants/publicApiRoutes.ts | Routes that require Bearer (vs management) auth |
constants/upstreamHeaders.ts | Header denylist for upstream requests |
validation/schemas.ts | ~80 Zod schemas (single source of truth for API contracts) |
validation/helpers.ts | Zod validation helpers (validateBody, etc.) |
types/ | Shared TS types |
contracts/ | Public API contracts (consumed by files: in package.json) |
utils/circuitBreaker.ts | Provider circuit breaker (see docs/architecture/RESILIENCE_GUIDE.md) |
utils/apiAuth.ts | API key validation, scope checking |
utils/fetchTimeout.ts | Timeout/abort wrappers for upstream fetch |
open-sse/ — Streaming Engine WorkspaceSeparate npm workspace (@omniroute/open-sse). Handles request processing + provider execution.
open-sse/
├── handlers/ # 16 files (12 handlers + 4 helpers): chatCore, responsesHandler, embeddings, audio, image, video, music, rerank, moderations, search, etc.
├── executors/ # 67 provider-specific executors (extend BaseExecutor)
├── translator/ # Format converters (9 request, 9 response, 9 helpers)
├── transformer/ # Responses API ↔ Chat Completions (TransformStream)
├── services/ # ~80+ service modules (combo, accountFallback, autoCombo, reasoningCache, claude code/chatgpt stealth, modelDeprecation, taskAwareRouter, workflowFSM, etc.)
├── mcp-server/ # MCP server (105 tools, 3 transports, 31 scopes)
├── config/ # Provider/model registries, header config, model aliases
├── utils/ # TLS client, proxy fetch/dispatcher, network helpers
├── index.ts # Workspace entry
├── package.json # Workspace manifest
├── tsconfig.json # Workspace TS config
└── types.d.ts # Workspace type declarations
open-sse/mcp-server/| Path | Purpose |
|---|---|
server.ts | MCP server lifecycle (stdio + HTTP transports) |
httpTransport.ts | HTTP Streamable + SSE transports (/api/mcp/sse, /api/mcp/stream) |
audit.ts | Audit logging to mcp_tool_audit table |
scopeEnforcement.ts | Per-tool scope validation |
runtimeHeartbeat.ts | Health heartbeat to DATA_DIR/runtime/mcp-heartbeat.json |
descriptionCompressor.ts | Compress tool description metadata to save context |
schemas/tools.ts | 36 base tool definitions + scopes |
tools/advancedTools.ts | Advanced tool implementations |
tools/memoryTools.ts | 3 memory tools (search/add/clear) |
tools/skillTools.ts | 4 skill tools (list/enable/execute/executions) |
tools/compressionTools.ts | 5 compression tools |
README.md | Internal MCP server README (cross-linked from docs/frameworks/MCP-SERVER.md) |
electron/ — Desktop Wrapper| File | Purpose |
|---|---|
main.js | Electron main process (BrowserWindow, embedded Next.js server, tray, auto-update) |
preload.js | IPC bridge (contextBridge → window.omniroute) |
package.json | electron-builder config + Electron 41 + electron-builder 26.10 deps |
assets/ | App icons (Windows .ico, macOS .icns, Linux .png) |
dist-electron/ | Build output (gitignored) |
types.d.ts | Type declarations for renderer bridge |
README.md | Internal Electron README (see also docs/guides/ELECTRON_GUIDE.md) |
bin/ — CLI| File | Purpose |
|---|---|
omniroute.mjs | Main CLI entry — omniroute serve, omniroute setup, omniroute doctor, omniroute providers, omniroute combos, etc. |
reset-password.mjs | Standalone password reset CLI |
cli/commands/setup.mjs | Interactive + non-interactive setup wizard |
cli/commands/doctor.mjs | System health diagnostics (8+ checks) |
cli/commands/providers.mjs | Provider list/test/validate |
cli/{args,data-dir,encryption,io,provider-catalog,provider-store,provider-test,settings-store,sqlite}.mjs | CLI helper modules |
cli/tray/tray.ts | System tray integration (cross-platform: NotifyIcon on Windows, systray2 on macOS/Linux) |
cli/tray/tray.ps1 | PowerShell NotifyIcon backend (Windows, zero new binaries) |
cli/tray/autostart.ts | Cross-platform autostart (LaunchAgent / .desktop / registry) |
cli/runtime/sqliteRuntime.mjs | 5-step SQLite driver resolution chain (bundled → runtime → lazy-install → node:sqlite → sql.js) |
cli/runtime/magicBytes.mjs | Binary magic-byte validation (ELF / Mach-O / Mach-O fat / PE) |
cli/runtime/index.mjs | warmUpRuntimes() — pre-resolves drivers at postinstall / first startup |
nodeRuntimeSupport.mjs | Validate supported Node.js version on install |
skills/ — Public Agent Skills| File | Purpose |
|---|---|
skills/omniroute*/SKILL.md | 10 skill manifests for external AI agents (Claude Desktop, ChatGPT, Cursor, Cline) |
scripts/ — Build & Check Scripts| Script | Purpose |
|---|---|
run-next.mjs | Dev/start runner with env hydration |
build-next-isolated.mjs | Standalone build (Next.js 16 standalone) |
prepublish.ts | Package preparation before npm pack |
postinstall.mjs | Auto-create .env from .env.example on first install |
sync-env.mjs | Re-sync .env keys with .env.example |
check-cycles.mjs | Detect circular dependencies |
check-route-validation.mjs | Validate all API routes have Zod validation |
check-t11-any-budget.mjs | Enforce explicit any budget per file |
check-docs-sync.mjs | Validate docs version sync (existing pre-commit) |
check-env-doc-sync.mjs | NEW: cross-check env vars in code vs .env.example vs ENVIRONMENT.md |
check-docs-counts-sync.mjs | NEW: validate counts (executors, strategies, OAuth, A2A skills) match docs |
check-deprecated-versions.mjs | NEW: flag stale versions/dates in docs |
check-supported-node-runtime.ts | Validate current Node version is supported |
check-pr-test-policy.mjs | Enforce "tests required" rule on production code changes |
gen-provider-reference.ts | NEW: auto-generate docs/reference/PROVIDER_REFERENCE.md from catalog |
i18n/generate-multilang.mjs | Translate UI strings + docs via Google Translate |
i18n_autotranslate.py | LLM-based doc translation pipeline |
validate_translation.py | Per-locale translation validation |
check_translations.py | Code-side i18n key check |
run-playwright-tests.mjs | Playwright E2E runner |
run-protocol-clients-tests.mjs | MCP/A2A E2E runner |
run-ecosystem-tests.mjs | Ecosystem (provider integration) tests |
test-report-summary.mjs | Generate coverage summary markdown |
smoke-electron-packaged.mjs | Smoke-test packaged Electron build |
native-binary-compat.mjs | Validate native deps (better-sqlite3) match Electron's Node |
validate-pack-artifact.ts | Validate npm pack output |
responses-ws-proxy.mjs | WebSocket bridge for Codex Responses API |
v1-ws-bridge.mjs | WebSocket bridge for /api/v1/ws endpoint |
standalone-server-ws.mjs | Standalone WS server runner |
system-info.mjs | Print system/runtime info for support |
healthcheck.mjs | One-shot health check (used by Docker HEALTHCHECK) |
uninstall.mjs | Clean uninstall script |
docs/ — Public Documentation (44 files + 4 subdirs)| Doc | Purpose |
|---|---|
ARCHITECTURE.md | High-level architecture, subsystem map, dashboard surface |
CODEBASE_DOCUMENTATION.md | Engineering reference: directories, modules, conventions |
FEATURES.md | Feature matrix with v3.8 highlights |
USER_GUIDE.md | End-user manual (setup, models, combos, CLIs, audio, etc.) |
API_REFERENCE.md | API endpoint reference with auth model |
openapi.yaml | OpenAPI 3.0 spec (121 paths) |
SETUP_GUIDE.md | Install methods (npm, npx, Docker, Electron, Termux, source) |
ENVIRONMENT.md | All env vars (~219 used in code, ~810 lines .env.example) |
TROUBLESHOOTING.md | Common errors + v3.8.0 known issues |
RELEASE_CHECKLIST.md | Full release flow (skills, husky, conventional commits, deploy) |
COVERAGE_PLAN.md | Coverage goals and current state |
FREE_TIERS.md | Curated free-tier providers (48+ free + 11 OAuth) |
CLI-TOOLS.md | External CLI integrations + Internal OmniRoute CLI |
I18N.md | i18n architecture, adding a language, 43 locales |
UNINSTALL.md | Clean uninstall steps |
PROVIDER_REFERENCE.md | Auto-generated catalog of 338 providers (regen: npm run gen:provider-reference) |
| Doc | Purpose |
|---|---|
MCP-SERVER.md | MCP server: 105 tools, 3 transports, 31 scopes, REST endpoints |
A2A-SERVER.md | A2A v0.3: JSON-RPC, 6 skills, REST helpers, agent card |
AGENT_PROTOCOLS_GUIDE.md | Unified guide: A2A vs ACP vs Cloud Agents |
CLOUD_AGENT.md | Codex Cloud / Devin / Jules orchestration |
SKILLS.md | Skills framework (built-in + marketplace + SkillsSH + sandbox) |
RADAR.md | Radar free-model catalog overlay (RADAR_ENABLED, off by default) |
MEMORY.md | Memory system (SQLite FTS5 + Qdrant) |
EVALS.md | Eval framework (suites, runs, rubrics) |
GUARDRAILS.md | PII masker, prompt injection, vision bridge |
COMPLIANCE.md | Audit log, retention, noLog opt-out |
WEBHOOKS.md | HMAC-signed webhook delivery |
REASONING_REPLAY.md | Hybrid memory/SQLite cache for reasoning_content |
AUTHZ_GUIDE.md | Authorization pipeline (classify → policies → enforce) |
RESILIENCE_GUIDE.md | Circuit breaker + cooldown + model lockout |
STEALTH_GUIDE.md | TLS fingerprinting (JA3/JA4), Claude Code CCH, MITM cert |
AUTO-COMBO.md | Auto Combo engine (9-factor scoring, 4 mode packs, virtual factory) |
| Doc | Purpose |
|---|---|
COMPRESSION_GUIDE.md | Overview of compression modes + roadmap |
COMPRESSION_ENGINES.md | Caveman + RTK engines, registry contract |
COMPRESSION_RULES_FORMAT.md | Caveman rule pack JSON schema |
COMPRESSION_LANGUAGE_PACKS.md | Per-language rule pack inventory |
RTK_COMPRESSION.md | RTK declarative pipeline (49 filters) |
| Doc | Purpose |
|---|---|
DOCKER_GUIDE.md | Docker build, profiles (base/cli/host/cliproxyapi), Redis sidecar |
VM_DEPLOYMENT_GUIDE.md | Generic VM/VPS deployment (Ubuntu/Debian + nginx + systemd) |
FLY_IO_DEPLOYMENT_GUIDE.md | Fly.io deployment (currently Chinese-only) |
TERMUX_GUIDE.md | Android headless via Termux |
PWA_GUIDE.md | Progressive Web App install + service worker |
ELECTRON_GUIDE.md | Desktop app build + sign + distribute |
TUNNELS_GUIDE.md | Cloudflared + ngrok + Tailscale Funnel |
PROXY_GUIDE.md | 4-level outbound proxy + 1proxy marketplace |
| Subdir | Purpose |
|---|---|
docs/archive/ | Archived/historical docs (e.g., RFC-AUTO-ASSESSMENT-DRAFT.md — superseded by EVALS) |
docs/i18n/ | Localized doc translations (~42 locales) |
docs/screenshots/ | Image assets for guides |
_tasks/superpowers/ | Plans/specs from superpowers (writing-plans/brainstorming) + research — isolated, separately-versioned repo, gitignored by the main tree. See CLAUDE.md → "Planning & Research Artifacts". |
tests/ — Test Suites| Subdir | Type | Runner |
|---|---|---|
tests/unit/ | Unit tests (~500 files, fastest) | Node native test runner |
tests/integration/ | Multi-module + DB integration tests | Node native test runner (concurrency 1) |
tests/e2e/ | UI + workflow E2E | Playwright |
tests/protocols-e2e/ | MCP + A2A real-client E2E | Custom protocol clients |
tests/ecosystem/ | Provider integration (network-touching) | Node native test runner |
public/ — Static Assets| Path | Purpose |
|---|---|
public/ (root) | Favicons, robots.txt, manifest, service worker, marketing images |
public/providers/ | Provider logo PNG/SVG (used in dashboard) |
config/ — Static Configs + Quality-Gate StateShipped configuration templates plus the committed quality-gate baselines (moved here from the repo root in v3.8.26 to keep the root lean).
| Path | Purpose |
|---|---|
config/i18n.json | Locale list + metadata (canonical source for the 42-locale count) |
config/i18n-schema.json | JSON schema validating i18n.json |
config/payloadRules.json | Upstream payload sanitization rules |
config/quality/quality-baseline.json | Multi-metric ratchet baseline (scripts/quality/check-quality-ratchet.mjs) |
config/quality/complexity-baseline.json | Frozen ESLint-complexity baseline (check-complexity.mjs) |
config/quality/duplication-baseline.json | Frozen jscpd duplication baseline (check-duplication.mjs) |
config/quality/file-size-baseline.json | Frozen per-file size baseline (check-file-size.mjs) |
config/quality/test-discovery-baseline.json | Frozen orphan-test baseline (check-test-discovery.mjs) |
config/quality/dependency-allowlist.json | Approved dependencies allowlist (check-deps.mjs) |
config/quality/.license-allowlist.json | SPDX license allowlist (check-licenses.mjs) |
config/quality/quality-metrics.json | Ephemeral collected metrics (generated by collect-metrics.mjs; gitignored) |
.github/ — GitHub Integration| Path | Purpose |
|---|---|
.github/workflows/ | GitHub Actions CI/CD workflows (lint, test, coverage, release) |
.github/ISSUE_TEMPLATE/ | Bug/feature issue templates |
.github/PULL_REQUEST_TEMPLATE.md | PR template |
.github/dependabot.yml | Dependency update config |
.husky/ — Git Hooks| File | Purpose |
|---|---|
pre-commit | Runs lint-staged + check-docs-sync + check:any-budget:t11 |
pre-push | Currently disabled (commented). Run npm run test:unit manually. |
_/ | Husky internals |
.claude/ — Claude Code Slash Commands| File | Purpose |
|---|---|
commands/version-bump-cc.md | /version-bump-cc — bump version + auto-changelog |
commands/generate-release-cc.md | /generate-release-cc — full release workflow |
commands/deploy-vps-{local,akamai,both}-cc.md | Deploy to VPS |
commands/capture-release-evidences-cc.md | Browser-record new features as WebP |
commands/review-{prs,discussions}-cc.md | Triage GitHub PRs/discussions |
commands/{review-issues,implement-features}-cc.md | Issue workflows |
settings.local.json | Per-project Claude Code settings |
.agents/ — Generic Agent Workflows (Codex / Cursor / etc.)| Path | Purpose |
|---|---|
workflows/*-ag.md | 11 workflow definitions (mirror of .claude/commands/) |
skills/<name>/SKILL.md | 9 skill definitions with Codex Execution Notes |
Note: Workflows and commands are currently identical byte-by-byte. If
.agents/is meant to target a different agent runtime (Codex), the variants need to diverge meaningfully.
_ideia/, _mono_repo/, _references/, _tasks/ — Out-of-treeThese underscore-prefixed directories hold non-shipping content:
_ideia/ — design notes (defer / notfit / viable categories)_mono_repo/ — historic subprojects (omnirouteCloud, omnirouteSite, vscode-extension)_references/ — read-only clones of related OSS projects (LiteLLM, 9router, ClawRouter, CLIProxyAPI, modelrelay, new-api, etc.) for cross-reference during development_tasks/ — per-release task tracking files (informal)Not included in npm pack output. See .npmignore.
| Path | Purpose |
|---|---|
node_modules/ | npm dependencies |
.next/ | Next.js build output |
coverage/ | c8 coverage reports |
logs/ | Runtime logs |
package/ | npm pack staging |
.playwright-mcp/ | Playwright MCP test artifacts |
.issues/ | Local issue cache |
tsconfig.tsbuildinfo | TS incremental cache |
CONTRIBUTING.md → CLAUDE.md → docs/architecture/ARCHITECTURE.md → docs/architecture/CODEBASE_DOCUMENTATION.md.docs/architecture/ARCHITECTURE.md § Adding a New Provider + cross-check docs/reference/PROVIDER_REFERENCE.md.docs/architecture/ARCHITECTURE.md § Adding a New API Route + src/shared/validation/schemas.ts.docs/frameworks/MCP-SERVER.md § Adding a Tool.docs/frameworks/A2A-SERVER.md § Adding a New Skill.docs/guides/SETUP_GUIDE.md.docs/guides/DOCKER_GUIDE.md / docs/ops/VM_DEPLOYMENT_GUIDE.md / docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md.docs/ops/RELEASE_CHECKLIST.md (and /generate-release-cc Claude Code skill).