--- description: Project structure, conventions, and coding guidelines for the 9Router codebase. Applies to all source code edits, reviews, and architectural decisions. applyTo: '**/*' --- # 9Router — Project Structure & Coding Guidelines ## What This Is 9Router (`9router-app`) is a local AI routing gateway + Next.js dashboard. It exposes one OpenAI-compatible endpoint (`/v1/*`) and routes traffic across 40+ upstream providers with format translation, model-combo fallback, multi-account fallback, OAuth/API-key credential management, token refresh, quota/usage tracking, and optional cloud sync. ### Two Published Artifacts (One Repo) | Artifact | Location | npm name | Purpose | |----------|----------|----------|---------| | Dashboard + Gateway | root `package.json` | `9router-app` | Next.js server — actual routing engine | | CLI Launcher | `cli/` | `9router` | Separate package — installs/starts server, manages tray | ## Directory Map ``` 9router/ ├── src/ # Next.js app + dashboard + compat APIs │ ├── app/ │ │ ├── api/ # Management + compatibility APIs │ │ │ ├── v1/ # OpenAI-compatible endpoint (routed from /v1/* by next.config.mjs) │ │ │ ├── v1beta/ # Gemini-compatible endpoint │ │ │ ├── providers/ # Provider CRUD APIs │ │ │ ├── auth/ # Authentication APIs (login, oauth, keys) │ │ │ ├── models/ # Model listing API │ │ │ ├── combos/ # Model combo CRUD │ │ │ ├── oauth/ # OAuth flow handlers │ │ │ ├── settings/ # Dashboard settings │ │ │ ├── usage/ # Usage/statistics │ │ │ ├── keys/ # API key management │ │ │ ├── mcp/ # MCP integration │ │ │ ├── pricing/ # Pricing data │ │ │ ├── proxy-pools/ # Proxy pool management │ │ │ ├── pxpipe/ # PXPipe token saver │ │ │ ├── translator/ # Translator test endpoints │ │ │ ├── tags/ # Tag management │ │ │ ├── tunnel/ # Tunnel management │ │ │ ├── health/ # Health check │ │ │ └── version/ # Version info │ │ ├── dashboard/ # Dashboard pages (Next.js pages router style) │ │ ├── login/ # Login page │ │ ├── landing/ # Landing page │ │ ├── callback/ # OAuth callback handlers │ │ ├── layout.js # Root layout │ │ ├── page.js # Root page (redirects) │ │ └── globals.css # Global styles │ ├── lib/ │ │ ├── db/ # SQLite persistence layer │ │ │ ├── driver.js # Adapter fallback: bun:sqlite → better-sqlite3 → node:sqlite → sql.js │ │ │ ├── adapters/ # Per-runtime SQLite adapters │ │ │ ├── repos/ # Per-entity repos (connectionsRepo, combosRepo, settingsRepo, etc.) │ │ │ ├── migrations/ # Schema migrations │ │ │ ├── paths.js # DB file path resolver (DATA_DIR || ~/.9router/) │ │ │ └── helpers/ # JSON column helpers, backups │ │ ├── localDb.js # Backward-compat shim → re-exports @/lib/db/index.js │ │ ├── usageDb.js # Usage + log persistence (~/.9router/usage.json, log.txt) │ │ ├── requestDetailsDb.js # Request detail logging DB │ │ ├── oauth/ # OAuth flow helpers │ │ ├── headroom/ # Headroom token compression │ │ ├── pxpipe/ # PXPipe multimodal compression │ │ ├── qoder/ # Qoder provider helpers │ │ ├── tunnel/ # Tunnel helpers │ │ ├── network/ # Network utilities │ │ ├── auth/ # Auth utilities │ │ └── updater/ # App updater │ ├── sse/ # App-side SSE glue (entry → open-sse engine) │ │ ├── handlers/ # Chat handler (combo expansion, account selection) │ │ ├── services/ # Token refresh, credential management │ │ └── utils/ # SSE-specific utilities │ ├── store/ # Zustand client stores │ │ ├── index.js # Re-exports all stores │ │ ├── providerStore.js # Provider state │ │ ├── settingsStore.js # App settings │ │ ├── userStore.js # User/auth state │ │ ├── themeStore.js # Theme preferences │ │ ├── notificationStore.js # Notification state │ │ └── headerSearchStore.js # Header search state │ ├── shared/ # Shared code (client + server) │ │ ├── components/ # Reusable React components │ │ ├── constants/ # Re-exported config from open-sse │ │ ├── hooks/ # React hooks │ │ ├── services/ # Shared API clients │ │ └── utils/ # Shared utilities │ ├── i18n/ # Runtime i18n (client-side JSON-based) │ │ ├── config.js # Locale list + constants │ │ ├── runtime.js # Client: load translation JSON, translate() function │ │ └── RuntimeI18nProvider.js # React context provider │ ├── dashboardGuard.js # Auth guard for dashboard routes │ ├── proxy.js # Proxy middleware │ └── models/ # Data models ├── open-sse/ # Provider-agnostic routing/translation ENGINE │ ├── config/ # ALL constants — NEVER hardcode elsewhere │ │ ├── providers.js # Provider definitions │ │ ├── providerModels.js # Model alias → model matrix │ │ ├── models.js # Model constants │ │ ├── runtimeConfig.js # Timeouts, token limits, retry config │ │ ├── appConstants.js # App-wide constants (endpoints, header builders) │ │ └── *Constants.js # Provider-specific constants │ ├── translator/ # Format conversion (client ↔ provider) │ │ ├── index.js # Registry + translateRequest/translateResponse │ │ ├── request/ # Request translators (e.g., openai-to-claude.js) │ │ ├── response/ # Response translators │ │ ├── schema/ # Enums: ROLE, CLAUDE_BLOCK, OPENAI_BLOCK │ │ ├── concerns/ # Shared translation logic │ │ ├── formats/ # Per-format helpers │ │ └── formats.js # Format enum │ ├── executors/ # Per-provider upstream HTTP calls │ │ ├── base.js # BaseExecutor class │ │ ├── default.js # DefaultExecutor (OpenAI-compatible providers) │ │ ├── index.js # Executor registry map │ │ └── {provider}.js # One file per non-standard provider │ ├── handlers/ # Per-modality cores (chat, image, embedding, tts, stt, search) │ │ ├── chatCore.js # Main chat handler entry │ │ ├── chatCore/ # Streaming/non-streaming/SSE-to-JSON sub-handlers │ │ ├── embedingsCore.js # Embedding handler │ │ ├── imageGenerationCore.js # Image gen handler │ │ ├── ttsCore.js # TTS handler │ │ └── sttCore.js # STT handler │ ├── providers/ # Provider registry + capabilities + pricing │ │ ├── index.js # PROVIDERS export │ │ ├── registry/ # One file per provider │ │ ├── REGISTRY_TEMPLATE.js # Template for new providers │ │ ├── capabilities.js # Model capability resolver │ │ ├── pricing.js # Pricing data │ │ └── shared.js # Shared provider constants │ ├── rtk/ # Request Token Killer (pre-translate compression) │ │ ├── index.js # tool_result content compressor │ │ ├── headroom.js # External compress proxy │ │ ├── caveman.js # System prompt injector │ │ └── filters/ # Per-tool compressors + autodetect │ ├── transformer/ # Response format transformers │ ├── shared/ # Cross-provider auth/identity │ ├── services/ # Model, provider, combo, account fallback, token refresh │ └── utils/ # Stream handlers, SSE, error, proxy fetch, cloaking ├── tests/ # Independent ESM vitest package │ ├── unit/ # Unit tests │ ├── translator/ # Translator tests │ ├── __baseline__/ # Regression baseline snapshots + known-fails │ └── vitest.config.js # Test config (resolves @/ and open-sse aliases) ├── cli/ # CLI launcher (published separately as '9router') │ ├── cli.js # CLI entry │ ├── package.json # Independent version │ ├── scripts/ # Build scripts │ ├── src/cli/ # CLI source │ └── hooks/ # npm hooks (postinstall, runtime detection) ├── docs/ARCHITECTURE.md # Full system architecture docs ├── open-sse/AGENTS.md # Engine-specific guide ("how to add X") ├── scripts/ # Registry migration + maintenance scripts ├── skills/ # AI skill definitions for 9Router ├── gitbook/ # GitBook documentation site (separate Next.js app) ├── images/ # Static images ├── public/ # Public assets │ ├── i18n/literals/ # Translation JSON files │ └── icons/ # App icons └── i18n/ # Translated README files ``` ## Coding Conventions ### Language & Tooling - **Plain JavaScript (ESM)** — no TypeScript. Use JSDoc for type annotations where helpful. - **Path aliases** (from `jsconfig.json`): - `@/*` → `src/*` - `open-sse` → `open-sse` - `open-sse/*` → `open-sse/*` - **Lint**: `eslint.config.mjs` extending `eslint-config-next` (core web vitals) - **Commit style**: Conventional Commits — `feat(scope):`, `fix(scope):`, `chore(scope):` - **Versioning**: Root and `cli/package.json` are versioned independently; log changes in `CHANGELOG.md` ### Naming & Code Style - **camelCase** for variables, functions, methods - **PascalCase** for classes (e.g., `BaseExecutor`, `DefaultExecutor`) - **UPPER_SNAKE_CASE** for constants/enums (e.g., `ROLE`, `CLAUDE_BLOCK`, `FORMATS`) - **Files**: kebab-case or camelCase as appropriate (e.g., `chatCore.js`, `providerModels.js`, `appConstants.js`) - **No hardcoded strings** — use constants from `open-sse/config/` or `open-sse/translator/schema/` - **Config-driven**: All provider/model/timeout/endpoint data lives in `open-sse/config/`, not scattered in code ### Import Conventions ```javascript // From src/ code (Next.js app side): import { getDb } from "@/lib/db"; import { getProviderConnections } from "@/lib/localDb"; // backward-compat shim import { getProviderConnections } from "@/lib/db/index.js"; // preferred for new code import { loadTranslations } from "@/i18n/runtime"; import { useProviderStore } from "@/store/providerStore"; // From open-sse/ code (engine side): import { PROVIDERS } from "../providers/index.js"; import { register } from "../translator/index.js"; import { BaseExecutor } from "./base.js"; import { proxyAwareFetch } from "../utils/proxyFetch.js"; import { ROLE, CLAUDE_BLOCK } from "../translator/schema/index.js"; ``` ### Client/Server Boundary Files in `src/app/` are Next.js app router pages and API routes. Client components must have `"use client"` directive at the top. See Zustand stores in `src/store/` for the client-side state pattern. ## Architecture Rules ### 1. `src/sse/` vs `open-sse/` Boundary - **`src/sse/`** — App-side entry glue: parses incoming requests, expands combos, selects accounts - **`open-sse/`** — Provider-agnostic engine: translates formats, dispatches to executors, handles streaming Cross this boundary **consciously**. The engine (`open-sse/`) is designed to be usable standalone and should not import from `src/`. ### 2. Request Flow ``` /v1/* request → next.config.mjs rewrite (/v1/* → /api/v1/*) → src/sse/handlers/chat.js (parse, combo expansion, account selection loop) → open-sse/handlers/chatCore.js (detect source format, translate, dispatch) → open-sse/executors/{provider}.js (per-provider upstream HTTP call) → open-sse/translator/* (client format ↔ provider format) → SSE stream back to client ``` ### 3. Translator Pipeline - **OpenAI is the pivot format** — all translation routes through OpenAI as the intermediate format - **Direct routes** are preferred for fragile pairs (thinking blocks, tool ids, non-base64 images, `is_error`): register on the exact `source:target` pair to skip the lossy double-hop - **Self-registration**: Translators call `register(from, to, reqFn, resFn)` as an import side effect. A new translator file **MUST be imported in `open-sse/translator/index.js`** or it never runs - Add request translators to `open-sse/translator/request/`, response translators to `open-sse/translator/response/` - Reuse shared logic from `open-sse/translator/schema/` and `open-sse/translator/concerns/` ### 4. Provider Registration - One file per provider in `open-sse/providers/registry/` - `providers/registry/index.js` is **auto-generated** — regenerate with `scripts/migrate-registry.mjs`, don't hand-edit - To add a provider: copy `REGISTRY_TEMPLATE.js`, add models to `config/providerModels.js` - Only add an executor in `open-sse/executors/` for **non-OpenAI-compatible** upstreams ### 5. Executor Pattern ```javascript // BaseExecutor defines the interface (open-sse/executors/base.js): // getBaseUrls() → array of base URLs (for fallback) // buildUrl(model, stream, urlIndex, credentials) // buildHeaders(credentials, stream) // transformRequest(model, body, stream, credentials) // execute(model, body, stream, urlIndex, credentials, signal, ...) // For OpenAI-compatible providers — no custom executor needed (DefaultExecutor handles it) // For non-standard providers — subclass BaseExecutor, override as needed // Register in open-sse/executors/index.js map ``` ### 6. Persistence (SQLite) - **State is in SQLite**, NOT `db.json` (ARCHITECTURE.md is stale on this point) - Adapter fallback chain: `bun:sqlite` → `better-sqlite3` (optional dep) → `node:sqlite` (Node ≥22.5) → `sql.js` (pure-JS) - `better-sqlite3` is in `optionalDependencies` — install never fails without build tools - New code should import from `@/lib/db/index.js` - Per-entity logic lives in `src/lib/db/repos/*` (e.g., `connectionsRepo.js`, `combosRepo.js`) - Schema/migrations in `src/lib/db/migrations/` - DB file location: `DATA_DIR` env var, else `~/.9router/` - Usage/logs (`src/lib/usageDb.js`) live under `~/.9router` and do **not** follow `DATA_DIR` - Repo pattern: each repo exports `getAll(db)`, `getById(db, id)`, `create(db, data)`, `update(db, id, data)`, `delete(db, id)`, `upsert(db, data)` using the `getAdapter()` from `driver.js` ### 7. RTK (Request Token Killer) - Pre-translate hooks that compress `tool_result` content in-place to cut tokens - **Fail-open**: any error returns null and leaves the body untouched — **never throw** out of them - Skips `is_error`/`status:"error"` results to preserve traces - Located in `open-sse/rtk/` ### 8. Security Considerations - `custom-server.js` wraps Next standalone server to derive client IP from TCP socket and strip attacker-controlled `X-Forwarded-For` — preserve this when touching request/IP/rate-limit code - Sensitive env vars: `JWT_SECRET`, `INITIAL_PASSWORD` (default `123456`), `API_KEY_SECRET`, `MACHINE_ID_SALT` - Full env contract in `.env.example` ## Key Design Patterns ### Zustand Stores (Client State) ```javascript "use client"; import { create } from "zustand"; // Exported as default. Contains: state fields, setters, async fetch methods. // fetchXxx() skips network when cache is fresh (< CLIENT_STORE_TTL_MS) ``` ### I18n Pattern - Client-side runtime i18n (JSON files served from `/i18n/literals/{locale}.json`) - Import `translate()` from `@/i18n/runtime` in any client component - 35+ locales supported; English is the default (no translation JSON loaded) ### API Route Pattern Next.js app router route handlers export HTTP method functions: ```javascript // src/app/api/some-endpoint/route.js export async function GET(request) { ... } export async function POST(request) { ... } ``` ### React Components - Reusable components in `src/shared/components/` - Use `"use client"` directive for interactive components - Components are plain JSX functions (no TypeScript) - Theming via CSS custom properties and `ThemeProvider` ## Tests - **Vitest** ESM package in `tests/` — independent from root `npm test` - Must `npm install` root deps first (tests import from `src/`) - `vitest.config.js` resolves `@/` and `open-sse` aliases from repo root - Not expected to be all-green: ~938 pass, ~64 fail on clean checkout - Judge regressions with `tests/__baseline__/verify-no-regression.mjs` - `*.real.test.js` make live provider calls — skip unless credentials are set ## Commands Quick Reference ```bash # Dev (default port 20127, API at /v1, dashboard at /dashboard): PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev # Build + production: npm run build && PORT=20128 HOSTNAME=0.0.0.0 npm run start # Bun variants: npm run dev:bun / build:bun / start:bun # Lint: npx eslint . # Test: cd tests && npx vitest run # Single test: cd tests && npx vitest run unit/capabilities.test.js # CLI pack: npm run cli:pack ``` ## Documentation Before making changes in these areas, read the authoritative docs: - `docs/ARCHITECTURE.md` — Full system architecture: request lifecycle, combo/account fallback, OAuth, cloud sync, data model - `open-sse/AGENTS.md` — Engine conventions, how to add a provider/executor/translator - `.env.example` — Full environment variable contract ## Common Pitfalls 1. Don't hand-edit `open-sse/providers/registry/index.js` — it's auto-generated 2. Don't forget to import new translators in `open-sse/translator/index.js` — they self-register as side effects 3. Don't hardcode role/block/model strings — use `open-sse/translator/schema/` and `open-sse/config/` 4. Binary/protobuf upstreams (kiro EventStream, cursor protobuf, commandcode NDJSON) don't round-trip through OpenAI — handle in their own executor 5. RTK hooks must return null on error, never throw — they mutate in-place 6. `ARCHITECTURE.md` is stale on persistence (says `db.json`, reality is SQLite under `src/lib/db/`) 7. Usage/logs (`usage.json`, `log.txt`) do NOT follow `DATA_DIR` — they always live under `~/.9router/` 8. Tests need root `npm install` first before `cd tests && npm install`