# ken00h/claude-lb architecture

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

- Interactive diagram: https://gitdiagram.com/ken00h/claude-lb
- Repository: https://github.com/ken00h/claude-lb

## Overview

claude-lb is a work-in-progress Claude/Anthropic account load balancer and proxy with a usage dashboard. Its intended flow is an API client sending Anthropic-compatible requests, account-pool selection and failover, then usage tracking and dashboard reporting. The README explicitly warns that the bundled Codex proxy core is currently inert; the proxy path below represents the documented target, not a working end-to-end flow. The tree and source index show substantial account, dashboard, persistence, and usage subsystems, but sampled excerpts do not establish all runtime wiring.

Main entry points: [`app/modules/proxy/service.py`](https://github.com/ken00h/claude-lb/blob/main/app/modules/proxy/service.py) (Request proxy), [`app/db/models.py`](https://github.com/ken00h/claude-lb/blob/main/app/db/models.py) (Application database), [`app/modules/accounts/service.py`](https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/service.py) (Account lifecycle), [`app/modules/accounts/auth_manager.py`](https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/auth_manager.py) (Account credentials)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Proxy and routing"]
  node_proxy["Request proxy<br/>[service.py]"]
  node_routing["Account routing<br/>[load_balancer.py]"]
end

subgraph group_identity["Accounts and access"]
  node_accounts_api["Account management API<br/>[api.py]"]
  node_account_service["Account lifecycle<br/>[service.py]"]
  node_account_auth["Account credentials<br/>[auth_manager.py]"]
  node_dashboard_auth["Dashboard authentication<br/>[service.py]"]
  node_access["Roles and users<br/>[service.py]"]
end

subgraph group_insight["Usage and dashboard"]
  node_usage["Usage ingestion<br/>[live_ingest.py]"]
  node_request_logs["Request records<br/>[repository.py]"]
  node_dashboard["Dashboard data<br/>[service.py]"]
  node_frontend["Dashboard UI<br/>[App.tsx]"]
end

subgraph group_platform["Application platform"]
  node_database[("Application database<br/>[models.py]")]
  node_app["Application runtime<br/>[main.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_crypto["Token encryption<br/>[crypto.py]"]
end

node_client(("API client"))
node_upstream["Claude upstream"]

node_client -.->|"sends requests"| node_proxy
node_proxy -.->|"selects accounts"| node_routing
node_proxy -.->|"forwards requests"| node_upstream
node_accounts_api -.->|"manages accounts"| node_account_service
node_account_service -->|"refreshes credentials"| node_account_auth
node_account_auth -->|"uses encryption"| node_crypto
node_dashboard_auth -->|"checks roles"| node_access
node_usage -->|"settles snapshots"| node_database
node_request_logs -->|"stores request records"| node_database
node_dashboard -.->|"reads dashboard data"| node_database
node_frontend -.->|"presents usage"| node_dashboard
node_app -->|"loads configuration"| node_settings
node_settings -->|"configures key path"| node_crypto

click node_proxy "https://github.com/ken00h/claude-lb/blob/main/app/modules/proxy/service.py"
click node_routing "https://github.com/ken00h/claude-lb/blob/main/app/modules/proxy/load_balancer.py"
click node_accounts_api "https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/api.py"
click node_account_service "https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/service.py"
click node_account_auth "https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/auth_manager.py"
click node_dashboard_auth "https://github.com/ken00h/claude-lb/blob/main/app/modules/dashboard_auth/service.py"
click node_access "https://github.com/ken00h/claude-lb/blob/main/app/modules/dashboard_roles/service.py"
click node_usage "https://github.com/ken00h/claude-lb/blob/main/app/modules/usage/live_ingest.py"
click node_request_logs "https://github.com/ken00h/claude-lb/blob/main/app/modules/request_logs/repository.py"
click node_dashboard "https://github.com/ken00h/claude-lb/blob/main/app/modules/dashboard/service.py"
click node_frontend "https://github.com/ken00h/claude-lb/blob/main/frontend/src/App.tsx"
click node_database "https://github.com/ken00h/claude-lb/blob/main/app/db/models.py"
click node_app "https://github.com/ken00h/claude-lb/blob/main/app/main.py"
click node_settings "https://github.com/ken00h/claude-lb/blob/main/app/core/config/settings.py"
click node_crypto "https://github.com/ken00h/claude-lb/blob/main/app/core/crypto.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_proxy,node_routing,node_client toneBlue
class node_accounts_api,node_account_service,node_account_auth,node_dashboard_auth,node_access toneAmber
class node_usage,node_request_logs,node_dashboard,node_frontend toneMint
class node_database,node_app,node_settings,node_crypto toneRose
class node_upstream toneIndigo
```

## Components

### Proxy and routing

- [Request proxy](https://github.com/ken00h/claude-lb/blob/main/app/modules/proxy/service.py): `app/modules/proxy/service.py`
- [Account routing](https://github.com/ken00h/claude-lb/blob/main/app/modules/proxy/load_balancer.py): `app/modules/proxy/load_balancer.py`

### Accounts and access

- [Account management API](https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/api.py): `app/modules/accounts/api.py`
- [Account lifecycle](https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/service.py): `app/modules/accounts/service.py`
- [Account credentials](https://github.com/ken00h/claude-lb/blob/main/app/modules/accounts/auth_manager.py): `app/modules/accounts/auth_manager.py`
- [Dashboard authentication](https://github.com/ken00h/claude-lb/blob/main/app/modules/dashboard_auth/service.py): `app/modules/dashboard_auth/service.py`
- [Roles and users](https://github.com/ken00h/claude-lb/blob/main/app/modules/dashboard_roles/service.py): `app/modules/dashboard_roles/service.py`

### Usage and dashboard

- [Usage ingestion](https://github.com/ken00h/claude-lb/blob/main/app/modules/usage/live_ingest.py): `app/modules/usage/live_ingest.py`
- [Request records](https://github.com/ken00h/claude-lb/blob/main/app/modules/request_logs/repository.py): `app/modules/request_logs/repository.py`
- [Dashboard data](https://github.com/ken00h/claude-lb/blob/main/app/modules/dashboard/service.py): `app/modules/dashboard/service.py`
- [Dashboard UI](https://github.com/ken00h/claude-lb/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Application platform

- [Application database](https://github.com/ken00h/claude-lb/blob/main/app/db/models.py): `app/db/models.py`
- [Application runtime](https://github.com/ken00h/claude-lb/blob/main/app/main.py): `app/main.py`
- [Runtime settings](https://github.com/ken00h/claude-lb/blob/main/app/core/config/settings.py): `app/core/config/settings.py`
- [Token encryption](https://github.com/ken00h/claude-lb/blob/main/app/core/crypto.py): `app/core/crypto.py`

### Other components

- **API client**
- **Claude upstream**

## Connections

- API client → Request proxy: sends requests
- Request proxy → Account routing: selects accounts
- Request proxy → Claude upstream: forwards requests
- Account management API → Account lifecycle: manages accounts
- Account lifecycle → Account credentials: refreshes credentials (evidence: `app/modules/accounts/auth_manager.py`)
- Account credentials → Token encryption: uses encryption (evidence: `app/modules/accounts/auth_manager.py`)
- Dashboard authentication → Roles and users: checks roles (evidence: `app/modules/dashboard_auth/service.py`)
- Usage ingestion → Application database: settles snapshots (evidence: `app/modules/usage/live_ingest.py`)
- Request records → Application database: stores request records (evidence: `app/modules/request_logs/repository.py`)
- Dashboard data → Application database: reads dashboard data
- Dashboard UI → Dashboard data: presents usage
- Application runtime → Runtime settings: loads configuration (evidence: `app/main.py`)
- Runtime settings → Token encryption: configures key path (evidence: `app/core/crypto.py`)
