# quantumnous/new-api architecture

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

- Interactive diagram: https://gitdiagram.com/quantumnous/new-api
- Repository: https://github.com/quantumnous/new-api

## Overview

New API is a self-hosted AI gateway: a client sends a model request through its API, the gateway selects a configured upstream channel, adapts the request and response, and accounts for usage. Separate product branches manage channels and model pricing, user access, asynchronous task plugins, and the web console. The README documents these capabilities; sampled source confirms the embedding relay’s conversion, upstream request, and quota-accounting steps. Other subsystem links reflect documented roles, not inspected call sites.

Main entry points: [`relay`](https://github.com/quantumnous/new-api/tree/main/relay) (Protocol handlers), [`web/src`](https://github.com/quantumnous/new-api/tree/main/web/src) (Web console), [`controller/relay.go`](https://github.com/quantumnous/new-api/blob/main/controller/relay.go) (Relay entry), [`service/billing.go`](https://github.com/quantumnous/new-api/blob/main/service/billing.go) (Usage settlement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Model gateway"]
  node_api["API routes<br/>[relay-router.go]"]
  node_relay["Relay entry<br/>[relay.go]"]
  node_protocol["Protocol handlers"]
  node_convert["Protocol conversion"]
end

subgraph group_routing["Channels and models"]
  node_channel_select["Channel selection<br/>[channel_select.go]"]
  node_channel_config["Channel management<br/>[channel.go]"]
  node_model_config["Model configuration<br/>[model.go]"]
  node_adapters["Provider adapters"]
end

subgraph group_billing["Usage and billing"]
  node_billing["Usage settlement<br/>[billing.go]"]
  node_pricing["Pricing rules"]
  node_usage_logs[("Usage records<br/>[log.go]")]
  node_payments["Payment integrations<br/>[webhook.go]"]
end

subgraph group_identity["Access and console"]
  node_accounts["Users and keys<br/>[user.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_permissions["Permissions"]
  node_console["Web console"]
end

subgraph group_tasks["Tasks and integrations"]
  node_task_api["Task API<br/>[task.go]"]
  node_plugin_runtime["Plugin runtime"]
  node_task_plugins["Task plugins"]
  node_task_state[("Task records<br/>[task.go]")]
end

node_client(("API client"))
node_upstream(("Model providers"))
node_payment_services(("Payment providers"))

node_client -->|"sends request"| node_api
node_api -->|"dispatches"| node_relay
node_relay -->|"checks access"| node_auth
node_relay -->|"dispatches"| node_protocol
node_protocol -->|"selects channel"| node_channel_select
node_protocol -->|"converts payload"| node_convert
node_protocol -->|"uses adapter"| node_adapters
node_adapters -->|"sends request"| node_upstream
node_protocol -->|"reports usage"| node_billing
node_billing -->|"evaluates pricing"| node_pricing
node_billing -->|"records usage"| node_usage_logs
node_console -->|"configures channels"| node_channel_config
node_console -->|"configures models"| node_model_config
node_console -->|"manages accounts"| node_accounts
node_console -->|"manages permissions"| node_permissions
node_task_api -->|"invokes hooks"| node_plugin_runtime
node_plugin_runtime -->|"loads plugins"| node_task_plugins
node_task_api -->|"stores task state"| node_task_state
node_payments -.->|"integrates payments"| node_payment_services

click node_api "https://github.com/quantumnous/new-api/blob/main/router/relay-router.go"
click node_relay "https://github.com/quantumnous/new-api/blob/main/controller/relay.go"
click node_protocol "https://github.com/quantumnous/new-api/tree/main/relay"
click node_convert "https://github.com/quantumnous/new-api/tree/main/relaykit/relayconvert"
click node_channel_select "https://github.com/quantumnous/new-api/blob/main/service/channel_select.go"
click node_channel_config "https://github.com/quantumnous/new-api/blob/main/controller/channel.go"
click node_model_config "https://github.com/quantumnous/new-api/blob/main/controller/model.go"
click node_adapters "https://github.com/quantumnous/new-api/tree/main/relay/channel"
click node_billing "https://github.com/quantumnous/new-api/blob/main/service/billing.go"
click node_pricing "https://github.com/quantumnous/new-api/tree/main/pkg/billingexpr"
click node_usage_logs "https://github.com/quantumnous/new-api/blob/main/model/log.go"
click node_accounts "https://github.com/quantumnous/new-api/blob/main/controller/user.go"
click node_auth "https://github.com/quantumnous/new-api/blob/main/middleware/auth.go"
click node_permissions "https://github.com/quantumnous/new-api/tree/main/service/authz"
click node_console "https://github.com/quantumnous/new-api/tree/main/web/src"
click node_task_api "https://github.com/quantumnous/new-api/blob/main/controller/task.go"
click node_plugin_runtime "https://github.com/quantumnous/new-api/tree/main/pkg/jsplugin"
click node_task_plugins "https://github.com/quantumnous/new-api/tree/main/plugins/tasks"
click node_task_state "https://github.com/quantumnous/new-api/blob/main/model/task.go"
click node_payments "https://github.com/quantumnous/new-api/blob/main/service/webhook.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_api,node_relay,node_protocol,node_convert,node_client toneBlue
class node_channel_select,node_channel_config,node_model_config,node_adapters toneAmber
class node_billing,node_pricing,node_usage_logs,node_payments toneMint
class node_accounts,node_auth,node_permissions,node_console toneRose
class node_task_api,node_plugin_runtime,node_task_plugins,node_task_state,node_upstream,node_payment_services toneIndigo
```

## Components

### Model gateway

- [API routes](https://github.com/quantumnous/new-api/blob/main/router/relay-router.go): `router/relay-router.go`
- [Relay entry](https://github.com/quantumnous/new-api/blob/main/controller/relay.go): `controller/relay.go`
- [Protocol handlers](https://github.com/quantumnous/new-api/tree/main/relay): `relay`
- [Protocol conversion](https://github.com/quantumnous/new-api/tree/main/relaykit/relayconvert): `relaykit/relayconvert`

### Channels and models

- [Channel selection](https://github.com/quantumnous/new-api/blob/main/service/channel_select.go): `service/channel_select.go`
- [Channel management](https://github.com/quantumnous/new-api/blob/main/controller/channel.go): `controller/channel.go`
- [Model configuration](https://github.com/quantumnous/new-api/blob/main/controller/model.go): `controller/model.go`
- [Provider adapters](https://github.com/quantumnous/new-api/tree/main/relay/channel): `relay/channel`

### Usage and billing

- [Usage settlement](https://github.com/quantumnous/new-api/blob/main/service/billing.go): `service/billing.go`
- [Pricing rules](https://github.com/quantumnous/new-api/tree/main/pkg/billingexpr): `pkg/billingexpr`
- [Usage records](https://github.com/quantumnous/new-api/blob/main/model/log.go): `model/log.go`
- [Payment integrations](https://github.com/quantumnous/new-api/blob/main/service/webhook.go): `service/webhook.go`

### Access and console

- [Users and keys](https://github.com/quantumnous/new-api/blob/main/controller/user.go): `controller/user.go`
- [Authentication](https://github.com/quantumnous/new-api/blob/main/middleware/auth.go): `middleware/auth.go`
- [Permissions](https://github.com/quantumnous/new-api/tree/main/service/authz): `service/authz`
- [Web console](https://github.com/quantumnous/new-api/tree/main/web/src): `web/src`

### Tasks and integrations

- [Task API](https://github.com/quantumnous/new-api/blob/main/controller/task.go): `controller/task.go`
- [Plugin runtime](https://github.com/quantumnous/new-api/tree/main/pkg/jsplugin): `pkg/jsplugin`
- [Task plugins](https://github.com/quantumnous/new-api/tree/main/plugins/tasks): `plugins/tasks`
- [Task records](https://github.com/quantumnous/new-api/blob/main/model/task.go): `model/task.go`

### Other components

- **API client**
- **Model providers**
- **Payment providers**

## Connections

- API client → API routes: sends request
- API routes → Relay entry: dispatches
- Relay entry → Authentication: checks access
- Relay entry → Protocol handlers: dispatches
- Protocol handlers → Channel selection: selects channel
- Protocol handlers → Protocol conversion: converts payload
- Protocol handlers → Provider adapters: uses adapter
- Provider adapters → Model providers: sends request
- Protocol handlers → Usage settlement: reports usage
- Usage settlement → Pricing rules: evaluates pricing
- Usage settlement → Usage records: records usage
- Web console → Channel management: configures channels
- Web console → Model configuration: configures models
- Web console → Users and keys: manages accounts
- Web console → Permissions: manages permissions
- Task API → Plugin runtime: invokes hooks
- Plugin runtime → Task plugins: loads plugins
- Task API → Task records: stores task state
- Payment integrations → Payment providers: integrates payments
