Main Source Directories in OmniRoute: Project Structure Guide

The OmniRoute codebase organizes its TypeScript source code into two primary trees—src/ for the Next.js application and domain logic, and open-sse/ for the streaming engine—supplemented by docs/ and tests/ directories.

OmniRoute is an open-source LLM routing platform built with Next.js and TypeScript. Understanding the main source directories in OmniRoute is essential for navigating its architecture, which cleanly separates the web API layer from the core streaming engine. This guide maps each top-level directory to its functional role and highlights the key files that power the system's routing capabilities.

Top-Level Source Trees

The repository root contains four primary directories that define the project layout. These separate the application code, the streaming engine, documentation, and test suites.

src/ – Core Application Layer

The src/ directory houses the entire Next.js application, including the App Router, API endpoints, domain logic, and shared libraries. This is where the bulk of the business logic resides, from provider management to policy enforcement.

open-sse/ – Streaming Engine

The open-sse/ directory contains the streaming engine that powers all LLM request handling. It includes executors, translators, transformers, and low-level streaming utilities. Files like open-sse/handlers/chat.ts and open-sse/executors/default.ts implement the core request processing pipeline, while open-sse/utils/proxyDispatcher.ts manages upstream proxy selection.

docs/ and tests/ – Documentation and Quality Assurance

The docs/ directory contains human-readable architecture documentation, such as docs/architecture/ARCHITECTURE.md, while the tests/ directory organizes unit, integration, and end-to-end test suites, including files like tests/unit/chatCore.test.ts.

Deep Dive into the src/ Directory Structure

Within the src/ tree, the codebase follows a feature-based organization that separates routing logic, data access, and shared utilities.

src/app/ – API Routes and Next.js App Router

The src/app/ directory implements the Next.js App Router structure. It contains all HTTP-exposed endpoints, including the critical chat completion API at src/app/api/v1/chat/completions/route.ts and the embeddings endpoint at src/app/api/v1/embeddings/route.ts. These files serve as the entry points for incoming requests before they delegate to the underlying libraries.

src/lib/ – Reusable Libraries and Domain Modules

The src/lib/ directory contains modular libraries for database access, skill registries, and server implementations. Key files include src/lib/db/providers.ts for provider catalog management and src/lib/skills/registry.ts for skill registration. Database compression utilities live in src/lib/db/compression.ts, and the local database abstraction is exported from src/lib/localDb.ts.

src/domain/ – Business Logic and Policies

The src/domain/ directory isolates business logic and policy enforcement. The src/domain/policyEngine.ts file implements the core policy evaluation used for routing decisions, determining provider selection, cost optimization, and fallback strategies based on real-time availability.

src/shared/ – Utilities and Validation

The src/shared/ directory provides cross-cutting concerns used throughout the application. It houses constants in src/shared/constants/providers.ts and validation schemas in src/shared/validation/providerSchema.ts. These files ensure type safety and consistent configuration across the API and streaming layers.

src/types/ – Global TypeScript Definitions

The src/types/ directory defines global TypeScript interfaces, including provider configurations in src/types/provider.ts. These type definitions provide the contracts used between the API layer, domain logic, and database modules.

Practical Navigation Examples

When extending OmniRoute, developers interact with these directories through specific import patterns. Here are practical examples for common tasks.

Importing a database module from the library layer:

// Fetching a provider record from the local database
import { getProvider } '@/lib/localDb';

const provider = await getProvider('openai');

Delegating a request to the streaming engine:

import { handleChat } from '@/open-sse/handlers/chat';

// In a Next.js API route
export const POST = async (req: Request) => handleChat(req);

Validating incoming payloads against shared schemas:

import { providerSchema } from '@/shared/validation/providerSchema';

const parsed = providerSchema.parse(request.body);

Registering a new MCP tool through the library layer:

import { registerTool } from '@/lib/mcp/server';
import { z } from 'zod';

registerTool({
  name: 'my_custom_tool',
  description: 'Executes a custom operation',
  inputSchema: z.object({ /* schema definition */ }),
  handler: async (args) => { /* implementation */ },
});

Summary

• src/ contains the Next.js application, domain logic, and library modules, organized into app/, lib/, domain/, shared/, and types/ subdirectories.
• open-sse/ houses the streaming engine with handlers, executors, and utilities for processing LLM requests.
• src/app/api/v1/chat/completions/route.ts serves as the primary entry point for chat completion requests.
• src/lib/db/providers.ts and src/lib/skills/registry.ts manage provider catalogs and skill registrations.
• src/domain/policyEngine.ts encapsulates routing and fallback policies.
• docs/ and tests/ provide architecture documentation and comprehensive test coverage.

Frequently Asked Questions

What is the purpose of the open-sse directory in OmniRoute?

The open-sse/ directory contains the streaming engine responsible for handling all LLM request processing. It includes the chat handler in open-sse/handlers/chat.ts, the default executor in open-sse/executors/default.ts, and proxy dispatching logic in open-sse/utils/proxyDispatcher.ts. This separation allows the streaming layer to operate independently from the web API layer.

Where does OmniRoute handle API routing logic?

API routing logic resides in the src/app/ directory using the Next.js App Router convention. The chat completions endpoint is implemented in src/app/api/v1/chat/completions/route.ts, while embeddings are handled in src/app/api/v1/embeddings/route.ts. These routes delegate business logic to the src/domain/ and src/lib/ layers.

How are database modules organized in OmniRoute?

Database modules are centralized under src/lib/db/. The src/lib/db/providers.ts file manages provider records, src/lib/db/compression.ts handles data compression utilities, and src/lib/localDb.ts exports a unified interface for database operations. This structure keeps persistence logic isolated from API routes.

Where should I add a new provider integration in OmniRoute?

New provider integrations require changes in multiple directories. Add provider-specific logic to src/lib/db/providers.ts, update the constants list in src/shared/constants/providers.ts, and implement any custom execution logic in the open-sse/executors/ directory. Type definitions should be added to src/types/provider.ts to maintain type safety across the integration.

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