How to Perform Code Reviews for OmniRoute: A Technical Guide

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. 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. 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. All database access must route through these modules; direct SQL in API routes violates the architectural contract documented in 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. New tools require registration here with Zod input schemas. Additionally, the A2A (Agent-to-Agent) server at 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 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 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:

# 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. 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:

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. 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:

// 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 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:

# 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 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, which receives validated requests from Next.js routes and coordinates with the combo engine at 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. 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. The project uses SQLite via better-sqlite3. Direct SQL queries in API routes violate the architectural guidelines (per 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}