# songquanpeng/one-api architecture

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

- Interactive diagram: https://gitdiagram.com/songquanpeng/one-api
- Repository: https://github.com/songquanpeng/one-api

## Overview

One API is an OpenAI-compatible gateway that fronts many model providers, alongside an account and operations dashboard. The principal request path accepts a client API call, routes and selects a configured channel, adapts the request for the provider, then returns a compatible response and accounts usage. The README also documents streaming, images, retries, token and channel controls, billing, redemptions, and several login methods. Wiring is inferred only where supported by the tree, README, or sampled code; unsampled subsystem internals are represented at their enclosing paths.

Main entry points: [`model/main.go`](https://github.com/songquanpeng/one-api/blob/main/model/main.go) (Application data), [`relay/controller`](https://github.com/songquanpeng/one-api/tree/main/relay/controller) (Relay handlers), [`relay/billing`](https://github.com/songquanpeng/one-api/tree/main/relay/billing) (Usage billing), [`router/relay.go`](https://github.com/songquanpeng/one-api/blob/main/router/relay.go) (HTTP routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API gateway"]
  node_router["HTTP routing<br/>[relay.go]"]
  node_relay["Relay handlers"]
  node_selection["Channel selection<br/>[distributor.go]"]
  node_billing["Usage billing"]
end

subgraph group_providers["Provider adapters"]
  node_adapter["Provider adapters"]
end

subgraph group_management["Management"]
  node_adminroutes["Management routes<br/>[api.go]"]
  node_controllers["Admin controllers"]
  node_auth["Authentication"]
  node_tokens["Token controls<br/>[token.go]"]
  node_channels["Channel controls<br/>[channel.go]"]
  node_redemptions["Redemptions<br/>[redemption.go]"]
end

subgraph group_persistence["State and billing"]
  node_database[("Application data<br/>[main.go]")]
  node_logs[("Usage logs<br/>[log.go]")]
  node_monitoring["Channel monitoring"]
end

subgraph group_clients["User interfaces"]
  node_adminui["Admin dashboard<br/>[App.js]"]
  node_webapi["Web API client<br/>[api.js]"]
end

node_client(("API client"))
node_provider(("Model providers"))
node_oauth(("OAuth services"))

node_client -->|"sends request"| node_router
node_router -->|"dispatches"| node_relay
node_relay -->|"selects channel"| node_selection
node_relay -->|"invokes adapter"| node_adapter
node_adapter -->|"calls provider"| node_provider
node_relay -->|"accounts usage"| node_billing
node_billing -->|"reads pricing"| node_database
node_billing -->|"records usage"| node_logs
node_selection -->|"reads channels"| node_database
node_adminui -->|"calls API"| node_webapi
node_webapi -->|"sends requests"| node_adminroutes
node_adminroutes -->|"dispatches"| node_controllers
node_controllers -->|"reads and writes"| node_database
node_auth -.->|"delegates login"| node_oauth
node_tokens -->|"manages tokens"| node_database
node_channels -->|"manages channels"| node_database
node_redemptions -->|"manages codes"| node_database
node_monitoring -->|"tracks channels"| node_database

click node_router "https://github.com/songquanpeng/one-api/blob/main/router/relay.go"
click node_relay "https://github.com/songquanpeng/one-api/tree/main/relay/controller"
click node_selection "https://github.com/songquanpeng/one-api/blob/main/middleware/distributor.go"
click node_billing "https://github.com/songquanpeng/one-api/tree/main/relay/billing"
click node_adapter "https://github.com/songquanpeng/one-api/tree/main/relay/adaptor"
click node_adminui "https://github.com/songquanpeng/one-api/blob/main/web/default/src/App.js"
click node_webapi "https://github.com/songquanpeng/one-api/blob/main/web/default/src/helpers/api.js"
click node_adminroutes "https://github.com/songquanpeng/one-api/blob/main/router/api.go"
click node_controllers "https://github.com/songquanpeng/one-api/tree/main/controller"
click node_auth "https://github.com/songquanpeng/one-api/tree/main/controller/auth"
click node_tokens "https://github.com/songquanpeng/one-api/blob/main/controller/token.go"
click node_channels "https://github.com/songquanpeng/one-api/blob/main/controller/channel.go"
click node_redemptions "https://github.com/songquanpeng/one-api/blob/main/controller/redemption.go"
click node_database "https://github.com/songquanpeng/one-api/blob/main/model/main.go"
click node_logs "https://github.com/songquanpeng/one-api/blob/main/model/log.go"
click node_monitoring "https://github.com/songquanpeng/one-api/tree/main/monitor"

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_router,node_relay,node_selection,node_billing,node_client toneBlue
class node_adapter toneAmber
class node_adminroutes,node_controllers,node_auth,node_tokens,node_channels,node_redemptions toneMint
class node_database,node_logs,node_monitoring toneRose
class node_adminui,node_webapi,node_provider,node_oauth toneIndigo
```

## Components

### API gateway

- [HTTP routing](https://github.com/songquanpeng/one-api/blob/main/router/relay.go): `router/relay.go`
- [Relay handlers](https://github.com/songquanpeng/one-api/tree/main/relay/controller): `relay/controller`
- [Channel selection](https://github.com/songquanpeng/one-api/blob/main/middleware/distributor.go): `middleware/distributor.go`
- [Usage billing](https://github.com/songquanpeng/one-api/tree/main/relay/billing): `relay/billing`

### Provider adapters

- [Provider adapters](https://github.com/songquanpeng/one-api/tree/main/relay/adaptor): `relay/adaptor`

### Management

- [Management routes](https://github.com/songquanpeng/one-api/blob/main/router/api.go): `router/api.go`
- [Admin controllers](https://github.com/songquanpeng/one-api/tree/main/controller): `controller`
- [Authentication](https://github.com/songquanpeng/one-api/tree/main/controller/auth): `controller/auth`
- [Token controls](https://github.com/songquanpeng/one-api/blob/main/controller/token.go): `controller/token.go`
- [Channel controls](https://github.com/songquanpeng/one-api/blob/main/controller/channel.go): `controller/channel.go`
- [Redemptions](https://github.com/songquanpeng/one-api/blob/main/controller/redemption.go): `controller/redemption.go`

### State and billing

- [Application data](https://github.com/songquanpeng/one-api/blob/main/model/main.go): `model/main.go`
- [Usage logs](https://github.com/songquanpeng/one-api/blob/main/model/log.go): `model/log.go`
- [Channel monitoring](https://github.com/songquanpeng/one-api/tree/main/monitor): `monitor`

### User interfaces

- [Admin dashboard](https://github.com/songquanpeng/one-api/blob/main/web/default/src/App.js): `web/default/src/App.js`
- [Web API client](https://github.com/songquanpeng/one-api/blob/main/web/default/src/helpers/api.js): `web/default/src/helpers/api.js`

### Other components

- **API client**
- **Model providers**
- **OAuth services**

## Connections

- API client → HTTP routing: sends request
- HTTP routing → Relay handlers: dispatches
- Relay handlers → Channel selection: selects channel
- Relay handlers → Provider adapters: invokes adapter
- Provider adapters → Model providers: calls provider
- Relay handlers → Usage billing: accounts usage
- Usage billing → Application data: reads pricing
- Usage billing → Usage logs: records usage
- Channel selection → Application data: reads channels
- Admin dashboard → Web API client: calls API
- Web API client → Management routes: sends requests
- Management routes → Admin controllers: dispatches
- Admin controllers → Application data: reads and writes
- Authentication → OAuth services: delegates login
- Token controls → Application data: manages tokens
- Channel controls → Application data: manages channels
- Redemptions → Application data: manages codes
- Channel monitoring → Application data: tracks channels