# OmniRoute Project Structure: A Deep Dive into the Next.js, Electron, and Streaming Engine Architecture

> Explore the OmniRoute project structure featuring Nextjs, Electron, and a streaming engine. Understand the monorepo organization for efficient development.

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

---

**OmniRoute organizes its codebase as a monorepo with distinct top-level directories for the Next.js 16 frontend (`src/`), a dedicated streaming engine (`open-sse/`), an Electron desktop wrapper (`electron/`), and comprehensive test suites (`tests/`).**

The repository at `diegosouzapw/OmniRoute` separates concerns between UI rendering, API routing, and server-side streaming while maintaining tight integration through type-safe TypeScript utilities. This architecture supports everything from chat completion endpoints to complex multi-provider routing strategies.

## Top-Level Directory Layout

The **project structure** follows a clear separation of concerns at the root level:

| Directory | Purpose | Key Contents |
|-----------|---------|--------------|
| `src/` | Core TypeScript application code | Next.js App Router, API routes, domain libraries |
| `open-sse/` | Server-side streaming engine | Request handlers, provider executors, translators |
| `electron/` | Desktop application wrapper | Main process, preload scripts, OAuth management |
| `tests/` | Verification suites | Unit tests (Vitest), integration tests, E2E (Playwright) |
| `docs/` | Documentation and specifications | OpenAPI specs, architecture diagrams |
| `config/` | Runtime configuration | i18n settings, quality baselines, payload rules |
| `public/` | Static assets | Icons, service workers, public files |

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 the build pipeline and TypeScript compilation settings for the entire monorepo.

## The Next.js Application Layer

### App Router and API Endpoints

The `src/app/` directory houses the **Next.js 16 App Router** implementation. This contains page components, layouts, and error boundaries that render the dashboard and API Explorer.

API routes reside under `src/app/api/v1/`, following a RESTful structure:

- [`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 streaming chat completions
- [`src/app/api/v1/models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/models/route.ts) – Provider model listing and metadata
- [`src/app/api/v1/_shared/rateLimit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/_shared/rateLimit.ts) – Shared rate-limiting logic across routes

Each route validates input using Zod schemas from `src/shared/validation/` before delegating to the streaming engine.

### Domain Libraries and Shared Utilities

The `src/lib/` directory contains domain-specific modules isolated by concern:

- [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) – SQLite connection singleton and schema definitions
- [`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts) – A2A protocol skill registration
- `src/lib/guardrails/` – Safety and content filtering implementations

Shared utilities in `src/shared/` provide cross-cutting functionality:

- [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts) – Zod schemas for provider identifiers
- [`src/shared/utils/tiktokenCounter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/tiktokenCounter.ts) – Token counting utilities
- [`src/shared/utils/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/apiKey.ts) – API key policy enforcement

### Frontend State Management

The `src/store/` directory contains **Zustand** stores for UI state:

- [`src/store/themeStore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/store/themeStore.ts) – Theme preferences and dark mode toggling
- Notification management and email privacy settings

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

The `open-sse/` directory is the heart of OmniRoute's request processing pipeline. This is where **Server-Sent Events (SSE)** are orchestrated between upstream LLM providers and downstream clients.

### Request Handlers and Executors

Incoming requests flow through specialized handlers:

- [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) – Entry point for chat completion requests
- [`open-sse/handlers/responsesHandler.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/responsesHandler.ts) – Response transformation logic
- [`open-sse/handlers/embeddings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/embeddings.ts) – Vector embedding requests

Executors in `open-sse/executors/` handle provider-specific HTTP implementations:

- [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) – Base executor for OpenAI-compatible APIs
- [`open-sse/executors/cursor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/cursor.ts) – Cursor-specific request formatting
- [`open-sse/executors/vertex.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/vertex.ts) – Google Vertex AI integration

### Translation and Routing Services

The `open-sse/translator/` directory converts between OpenAI-compatible request formats and provider-specific payloads. Supporting services include:

- [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) – **Combo routing engine** for multi-provider strategies (sequential, parallel, weighted)
- [`open-sse/services/rateLimitManager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/rateLimitManager.ts) – Distributed rate limiting
- `open-sse/utils/` – Size estimation, error handling, and keep-alive management

## Desktop and Testing Infrastructure

### Electron Wrapper

The `electron/` directory wraps the Next.js application 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 flows for desktop authentication

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

### Test Organization

The `tests/` directory is organized by scope:

- `tests/unit/` – Fast module tests for provider registries and guardrails
- `tests/integration/` – Full request pipeline testing
- `tests/e2e/` – Playwright browser automation tests

Tests run with the native Node test runner (`node --import tsx/esm --test`) and Vitest for the MCP server components.

## How Request Flow Works Through the Project Structure

Understanding the **project structure** requires tracing how a chat completion request travels through the system:

1. **Client** requests `/api/v1/chat/completions` via the Next.js UI in `src/app/`
2. **Route validation** occurs in [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) using Zod schemas
3. **Authentication** is enforced via [`src/shared/utils/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/apiKey.ts)
4. **Delegation** to [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) bridges the HTTP API to the streaming engine
5. **Translation** in `open-sse/translator/` converts the request format for the target provider
6. **Execution** via `open-sse/executors/` dispatches to the upstream LLM (OpenAI, Anthropic, etc.)
7. **Streaming** responses flow back through [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) to the client

The **combo routing engine** ([`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)) can intercept this flow to run multiple providers in parallel or sequence, applying cost-optimization or fallback strategies.

## Extending the Architecture

### 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 by extending the default 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…
}

```

### Integrating with Electron IPC

Expose functionality to the renderer via the preload script:

```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** uses a monorepo **project structure** separating the Next.js frontend (`src/`), streaming engine (`open-sse/`), and Electron desktop client (`electron/`)
- The `src/app/api/v1/` directory contains REST endpoints that validate requests before delegating to `open-sse` handlers
- **Streaming logic** is isolated in `open-sse/` with clear boundaries between handlers, translators, and provider-specific executors
- **Type safety** is enforced through Zod schemas in `src/shared/validation/` and used consistently across API routes
- The **combo routing engine** ([`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)) enables sophisticated multi-provider strategies without mixing concerns into the API layer
- **Electron** reuses the Next.js build output, maintaining a single codebase for web and desktop

## Frequently Asked Questions

### What is the relationship between `src/app/api` and the `open-sse` directory?

The `src/app/api/v1/` routes handle HTTP ingress, authentication, and input validation using Zod schemas. Once validated, these routes delegate to thin wrappers in `src/sse/handlers/`, which bridge to the `open-sse/` streaming engine. This separation keeps HTTP concerns (headers, cookies, CORS) distinct from streaming logic (SSE formatting, provider translation, retry logic).

### How does the Electron desktop app reuse the Next.js codebase?

The [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js) process creates a browser window that loads the Next.js application. The [`electron/preload.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/preload.js) script exposes a secure IPC bridge to the renderer, allowing the same React components used in the web version to run in a desktop shell. The build pipeline outputs to a directory that Electron serves locally, ensuring feature parity between web and desktop without code duplication.

### Where are LLM provider credentials and configurations managed?

Provider configurations are validated against schemas in [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts). Credentials are handled within executor classes in `open-sse/executors/` (such as [`default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/default.ts) or [`vertex.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/vertex.ts)), which retrieve API keys from environment variables or secure storage. The [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) SQLite layer persists user-specific provider preferences and rate-limit counters.

### How does the combo routing engine select which LLM provider to use?

The combo routing engine, implemented in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), applies strategies defined in the request configuration. It can execute providers sequentially for fallback scenarios, parallel for latency optimization, or weighted for cost distribution. The engine intercepts requests after translation but before execution, allowing dynamic provider selection based on availability, token costs, or response quality metrics.