# wei-shaw/claude-relay-service architecture

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

- Interactive diagram: https://gitdiagram.com/wei-shaw/claude-relay-service
- Repository: https://github.com/wei-shaw/claude-relay-service

## Overview

Claude Relay Service is a self-hosted, multi-account API relay with API-key access control and a web administration interface. The main workflow is: a client sends an authenticated model request; a provider route selects an eligible account; the relay contacts the upstream service and returns the response. Operators manage accounts and keys and inspect usage through the admin interface. The README documents additional provider and compatibility paths; sampled source confirms selected Gemini and OpenAI flows, but not every route-to-relay connection.

Main entry points: [`src/models/redis.js`](https://github.com/wei-shaw/claude-relay-service/blob/main/src/models/redis.js) (Redis state), [`src/app.js`](https://github.com/wei-shaw/claude-relay-service/blob/main/src/app.js) (HTTP application), [`src/routes/openaiRoutes.js`](https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/openaiRoutes.js) (OpenAI routes), [`src/services/relay/claudeRelayService.js`](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/relay/claudeRelayService.js) (Claude relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request relay"]
  node_app["HTTP application<br/>[app.js]"]
  node_openai_route["OpenAI routes<br/>[openaiRoutes.js]"]
  node_gemini_handler["Gemini handlers<br/>[geminiHandlers.js]"]
  node_openai_gemini["OpenAI Gemini"]
  node_claude_relay["Claude relay"]
  node_gemini_relay["Gemini relay"]
end

subgraph group_accounts["Accounts and access"]
  node_key_service["API key service<br/>[apiKeyService.js]"]
  node_user_routes["User routes<br/>[userRoutes.js]"]
  node_claude_accounts["Claude accounts"]
  node_gemini_accounts["Gemini accounts"]
  node_openai_scheduler["OpenAI scheduler"]
  node_gemini_scheduler["Gemini scheduler"]
end

subgraph group_admin["Administration"]
  node_admin_routes["Admin routes<br/>[index.js]"]
  node_spa["Admin interface<br/>[App.vue]"]
  node_spa_stores["Admin state<br/>[accounts.js]"]
end

subgraph group_state["Persistence and metering"]
  node_redis[("Redis state<br/>[redis.js]")]
  node_pricing["Pricing service<br/>[pricingService.js]"]
end

node_claude_client(("Claude clients"))
node_gemini_client(("Gemini clients"))
node_operator(("Operator"))
node_upstream(("Model providers"))

node_claude_client -->|"sends requests"| node_app
node_gemini_client -->|"sends requests"| node_app
node_operator -->|"manages service"| node_spa
node_app -->|"dispatches"| node_openai_route
node_app -->|"dispatches"| node_admin_routes
node_app -->|"dispatches"| node_user_routes
node_openai_route -->|"selects account"| node_openai_scheduler
node_openai_route -.->|"relays request"| node_claude_relay
node_gemini_handler -->|"selects account"| node_gemini_scheduler
node_openai_gemini -->|"selects account"| node_gemini_scheduler
node_openai_gemini -->|"loads account"| node_gemini_accounts
node_gemini_handler -->|"loads account"| node_gemini_accounts
node_openai_route -->|"sends request"| node_upstream
node_claude_relay -->|"loads account"| node_claude_accounts
node_claude_relay -->|"sends request"| node_upstream
node_gemini_relay -->|"sends request"| node_upstream
node_user_routes -->|"manages keys"| node_key_service
node_key_service -->|"reads and writes"| node_redis
node_claude_accounts -->|"reads and writes"| node_redis
node_gemini_accounts -->|"reads and writes"| node_redis
node_openai_scheduler -->|"reads state"| node_redis
node_gemini_scheduler -->|"reads state"| node_redis
node_spa -->|"uses state"| node_spa_stores
node_spa_stores -->|"calls API"| node_admin_routes
node_admin_routes -->|"reads and writes"| node_redis
node_key_service -.->|"uses pricing"| node_pricing

click node_app "https://github.com/wei-shaw/claude-relay-service/blob/main/src/app.js"
click node_openai_route "https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/openaiRoutes.js"
click node_gemini_handler "https://github.com/wei-shaw/claude-relay-service/blob/main/src/handlers/geminiHandlers.js"
click node_openai_gemini "https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/openaiGeminiRoutes.js"
click node_claude_relay "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/relay/claudeRelayService.js"
click node_gemini_relay "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/relay/geminiRelayService.js"
click node_key_service "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/apiKeyService.js"
click node_user_routes "https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/userRoutes.js"
click node_claude_accounts "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/account/claudeAccountService.js"
click node_gemini_accounts "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/account/geminiAccountService.js"
click node_openai_scheduler "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/scheduler/unifiedOpenAIScheduler.js"
click node_gemini_scheduler "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/scheduler/unifiedGeminiScheduler.js"
click node_admin_routes "https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/admin/index.js"
click node_spa "https://github.com/wei-shaw/claude-relay-service/blob/main/web/admin-spa/src/App.vue"
click node_spa_stores "https://github.com/wei-shaw/claude-relay-service/blob/main/web/admin-spa/src/stores/accounts.js"
click node_redis "https://github.com/wei-shaw/claude-relay-service/blob/main/src/models/redis.js"
click node_pricing "https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/pricingService.js"

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_app,node_openai_route,node_gemini_handler,node_openai_gemini,node_claude_relay,node_gemini_relay,node_claude_client,node_gemini_client toneBlue
class node_key_service,node_user_routes,node_claude_accounts,node_gemini_accounts,node_openai_scheduler,node_gemini_scheduler toneAmber
class node_admin_routes,node_spa,node_spa_stores toneMint
class node_redis,node_pricing toneRose
class node_operator,node_upstream toneIndigo
```

## Components

### Request relay

- [HTTP application](https://github.com/wei-shaw/claude-relay-service/blob/main/src/app.js): `src/app.js`
- [OpenAI routes](https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/openaiRoutes.js): `src/routes/openaiRoutes.js`
- [Gemini handlers](https://github.com/wei-shaw/claude-relay-service/blob/main/src/handlers/geminiHandlers.js): `src/handlers/geminiHandlers.js`
- [OpenAI Gemini](https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/openaiGeminiRoutes.js): `src/routes/openaiGeminiRoutes.js`
- [Claude relay](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/relay/claudeRelayService.js): `src/services/relay/claudeRelayService.js`
- [Gemini relay](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/relay/geminiRelayService.js): `src/services/relay/geminiRelayService.js`

### Accounts and access

- [API key service](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/apiKeyService.js): `src/services/apiKeyService.js`
- [User routes](https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/userRoutes.js): `src/routes/userRoutes.js`
- [Claude accounts](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/account/claudeAccountService.js): `src/services/account/claudeAccountService.js`
- [Gemini accounts](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/account/geminiAccountService.js): `src/services/account/geminiAccountService.js`
- [OpenAI scheduler](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/scheduler/unifiedOpenAIScheduler.js): `src/services/scheduler/unifiedOpenAIScheduler.js`
- [Gemini scheduler](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/scheduler/unifiedGeminiScheduler.js): `src/services/scheduler/unifiedGeminiScheduler.js`

### Administration

- [Admin routes](https://github.com/wei-shaw/claude-relay-service/blob/main/src/routes/admin/index.js): `src/routes/admin/index.js`
- [Admin interface](https://github.com/wei-shaw/claude-relay-service/blob/main/web/admin-spa/src/App.vue): `web/admin-spa/src/App.vue`
- [Admin state](https://github.com/wei-shaw/claude-relay-service/blob/main/web/admin-spa/src/stores/accounts.js): `web/admin-spa/src/stores/accounts.js`

### Persistence and metering

- [Redis state](https://github.com/wei-shaw/claude-relay-service/blob/main/src/models/redis.js): `src/models/redis.js`
- [Pricing service](https://github.com/wei-shaw/claude-relay-service/blob/main/src/services/pricingService.js): `src/services/pricingService.js`

### Other components

- **Claude clients**
- **Gemini clients**
- **Operator**
- **Model providers**

## Connections

- Claude clients → HTTP application: sends requests
- Gemini clients → HTTP application: sends requests
- Operator → Admin interface: manages service
- HTTP application → OpenAI routes: dispatches
- HTTP application → Admin routes: dispatches
- HTTP application → User routes: dispatches
- OpenAI routes → OpenAI scheduler: selects account
- OpenAI routes → Claude relay: relays request
- Gemini handlers → Gemini scheduler: selects account
- OpenAI Gemini → Gemini scheduler: selects account
- OpenAI Gemini → Gemini accounts: loads account
- Gemini handlers → Gemini accounts: loads account
- OpenAI routes → Model providers: sends request
- Claude relay → Claude accounts: loads account
- Claude relay → Model providers: sends request
- Gemini relay → Model providers: sends request
- User routes → API key service: manages keys
- API key service → Redis state: reads and writes
- Claude accounts → Redis state: reads and writes
- Gemini accounts → Redis state: reads and writes
- OpenAI scheduler → Redis state: reads state
- Gemini scheduler → Redis state: reads state
- Admin interface → Admin state: uses state
- Admin state → Admin routes: calls API
- Admin routes → Redis state: reads and writes
- API key service → Pricing service: uses pricing