# Understanding the Project Structure of OmniRoute: A Complete Guide

> Explore the OmniRoute project structure, a TypeScript monorepo featuring Next.js, SSE engine, Electron wrapper, and robust testing. Understand its organized architecture for seamless integration.

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

---

**OmniRoute is organized as a TypeScript monorepo that combines a Next.js 16 App Router frontend, a custom server-side streaming engine called `open-sse`, an Electron desktop wrapper, and comprehensive testing suites.** This architecture separates UI concerns, API routing, streaming logic, and desktop functionality while maintaining tight integration through shared types and delegation patterns.

The repository follows a clear directory hierarchy designed to support LLM provider abstraction, combo routing strategies, and real-time streaming capabilities. Below is a detailed breakdown of how the codebase is organized and how its components interact.

## Top-Level Directory Layout

The root of the repository contains seven primary directories and configuration files that define the project's boundaries:

- **`src/`** – Core application code including UI components, API routes, domain libraries, and shared utilities
- **`open-sse/``** – The streaming engine responsible for request translation, executor selection, and SSE response management
- **`electron/`** – Desktop client wrapper containing the main process, preload scripts, and OAuth handlers
- **`docs/`** – Auto-generated OpenAPI specifications and architecture documentation
- **`tests/`** – Unit, integration, and end-to-end test suites using Vitest and Playwright
- **`config/`** – Runtime configuration files for i18n, quality baselines, and payload rules
- **`public/`** – Static assets served by Next.js including icons and service workers

Root configuration files like [`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` establish build settings and TypeScript paths that enable cross-directory imports.

## Deep Dive into Core Directories

### The Next.js Application (`src/`)

The `src/` directory houses the full-stack Next.js application with clear separation between UI and API concerns:

**`src/app/`** contains the **Next.js App Router** implementation, including [`layout.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/layout.tsx) and [`page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/page.tsx) for the dashboard interface. Nested within this is **`src/app/api/v1/`**, which exposes REST endpoints like `/api/v1/chat/completions` and `/api/v1/models`. Each route file validates input using Zod schemas and delegates to the streaming engine.

**`src/lib/`** provides domain-specific libraries including the SQLite database layer ([`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts)), A2A protocol implementations, guardrails, and the skills registry ([`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts)).

**`src/shared/`** contains validation schemas ([`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts)), token counting utilities ([`src/shared/utils/tiktokenCounter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/tiktokenCounter.ts)), and API key management helpers.

**`src/store/`** manages frontend state using Zustand for themes and notifications, while **`src/sse/`** contains thin wrappers that bridge Next.js API routes to the `open-sse` engine.

### The Streaming Engine (`open-sse/`)

The `open-sse/` directory implements the core request processing pipeline:

- **`handlers/`** – Core request processors including [`chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/chatCore.ts) and [`responsesHandler.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/responsesHandler.ts)
- **`executors/`** – Provider-specific implementations like [`default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/default.ts) (OpenAI-compatible), [`cursor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cursor.ts), and [`vertex.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/vertex.ts)
- **`translator/`** – Converts between OpenAI-compatible formats and provider-specific payloads
- **`services/`** – High-level services including the combo routing engine ([`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)), rate-limit manager, and compression pipeline

The entry point for chat completions is [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts), which coordinates translation, executor selection, and streaming response management.

### Desktop Client (`electron/`)

The **`electron/`** directory wraps the Next.js application as a native desktop application:

- **[`main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/main.js)** – Creates the browser window and sets up IPC channels for the main process
- **[`preload.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/preload.js)** – Exposes secure APIs to the renderer using `contextBridge`
- **[`loginManager.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/loginManager.js)** – Handles OAuth flows specific to the desktop environment

The Electron wrapper reuses the same Next.js build output, allowing the full OmniRoute UI to run outside the browser.

### Testing and Documentation

The **`tests/`** directory is organized into `unit/` (fast module tests), `integration/` (full pipeline tests), and `e2e/` (Playwright browser tests). The **`docs/`** directory contains [`openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/openapi.yaml), which powers the interactive API Explorer in the UI.

## How Components Interact

The request flow through the OmniRoute project structure follows a precise delegation pattern:

1. **Client requests** hit the Next.js App Router (`src/app/api/v1/*/route.ts`)
2. **Validation** occurs using Zod schemas from `src/shared/validation/`
3. **Authentication** is enforced via [`src/shared/utils/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/apiKey.ts)
4. **Delegation** passes control to `src/sse/handlers/` wrappers
5. **Translation** converts formats in `open-sse/translator/`
6. **Execution** selects the appropriate provider in `open-sse/executors/`
7. **Streaming** returns responses through the SSE engine
8. **UI updates** consume the stream in real-time via the frontend stores

The **combo routing engine** ([`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)) can execute multiple provider targets sequentially or in parallel, applying strategies like priority-based or cost-optimized routing.

## Key Implementation Examples

### Adding a New API Route

Create a new route file following the App Router convention:

```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!' });
}

```

This pattern enforces API-key validation before processing requests, consistent with the implementation in [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts).

### Registering a Custom Executor

First, implement a provider-specific executor:

```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',
    };
  }
}

```

Then register it 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…
}

```

### Using the Electron IPC Bridge

Expose desktop APIs securely:

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

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

```

Access from the renderer:

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

```

## Summary

- **OmniRoute** organizes code as a TypeScript monorepo with distinct directories for the Next.js frontend (`src/`), streaming engine (`open-sse/`), and desktop wrapper (`electron/`)
- **API routes** in `src/app/api/v1/` validate requests with Zod before delegating to `open-sse` handlers
- **The streaming engine** handles request translation, executor selection, and SSE response management through a pipeline of handlers, translators, and executors
- **Provider support** is extensible through the executor pattern in `open-sse/executors/`, with a default OpenAI-compatible implementation
- **Desktop functionality** wraps the Next.js application using Electron's main process and preload scripts
- **Testing** covers unit, integration, and end-to-end scenarios using Vitest and Playwright

## Frequently Asked Questions

### What is the main purpose of the `open-sse` directory?

The `open-sse` directory contains the server-side streaming engine that handles request translation, provider selection, and SSE response management. It acts as the middle layer between the Next.js API routes and upstream LLM providers, managing the complexity of format translation and streaming responses. The core logic resides in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts).

### How does OmniRoute handle authentication?

Authentication is enforced at the API route level using utilities in [`src/shared/utils/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/apiKey.ts). Each route calls `ensureApiKey()` to validate credentials before processing requests. The system also supports OAuth flows for the desktop application, managed by [`electron/loginManager.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/loginManager.js).

### Can I run OmniRoute as a desktop application?

Yes. The `electron/` directory contains a complete desktop wrapper that reuses the Next.js build output. The [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js) file creates the browser window, while [`electron/preload.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/preload.js) exposes secure IPC channels to the renderer. This allows the full OmniRoute UI to run as a native application on Windows, macOS, or Linux.

### What testing frameworks does OmniRoute use?

OmniRoute uses Vitest for the MCP server tests and the native Node test runner (`node --import tsx/esm --test`) for unit and integration tests. End-to-end testing is implemented with Playwright, which spins up a development server and interacts with the application through a browser. Test suites are organized in `tests/unit/`, `tests/integration/`, and `tests/e2e/`.