Understanding the Project Structure of OmniRoute: Architecture and Organization

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, 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 for the global application layout and 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 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 – Primary endpoint for chat completions that validates input and delegates to the streaming engine.
• src/app/api/v1/models/route.ts – Returns available model configurations.
• 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 for SQLite connection management and src/lib/skills/registry.ts for capability registration. Shared utilities reside in src/shared/, featuring Zod validation schemas in src/shared/validation/providerSchema.ts and token counting utilities in 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, 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 – Entry point for chat completion requests, coordinating translation and execution.
• open-sse/handlers/responsesHandler.ts – Manages response transformations.
• open-sse/handlers/embeddings.ts – Handles embedding generation requests.

Provider-specific implementations reside in executors/, including open-sse/executors/default.ts for OpenAI-compatible providers, cursor.ts, and 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 – 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 – Creates the browser window and sets up IPC channels.
• electron/preload.js – Securely exposes APIs to the renderer process.
• 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, 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 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 for multi-provider strategies.

Extending the Codebase

Adding a New API Route

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

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

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

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

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

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

Access from the frontend:

// 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 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 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 and secure IPC via 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.

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, validates input using Zod schemas from src/shared/validation/, enforces authentication via utilities in 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 for the main process window management, electron/preload.js for secure IPC bridge setup, and 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, 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 and validation schemas to access data through a centralized, type-safe interface.

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