# 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