Understanding the Project Structure of OmniRoute: A Complete Guide

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, 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 and 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), A2A protocol implementations, guardrails, and the skills registry (src/lib/skills/registry.ts).

src/shared/ contains validation schemas (src/shared/validation/providerSchema.ts), token counting utilities (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 and responsesHandler.ts
• executors/ – Provider-specific implementations like default.ts (OpenAI-compatible), cursor.ts, and 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), rate-limit manager, and compression pipeline

The entry point for chat completions is 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 – Creates the browser window and sets up IPC channels for the main process
• preload.js – Exposes secure APIs to the renderer using contextBridge
• 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, 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
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) 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:

// 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.

Registering a Custom Executor

First, implement a provider-specific executor:

// 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:

// 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:

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

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

Access from the renderer:

// 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.

How does OmniRoute handle authentication?

Authentication is enforced at the API route level using utilities in 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.

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 file creates the browser window, while 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/.

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