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

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.

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, next.config.mjs, TypeScript configs) live in the repository root, while static assets served by Next.js reside in public/. The 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, which forwards processing to the streaming handler at 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 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), 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 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 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) 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.

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:

# 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 ultimately invokes bin/omniroute.mjs to initialize both the web server and streaming engine.

Calling the Chat Completions API

Test the API endpoint directly:

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 into src/sse/handlers/chat.ts, which manages the SSE stream.

Using the CLI for Administrative Tasks

List configured providers via the command line:

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.

Integrating with the MCP Server Programmatically

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

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.

Key Files and Their Roles

File	Purpose
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	Defines hard architectural rules (no raw SQL in routes, mandatory Zod validation).
src/app/api/v1/chat/completions/route.ts	Entry point for OpenAI-compatible chat completions API.
src/sse/handlers/chat.ts	Orchestrates validation, routing strategy selection, and SSE streaming.
open-sse/index.ts	Bootstraps the streaming engine and registers all components.
open-sse/mcp-server/server.ts	Runs the MCP tool server with 110+ available functions.
open-sse/services/fusion.ts	Implements the fusion combo strategy with parallel provider fan-out.
src/lib/db/core.ts	Provides the singleton SQLite connection with WAL mode.
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 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.

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

According to the architectural rules in AGENTS.md, all database interactions must flow through the domain modules in src/lib/db/. The singleton pattern in 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. 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, 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, which manages the SSE connection and applies the selected combo strategy from open-sse/services/.

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