# How the OmniRoute Project Is Structured in Its Monorepo: Workspace Layout and Architecture

> Explore the OmniRoute monorepo structure. Discover its workspace layout for Next.js, streaming engine, desktop client, and CLI tooling. Understand the architectural rules governing this project.

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

---

**The OmniRoute project uses a single Git repository monorepo with clearly separated workspaces: `src/` for the Next.js frontend and API, `open-sse/` for the streaming engine and MCP server, `electron/` for the desktop client, and `bin/` for CLI tooling, all governed by strict architectural rules defined in [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md).**

The diegosouzapw/OmniRoute repository organizes its entire codebase as a monorepo, housing the web dashboard, streaming API engine, desktop application, and administrative tooling in one unified Git repository. This **OmniRoute monorepo structure** enables tight integration between the **Open-SSE engine** and the **Next.js** frontend while maintaining clear boundaries between the web interface, core routing logic, and native desktop wrapper.

## Workspace Overview

The repository root contains seven primary workspaces that separate production code from auxiliary tooling:

- **`src/`** – Contains the Next.js 16 application serving both the public dashboard UI and API route handlers.
- **`open-sse/`** – Hosts the streaming request engine, routing logic, translators, executors, resilience mechanisms, and the MCP (Model Context Protocol) server exposing 110+ tools.
- **`electron/`** – Provides the native desktop client that wraps the same backend binary used by the web version.
- **`bin/`** – Holds the CLI scripts, including the primary `omniroute.mjs` entry point for server management and administrative commands.
- **`scripts/`** – Contains automation utilities for builds, quality gates, releases, and development workflows.
- **`tests/`** – Organizes unit tests (Vitest), integration tests, and end-to-end test suites.
- **`docs/`** – Stores architecture documents, security guides, routing specifications, and user documentation.

All configuration files ([`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json), `next.config.mjs`, TypeScript configs) live in the repository root, while static assets served by Next.js reside in `public/`. The [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md) file at the root enforces hard rules prohibiting raw SQL in routes and requiring Zod validation for all inputs.

## Core Architecture Layers

The **OmniRoute project structure** implements a layered architecture that processes requests through distinct stages before reaching upstream providers.

### API Routes and Request Delegation

All external requests enter through `src/app/api/v1/...` following a strict middleware chain: **CORS → Zod validation → optional authentication → handler delegation**. For example, requests to `POST /v1/chat/completions` hit [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts), which forwards processing to the streaming handler at [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts). This pattern ensures type safety and security at the boundary before any business logic executes.

### The Open-SSE Streaming Engine

The `open-sse/` directory contains the core request-processing pipeline. The entry point [`open-sse/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/index.ts) bootstraps the engine and registers all handlers, executors, and format translators. This workspace implements **resilience mechanisms** including provider circuit breakers, connection cooldowns, and model lockouts to handle upstream failures gracefully.

The engine also hosts the **MCP server** ([`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts)), which exposes over 110 built-in tools for model context operations, running as a separate runtime process with heartbeat monitoring.

### Routing and Combo Strategies

Located in `open-sse/services/`, the routing layer implements 19 distinct combo strategies including priority-based routing, weighted distribution, fusion (fan-out-then-judge), and automatic failover. The file [`open-sse/services/fusion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/fusion.ts) demonstrates the parallel fan-out pattern where requests are sent to multiple providers simultaneously, with a judge model selecting the optimal response.

### Database Persistence

All data persistence flows through `src/lib/db/`, which uses **SQLite with Write-Ahead Logging (WAL)**. The singleton pattern in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) provides the sole database instance, ensuring no raw SQL appears in API routes—a strict architectural rule enforced by the codebase conventions.

### Desktop Integration

The `electron/` workspace contains a minimal Electron main process ([`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js)) that launches the same server binary used by the web version (`bin/omniroute.mjs`). This allows the desktop client to provide a native UI wrapper while reusing 100% of the backend logic.

### Command-Line Interface

The `bin/` directory provides administrative tooling through `bin/omniroute.mjs`, which handles server boot, database migrations, password resets, and provider management. Commands such as `node bin/omniroute.mjs providers list` interact with the provider catalog defined in [`src/lib/db/providerCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providerCatalog.ts).

### Documentation and Quality Automation

The `docs/` workspace contains architecture decisions, resilience guides, and API specifications, while `scripts/` houses build pipelines and quality gates. The command `npm run check:docs-all` validates documentation integrity before releases.

## Directory Structure Walkthrough

The following tree illustrates the **OmniRoute monorepo structure** and key file locations:

```

/ (repo root)
├─ src/                     # Next.js 16 app (frontend + API routes)

│   ├─ app/                 # App Router pages & API endpoints

│   │   ├─ api/
│   │   │   └─ v1/
│   │   │       └─ chat/
│   │   │           └─ completions/
│   │   │               └─ route.ts   ← POST /v1/chat/completions
│   │   └─ (dashboard UI pages)
│   ├─ sse/                 # Request-processing handlers

│   │   └─ handlers/
│   │       └─ chat.ts      # Core chat completion logic

│   └─ lib/
│       └─ db/
│           └─ core.ts      # SQLite singleton instance

├─ open-sse/                # Streaming engine & MCP server

│   ├─ index.ts             # Engine bootstrap

│   ├─ handlers/            # Low-level request handlers

│   ├─ executors/           # Provider HTTP dispatch

│   ├─ translator/          # Format conversion (OpenAI/Claude/Gemini)

│   ├─ services/            # Combo routing & resilience

│   │   └─ fusion.ts        # Fusion strategy implementation

│   └─ mcp-server/
│       └─ server.ts        # MCP tool server (110+ tools)

├─ electron/                # Desktop client

│   └─ main.js              # Electron main process

├─ bin/                     # CLI scripts

│   └─ omniroute.mjs        # Primary CLI entry point

├─ scripts/                 # Build, lint, release utilities

├─ tests/                   # Vitest unit, integration, E2E suites

├─ docs/                    # Architecture & security guides

├─ public/                  # Static assets (OpenAPI spec, icons)

└─ AGENTS.md                # Project conventions & hard rules

```

## Practical Usage Examples

### Starting the Development Server

To boot the complete OmniRoute stack locally:

```bash

# Install dependencies and generate .env from .env.example

npm install

# Start Next.js + Open-SSE engine

npm run dev

```

The `dev` script in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) ultimately invokes `bin/omniroute.mjs` to initialize both the web server and streaming engine.

### Calling the Chat Completions API

Test the API endpoint directly:

```bash
curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4o-mini",
        "messages": [{ "role": "user", "content": "Hello, OmniRoute!" }]
      }'

```

This request flows through [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) into [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts), which manages the SSE stream.

### Using the CLI for Administrative Tasks

List configured providers via the command line:

```bash
node bin/omniroute.mjs providers list

```

The CLI parses commands in `bin/cli/utils/serverHost.mjs` and queries the provider catalog from [`src/lib/db/providerCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/providerCatalog.ts).

### Integrating with the MCP Server Programmatically

Connect to the MCP server from a Node.js application:

```javascript
import { createMcpClient } from '@omniroute/open-sse/mcp-client';

(async () => {
  const client = await createMcpClient({ url: 'http://localhost:20128/mcp' });
  const result = await client.callTool('listModels', { provider: 'openai' });
  console.log(result);
})();

```

This client communicates with the server implementation in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts).

## Key Files and Their Roles

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) | Declares dependencies, scripts (`dev`, `build`, `test`), and workspace metadata. |
| `next.config.mjs` | Configures Next.js 16 and the custom server integration. |
| [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md) | Defines hard architectural rules (no raw SQL in routes, mandatory Zod validation). |
| [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) | Entry point for OpenAI-compatible chat completions API. |
| [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) | Orchestrates validation, routing strategy selection, and SSE streaming. |
| [`open-sse/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/index.ts) | Bootstraps the streaming engine and registers all components. |
| [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) | Runs the MCP tool server with 110+ available functions. |
| [`open-sse/services/fusion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/fusion.ts) | Implements the fusion combo strategy with parallel provider fan-out. |
| [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) | Provides the singleton SQLite connection with WAL mode. |
| [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js) | Launches the desktop UI and embedded server binary. |
| `bin/omniroute.mjs` | Primary CLI for server operations, migrations, and maintenance. |

## Summary

- The **OmniRoute monorepo** consolidates frontend, backend, desktop, and CLI code into a single Git repository with clearly defined workspace boundaries.
- The `src/` directory handles the Next.js 16 web interface and API routes, enforcing CORS → Zod → auth → handler chains.
- The `open-sse/` workspace contains the streaming engine, 19 combo routing strategies, resilience mechanisms, and the MCP server with 110+ tools.
- Database access is centralized in `src/lib/db/` using SQLite with WAL, with strict prohibitions against SQL in route files.
- The `electron/` and `bin/` workspaces provide native desktop and command-line interfaces that reuse the same core backend logic.
- Architecture rules in [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md) maintain code quality, while `scripts/` and `tests/` ensure automated quality gates and coverage requirements (≥ 60%) are met.

## Frequently Asked Questions

### What is the purpose of the `open-sse/` workspace in the OmniRoute project?

The `open-sse/` workspace houses the **Open-SSE streaming engine**, which handles Server-Sent Events (SSE), implements 19 combo routing strategies (like fusion and priority), manages provider resilience through circuit breakers, and runs the **MCP server** exposing over 110 tools. It operates independently from the Next.js frontend but is bootstrapped alongside it via [`open-sse/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/index.ts).

### How does OmniRoute prevent database leaks or raw SQL in API routes?

According to the architectural rules in [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md), all database interactions must flow through the domain modules in `src/lib/db/`. The singleton pattern in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) provides the sole SQLite connection, and hard rule enforcement prevents any raw SQL from appearing in API route files located in `src/app/api/`. All persistence uses parameterized queries through these centralized modules.

### Can the OmniRoute project run as a standalone desktop application?

Yes. The `electron/` workspace contains a native desktop client defined in [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js). This Electron application launches the same server binary used by the web interface (`bin/omniroute.mjs`), providing a native UI wrapper while maintaining functional parity with the browser-based dashboard.

### Where are the API route handlers defined for chat completions?

The HTTP route definition resides in [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts), which handles the initial CORS, Zod validation, and authentication checks. The actual streaming logic and provider routing are delegated to [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts), which manages the SSE connection and applies the selected combo strategy from `open-sse/services/`.