Where Is the Core Routing Logic in OmniRoute? A Deep Dive into the Combo Service

The core routing logic in OmniRoute is implemented in the Combo Service at open-sse/services/combo.ts, which exports the handleComboChat entry point and implements 17 built-in routing strategies that determine which provider and model handle each request.

The core routing logic in OmniRoute resides within a centralized TypeScript module that orchestrates how AI requests are distributed across multiple providers and models. This engine, known as the Combo Service, acts as the decision-making layer for every chat completion, embedding, and image generation request that passes through the system. All API routes ultimately delegate to this service when a combo configuration is active, making it the authoritative source for target resolution and load balancing.

The Combo Service: OmniRoute's Central Routing Engine

The heart of OmniRoute's request-routing mechanism lives in open-sse/services/combo.ts. This module contains the combo-routing engine, the handleComboChat entry point, the combo-target resolution flow, and the implementation of the 17 built-in routing strategies (priority, weighted, round-robin, P2C, etc.).

According to the OmniRoute source code, this file is responsible for:

• Resolving combo configurations from the database
• Selecting targets based on the active routing strategy
• Orchestrating per-target request handling
• Managing fallback policies when providers fail

Key Entry Points and Functions

handleComboChat: The Primary Dispatch Function

The handleComboChat function serves as the main entry point for processing requests through the combo engine. Located in open-sse/services/combo.ts, this function accepts a combo configuration, request body, and context (including auth and abort signals), then dispatches the request to the appropriate provider based on the configured strategy.

resolveComboTargets: Strategy-Based Target Resolution

For scenarios requiring direct access to routing logic without full request processing, the resolveComboTargets function (also in open-sse/services/combo.ts) allows developers to execute a specific routing strategy against a combo ID. This function references ROUTING_STRATEGY_VALUES from src/shared/constants/routingStrategies.ts to determine provider ordering.

Routing Strategies and Configuration

The combo service implements 17 distinct routing strategies, including priority-based, weighted distribution, round-robin, and Power of Two Choices (P2C). These strategies are enumerated in src/shared/constants/routingStrategies.ts and referenced by the combo service during target resolution.

When a request arrives, the engine:

1. Loads the combo configuration from the database layer
2. Identifies the assigned strategy from the 17 available options
3. Applies the strategy logic to rank or select providers
4. Returns the ordered list of targets for request execution

Request Flow: From API Route to Provider Selection

The routing pipeline follows a clear delegation path through the OmniRoute codebase:

1. API Route: src/app/api/v1/chat/completions/route.ts receives incoming chat requests via the Next.js API handler
2. Chat Core: open-sse/handlers/chatCore.ts acts as the entry point for standard chat-completion requests, forwarding to the combo service when a combo is active
3. Combo Service: open-sse/services/combo.ts applies the selected routing strategy to choose the best provider and model for the request

This architecture ensures that all routing decisions are centralized in the combo service, regardless of which API endpoint initiated the request.

Database Layer for Combo Configurations

The combo service relies on two primary database modules for persistence:

• src/lib/db/combo.ts: Handles the storage and retrieval of combo definitions
• src/lib/db/comboCombos.ts: Stores combo-specific configuration including assigned providers, model overrides, and fallback policies

These modules provide the data layer that handleComboChat queries to resolve which providers are available for a given combo ID.

Code Examples

Manually Invoking the Combo Router

// Example: manually invoking the combo router (simplified)
import { handleComboChat } from '@/open-sse/services/combo';
import { getComboConfig } from '@/src/lib/db/combos';

// Assume we have a combo ID from the client request
const comboId = 'my-high-throughput-combo';
const comboConfig = await getComboConfig(comboId);

// The request body follows the OpenAI chat-completion schema
const requestBody = {
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello, world!' }],
  temperature: 0.7,
};

// Dispatch the request through the combo engine
const response = await handleComboChat({
  combo: comboConfig,
  body: requestBody,
  // context includes auth, abort signal, etc.
});
console.log(response);

Using a Built-In Routing Strategy Directly

// Example: using a built-in routing strategy directly
import { resolveComboTargets } from '@/open-sse/services/combo';
import { ROUTING_STRATEGY_VALUES } from '@/src/shared/constants/routingStrategies';

// Pick a strategy (e.g., weighted round-robin)
const strategy = ROUTING_STRATEGY_VALUES.WEIGHTED;
const targets = await resolveComboTargets({
  comboId: 'cost-optimized-combo',
  strategy,
});
console.log('Ordered targets:', targets);

Summary

• The core routing logic in OmniRoute is located in open-sse/services/combo.ts, which implements the Combo Service
• handleComboChat is the primary entry point for dispatching requests through the routing engine
• The system supports 17 built-in routing strategies defined in src/shared/constants/routingStrategies.ts
• The request flow moves from src/app/api/v1/chat/completions/route.ts → open-sse/handlers/chatCore.ts → open-sse/services/combo.ts
• Database configuration is managed through src/lib/db/combo.ts and src/lib/db/comboCombos.ts

Frequently Asked Questions

Where is the core routing logic located in OmniRoute?

The core routing logic is located in open-sse/services/combo.ts. This file contains the Combo Service, which implements all routing strategies, the handleComboChat function for request dispatch, and the target resolution logic that determines which provider handles each request.

What function handles the actual routing of chat requests?

The handleComboChat function in open-sse/services/combo.ts handles the actual routing of chat requests. It accepts a combo configuration and request body, then applies the configured routing strategy to select the appropriate provider and model. For direct strategy execution without full request processing, use resolveComboTargets from the same file.

How many routing strategies does OmniRoute implement?

OmniRoute implements 17 built-in routing strategies including priority, weighted, round-robin, and Power of Two Choices (P2C). These strategies are enumerated in src/shared/constants/routingStrategies.ts and referenced by the combo service to determine how requests are distributed across providers.

How does a chat request flow through the routing system?

A chat request enters through src/app/api/v1/chat/completions/route.ts, which passes it to open-sse/handlers/chatCore.ts. When a combo configuration is active, the chat core delegates to handleComboChat in open-sse/services/combo.ts. The combo service then queries the database configuration and applies the selected routing strategy to choose the best provider and model for the request.

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