# soju06/codex-lb architecture

> Architecture diagram of the GitHub repository soju06/codex-lb, 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/soju06/codex-lb
- Repository: https://github.com/soju06/codex-lb

## Overview

codex-lb pools ChatGPT accounts behind an OpenAI-compatible proxy. A client request enters the proxy, is routed to an eligible pooled account, and is forwarded upstream; account credentials and usage are managed through the dashboard and persisted for reporting and control. The README documents API-key limits, dashboard authentication, model synchronization, and automation capabilities. The graph uses documented product behavior and paths from the tree; sampled excerpts were partial, so uncertain internal call wiring is not asserted.

Main entry points: [`app/db/models.py`](https://github.com/soju06/codex-lb/blob/main/app/db/models.py) (Application database), [`app/modules/proxy/service.py`](https://github.com/soju06/codex-lb/blob/main/app/modules/proxy/service.py) (Proxy service), [`app/modules/dashboard/api.py`](https://github.com/soju06/codex-lb/blob/main/app/modules/dashboard/api.py) (Dashboard APIs), [`app/modules/accounts/service.py`](https://github.com/soju06/codex-lb/blob/main/app/modules/accounts/service.py) (Account management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Proxy and routing"]
  node_proxy_api["Proxy endpoints<br/>[api.py]"]
  node_proxy_service["Proxy service<br/>[service.py]"]
  node_selection["Account selection<br/>[load_balancer.py]"]
  node_codex_client["Codex transport<br/>[codex.py]"]
  node_models["Model synchronization"]
end

subgraph group_accounts["Accounts and identity"]
  node_account_api["Account endpoints<br/>[api.py]"]
  node_account_service["Account management<br/>[service.py]"]
  node_account_auth["Token refresh<br/>[auth_manager.py]"]
  node_oauth["OAuth management<br/>[service.py]"]
end

subgraph group_dashboard["Dashboard and controls"]
  node_frontend["Dashboard interface<br/>[App.tsx]"]
  node_dashboard_api["Dashboard APIs<br/>[api.py]"]
  node_dashboard_auth["Dashboard authentication<br/>[service.py]"]
  node_api_keys["API key controls<br/>[service.py]"]
  node_automations["Account automations<br/>[service.py]"]
end

subgraph group_usage["Usage and reporting"]
  node_usage["Usage tracking<br/>[service.py]"]
  node_live_ingest["Live usage ingest<br/>[live_ingest.py]"]
  node_request_logs["Request logs<br/>[repository.py]"]
  node_reports["Reports<br/>[service.py]"]
end

subgraph group_platform["Runtime and persistence"]
  node_database[("Application database<br/>[models.py]")]
  node_app_runtime["Application runtime<br/>[main.py]"]
end

node_client(("OpenAI clients"))
node_upstream{{"ChatGPT upstream"}}
node_dashboard_user(("Dashboard users"))

node_client -->|"sends requests"| node_proxy_api
node_proxy_api -->|"dispatches"| node_proxy_service
node_proxy_service -->|"selects account"| node_selection
node_proxy_service -->|"forwards request"| node_codex_client
node_codex_client -->|"sends upstream"| node_upstream
node_upstream -->|"returns response"| node_codex_client
node_dashboard_user -->|"uses dashboard"| node_frontend
node_frontend -->|"calls APIs"| node_dashboard_api
node_dashboard_api -->|"checks access"| node_dashboard_auth
node_dashboard_api -->|"manages accounts"| node_account_service
node_account_api -->|"dispatches"| node_account_service
node_account_service -->|"reads and writes"| node_database
node_account_service -->|"refreshes credentials"| node_account_auth
node_oauth -->|"updates credentials"| node_account_service
node_dashboard_api -->|"manages keys"| node_api_keys
node_api_keys -->|"reads and writes"| node_database
node_dashboard_api -->|"manages jobs"| node_automations
node_automations -->|"reads and writes"| node_database
node_proxy_service -->|"updates usage"| node_usage
node_usage -->|"reads and writes"| node_database
node_live_ingest -->|"persists snapshots"| node_database
node_proxy_service -->|"records requests"| node_request_logs
node_request_logs -->|"writes and queries"| node_database
node_reports -->|"queries aggregates"| node_request_logs
node_reports -->|"serves dashboard data"| node_frontend
node_models -.->|"fetches models"| node_upstream
node_app_runtime -->|"hosts routes"| node_proxy_api

click node_proxy_api "https://github.com/soju06/codex-lb/blob/main/app/modules/proxy/api.py"
click node_proxy_service "https://github.com/soju06/codex-lb/blob/main/app/modules/proxy/service.py"
click node_selection "https://github.com/soju06/codex-lb/blob/main/app/modules/proxy/load_balancer.py"
click node_codex_client "https://github.com/soju06/codex-lb/blob/main/app/core/clients/codex.py"
click node_account_api "https://github.com/soju06/codex-lb/blob/main/app/modules/accounts/api.py"
click node_account_service "https://github.com/soju06/codex-lb/blob/main/app/modules/accounts/service.py"
click node_account_auth "https://github.com/soju06/codex-lb/blob/main/app/modules/accounts/auth_manager.py"
click node_oauth "https://github.com/soju06/codex-lb/blob/main/app/modules/oauth/service.py"
click node_frontend "https://github.com/soju06/codex-lb/blob/main/frontend/src/App.tsx"
click node_dashboard_api "https://github.com/soju06/codex-lb/blob/main/app/modules/dashboard/api.py"
click node_dashboard_auth "https://github.com/soju06/codex-lb/blob/main/app/modules/dashboard_auth/service.py"
click node_api_keys "https://github.com/soju06/codex-lb/blob/main/app/modules/api_keys/service.py"
click node_automations "https://github.com/soju06/codex-lb/blob/main/app/modules/automations/service.py"
click node_usage "https://github.com/soju06/codex-lb/blob/main/app/modules/usage/service.py"
click node_live_ingest "https://github.com/soju06/codex-lb/blob/main/app/modules/usage/live_ingest.py"
click node_request_logs "https://github.com/soju06/codex-lb/blob/main/app/modules/request_logs/repository.py"
click node_reports "https://github.com/soju06/codex-lb/blob/main/app/modules/reports/service.py"
click node_models "https://github.com/soju06/codex-lb/blob/main/app/core/openai/model_refresh_scheduler.py"
click node_database "https://github.com/soju06/codex-lb/blob/main/app/db/models.py"
click node_app_runtime "https://github.com/soju06/codex-lb/blob/main/app/main.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_api,node_proxy_service,node_selection,node_codex_client,node_models,node_client,node_dashboard_user toneBlue
class node_account_api,node_account_service,node_account_auth,node_oauth toneAmber
class node_frontend,node_dashboard_api,node_dashboard_auth,node_api_keys,node_automations toneMint
class node_usage,node_live_ingest,node_request_logs,node_reports toneRose
class node_database,node_app_runtime,node_upstream toneIndigo
```

## Components

### Proxy and routing

- [Proxy endpoints](https://github.com/soju06/codex-lb/blob/main/app/modules/proxy/api.py): `app/modules/proxy/api.py`
- [Proxy service](https://github.com/soju06/codex-lb/blob/main/app/modules/proxy/service.py): `app/modules/proxy/service.py`
- [Account selection](https://github.com/soju06/codex-lb/blob/main/app/modules/proxy/load_balancer.py): `app/modules/proxy/load_balancer.py`
- [Codex transport](https://github.com/soju06/codex-lb/blob/main/app/core/clients/codex.py): `app/core/clients/codex.py`
- [Model synchronization](https://github.com/soju06/codex-lb/blob/main/app/core/openai/model_refresh_scheduler.py): `app/core/openai/model_refresh_scheduler.py`

### Accounts and identity

- [Account endpoints](https://github.com/soju06/codex-lb/blob/main/app/modules/accounts/api.py): `app/modules/accounts/api.py`
- [Account management](https://github.com/soju06/codex-lb/blob/main/app/modules/accounts/service.py): `app/modules/accounts/service.py`
- [Token refresh](https://github.com/soju06/codex-lb/blob/main/app/modules/accounts/auth_manager.py): `app/modules/accounts/auth_manager.py`
- [OAuth management](https://github.com/soju06/codex-lb/blob/main/app/modules/oauth/service.py): `app/modules/oauth/service.py`

### Dashboard and controls

- [Dashboard interface](https://github.com/soju06/codex-lb/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard APIs](https://github.com/soju06/codex-lb/blob/main/app/modules/dashboard/api.py): `app/modules/dashboard/api.py`
- [Dashboard authentication](https://github.com/soju06/codex-lb/blob/main/app/modules/dashboard_auth/service.py): `app/modules/dashboard_auth/service.py`
- [API key controls](https://github.com/soju06/codex-lb/blob/main/app/modules/api_keys/service.py): `app/modules/api_keys/service.py`
- [Account automations](https://github.com/soju06/codex-lb/blob/main/app/modules/automations/service.py): `app/modules/automations/service.py`

### Usage and reporting

- [Usage tracking](https://github.com/soju06/codex-lb/blob/main/app/modules/usage/service.py): `app/modules/usage/service.py`
- [Live usage ingest](https://github.com/soju06/codex-lb/blob/main/app/modules/usage/live_ingest.py): `app/modules/usage/live_ingest.py`
- [Request logs](https://github.com/soju06/codex-lb/blob/main/app/modules/request_logs/repository.py): `app/modules/request_logs/repository.py`
- [Reports](https://github.com/soju06/codex-lb/blob/main/app/modules/reports/service.py): `app/modules/reports/service.py`

### Runtime and persistence

- [Application database](https://github.com/soju06/codex-lb/blob/main/app/db/models.py): `app/db/models.py`
- [Application runtime](https://github.com/soju06/codex-lb/blob/main/app/main.py): `app/main.py`

### Other components

- **OpenAI clients**
- **ChatGPT upstream**
- **Dashboard users**

## Connections

- OpenAI clients → Proxy endpoints: sends requests
- Proxy endpoints → Proxy service: dispatches
- Proxy service → Account selection: selects account
- Proxy service → Codex transport: forwards request
- Codex transport → ChatGPT upstream: sends upstream
- ChatGPT upstream → Codex transport: returns response
- Dashboard users → Dashboard interface: uses dashboard
- Dashboard interface → Dashboard APIs: calls APIs
- Dashboard APIs → Dashboard authentication: checks access
- Dashboard APIs → Account management: manages accounts
- Account endpoints → Account management: dispatches
- Account management → Application database: reads and writes
- Account management → Token refresh: refreshes credentials
- OAuth management → Account management: updates credentials
- Dashboard APIs → API key controls: manages keys
- API key controls → Application database: reads and writes
- Dashboard APIs → Account automations: manages jobs
- Account automations → Application database: reads and writes
- Proxy service → Usage tracking: updates usage
- Usage tracking → Application database: reads and writes
- Live usage ingest → Application database: persists snapshots
- Proxy service → Request logs: records requests
- Request logs → Application database: writes and queries
- Reports → Request logs: queries aggregates
- Reports → Dashboard interface: serves dashboard data
- Model synchronization → ChatGPT upstream: fetches models
- Application runtime → Proxy endpoints: hosts routes