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

> Contribute to OmniRoute development by cloning the AI Gateway codebase. Follow our Git workflow to extend providers, routing strategies, or compression engines. Ensure mandatory 60% test coverage.

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

---

**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**:
   ```bash
   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.
   ```bash
   cp .env.example .env
   ```

   
   Generate secrets using OpenSSL:
   ```bash
   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.
   ```bash
   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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)**, which delegates to **[`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)**.

### Combo Engine and Routing Strategies

The **combo engine** located in **[`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts)**.

The [`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/compression/engines/registry.ts)** (engine registration) and **[`open-sse/compression/strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts)**:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/example-ai.ts)**:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts)**:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts)**
2. Implement the logic in **[`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)** (e.g., a new weight function)
3. Update documentation in [`docs/routing/AUTO-COMBO.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/routing/AUTO-COMBO.md)
4. Add unit tests in [`tests/unit/combo-strategy.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/compression/engines/registry.ts)**
3. Add a preset in **[`open-sse/compression/strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

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

```

Environment variables are documented in **[`CONTRIBUTING.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/CONTRIBUTING.md)** and reflected in the dashboard UI.

### Creating a Feature Branch

Follow the branch-naming conventions from [`CONTRIBUTING.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/CONTRIBUTING.md) (`feat/`, `fix/`, `refactor/`):

```bash
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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts), modify routing in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`.