# hylmithecoder/router-ai architecture

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

- Interactive diagram: https://gitdiagram.com/hylmithecoder/router-ai
- Repository: https://github.com/hylmithecoder/router-ai

## Overview

AI Router exposes OpenAI-compatible and unified chat APIs, authenticates and enforces per-key quotas, selects upstream providers with failover, and records usage for administration. The dashboard manages keys, providers, and usage. The tree also contains a separate local ALPR inference service; its documented detection, OCR, and plate-format stages are shown independently because the sampled code does not establish a connection to the Rust gateway. The route and UI links reflect README capabilities; unsampled handler and frontend wiring is not expanded.

Main entry points: [`src/routes/mod.rs`](https://github.com/hylmithecoder/router-ai/blob/master/src/routes/mod.rs) (HTTP Routes), [`src/ai/router.rs`](https://github.com/hylmithecoder/router-ai/blob/master/src/ai/router.rs) (Provider Router), [`src/handlers/chat.rs`](https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/chat.rs) (Chat Handlers), [`src/handlers/admin.rs`](https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/admin.rs) (Admin Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway API"]
  node_backend["Rust Server<br/>[server.rs]"]
  node_routes["HTTP Routes<br/>[mod.rs]"]
  node_auth["Auth and Quota<br/>[middleware.rs]"]
  node_chat["Chat Handlers<br/>[chat.rs]"]
  node_vision["Vision Handler<br/>[vision.rs]"]
end

subgraph group_routing["AI Routing"]
  node_ai_router["Provider Router<br/>[router.rs]"]
  node_provider["Provider Calls<br/>[provider.rs]"]
  node_stream["Usage Streaming<br/>[usage_stream.rs]"]
  node_upstreams{{"AI Providers"}}
end

subgraph group_admin["Admin and Storage"]
  node_admin_handler["Admin Handlers<br/>[admin.rs]"]
  node_sqlite[("SQLite Store<br/>[sqlite.rs]")]
end

subgraph group_dashboard["Dashboard"]
  node_webui["Admin Dashboard<br/>[Dashboard.tsx]"]
  node_webapi["Dashboard API Client<br/>[api.ts]"]
end

subgraph group_alpr["Local ALPR"]
  node_alpr_server["ALPR Service<br/>[server.py]"]
  node_engine["Plate Detection OCR<br/>[engine.py]"]
  node_format["Plate Formatting<br/>[plate_format.py]"]
end

node_client(("API Client"))
node_image_client(("Image Client"))

node_client -->|"sends requests"| node_routes
node_backend -->|"serves"| node_routes
node_routes -->|"applies auth"| node_auth
node_routes -->|"dispatches chat"| node_chat
node_routes -->|"dispatches vision"| node_vision
node_chat -->|"routes completion"| node_ai_router
node_vision -->|"routes vision"| node_ai_router
node_ai_router -->|"invokes"| node_provider
node_provider -->|"sends requests"| node_upstreams
node_ai_router -->|"records provider status"| node_sqlite
node_routes -->|"dispatches admin"| node_admin_handler
node_admin_handler -->|"reads and writes"| node_sqlite
node_admin_handler -->|"manages providers"| node_ai_router
node_chat -->|"records usage"| node_sqlite
node_webui -->|"requests admin data"| node_webapi
node_webapi -->|"calls admin API"| node_routes
node_image_client -->|"posts image"| node_alpr_server
node_alpr_server -->|"invokes inference"| node_engine
node_engine -->|"parses candidates"| node_format

click node_backend "https://github.com/hylmithecoder/router-ai/blob/master/src/server.rs"
click node_routes "https://github.com/hylmithecoder/router-ai/blob/master/src/routes/mod.rs"
click node_auth "https://github.com/hylmithecoder/router-ai/blob/master/src/middleware.rs"
click node_chat "https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/chat.rs"
click node_vision "https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/vision.rs"
click node_ai_router "https://github.com/hylmithecoder/router-ai/blob/master/src/ai/router.rs"
click node_provider "https://github.com/hylmithecoder/router-ai/blob/master/src/ai/provider.rs"
click node_stream "https://github.com/hylmithecoder/router-ai/blob/master/src/ai/usage_stream.rs"
click node_admin_handler "https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/admin.rs"
click node_sqlite "https://github.com/hylmithecoder/router-ai/blob/master/src/database/sqlite.rs"
click node_webui "https://github.com/hylmithecoder/router-ai/blob/master/webui/app/pages/Dashboard.tsx"
click node_webapi "https://github.com/hylmithecoder/router-ai/blob/master/webui/lib/api.ts"
click node_alpr_server "https://github.com/hylmithecoder/router-ai/blob/master/python-alpr-local/server.py"
click node_engine "https://github.com/hylmithecoder/router-ai/blob/master/python-alpr-local/engine.py"
click node_format "https://github.com/hylmithecoder/router-ai/blob/master/python-alpr-local/plate_format.py"

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_backend,node_routes,node_auth,node_chat,node_vision,node_client,node_image_client toneBlue
class node_ai_router,node_provider,node_stream,node_upstreams toneAmber
class node_admin_handler,node_sqlite toneMint
class node_webui,node_webapi toneRose
class node_alpr_server,node_engine,node_format toneIndigo
```

## Components

### Gateway API

- [Rust Server](https://github.com/hylmithecoder/router-ai/blob/master/src/server.rs): `src/server.rs`
- [HTTP Routes](https://github.com/hylmithecoder/router-ai/blob/master/src/routes/mod.rs): `src/routes/mod.rs`
- [Auth and Quota](https://github.com/hylmithecoder/router-ai/blob/master/src/middleware.rs): `src/middleware.rs`
- [Chat Handlers](https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/chat.rs): `src/handlers/chat.rs`
- [Vision Handler](https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/vision.rs): `src/handlers/vision.rs`

### AI Routing

- [Provider Router](https://github.com/hylmithecoder/router-ai/blob/master/src/ai/router.rs): `src/ai/router.rs`
- [Provider Calls](https://github.com/hylmithecoder/router-ai/blob/master/src/ai/provider.rs): `src/ai/provider.rs`
- [Usage Streaming](https://github.com/hylmithecoder/router-ai/blob/master/src/ai/usage_stream.rs): `src/ai/usage_stream.rs`
- **AI Providers**

### Admin and Storage

- [Admin Handlers](https://github.com/hylmithecoder/router-ai/blob/master/src/handlers/admin.rs): `src/handlers/admin.rs`
- [SQLite Store](https://github.com/hylmithecoder/router-ai/blob/master/src/database/sqlite.rs): `src/database/sqlite.rs`

### Dashboard

- [Admin Dashboard](https://github.com/hylmithecoder/router-ai/blob/master/webui/app/pages/Dashboard.tsx): `webui/app/pages/Dashboard.tsx`
- [Dashboard API Client](https://github.com/hylmithecoder/router-ai/blob/master/webui/lib/api.ts): `webui/lib/api.ts`

### Local ALPR

- [ALPR Service](https://github.com/hylmithecoder/router-ai/blob/master/python-alpr-local/server.py): `python-alpr-local/server.py`
- [Plate Detection OCR](https://github.com/hylmithecoder/router-ai/blob/master/python-alpr-local/engine.py): `python-alpr-local/engine.py`
- [Plate Formatting](https://github.com/hylmithecoder/router-ai/blob/master/python-alpr-local/plate_format.py): `python-alpr-local/plate_format.py`

### Other components

- **API Client**
- **Image Client**

## Connections

- API Client → HTTP Routes: sends requests
- Rust Server → HTTP Routes: serves
- HTTP Routes → Auth and Quota: applies auth
- HTTP Routes → Chat Handlers: dispatches chat
- HTTP Routes → Vision Handler: dispatches vision
- Chat Handlers → Provider Router: routes completion
- Vision Handler → Provider Router: routes vision
- Provider Router → Provider Calls: invokes
- Provider Calls → AI Providers: sends requests
- Provider Router → SQLite Store: records provider status
- HTTP Routes → Admin Handlers: dispatches admin
- Admin Handlers → SQLite Store: reads and writes
- Admin Handlers → Provider Router: manages providers
- Chat Handlers → SQLite Store: records usage
- Admin Dashboard → Dashboard API Client: requests admin data
- Dashboard API Client → HTTP Routes: calls admin API
- Image Client → ALPR Service: posts image
- ALPR Service → Plate Detection OCR: invokes inference
- Plate Detection OCR → Plate Formatting: parses candidates