# Main Source Directories in OmniRoute: Project Structure Guide

> Explore the main source directories in OmniRoute's project structure. Understand the organization of src for Next.js and open-sse for the streaming engine.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chat.ts) and [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) implement the core request processing pipeline, while [`open-sse/utils/proxyDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) and the embeddings endpoint at [`src/app/api/v1/embeddings/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providers.ts) for provider catalog management and [`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts) for skill registration. Database compression utilities live in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts), and the local database abstraction is exported from [`src/lib/localDb.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) and validation schemas in [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

const provider = await getProvider('openai');

```

Delegating a request to the streaming engine:

```typescript
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:

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

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

```

Registering a new MCP tool through the library layer:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)** serves as the primary entry point for chat completion requests.
- **[`src/lib/db/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providers.ts)** and **[`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts)** manage provider catalogs and skill registrations.
- **[`src/domain/policyEngine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chat.ts), the default executor in [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts), and proxy dispatching logic in [`open-sse/utils/proxyDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts), while embeddings are handled in [`src/app/api/v1/embeddings/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providers.ts) file manages provider records, [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) handles data compression utilities, and [`src/lib/localDb.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providers.ts), update the constants list in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/types/provider.ts) to maintain type safety across the integration.