Main Directories in the OmniRoute Repository: Complete Structure Guide

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

npm install
npm run dev

Launch the CLI tools directly from the bin/ directory:

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

Build the Electron desktop client from source:

cd electron
npm install
npm run build

Execute the complete test suite covering all major directories:

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 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.
• 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.
• Continuous integration configurations are located under .github/, specifically in .github/workflows/ci.yml.
• API documentation and static assets are stored in docs/ and public/, with the OpenAPI specification available at 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 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, 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, 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 defines the pipeline that performs linting, type-checking, and test execution on every pull request to the repository.

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