How to Contribute to OmniRoute Development: A Complete Guide to the AI Gateway Codebase

Contributing to OmniRoute requires Node.js ≥24 LTS, cloning the repository from GitHub, installing dependencies via npm install, and following the documented Git workflow to extend providers, routing strategies, or compression engines while maintaining the mandatory 60% test coverage threshold.

OmniRoute is a free, open-source AI gateway that unifies 237 providers and 17 routing strategies under a single API. Whether you want to add support for a new AI provider, implement a custom routing algorithm, or optimize the ten-engine compression pipeline, this guide provides the exact file paths, function signatures, and code patterns used in the diegosouzapw/OmniRoute repository.

Development Environment Setup

Setting up the OmniRoute development environment involves installing prerequisites, cloning the repository, and configuring local secrets.

1. Install prerequisites: Node.js ≥24 LTS, npm 10+, and Git.

2. Clone and install:

   git clone https://github.com/diegosouzapw/OmniRoute.git
   cd OmniRoute
   npm install

3. Configure environment variables: Copy the example environment file and generate security secrets.

   cp .env.example .env

   Generate secrets using OpenSSL:

   openssl rand -base64 48  # For JWT_SECRET
   
   openssl rand -hex 32     # For API_KEY_SECRET
   

4. Run the development server: Use npm run dev for hot-reload mode or npm run start for production mode. The dashboard becomes available at http://localhost:20128/dashboard.

5. Verify the test suite: All contributions must maintain ≥60% coverage.

   npm run test:all

Core Architecture You Will Extend

Understanding the modular architecture is essential before modifying the codebase. The four primary extension points are the provider registry, request pipeline, combo engine, and compression pipeline.

Provider Registry (src/shared/constants/providers.ts)

All 237 providers are defined in src/shared/constants/providers.ts. This file aggregates provider groups (no-auth, OAuth, API-key, self-hosted) and constructs lookup objects including AI_PROVIDERS, ALIAS_TO_ID, and ID_TO_ALIAS.

Key helper functions include:

• isOpenAICompatibleProvider() – Detects providers prefixed with "openai-compatible-"
• supportsBulkApiKey() – Determines if a provider supports bulk API-key entry via the UI

Request Pipeline Flow

Incoming HTTP requests follow a strict path through the Next.js API routes. According to the source code in open-sse/handlers/chatCore.ts, the flow is:

Next.js route → chatCore.ts → combo.handleComboChat() → resolveComboTargets()
→ handleSingleModel() → executor.execute() → upstream provider
→ translateResponse() → SSE / JSON response

The entry point for chat completions is src/app/api/v1/chat/completions/route.ts, which delegates to open-sse/handlers/chatCore.ts.

Combo Engine and Routing Strategies

The combo engine located in open-sse/services/combo.ts implements the 17 routing strategies (including priority, cost-optimized, and fusion). Strategy constants are defined in src/shared/constants/routingStrategies.ts.

The combo.ts file handles virtual combo resolution, iterates over ordered targets, and applies the selected strategy logic to route requests across multiple providers.

Compression Pipeline

The ten-engine compression stack is orchestrated by open-sse/compression/engines/registry.ts (engine registration) and open-sse/compression/strategySelector.ts (per-request mode selection). Individual engines like rtk, caveman, and ultra reside under open-sse/compression/engines/.

Common Contribution Workflows

Adding a New AI Provider

To add a new provider such as "example-ai", you must modify the registry, create an executor, and write tests.

First, extend the provider definition in src/shared/constants/providers.ts:

// Inside src/shared/constants/providers.ts
import { OAUTH_PROVIDERS } from "./providers/oauth";

export const OAUTH_PROVIDERS = {
  ...OAUTH_PROVIDERS,
  "example-ai": {
    id: "example-ai",
    name: "Example AI",
    alias: "example",
    auth: "oauth",
    clientId: "",      // Populated via .env
    clientSecret: "",  // Populated via .env
  },
};

Second, create a custom executor if the provider requires non-standard request handling. Create open-sse/executors/example-ai.ts:

import { BaseExecutor } from "./base";

export class ExampleAiExecutor extends BaseExecutor {
  buildUrl() {
    return `https://api.example.ai/v1/chat/completions`;
  }
  // Override headers or payload transformation as needed
}

Third, register the executor in open-sse/executors/index.ts:

import { ExampleAiExecutor } from "./example-ai";

export function getExecutor(providerId: string) {
  switch (providerId) {
    case "example-ai":
      return new ExampleAiExecutor();
    // existing cases …
  }
}

Fourth, add unit tests in tests/unit/example-ai.test.ts verifying:

• Provider registration via getProviderById('example-ai')
• URL and header construction
• Response translation with mock data

Finally, run the full validation suite:

npm run lint
npm run typecheck:core
npm run test:all

Implementing Custom Routing Strategies

To add a new routing strategy to the combo engine:

1. Add a constant to src/shared/constants/routingStrategies.ts
2. Implement the logic in open-sse/services/combo.ts (e.g., a new weight function)
3. Update documentation in docs/routing/AUTO-COMBO.md
4. Add unit tests in tests/unit/combo-strategy.test.ts

Contributing New Compression Engines

To contribute a new compression engine:

1. Create the engine under open-sse/compression/engines/ implementing the CompressionEngine interface
2. Register it in open-sse/compression/engines/registry.ts
3. Add a preset in open-sse/compression/strategySelector.ts if you want a named mode
4. Provide benchmarks in tests/perf/compression/ and run npm run eval:compression to compare savings versus fidelity

Everyday Development Commands

Running the Development Server on a Custom Port

PORT=20222 NEXT_PUBLIC_BASE_URL=http://localhost:20222 npm run dev

Environment variables are documented in CONTRIBUTING.md and reflected in the dashboard UI.

Creating a Feature Branch

Follow the branch-naming conventions from CONTRIBUTING.md (feat/, fix/, refactor/):

git checkout -b feat/add-example-provider
git add .
git commit -m "feat: add Example AI OAuth provider"
git push -u origin feat/add-example-provider

Running a Single Test File

node --import tsx/esm --test tests/unit/example-ai.test.ts

Summary

• Setup: Install Node.js ≥24 LTS, clone diegosouzapw/OmniRoute, run npm install, configure .env secrets, and verify with npm run test:all
• Architecture: Extend providers in src/shared/constants/providers.ts, modify routing in open-sse/services/combo.ts, and adjust compression in open-sse/compression/engines/
• Adding Providers: Requires registry updates, executor creation in open-sse/executors/, registration in open-sse/executors/index.ts, and unit tests maintaining ≥60% coverage
• Quality Gates: All code must pass npm run lint, npm run typecheck:core, and the full test suite

Frequently Asked Questions

What are the minimum system requirements to contribute to OmniRoute development?

You need Node.js version 24 LTS or higher, npm version 10 or higher, and Git installed locally. The development server runs on port 20128 by default, and you must be able to generate secure random strings using OpenSSL for the JWT_SECRET and API_KEY_SECRET environment variables.

How do I add a new AI provider to OmniRoute?

First, add the provider definition to src/shared/constants/providers.ts in the appropriate section (OAuth, API-key, etc.). If the provider requires custom request handling, create an executor class in open-sse/executors/ extending BaseExecutor, then register it in open-sse/executors/index.ts. Finally, write unit tests in tests/unit/ and ensure the code passes linting and type checking.

Where is the routing logic implemented in OmniRoute?

The routing logic is implemented in open-sse/services/combo.ts, which handles the 17 routing strategies including priority, cost-optimized, and fusion. Strategy constants are defined in src/shared/constants/routingStrategies.ts. The combo engine resolves virtual combos, iterates over ordered targets, and applies the selected strategy to route requests to upstream providers.

How do I run specific tests during OmniRoute development?

Use the Node.js test runner with the following command pattern: node --import tsx/esm --test tests/unit/your-test-file.test.ts. To run the full suite and verify coverage remains above 60%, use npm run test:all. All tests must pass before submitting a pull request along with npm run lint and npm run typecheck:core.

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