--- title: "Repository Map" version: 3.8.2 lastUpdated: 2026-05-13 --- # 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/.ts` | One module per domain: providers, combos, apiKeys, users, sessions, usage, audit*log, 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//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).