Skip to content

Latest commit

 

History

History
106 lines (77 loc) · 4.28 KB

AGENTS.md

File metadata and controls

106 lines (77 loc) · 4.28 KB

omniroute — Agent Guidelines

Project

Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.)

Stack

  • Runtime: Next.js 16 (App Router), Node.js, ES Modules
  • Language: TypeScript 5.9 (src/) + JavaScript (open-sse/)
  • Database: better-sqlite3 (SQLite) — DATA_DIR configurable, default ~/.omniroute/
  • Streaming: SSE via open-sse internal package
  • Styling: Tailwind CSS v4
  • Docker: Multi-stage Dockerfile, 3 profiles (base / cli / host)

Architecture

Data Layer (src/lib/db/)

All persistence uses SQLite through domain-specific modules:

Module Responsibility
core.ts SQLite engine, migrations, WAL, encryption
providers.ts Provider connections & nodes
models.ts Model aliases, MITM aliases, custom models
combos.ts Combo configurations
apiKeys.ts API key management & validation
settings.ts Settings, pricing, proxy config
backup.ts Backup / restore operations

src/lib/localDb.ts is a re-export layer only — all 27+ consumers import from it, but the real logic lives in src/lib/db/.

Request Pipeline (open-sse/)

Handler Role
chatCore.js Main chat completions proxy (SSE / non-SSE)
responsesHandler.js OpenAI Responses API compat
responseTranslator.js Format translation for Responses API
embeddings.js Embedding proxy
imageGeneration.js Image generation proxy
sseParser.js SSE stream parser
usageExtractor.js Token usage extraction from responses

Translation between provider formats: open-sse/translator/

OAuth & Tokens (src/lib/oauth/)

18 modules handling OAuth flows, token refresh, and provider credentials. Default credentials are hardcoded in src/lib/oauth/constants/oauth.ts, overridable via env vars or data/provider-credentials.json.

Supporting Systems

System Location
Usage tracking & analytics src/lib/usageDb.ts, src/lib/usageAnalytics.ts
Token health checks src/lib/tokenHealthCheck.ts
Cloud sync src/lib/cloudSync.ts
Proxy logging src/lib/proxyLogger.ts
Data paths resolution src/lib/dataPaths.ts

Adding a New Provider

  1. Register in src/shared/constants/providers.ts
  2. Add executor in open-sse/executors/
  3. Add translator rules in open-sse/translator/ (if non-OpenAI format)
  4. Add OAuth config in src/lib/oauth/constants/oauth.ts (if OAuth-based)

Review Focus

Security

  • No hardcoded API keys or secrets in commits
  • Auth middleware on all API routes
  • Input validation on user-facing endpoints
  • SQLite encryption key must not be logged

Architecture

  • DB operations go through src/lib/db/ modules, never raw SQL in routes
  • Provider requests flow through open-sse/handlers/
  • Translations use open-sse/translator/ modules
  • localDb.ts is re-exports only — add new functions to the proper db/*.ts module

Code Quality

  • Consistent error handling with try/catch
  • Proper HTTP status codes
  • No memory leaks in SSE streams (abort signals, cleanup)
  • Rate limit headers must be parsed correctly

Docker

  • Dockerfile has two targets: runner-base and runner-cli
  • docker-compose.yml — development (3 profiles)
  • docker-compose.prod.yml — isolated production instance (port 20130)
  • Data persists in named volumes (omniroute-data / omniroute-prod-data)

Review Mode

  • Provide analysis and suggestions only
  • Focus on bugs, security, performance, and best practices