# lanterncx/codex-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/lanterncx/codex-gateway
- Repository: https://github.com/lanterncx/codex-gateway

## Overview

codex-gateway is a self-hosted OpenAI-compatible API gateway. The primary workflow is interactive OAuth login to save a token, then serving authenticated client requests by validating a fixed downstream key, obtaining or refreshing an OAuth access token, and proxying or adapting requests to an upstream service. It also exposes health and model endpoints, supports both Codex OAuth and direct OpenAI API modes, and provides structured request logging. Edges reflect the README and shown source; unsampled wiring is omitted where not established.

Main entry points: [`internal/server/server.go`](https://github.com/lanterncx/codex-gateway/blob/main/internal/server/server.go) (HTTP server), [`internal/cli/auth_login.go`](https://github.com/lanterncx/codex-gateway/blob/main/internal/cli/auth_login.go) (OAuth login), [`internal/upstream/client.go`](https://github.com/lanterncx/codex-gateway/blob/main/internal/upstream/client.go) (HTTP upstream client), [`internal/server/handlers.go`](https://github.com/lanterncx/codex-gateway/blob/main/internal/server/handlers.go) (API handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_auth["CLI and OAuth"]
  node_cli["CLI commands<br/>[root.go]"]
  node_auth_login["OAuth login<br/>[auth_login.go]"]
  node_callback["Callback OAuth<br/>[callback_flow.go]"]
  node_device["Device OAuth<br/>[device_flow.go]"]
  node_token_store[("Token storage<br/>[token_store.go]")]
  node_token_manager["Token manager<br/>[manager.go]"]
end

subgraph group_runtime["Gateway runtime"]
  node_server["HTTP server<br/>[server.go]"]
  node_handlers["API handlers<br/>[handlers.go]"]
  node_auth_middleware["Key validation<br/>[middleware_auth.go]"]
end

subgraph group_upstream["Upstream access"]
  node_upstream_client["HTTP upstream client<br/>[client.go]"]
end

subgraph group_support["Configuration and observability"]
  node_config["Configuration<br/>[config.go]"]
  node_logging["Structured logging<br/>[logger.go]"]
  node_request_id["Request correlation<br/>[request_id.go]"]
end

node_operator(("Operator"))
node_api_client(("API client"))
node_oauth_service{{"OAuth service"}}
node_upstream_service{{"OpenAI or Codex API"}}

node_operator -->|"runs commands"| node_cli
node_cli -->|"starts login"| node_auth_login
node_auth_login -->|"loads settings"| node_config
node_auth_login -->|"runs callback flow"| node_callback
node_callback -->|"exchanges code"| node_oauth_service
node_auth_login -->|"saves token"| node_token_store
node_operator -.->|"may use device flow"| node_device
node_token_manager -->|"loads and saves"| node_token_store
node_token_manager -.->|"refreshes token"| node_oauth_service
node_api_client -->|"sends API requests"| node_server
node_server -->|"protects routes"| node_auth_middleware
node_server -->|"routes requests"| node_handlers
node_handlers -->|"gets access token"| node_token_manager
node_handlers -.->|"sends upstream requests"| node_upstream_client
node_upstream_client -->|"makes HTTP request"| node_upstream_service
node_config -->|"configures endpoints"| node_server
node_config -->|"configures upstream mode"| node_upstream_client
node_server -.->|"logs requests"| node_logging
node_upstream_client -->|"reads request ID"| node_request_id

click node_cli "https://github.com/lanterncx/codex-gateway/blob/main/internal/cli/root.go"
click node_auth_login "https://github.com/lanterncx/codex-gateway/blob/main/internal/cli/auth_login.go"
click node_callback "https://github.com/lanterncx/codex-gateway/blob/main/internal/oauth/callback_flow.go"
click node_device "https://github.com/lanterncx/codex-gateway/blob/main/internal/oauth/device_flow.go"
click node_token_store "https://github.com/lanterncx/codex-gateway/blob/main/internal/auth/token_store.go"
click node_token_manager "https://github.com/lanterncx/codex-gateway/blob/main/internal/auth/manager.go"
click node_config "https://github.com/lanterncx/codex-gateway/blob/main/internal/config/config.go"
click node_logging "https://github.com/lanterncx/codex-gateway/blob/main/internal/logging/logger.go"
click node_request_id "https://github.com/lanterncx/codex-gateway/blob/main/internal/logging/request_id.go"
click node_server "https://github.com/lanterncx/codex-gateway/blob/main/internal/server/server.go"
click node_handlers "https://github.com/lanterncx/codex-gateway/blob/main/internal/server/handlers.go"
click node_auth_middleware "https://github.com/lanterncx/codex-gateway/blob/main/internal/server/middleware_auth.go"
click node_upstream_client "https://github.com/lanterncx/codex-gateway/blob/main/internal/upstream/client.go"

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_cli,node_auth_login,node_callback,node_device,node_token_store,node_token_manager,node_api_client toneBlue
class node_server,node_handlers,node_auth_middleware toneAmber
class node_upstream_client,node_upstream_service toneMint
class node_config,node_logging,node_request_id toneRose
class node_operator,node_oauth_service toneIndigo
```

## Components

### CLI and OAuth

- [CLI commands](https://github.com/lanterncx/codex-gateway/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [OAuth login](https://github.com/lanterncx/codex-gateway/blob/main/internal/cli/auth_login.go): `internal/cli/auth_login.go`
- [Callback OAuth](https://github.com/lanterncx/codex-gateway/blob/main/internal/oauth/callback_flow.go): `internal/oauth/callback_flow.go`
- [Device OAuth](https://github.com/lanterncx/codex-gateway/blob/main/internal/oauth/device_flow.go): `internal/oauth/device_flow.go`
- [Token storage](https://github.com/lanterncx/codex-gateway/blob/main/internal/auth/token_store.go): `internal/auth/token_store.go`
- [Token manager](https://github.com/lanterncx/codex-gateway/blob/main/internal/auth/manager.go): `internal/auth/manager.go`

### Gateway runtime

- [HTTP server](https://github.com/lanterncx/codex-gateway/blob/main/internal/server/server.go): `internal/server/server.go`
- [API handlers](https://github.com/lanterncx/codex-gateway/blob/main/internal/server/handlers.go): `internal/server/handlers.go`
- [Key validation](https://github.com/lanterncx/codex-gateway/blob/main/internal/server/middleware_auth.go): `internal/server/middleware_auth.go`

### Upstream access

- [HTTP upstream client](https://github.com/lanterncx/codex-gateway/blob/main/internal/upstream/client.go): `internal/upstream/client.go`

### Configuration and observability

- [Configuration](https://github.com/lanterncx/codex-gateway/blob/main/internal/config/config.go): `internal/config/config.go`
- [Structured logging](https://github.com/lanterncx/codex-gateway/blob/main/internal/logging/logger.go): `internal/logging/logger.go`
- [Request correlation](https://github.com/lanterncx/codex-gateway/blob/main/internal/logging/request_id.go): `internal/logging/request_id.go`

### Other components

- **Operator**
- **API client**
- **OAuth service**
- **OpenAI or Codex API**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → OAuth login: starts login (evidence: `internal/cli/auth_login.go`)
- OAuth login → Configuration: loads settings (evidence: `internal/cli/auth_login.go`)
- OAuth login → Callback OAuth: runs callback flow (evidence: `internal/cli/auth_login.go`)
- Callback OAuth → OAuth service: exchanges code (evidence: `internal/oauth/callback_flow.go`)
- OAuth login → Token storage: saves token (evidence: `internal/cli/auth_login.go`)
- Operator → Device OAuth: may use device flow
- Token manager → Token storage: loads and saves (evidence: `internal/auth/manager.go`)
- Token manager → OAuth service: refreshes token
- API client → HTTP server: sends API requests (evidence: `README.md`)
- HTTP server → Key validation: protects routes (evidence: `internal/server/server.go`)
- HTTP server → API handlers: routes requests (evidence: `internal/server/server.go`)
- API handlers → Token manager: gets access token (evidence: `README.md`)
- API handlers → HTTP upstream client: sends upstream requests
- HTTP upstream client → OpenAI or Codex API: makes HTTP request (evidence: `internal/upstream/client.go`)
- Configuration → HTTP server: configures endpoints (evidence: `README.md`)
- Configuration → HTTP upstream client: configures upstream mode (evidence: `README.md`)
- HTTP server → Structured logging: logs requests
- HTTP upstream client → Request correlation: reads request ID (evidence: `internal/upstream/client.go`)
