wehub-resource-sync
584 lines
67 KiB
Markdown
584 lines
67 KiB
Markdown
---
|
|
title: "Repository Map"
|
|
version: 3.8.40
|
|
lastUpdated: 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/`](#config--static-configs--quality-gate-state).
|
|
|
|
---
|
|
|
|
## `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, 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` | **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).
|