Repository Map

One-line description for every directory and root file. Last updated: 2026-05-13 — OmniRoute v3.8.0

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 files
├── images/               # Marketing / README image assets
├── .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)
├── .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)
Tuto_Qdrant.md	Tutorial for enabling Qdrant vector memory — integration currently dormant (see banner; primary memory docs in `docs/frameworks/MEMORY.md`)
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 (815 lines, 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

`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/`	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.)

`src/db/` — Database (45+ modules + 55 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`	177 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

`open-sse/` — Streaming Engine Workspace

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 (37 tools, 3 transports, ~13 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`	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`)

`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
`generate-docs-index.mjs`	Build `src/app/docs/lib/docs-auto-generated.ts` from `docs/*.md`
`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 177 providers (regen: `npm run gen:provider-reference`)

Subsystem deep-dives

Doc	Purpose
`MCP-SERVER.md`	MCP server: 37 tools, 3 transports, ~13 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 (~40 locales)
`docs/screenshots/`	Image assets for guides
`docs/superpowers/plans/`	Implementation plans (generated by `superpowers:writing-plans` skill)

`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

Shipped configuration templates and sample files (referenced by setup wizard).

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

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