# How to Perform Code Reviews for OmniRoute: A Technical Guide

> Master OmniRoute code reviews. Ensure Nextjs App Router compliance, pass CI checks, respect SQLite abstraction, and adhere to security guardrails for robust code quality.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-11

---

**To perform code reviews for OmniRoute, verify that changes align with the Next.js App Router API pattern, pass the automated CI quality gates (lint, typecheck, tests), respect the SQLite database abstraction layer, and comply with security guardrails like PII masking.**

OmniRoute is a large-scale LLM proxy and router built on **Next.js App Router** (requiring Node.js ≥ 22) and a custom streaming engine called **open-sse**. Performing effective code reviews for this repository requires understanding how its nine architectural layers—from API routes to security guardrails—interact to process OpenAI-style requests through a combo-routing pipeline.

## Understanding OmniRoute's Core Architecture

A thorough review depends on knowing how components interact. The request flows from Next.js route handlers through the open-sse engine, which applies **combo routing** (one of 17 strategies) to select provider targets, then executes via provider-specific modules.

### API Layer and Route Handlers

All external requests enter through [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts). This file implements the canonical pattern: CORS preflight handling, **Zod** request validation, optional API-key authentication, and delegation to the streaming handler. Reviewers must ensure new routes follow this exact structure and never embed direct SQL queries.

### The open-sse Streaming Engine

The core processing lives in [`open-sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chat.ts). This handler manages rate-limiting, request translation, executor selection, retry logic, and SSE response transformation. When reviewing streaming changes, confirm that back-pressure handling and error boundaries align with the existing implementation in this file.

### Database and Domain Model

OmniRoute uses a **SQLite** wrapper via `better-sqlite3` with 95 domain-specific modules located in `src/lib/db/*`. The singleton instance is defined in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts). All database access must route through these modules; direct SQL in API routes violates the architectural contract documented in [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md).

### MCP Server and A2A Integration

The system exposes 94 built-in tools via the **MCP** (Model Context Protocol) server at [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts). New tools require registration here with Zod input schemas. Additionally, the **A2A** (Agent-to-Agent) server at [`src/lib/a2a/taskManager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/a2a/taskManager.ts) handles JSON-RPC 2.0 endpoints for asynchronous tasks.

## Automated Quality Gates in the CI Pipeline

Every pull request triggers the [`quality.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/quality.yml) GitHub Actions workflow, which enforces a continuous code-review baseline:

- **`npm run lint`** – ESLint with strict rules (no-eval, no-new-func, import order)
- **`npm run typecheck:core`** – Strict TypeScript compilation with no implicit any
- **`npm run test:all`** – Unit, integration, Vitest, and Playwright e2e suites
- **`npm run check:cycles`** – Circular import detection
- **`npm run semgrep` / CodeQL** – Static security analysis for hard-coded secrets and unsafe patterns
- **`nightly-resilience`** and **`nightly-compat`** – Resilience simulations for fallbacks and rate-limiting
- **`nightly-llm-security`** – Guardrail testing for prompt-injection and PII handling

Failing any of these checks blocks merging, so reviewers should verify that the CI pipeline passes before approving changes.

## Manual Code Review Checklist

While automation catches regressions, manual review must confirm architectural compliance:

1. **Confirm architectural fit** – New API routes must mirror `src/app/api/v1/*/route.ts` patterns. Streaming logic belongs in `open-sse/handlers/` or `open-sse/services/`. Database access must use `src/lib/db/*` modules.

2. **Validate Zod schemas** – Define new request/response payloads in `src/shared/validation/schemas/*.ts` and run `npm run typecheck:core` locally to ensure compilation.

3. **Guardrail compliance** – Verify that any new provider or executor respects contracts in `src/lib/guardrails/*`. Specifically, ensure PII-redaction defaults remain `false` (hard rule #20) and that no unsafe headers are injected.

4. **MCP/A2A integration** – Register new tools in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) with Zod schemas. Provide example scripts demonstrating SSE transport usage.

5. **Documentation integrity** – Update `docs/**` for new routes, providers, or combo strategies. Run `npm run check:fabricated-docs` to confirm that every documented name exists in the codebase.

6. **Test coverage** – Execute `npm run test:all` and ensure coverage stays above the project threshold (`npm run test:coverage`). New executors require at least one unit test under `tests/unit/`.

## Practical Code Review Examples

### Suggesting a Combo for Code Review Tasks

OmniRoute includes a CLI skill that suggests optimal provider combinations for specific tasks:

```bash

# Ask OmniRoute to recommend the best combo for a code review task

omniroute combo suggest --task "code review"

```

This command maps to the CLI skill defined in [`skills/cli-providers/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/skills/cli-providers/SKILL.md). Internally, it invokes the MCP tool `combo_suggest` with `{ task: "code review" }` and returns the selected provider/model list. Reviewers can use this to validate routing logic changes.

### Invoking the Code Review MCP Tool Directly

For programmatic verification of a pull request's files, invoke the built-in code review tool:

```javascript
import { createMcpClient } from '@omniroute/open-sse/mcp-client';

// Connect to the MCP SSE endpoint (default: http://localhost:3000/api/mcp/sse)
const client = await createMcpClient('http://localhost:3000/api/mcp/sse');

const result = await client.invoke('code_review', {
  // Optional: specify source files to analyze
  files: ['src/app/api/v1/chat/completions/route.ts'],
});

console.log(result);

```

The tool implementation resides in [`open-sse/mcp-server/tools/code_review.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/code_review.ts). It runs the same static-analysis pipeline used by CI, allowing reviewers to check specific files on demand.

### Validating a New Provider Implementation

When reviewing a new provider addition, verify the following pattern:

```typescript
// src/shared/constants/providers.ts
export const PROVIDERS = z.enum([
  // existing entries...
  "my_new_provider",
]);

// Register executor in open-sse/executors/my_new_provider.ts
export class MyNewProviderExecutor extends BaseExecutor {
  protected buildUrl() { 
    return "https://api.mynewprovider.com/v1/chat/completions"; 
  }
  
  protected buildHeaders() { 
    return { Authorization: `Bearer ${this.apiKey}` }; 
  }
}

```

After adding the provider, confirm that [`providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/providerRegistry.ts) is updated with the base URL and auth format, and that a unit test exists under `tests/unit/` mocking the fetch call.

### Running CI Checks Locally

Before submitting review approval, run the full quality pipeline locally:

```bash

# Install dependencies

pnpm install

# Lint and typecheck

npm run lint && npm run typecheck:core

# Run all tests

npm run test:all

# Run complete quality workflow

npm run check

```

## Summary

- **OmniRoute** uses a Next.js App Router and **open-sse** streaming engine with 17 combo routing strategies.
- All database access must flow through `src/lib/db/*` modules; never use raw SQL in routes.
- The [`quality.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/quality.yml) CI pipeline enforces linting, type-checking, tests, and security analysis.
- Reviewers must validate **Zod** schemas, **MCP** tool registration, and **guardrail** compliance (especially PII masking defaults).
- Use the built-in `omniroute combo suggest` CLI skill or the `code_review` MCP tool to analyze routing decisions.
- Maintain documentation integrity with `npm run check:fabricated-docs` and ensure test coverage thresholds are met.

## Frequently Asked Questions

### What is the open-sse engine in OmniRoute?

**open-sse** is OmniRoute's custom streaming engine that handles the central request pipeline. It manages rate-limiting, combo routing, request translation, executor selection, retry logic, and SSE response transformation. The main handler is implemented in [`open-sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chat.ts), which receives validated requests from Next.js routes and coordinates with the combo engine at [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) to determine provider targets.

### How does combo routing work in OmniRoute?

Combo routing determines an ordered list of provider/model targets (a "combo") using one of 17 strategies such as priority, weighted, or fill-first. The logic resides in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts). When a request arrives, the combo engine expands the requested combo ID, applies the selected strategy to choose targets, and passes the selections to the executor layer. Reviewers should verify that new combo strategies are registered and documented in `docs/`.

### Where should database logic be placed in OmniRoute?

All database logic must reside in the 95 domain-specific modules under `src/lib/db/*`, with the core singleton instance defined in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts). The project uses **SQLite** via `better-sqlite3`. Direct SQL queries in API routes violate the architectural guidelines (per [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md)). When reviewing changes, ensure that CRUD operations import from these modules rather than constructing SQL inline.

### What are the mandatory security checks for OmniRoute code reviews?

Every PR must pass **ESLint** with error-level rules, strict **TypeScript** compilation (`noImplicitAny`), and comprehensive tests including unit, integration, and e2e suites. Additionally, **Semgrep** and **CodeQL** static analysis detect hard-coded secrets and unsafe patterns. Manual review must verify **guardrail** compliance in `src/lib/guardrails/*`, ensuring that PII masking defaults remain `false` and that no provider injects unsafe headers or disables security features.