OmniRoute/docs/architecture/REPOSITORY_MAP.md

title, version, lastUpdated

title	version	lastUpdated
Repository Map	3.8.40	2026-06-28

Repository Map

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.

Top-level tree

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)

---

Root files

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 generated quality-metrics.json (gitignored). See ## config/.

---

src/ — Next.js application

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

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 + 110+ 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.)

src/db/ — Database (94 modules + 106 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	236 providers with Zod validation (source of truth)
constants/cliTools.ts	External CLI tool registry
constants/routingStrategies.ts	17 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 Workspace

Separate 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 (94 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

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	34 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)

Top-level guides

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 236 providers (regen: npm run gen:provider-reference)

Subsystem deep-dives

Doc	Purpose
MCP-SERVER.md	MCP server: 94 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)

Compression

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)

Deployment

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

Subdirectories

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 State

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)

---

.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-tree

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.

---

Generated / Gitignored

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

---

Navigation tips

• 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-check docs/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-cc Claude Code skill).