# s1line1/home-llm-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/s1line1/home-llm-gateway
- Repository: https://github.com/s1line1/home-llm-gateway

## Overview

home-llm-gateway routes OpenAI-compatible requests from clients through a cloud gateway to models hosted on edge machines. The main flow is HTTP admission and API-key authorization, model-aware agent selection, QUIC/mTLS frame transport, and HTTP/SSE response relay; agents maintain the outbound tunnel and call their local LLM. The gateway also provides key/agent administration, usage and metrics, and a hosted React dashboard. Edges use README statements and shown routing/HTTP code; unsampled subsystem links are omitted where their callers are not evidenced.

Main entry points: [`crates/gateway/src/proxy/mod.rs`](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/proxy/mod.rs) (Request Proxy), [`crates/gateway/src/http/mod.rs`](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/http/mod.rs) (HTTP Router), [`crates/gateway/src/auth.rs`](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/auth.rs) (Key Authorization), [`web/src/api/client.ts`](https://github.com/s1line1/home-llm-gateway/blob/main/web/src/api/client.ts) (Gateway API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway HTTP"]
  node_http["HTTP Router<br/>[mod.rs]"]
  node_auth["Key Authorization<br/>[auth.rs]"]
  node_proxy["Request Proxy<br/>[mod.rs]"]
  node_openai["OpenAI Semantics<br/>[openai.rs]"]
  node_admin["Admin API<br/>[admin.rs]"]
  node_observability["Health And Metrics<br/>[observability.rs]"]
end

subgraph group_edge["Edge Tunnel"]
  node_tunnel["QUIC Tunnel<br/>[tunnel.rs]"]
  node_agent["Edge Agent<br/>[lib.rs]"]
  node_agentconfig["Agent Configuration<br/>[config.rs]"]
end

subgraph group_state["Routing And State"]
  node_gatewaystate["Gateway State<br/>[state.rs]"]
  node_registry["Agent Registry<br/>[registry.rs]"]
  node_routing["Model Routing<br/>[routing.rs]"]
  node_ratelimit["Key Rate Limits<br/>[ratelimit.rs]"]
  node_keystore[("Key And Usage Store<br/>[mod.rs]")]
  node_keyhash["Key Hashing<br/>[hash.rs]"]
  node_usage["Usage Meter<br/>[usage_meter.rs]"]
end

subgraph group_web["Admin Dashboard"]
  node_dashboard["Dashboard App<br/>[main.tsx]"]
  node_webclient["Gateway API Client<br/>[client.ts]"]
  node_token["Admin Token<br/>[useAdminToken.ts]"]
  node_metricsclient["Metrics History"]
  node_metricsparse["Metrics Parser<br/>[metrics.ts]"]
  node_query["Query Configuration<br/>[queryClient.ts]"]
end

subgraph group_protocol["Tunnel Protocol"]
  node_protoframe["Tunnel Frames<br/>[frame.rs]"]
  node_protoio["Frame IO<br/>[io.rs]"]
end

node_client(("API Client"))
node_localmodel(("Local LLM"))

node_client -->|"sends HTTPS requests"| node_http
node_http -->|"authorizes API calls"| node_auth
node_http -->|"routes API requests"| node_proxy
node_http -->|"routes admin calls"| node_admin
node_http -->|"routes probes"| node_observability
node_proxy -->|"authenticates requests"| node_auth
node_proxy -->|"parses request facts"| node_openai
node_proxy -->|"selects edge"| node_routing
node_routing -->|"acquires agent"| node_registry
node_routing -->|"opens tunnel stream"| node_tunnel
node_proxy -->|"forwards framed request"| node_tunnel
node_tunnel -->|"exchanges frames"| node_protoframe
node_protoio -->|"encodes and decodes"| node_protoframe
node_agent -->|"connects outbound"| node_tunnel
node_agent -->|"forwards HTTP requests"| node_localmodel
node_agentconfig -->|"configures agent"| node_agent
node_admin -->|"manages API keys"| node_keystore
node_auth -->|"verifies keys"| node_keystore
node_keystore -->|"hashes credentials"| node_keyhash
node_auth -->|"checks key limits"| node_ratelimit
node_gatewaystate -->|"shares registry"| node_registry
node_gatewaystate -->|"shares key store"| node_keystore
node_proxy -->|"collects usage"| node_usage
node_dashboard -->|"loads gateway data"| node_webclient
node_dashboard -->|"provides metrics history"| node_metricsclient
node_metricsclient -->|"fetches metrics text"| node_webclient
node_metricsclient -->|"parses samples"| node_metricsparse
node_webclient -->|"calls gateway endpoints"| node_http
node_dashboard -->|"guards admin pages"| node_token
node_query -->|"clears token on 401"| node_token
node_webclient -->|"uses bearer token"| node_token
node_observability -->|"reads shared state"| node_gatewaystate

click node_http "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/http/mod.rs"
click node_auth "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/auth.rs"
click node_proxy "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/proxy/mod.rs"
click node_openai "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/openai.rs"
click node_admin "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/admin.rs"
click node_observability "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/http/observability.rs"
click node_gatewaystate "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/state.rs"
click node_registry "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/registry.rs"
click node_routing "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/proxy/routing.rs"
click node_ratelimit "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/ratelimit.rs"
click node_keystore "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/storage/mod.rs"
click node_keyhash "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/storage/hash.rs"
click node_usage "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/usage_meter.rs"
click node_tunnel "https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/proxy/tunnel.rs"
click node_agent "https://github.com/s1line1/home-llm-gateway/blob/main/crates/agent/src/lib.rs"
click node_agentconfig "https://github.com/s1line1/home-llm-gateway/blob/main/crates/agent/src/config.rs"
click node_protoframe "https://github.com/s1line1/home-llm-gateway/blob/main/crates/proto/src/frame.rs"
click node_protoio "https://github.com/s1line1/home-llm-gateway/blob/main/crates/proto/src/io.rs"
click node_dashboard "https://github.com/s1line1/home-llm-gateway/blob/main/web/src/main.tsx"
click node_webclient "https://github.com/s1line1/home-llm-gateway/blob/main/web/src/api/client.ts"
click node_token "https://github.com/s1line1/home-llm-gateway/blob/main/web/src/hooks/useAdminToken.ts"
click node_metricsclient "https://github.com/s1line1/home-llm-gateway/blob/main/web/src/hooks/useMetricsHistory.tsx"
click node_metricsparse "https://github.com/s1line1/home-llm-gateway/blob/main/web/src/api/metrics.ts"
click node_query "https://github.com/s1line1/home-llm-gateway/blob/main/web/src/api/queryClient.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_http,node_auth,node_proxy,node_openai,node_admin,node_observability,node_client toneBlue
class node_tunnel,node_agent,node_agentconfig toneAmber
class node_gatewaystate,node_registry,node_routing,node_ratelimit,node_keystore,node_keyhash,node_usage toneMint
class node_dashboard,node_webclient,node_token,node_metricsclient,node_metricsparse,node_query toneRose
class node_protoframe,node_protoio,node_localmodel toneIndigo
```

## Components

### Gateway HTTP

- [HTTP Router](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/http/mod.rs): `crates/gateway/src/http/mod.rs`
- [Key Authorization](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/auth.rs): `crates/gateway/src/auth.rs`
- [Request Proxy](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/proxy/mod.rs): `crates/gateway/src/proxy/mod.rs`
- [OpenAI Semantics](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/openai.rs): `crates/gateway/src/openai.rs`
- [Admin API](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/admin.rs): `crates/gateway/src/admin.rs`
- [Health And Metrics](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/http/observability.rs): `crates/gateway/src/http/observability.rs`

### Edge Tunnel

- [QUIC Tunnel](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/proxy/tunnel.rs): `crates/gateway/src/proxy/tunnel.rs`
- [Edge Agent](https://github.com/s1line1/home-llm-gateway/blob/main/crates/agent/src/lib.rs): `crates/agent/src/lib.rs`
- [Agent Configuration](https://github.com/s1line1/home-llm-gateway/blob/main/crates/agent/src/config.rs): `crates/agent/src/config.rs`

### Routing And State

- [Gateway State](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/state.rs): `crates/gateway/src/state.rs`
- [Agent Registry](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/registry.rs): `crates/gateway/src/registry.rs`
- [Model Routing](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/proxy/routing.rs): `crates/gateway/src/proxy/routing.rs`
- [Key Rate Limits](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/ratelimit.rs): `crates/gateway/src/ratelimit.rs`
- [Key And Usage Store](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/storage/mod.rs): `crates/gateway/src/storage/mod.rs`
- [Key Hashing](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/storage/hash.rs): `crates/gateway/src/storage/hash.rs`
- [Usage Meter](https://github.com/s1line1/home-llm-gateway/blob/main/crates/gateway/src/usage_meter.rs): `crates/gateway/src/usage_meter.rs`

### Admin Dashboard

- [Dashboard App](https://github.com/s1line1/home-llm-gateway/blob/main/web/src/main.tsx): `web/src/main.tsx`
- [Gateway API Client](https://github.com/s1line1/home-llm-gateway/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Admin Token](https://github.com/s1line1/home-llm-gateway/blob/main/web/src/hooks/useAdminToken.ts): `web/src/hooks/useAdminToken.ts`
- [Metrics History](https://github.com/s1line1/home-llm-gateway/blob/main/web/src/hooks/useMetricsHistory.tsx): `web/src/hooks/useMetricsHistory.tsx`
- [Metrics Parser](https://github.com/s1line1/home-llm-gateway/blob/main/web/src/api/metrics.ts): `web/src/api/metrics.ts`
- [Query Configuration](https://github.com/s1line1/home-llm-gateway/blob/main/web/src/api/queryClient.ts): `web/src/api/queryClient.ts`

### Tunnel Protocol

- [Tunnel Frames](https://github.com/s1line1/home-llm-gateway/blob/main/crates/proto/src/frame.rs): `crates/proto/src/frame.rs`
- [Frame IO](https://github.com/s1line1/home-llm-gateway/blob/main/crates/proto/src/io.rs): `crates/proto/src/io.rs`

### Other components

- **API Client**
- **Local LLM**

## Connections

- API Client → HTTP Router: sends HTTPS requests
- HTTP Router → Key Authorization: authorizes API calls (evidence: `crates/gateway/src/http/mod.rs`)
- HTTP Router → Request Proxy: routes API requests (evidence: `crates/gateway/src/http/mod.rs`)
- HTTP Router → Admin API: routes admin calls (evidence: `crates/gateway/src/http/mod.rs`)
- HTTP Router → Health And Metrics: routes probes (evidence: `crates/gateway/src/http/mod.rs`)
- Request Proxy → Key Authorization: authenticates requests (evidence: `crates/gateway/src/proxy/mod.rs`)
- Request Proxy → OpenAI Semantics: parses request facts (evidence: `crates/gateway/src/proxy/mod.rs`)
- Request Proxy → Model Routing: selects edge (evidence: `crates/gateway/src/proxy/routing.rs`)
- Model Routing → Agent Registry: acquires agent (evidence: `crates/gateway/src/proxy/routing.rs`)
- Model Routing → QUIC Tunnel: opens tunnel stream (evidence: `crates/gateway/src/proxy/routing.rs`)
- Request Proxy → QUIC Tunnel: forwards framed request (evidence: `crates/gateway/src/proxy/mod.rs`)
- QUIC Tunnel → Tunnel Frames: exchanges frames
- Frame IO → Tunnel Frames: encodes and decodes (evidence: `crates/proto/src/io.rs`)
- Edge Agent → QUIC Tunnel: connects outbound
- Edge Agent → Local LLM: forwards HTTP requests
- Agent Configuration → Edge Agent: configures agent (evidence: `crates/agent/src/lib.rs`)
- Admin API → Key And Usage Store: manages API keys (evidence: `crates/gateway/src/admin.rs`)
- Key Authorization → Key And Usage Store: verifies keys (evidence: `crates/gateway/src/auth.rs`)
- Key And Usage Store → Key Hashing: hashes credentials (evidence: `crates/gateway/src/storage/mod.rs`)
- Key Authorization → Key Rate Limits: checks key limits (evidence: `crates/gateway/src/auth.rs`)
- Gateway State → Agent Registry: shares registry (evidence: `crates/gateway/src/state.rs`)
- Gateway State → Key And Usage Store: shares key store (evidence: `crates/gateway/src/state.rs`)
- Request Proxy → Usage Meter: collects usage (evidence: `crates/gateway/src/proxy/mod.rs`)
- Dashboard App → Gateway API Client: loads gateway data (evidence: `web/src/main.tsx`)
- Dashboard App → Metrics History: provides metrics history (evidence: `web/src/main.tsx`)
- Metrics History → Gateway API Client: fetches metrics text (evidence: `web/src/hooks/useMetricsHistory.tsx`)
- Metrics History → Metrics Parser: parses samples (evidence: `web/src/hooks/useMetricsHistory.tsx`)
- Gateway API Client → HTTP Router: calls gateway endpoints
- Dashboard App → Admin Token: guards admin pages
- Query Configuration → Admin Token: clears token on 401 (evidence: `web/src/api/queryClient.ts`)
- Gateway API Client → Admin Token: uses bearer token (evidence: `web/src/hooks/useAdminToken.ts`)
- Health And Metrics → Gateway State: reads shared state (evidence: `crates/gateway/src/http/observability.rs`)
