# Main Directories in the OmniRoute Repository: Complete Structure Guide

> Explore the OmniRoute repository structure. Understand the main directories like src open-sse electron and bin to navigate the monorepo effectively. Get the complete guide now.

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

---

**The OmniRoute monorepo organizes its runtime components into ten top-level directories, including `src/` for the Next.js API, `open-sse/` for the streaming engine, `electron/` for the desktop client, and `bin/` for CLI executables.**

The **OmniRoute** repository (hosted at `diegosouzapw/OmniRoute`) is a comprehensive TypeScript monorepo that groups all runtime code, tooling, documentation, and CI assets into a hierarchical structure. Understanding the main directories in OmniRoute's repository enables developers to quickly locate the core request-handling engine, LLM streaming utilities, and deployment configurations.

## Core Application Directories

### src/ - Next.js API and Business Logic

The `src/` directory houses the primary **TypeScript** application source code. This includes **Next.js** API routes, data stores, shared utilities, validation schemas, and the database abstraction layer. According to the OmniRoute source code, the critical entry point [`src/server-init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts) wires together the API routes, database connections, and global middlewares, serving as the bootstrap file for the server-side runtime.

### open-sse/ - SSE Streaming Engine

The `open-sse/` directory contains the specialized streaming engine that powers all LLM requests. It encapsulates executors, translators, and Server-Sent Events (SSE) utilities required for real-time response handling. The core streaming handlers are exported from [`open-sse/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/index.ts), which acts as the primary interface for any component requiring streaming functionality.

### electron/ - Desktop Client

The `electron/` directory isolates the desktop client built with **Electron**. It contains the main process scripts, preload hooks, and packaging configuration required to wrap the web application as a native desktop experience. The window initialization logic resides in [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js), which creates the browser window and loads the compiled UI.

## Operational Tooling and Infrastructure

### bin/ - Executable Entry Points

The `bin/` directory stores executable scripts for the **CLI**, **MCP server**, and deployment helpers. The file `bin/omniroute.mjs` functions as the main CLI runner that spins up the HTTP gateway and parses command-line flags. For Model Context Protocol support, `bin/mcp-server.mjs` starts the MCP tool server, importing utilities directly from the `open-sse/` module.

### scripts/ - Build and Development Automation

This folder contains build automation, continuous integration helpers, and development utilities. Key scripts include post-install hooks, WebSocket server implementations (`codex-ws`), and environment setup routines that streamline the development workflow.

### tests/ - Validation Suites

The `tests/` directory organizes unit, integration, and end-to-end validation suites. It utilizes **Vitest** for unit testing, **Playwright** for browser automation, and shell scripts for integration testing across the `src/`, `open-sse/`, and `bin/` directories.

### config/ - Structured Configuration

JSON configuration files live in `config/`, defining payload validation rules, internationalization (i18n) schemas, and provider-specific settings that govern how the application processes requests.

## Documentation and Static Resources

### docs/ - Project Documentation

Human-readable architecture guides, roadmaps, and technical specifications reside in `docs/`. The [`docs/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/README.md) file provides an overview of the system architecture and quick-start instructions for new contributors.

### public/ - Static Web Assets

The `public/` directory serves static assets directly through the Next.js application, including icons, service workers, and the **OpenAPI** specification file ([`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml)) that documents every public API endpoint.

## CI/CD and Development Environment

### .github/ - Continuous Integration

GitHub Actions workflows, issue templates, and repository automation configurations are stored here. The file [`.github/workflows/ci.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/.github/workflows/ci.yml) defines the pipeline that lints, type-checks, and executes the full test suite on every pull request.

### .vscode/ - Editor Configuration

Recommended extensions, formatting rules, and workspace settings for **Visual Studio Code** are defined in this directory, ensuring consistent coding standards across the development team.

## Practical Navigation Examples

To interact with the main directories in OmniRoute's repository, use the following commands:

Start the development server, which concurrently loads the Next.js API from `src/` and the streaming engine from `open-sse/`:

```bash
npm install
npm run dev

```

Launch the CLI tools directly from the `bin/` directory:

```bash
node bin/omniroute.mjs --port 3000
node bin/mcp-server.mjs --socket /tmp/mcp

```

Build the **Electron** desktop client from source:

```bash
cd electron
npm install
npm run build

```

Execute the complete test suite covering all major directories:

```bash
npm run test:all

```

## Summary

- The **`src/`** directory contains the core Next.js application logic, API routes, and database layer, with [`src/server-init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts) serving as the primary entry point.
- The **`open-sse/`** directory implements the streaming engine for LLM request handling, exporting core utilities from [`open-sse/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/index.ts).
- Executable entry points reside in **`bin/`**, including the main CLI (`omniroute.mjs`) and MCP server (`mcp-server.mjs`).
- Desktop application code is isolated within **`electron/`**, with the main process defined in [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js).
- Continuous integration configurations are located under **`.github/`**, specifically in [`.github/workflows/ci.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/.github/workflows/ci.yml).
- API documentation and static assets are stored in **`docs/`** and **`public/`**, with the OpenAPI specification available at [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml).

## Frequently Asked Questions

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

The `open-sse/` directory houses the streaming engine responsible for handling all LLM requests via Server-Sent Events. As implemented in `diegosouzapw/OmniRoute`, this module contains executors, translators, and SSE utilities, with [`open-sse/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/index.ts) exporting the core streaming handlers used throughout the application.

### Where is the main entry point for the OmniRoute HTTP server?

The HTTP server initialization occurs in [`src/server-init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts), which wires together Next.js API routes, database connections, and global middlewares. When starting via the CLI, the executable `bin/omniroute.mjs` handles argument parsing and invokes the server initialization logic.

### How do I build the desktop client from the repository source?

Navigate to the `electron/` directory, install dependencies with `npm install`, and run `npm run build` to produce the packaged desktop application. The main process logic resides in [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js), which creates the application window and loads the web interface.

### Where are the GitHub Actions workflows and CI configurations stored?

All continuous integration configurations are located in the `.github/` directory. The primary workflow file [`.github/workflows/ci.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/.github/workflows/ci.yml) defines the pipeline that performs linting, type-checking, and test execution on every pull request to the repository.