# Understanding the Project Structure of OmniRoute: Architecture and Organization

> Explore the OmniRoute project structure a TypeScript monorepo. Discover its Nextjs App Router frontend, streaming engine, Electron wrapper, and shared libraries for unified LLM routing.

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

---

**OmniRoute is a TypeScript monorepo organized into distinct modules including a Next.js 16 App Router frontend, a standalone streaming engine (`open-sse`), an Electron desktop wrapper, and shared libraries, enabling unified LLM routing across web and desktop platforms.**

The `diegosouzapw/OmniRoute` repository implements a sophisticated LLM gateway with a clear separation between UI components, API routing, and streaming execution layers. The project structure maintains strict modularity while allowing tight integration between the web frontend, server-side streaming logic, and native desktop capabilities.

## Top-Level Directory Layout

The repository root contains seven primary directories that separate concerns by function:

- **`src/`** – Core TypeScript application code including UI components, API routes, and shared utilities.
- **`open-sse/`** – The streaming engine that manages request translation, provider executor selection, and Server-Sent Events (SSE) response handling.
- **`electron/`** – Desktop client wrapper containing the main process, preload scripts, and OAuth login management.
- **`docs/`** – Auto-generated OpenAPI specifications, user guides, and architecture diagrams.
- **`tests/`** – Comprehensive test suites organized as unit, integration, and end-to-end tests using Vitest and Playwright.
- **`config/`** – Runtime configuration files for internationalization, quality baselines, and payload rules.
- **`public/`** – Static assets served directly by Next.js, including icons and service workers.

Root configuration files include [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json), [`tsconfig.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.json), and `next.config.mjs`, which define project metadata, TypeScript settings, and build tooling.

## Core Application Code in src/

The `src/` directory houses the primary application logic using the Next.js 16 App Router architecture.

### Next.js App Router and UI Components

The **`src/app/`** directory contains page components, layouts, and static routes. Key files include [`src/app/layout.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/layout.tsx) for the global application layout and [`src/app/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/page.tsx) for the landing dashboard. The frontend utilizes Zustand stores located in `src/store/` for state management, including [`src/store/themeStore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/store/themeStore.ts) for theming and notification handling.

### REST API Layer

API endpoints follow the Next.js App Router convention in **`src/app/api/v1/`**, providing OpenAI-compatible routes:

- **[`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)** – Primary endpoint for chat completions that validates input and delegates to the streaming engine.
- **[`src/app/api/v1/models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/models/route.ts)** – Returns available model configurations.
- **[`src/app/api/v1/_shared/rateLimit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/_shared/rateLimit.ts)** – Common utilities for rate limiting and media handling shared across routes.

### Domain Libraries and Validation

The **`src/lib/`** directory contains domain-specific modules including [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) for SQLite connection management and [`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts) for capability registration. Shared utilities reside in **`src/shared/`**, featuring Zod validation schemas in [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts) and token counting utilities in [`src/shared/utils/tiktokenCounter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/tiktokenCounter.ts).

### SSE Bridge Layer

The **`src/sse/`** directory contains thin wrappers that bridge Next.js API routes to the standalone `open-sse` engine, such as [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts), ensuring clean separation between the HTTP layer and streaming logic.

## The open-sse Streaming Engine

The **`open-sse/`** directory implements the core request handling and streaming infrastructure.

### Request Handlers and Executors

The **`handlers/`** subdirectory contains the primary request processing logic:
- **[`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)** – Entry point for chat completion requests, coordinating translation and execution.
- **[`open-sse/handlers/responsesHandler.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/responsesHandler.ts)** – Manages response transformations.
- **[`open-sse/handlers/embeddings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/embeddings.ts)** – Handles embedding generation requests.

Provider-specific implementations reside in **`executors/`**, including [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) for OpenAI-compatible providers, [`cursor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cursor.ts), and [`vertex.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/vertex.ts). Executors encapsulate provider-specific payload building and authentication headers.

### Translation and Services

The **`translator/`** module converts between OpenAI-compatible formats and provider-specific payloads. High-level services in **`services/`** include:
- **[`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)** – The combo routing engine supporting sequential, parallel, and weighted multi-provider strategies.
- Rate limit management and token refresh services.
- Compression pipeline utilities.

## Desktop Client Architecture

The **`electron/`** directory enables the web application to run as a native desktop client:
- **[`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js)** – Creates the browser window and sets up IPC channels.
- **[`electron/preload.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/preload.js)** – Securely exposes APIs to the renderer process.
- **[`electron/loginManager.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/loginManager.js)** – Handles OAuth authentication flows for desktop users.

The Electron wrapper reuses the identical Next.js build output, ensuring feature parity between web and desktop deployments.

## Testing and Documentation Infrastructure

The **`tests/`** directory organizes quality assurance into:
- **`tests/unit/`** – Fast unit tests for individual modules like provider registries and guardrails.
- **`tests/integration/`** – Tests exercising full request pipelines through the API layer.
- **`tests/e2e/`** – Playwright browser tests against running dev servers.

The **`docs/`** directory contains [`docs/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/openapi.yaml), which powers the interactive API Explorer available in the UI.

## How the Components Interact

A typical request flows through the project structure as follows:

1. **Client Request** – The Next.js UI in `src/app/` renders the interface or receives direct HTTP calls.
2. **API Validation** – Routes in `src/app/api/v1/*` validate payloads using Zod schemas from `src/shared/validation/`.
3. **Authentication** – Utilities in [`src/shared/utils/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/apiKey.ts) enforce API-key policies.
4. **Delegation** – Validated requests pass to `src/sse/handlers/` which bridge to the `open-sse` engine.
5. **Translation** – The `open-sse/translator/` converts request formats for the target provider.
6. **Execution** – The appropriate executor in `open-sse/executors/` dispatches to the upstream LLM.
7. **Streaming** – Responses stream back via the SSE engine, optionally passing through the combo routing engine in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) for multi-provider strategies.

## Extending the Codebase

### Adding a New API Route

Create a new route file under `src/app/api/v1/`:

```typescript
// src/app/api/v1/custom/hello/route.ts
import { json } from 'next/headers';
import { ensureApiKey } from '@/shared/utils/apiKey';

export async function GET() {
  await ensureApiKey();               // enforce API-key policy
  return json({ message: 'Hello from OmniRoute!' });
}

```

### Registering a Custom Executor

Implement a new provider executor by extending the default base class:

```typescript
// open-sse/executors/myProvider.ts
import { DefaultExecutor } from './default';

export class MyProviderExecutor extends DefaultExecutor {
  protected buildUrl() {
    return 'https://api.myprovider.com/v1/chat/completions';
  }

  protected buildHeaders() {
    return {
      Authorization: `Bearer ${this.credentials.apiKey}`,
      'Content-Type': 'application/json',
    };
  }
}

```

Register the executor in the factory:

```typescript
// open-sse/executors/index.ts
import { MyProviderExecutor } from './myProvider';

export function getExecutor(providerId: string) {
  if (providerId === 'myProvider') return new MyProviderExecutor();
  // …existing branches…
}

```

### Exposing Desktop APIs

Securely expose main process functionality to the renderer:

```javascript
// electron/preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('omni', {
  getVersion: () => ipcRenderer.invoke('get-version'),
});

```

Access from the frontend:

```typescript
// src/app/dashboard/page.tsx
useEffect(() => {
  window.omni.getVersion().then(v => setVersion(v));
}, []);

```

## Summary

- **OmniRoute** separates concerns into `src/` (UI and API), `open-sse/` (streaming logic), and `electron/` (desktop wrapper).
- The **streaming engine** in `open-sse/` handles request translation via the `translator/` module and provider-specific execution through the `executors/` directory, with [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) serving as the primary entry point.
- **API routes** in `src/app/api/v1/` validate input using Zod schemas from `src/shared/validation/` before delegating to SSE handlers.
- The **combo routing engine** in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) enables sophisticated multi-provider strategies including parallel and weighted routing.
- **Electron integration** reuses the Next.js build output while adding native capabilities through [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js) and secure IPC via [`electron/preload.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/preload.js).

## Frequently Asked Questions

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

The `open-sse/` directory contains the standalone streaming engine responsible for request translation, provider executor selection, and Server-Sent Events (SSE) response management. It isolates LLM interaction logic from the Next.js frontend, allowing the same streaming infrastructure to serve both web and desktop clients through handlers like [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts).

### How does OmniRoute structure its API routes?

API routes follow Next.js 16 App Router conventions and reside in `src/app/api/v1/`. Each route file, such as [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts), validates input using Zod schemas from `src/shared/validation/`, enforces authentication via utilities in [`src/shared/utils/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/apiKey.ts), and delegates processing to the `open-sse` engine through bridge modules in `src/sse/handlers/`.

### Where does the desktop application logic reside?

Desktop-specific code lives in the `electron/` directory, including [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js) for the main process window management, [`electron/preload.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/preload.js) for secure IPC bridge setup, and [`electron/loginManager.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/loginManager.js) for OAuth flows. This structure allows the desktop client to reuse the web application code while adding native system capabilities.

### How is the database layer organized?

The database layer is implemented in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts), which provides a singleton SQLite connection and schema definitions. This location keeps persistence logic separate from API routes and streaming handlers, allowing the provider registry in [`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts) and validation schemas to access data through a centralized, type-safe interface.