| title | Repository Map |
|---|---|
| version | 3.8.26 |
| lastUpdated | 2026-06-15 |
One-line description for every directory and root file. Last updated: 2026-06-15 — OmniRoute v3.8.26
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 |
| semcheck.yaml | semcheck (spec↔code drift) 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/.- →
docs/ops/:DOCUMENTATION_AUDIT_REPORT.md.
src/
├── 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
| 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 |
| 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/ |
45+ domain DB modules + 55 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 |
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 flows for 14 providers (claude, codex, antigravity, cursor, github, gemini, kimi-coding, kilocode, cline, qwen, kiro, qoder, gitlab-duo, windsurf) |
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.) |
| 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. |
| 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/) |
| Module | Purpose |
|---|---|
authz/ |
Authorization pipeline: classify → policies → enforce — see docs/architecture/AUTHZ_GUIDE.md |
cors/ |
CORS configuration |
auth/ |
Session middleware |
| Module | Purpose |
|---|---|
constants/providers.ts |
226 providers with Zod validation (source of truth) |
constants/cliTools.ts |
External CLI tool registry |
constants/routingStrategies.ts |
14 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 |
Separate npm workspace (@omniroute/open-sse). Handles request processing + provider execution.
open-sse/
├── handlers/ # 15 files (11 handlers + 4 helpers): chatCore, responsesHandler, embeddings, audio, image, video, music, rerank, moderations, search, etc.
├── executors/ # 31 provider-specific executors (extend BaseExecutor)
├── translator/ # Format converters (9 request, 8 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 (87 tools, 3 transports, 30 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
| 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 |
30 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) |
| 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) |
| 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 |
| File | Purpose |
|---|---|
skills/omniroute*/SKILL.md |
10 skill manifests for external AI agents (Claude Desktop, ChatGPT, Cursor, Cline) |
| 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 |
| 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, 30 locales |
UNINSTALL.md |
Clean uninstall steps |
PROVIDER_REFERENCE.md |
Auto-generated catalog of 226 providers (regen: npm run gen:provider-reference) |
| Doc | Purpose |
|---|---|
MCP-SERVER.md |
MCP server: 87 tools, 3 transports, 30 scopes, REST endpoints |
A2A-SERVER.md |
A2A v0.3: JSON-RPC, 5 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) |
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 |
docs/superpowers/plans/ |
Implementation plans (generated by superpowers:writing-plans skill) |
| 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 |
| Path | Purpose |
|---|---|
public/ (root) |
Favicons, robots.txt, manifest, service worker, marketing images |
public/providers/ |
Provider logo PNG/SVG (used in dashboard) |
Shipped 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) |
| 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 |
| 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 |
| 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 |
| 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.
These 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 |
- New contributor? Read
CONTRIBUTING.md→CLAUDE.md→docs/architecture/ARCHITECTURE.md→docs/architecture/CODEBASE_DOCUMENTATION.md. - Adding a provider? Follow
docs/architecture/ARCHITECTURE.md § Adding a New Provider+ cross-checkdocs/reference/PROVIDER_REFERENCE.md. - Adding a route?
docs/architecture/ARCHITECTURE.md § Adding a New API Route+src/shared/validation/schemas.ts. - Adding an MCP tool?
docs/frameworks/MCP-SERVER.md § Adding a Tool. - Adding an A2A skill?
docs/frameworks/A2A-SERVER.md § Adding a New Skill. - Running locally?
docs/guides/SETUP_GUIDE.md. - Deploying?
docs/guides/DOCKER_GUIDE.md/docs/ops/VM_DEPLOYMENT_GUIDE.md/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md. - Releasing?
docs/ops/RELEASE_CHECKLIST.md(and/generate-release-ccClaude Code skill).