# gmagl/omniroute architecture

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

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

## Overview

OmniRoute is a self-hosted AI gateway: compatible AI tools send requests to a unified API, which authenticates and routes them to a large provider catalog, then streams results back. Its broader product includes automatic fallback, token compression, quota-aware routing, multimodal bridges, dashboard management, and CLI/MCP interfaces. The graph combines documented capabilities with relationships visible in sampled source and the SOURCE INDEX; unsampled subsystems are represented at supported directory paths, and their internal call links are omitted where unverified.

Main entry points: [`open-sse/index.ts`](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/index.ts) (Unified API), [`open-sse/handlers/chatCore/providerExecutionPipeline.ts`](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/handlers/chatCore/providerExecutionPipeline.ts) (Provider Execution), [`src/server/authz/pipeline.ts`](https://github.com/gmagl/omniroute/blob/release/v3.8.51/src/server/authz/pipeline.ts) (Request Auth), [`open-sse/utils/streamHandler.ts`](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/utils/streamHandler.ts) (Response Streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway Runtime"]
  node_api["Unified API<br/>[index.ts]"]
  node_auth["Request Auth<br/>[pipeline.ts]"]
  node_execution["Provider Execution"]
  node_stream["Response Streaming<br/>[streamHandler.ts]"]
  node_errors["Error Handling<br/>[error.ts]"]
end

subgraph group_providers["Provider Routing"]
  node_catalog["Provider Catalog"]
  node_connections[("Provider Connections<br/>[providers.ts]")]
  node_fallback["Fallback Routing<br/>[accountFallback.ts]"]
end

subgraph group_capabilities["Routing Capabilities"]
  node_compression["Token Compression"]
  node_quota["Quota Scheduling"]
  node_modality["Modality Bridge"]
end

subgraph group_interfaces["Product Interfaces"]
  node_dashboard["Management Dashboard"]
  node_cli["CLI"]
  node_mcp["MCP Tools<br/>[server.ts]"]
end

node_clients(("AI Clients"))
node_upstreams{{"AI Providers"}}

node_clients -->|"send requests"| node_api
node_api -.->|"authorize requests"| node_auth
node_auth -.->|"admit requests"| node_execution
node_execution -.->|"resolve providers"| node_catalog
node_execution -->|"read connections"| node_connections
node_execution -->|"retry alternatives"| node_fallback
node_execution -.->|"dispatch requests"| node_upstreams
node_execution -.->|"stream response"| node_stream
node_stream -->|"format errors"| node_errors
node_api -->|"compress prompts"| node_compression
node_api -->|"schedule by quota"| node_quota
node_api -->|"bridge modalities"| node_modality
node_dashboard -.->|"manage gateway"| node_api
node_cli -.->|"operate gateway"| node_api
node_mcp -.->|"expose tools"| node_api

click node_api "https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/index.ts"
click node_auth "https://github.com/gmagl/omniroute/blob/release/v3.8.51/src/server/authz/pipeline.ts"
click node_execution "https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/handlers/chatCore/providerExecutionPipeline.ts"
click node_stream "https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/utils/streamHandler.ts"
click node_errors "https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/utils/error.ts"
click node_catalog "https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/config/providerRegistry.ts"
click node_connections "https://github.com/gmagl/omniroute/blob/release/v3.8.51/src/lib/db/providers.ts"
click node_fallback "https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/services/accountFallback.ts"
click node_compression "https://github.com/gmagl/omniroute/tree/release/v3.8.51/open-sse/services/compression"
click node_quota "https://github.com/gmagl/omniroute/tree/release/v3.8.51/open-sse/services/usage"
click node_modality "https://github.com/gmagl/omniroute/blob/release/v3.8.51/src/lib/guardrails/videoBridgePipeline.ts"
click node_dashboard "https://github.com/gmagl/omniroute/tree/release/v3.8.51/src/app/(dashboard)"
click node_cli "https://github.com/gmagl/omniroute/tree/release/v3.8.51/bin/cli"
click node_mcp "https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/mcp-server/server.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_auth,node_execution,node_stream,node_errors,node_clients toneBlue
class node_catalog,node_connections,node_fallback toneAmber
class node_compression,node_quota,node_modality toneMint
class node_dashboard,node_cli,node_mcp toneRose
class node_upstreams toneIndigo
```

## Components

### Gateway Runtime

- [Unified API](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/index.ts): `open-sse/index.ts`
- [Request Auth](https://github.com/gmagl/omniroute/blob/release/v3.8.51/src/server/authz/pipeline.ts): `src/server/authz/pipeline.ts`
- [Provider Execution](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/handlers/chatCore/providerExecutionPipeline.ts): `open-sse/handlers/chatCore/providerExecutionPipeline.ts`
- [Response Streaming](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/utils/streamHandler.ts): `open-sse/utils/streamHandler.ts`
- [Error Handling](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/utils/error.ts): `open-sse/utils/error.ts`

### Provider Routing

- [Provider Catalog](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/config/providerRegistry.ts): `open-sse/config/providerRegistry.ts`
- [Provider Connections](https://github.com/gmagl/omniroute/blob/release/v3.8.51/src/lib/db/providers.ts): `src/lib/db/providers.ts`
- [Fallback Routing](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/services/accountFallback.ts): `open-sse/services/accountFallback.ts`

### Routing Capabilities

- [Token Compression](https://github.com/gmagl/omniroute/tree/release/v3.8.51/open-sse/services/compression): `open-sse/services/compression`
- [Quota Scheduling](https://github.com/gmagl/omniroute/tree/release/v3.8.51/open-sse/services/usage): `open-sse/services/usage`
- [Modality Bridge](https://github.com/gmagl/omniroute/blob/release/v3.8.51/src/lib/guardrails/videoBridgePipeline.ts): `src/lib/guardrails/videoBridgePipeline.ts`

### Product Interfaces

- [Management Dashboard](https://github.com/gmagl/omniroute/tree/release/v3.8.51/src/app/(dashboard)): `src/app/(dashboard)`
- [CLI](https://github.com/gmagl/omniroute/tree/release/v3.8.51/bin/cli): `bin/cli`
- [MCP Tools](https://github.com/gmagl/omniroute/blob/release/v3.8.51/open-sse/mcp-server/server.ts): `open-sse/mcp-server/server.ts`

### Other components

- **AI Clients**
- **AI Providers**

## Connections

- AI Clients → Unified API: send requests (evidence: `README.md`)
- Unified API → Request Auth: authorize requests
- Request Auth → Provider Execution: admit requests
- Provider Execution → Provider Catalog: resolve providers
- Provider Execution → Provider Connections: read connections (evidence: `open-sse/handlers/chatCore/providerExecutionPipeline.ts`)
- Provider Execution → Fallback Routing: retry alternatives (evidence: `open-sse/handlers/chatCore/providerExecutionPipeline.ts`)
- Provider Execution → AI Providers: dispatch requests
- Provider Execution → Response Streaming: stream response
- Response Streaming → Error Handling: format errors (evidence: `open-sse/utils/streamHandler.ts`)
- Unified API → Token Compression: compress prompts (evidence: `README.md`)
- Unified API → Quota Scheduling: schedule by quota (evidence: `README.md`)
- Unified API → Modality Bridge: bridge modalities (evidence: `README.md`)
- Management Dashboard → Unified API: manage gateway
- CLI → Unified API: operate gateway
- MCP Tools → Unified API: expose tools
