# mrbinjy/omniroute architecture

> Architecture diagram of the GitHub repository mrbinjy/omniroute, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrbinjy/omniroute
- Repository: https://github.com/mrbinjy/omniroute

## Overview

OmniRoute is a unified AI gateway: clients send compatible requests to its local API, which routes requests across provider connections and returns streamed or translated responses. The README also highlights provider cataloging, fallback and routing strategies, token compression, quota-aware scheduling, multimodal bridges, and operational interfaces. The graph preserves these documented capabilities; several links are dashed because their runtime wiring was not shown in the sampled source.

Main entry points: [`open-sse/index.ts`](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/index.ts) (Gateway API), [`open-sse/handlers/chatCore/providerExecutionPipeline.ts`](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/handlers/chatCore/providerExecutionPipeline.ts) (Chat Execution), [`src/lib/db/providers.ts`](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/lib/db/providers.ts) (Provider Connections), [`open-sse/utils/streamHandler.ts`](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/utils/streamHandler.ts) (Stream Handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway Runtime"]
  node_api["Gateway API<br/>[index.ts]"]
  node_authz["Request Authorization<br/>[pipeline.ts]"]
  node_chat["Chat Execution"]
  node_stream["Stream Handling<br/>[streamHandler.ts]"]
  node_errors["Error Mapping<br/>[error.ts]"]
end

subgraph group_routing["Routing And Providers"]
  node_connections[("Provider Connections<br/>[providers.ts]")]
  node_catalog["Provider Catalog<br/>[index.ts]"]
  node_fallback["Fallback Routing"]
  node_quota["Quota Scheduling<br/>[volcenginePlan.ts]"]
end

subgraph group_capabilities["Request Capabilities"]
  node_translation["Format Translation<br/>[index.ts]"]
  node_compression["Token Compression<br/>[engineCatalog.ts]"]
  node_multimodal["Modality Bridges"]
  node_combos["Model Combos<br/>[chaosEngine.ts]"]
end

subgraph group_operations["Management Interfaces"]
  node_dashboard["Web Dashboard"]
  node_cli["CLI"]
  node_mcp["MCP Interface<br/>[server.ts]"]
  node_desktop["Desktop App<br/>[main.js]"]
  node_mitm["Traffic Interception<br/>[manager.ts]"]
end

node_client(("AI Client"))

node_client -.->|"sends requests"| node_api
node_api -.->|"authorizes requests"| node_authz
node_api -.->|"dispatches requests"| node_chat
node_chat -->|"reads connections"| node_connections
node_chat -.->|"supports fallback"| node_fallback
node_chat -.->|"uses quota scheduling"| node_quota
node_chat -.->|"streams responses"| node_stream
node_stream -->|"builds error responses"| node_errors
node_catalog -.->|"catalogs providers"| node_connections
node_api -.->|"supports compatible formats"| node_translation
node_api -.->|"offers compression"| node_compression
node_api -.->|"offers modality bridges"| node_multimodal
node_api -.->|"offers model combos"| node_combos
node_dashboard -.->|"manages gateway"| node_api
node_cli -.->|"operates gateway"| node_api
node_mcp -.->|"exposes tools"| node_api
node_desktop -.->|"hosts server"| node_api
node_mitm -->|"uses provider state"| node_connections

click node_api "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/index.ts"
click node_authz "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/server/authz/pipeline.ts"
click node_chat "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/handlers/chatCore/providerExecutionPipeline.ts"
click node_stream "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/utils/streamHandler.ts"
click node_errors "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/utils/error.ts"
click node_connections "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/lib/db/providers.ts"
click node_catalog "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/config/providers/index.ts"
click node_fallback "https://github.com/mrbinjy/omniroute/tree/release/v3.8.52/open-sse/services"
click node_quota "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/services/usage/volcenginePlan.ts"
click node_translation "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/translator/index.ts"
click node_compression "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/services/compression/engineCatalog.ts"
click node_multimodal "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/lib/guardrails/videoBridgePipeline.ts"
click node_combos "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/services/autoCombo/chaosEngine.ts"
click node_dashboard "https://github.com/mrbinjy/omniroute/tree/release/v3.8.52/src/app"
click node_cli "https://github.com/mrbinjy/omniroute/tree/release/v3.8.52/bin/cli"
click node_mcp "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/mcp-server/server.ts"
click node_desktop "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/electron/main.js"
click node_mitm "https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/mitm/manager.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_authz,node_chat,node_stream,node_errors,node_client toneBlue
class node_connections,node_catalog,node_fallback,node_quota toneAmber
class node_translation,node_compression,node_multimodal,node_combos toneMint
class node_dashboard,node_cli,node_mcp,node_desktop,node_mitm toneRose
```

## Components

### Gateway Runtime

- [Gateway API](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/index.ts): `open-sse/index.ts`
- [Request Authorization](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/server/authz/pipeline.ts): `src/server/authz/pipeline.ts`
- [Chat Execution](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/handlers/chatCore/providerExecutionPipeline.ts): `open-sse/handlers/chatCore/providerExecutionPipeline.ts`
- [Stream Handling](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/utils/streamHandler.ts): `open-sse/utils/streamHandler.ts`
- [Error Mapping](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/utils/error.ts): `open-sse/utils/error.ts`

### Routing And Providers

- [Provider Connections](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/lib/db/providers.ts): `src/lib/db/providers.ts`
- [Provider Catalog](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/config/providers/index.ts): `open-sse/config/providers/index.ts`
- [Fallback Routing](https://github.com/mrbinjy/omniroute/tree/release/v3.8.52/open-sse/services): `open-sse/services`
- [Quota Scheduling](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/services/usage/volcenginePlan.ts): `open-sse/services/usage/volcenginePlan.ts`

### Request Capabilities

- [Format Translation](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/translator/index.ts): `open-sse/translator/index.ts`
- [Token Compression](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/services/compression/engineCatalog.ts): `open-sse/services/compression/engineCatalog.ts`
- [Modality Bridges](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/lib/guardrails/videoBridgePipeline.ts): `src/lib/guardrails/videoBridgePipeline.ts`
- [Model Combos](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/services/autoCombo/chaosEngine.ts): `open-sse/services/autoCombo/chaosEngine.ts`

### Management Interfaces

- [Web Dashboard](https://github.com/mrbinjy/omniroute/tree/release/v3.8.52/src/app): `src/app`
- [CLI](https://github.com/mrbinjy/omniroute/tree/release/v3.8.52/bin/cli): `bin/cli`
- [MCP Interface](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/open-sse/mcp-server/server.ts): `open-sse/mcp-server/server.ts`
- [Desktop App](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/electron/main.js): `electron/main.js`
- [Traffic Interception](https://github.com/mrbinjy/omniroute/blob/release/v3.8.52/src/mitm/manager.ts): `src/mitm/manager.ts`

### Other components

- **AI Client**

## Connections

- AI Client → Gateway API: sends requests (evidence: `README.md`)
- Gateway API → Request Authorization: authorizes requests
- Gateway API → Chat Execution: dispatches requests (evidence: `README.md`)
- Chat Execution → Provider Connections: reads connections (evidence: `open-sse/handlers/chatCore/providerExecutionPipeline.ts`)
- Chat Execution → Fallback Routing: supports fallback (evidence: `README.md`)
- Chat Execution → Quota Scheduling: uses quota scheduling (evidence: `README.md`)
- Chat Execution → Stream Handling: streams responses (evidence: `README.md`)
- Stream Handling → Error Mapping: builds error responses (evidence: `open-sse/utils/streamHandler.ts`)
- Provider Catalog → Provider Connections: catalogs providers (evidence: `README.md`)
- Gateway API → Format Translation: supports compatible formats (evidence: `README.md`)
- Gateway API → Token Compression: offers compression (evidence: `README.md`)
- Gateway API → Modality Bridges: offers modality bridges (evidence: `README.md`)
- Gateway API → Model Combos: offers model combos (evidence: `README.md`)
- Web Dashboard → Gateway API: manages gateway (evidence: `README.md`)
- CLI → Gateway API: operates gateway (evidence: `README.md`)
- MCP Interface → Gateway API: exposes tools (evidence: `README.md`)
- Desktop App → Gateway API: hosts server (evidence: `electron/main.js`)
- Traffic Interception → Provider Connections: uses provider state (evidence: `src/mitm/manager.ts`)