# ranxi2001/sub2api architecture

> Architecture diagram of the GitHub repository ranxi2001/sub2api, 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/ranxi2001/sub2api
- Repository: https://github.com/ranxi2001/sub2api
- Video tour (about a minute): https://gitdiagram.com/ranxi2001/sub2api/video

## Overview

Sub2API is an AI API gateway for distributing managed upstream account capacity. The main workflow is a client API-key request, gateway authentication and account selection, protocol adaptation and upstream forwarding, followed by usage-based billing. The README also documents account and key administration, user authentication, payments, and Mihomo egress management. Some links reflect README-described capabilities because their implementation was not sampled; uncertain internal wiring is omitted.

Main entry points: [`backend/internal/handler/gateway_handler.go`](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/gateway_handler.go) (Gateway handlers), [`backend/internal/handler/openai_gateway_handler.go`](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/openai_gateway_handler.go) (OpenAI gateway), [`backend/internal/payment/provider`](https://github.com/ranxi2001/sub2api/tree/production/backend/internal/payment/provider) (Payment providers), [`backend/internal/handler/payment_handler.go`](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/payment_handler.go) (Payment handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API gateway"]
  node_gateway_handler["Gateway handlers<br/>[gateway_handler.go]"]
  node_openai_gateway["OpenAI gateway"]
  node_cc_pipeline["CC pipeline"]
  node_protocol_adapters["Protocol adapters"]
end

subgraph group_management["Accounts and access"]
  node_account_admin["Account management<br/>[account_handler.go]"]
  node_api_keys["API keys<br/>[api_key_handler.go]"]
  node_auth["User authentication<br/>[auth_handler.go]"]
  node_oauth_admin["OpenAI OAuth"]
end

subgraph group_commerce["Billing and payments"]
  node_payment_handler["Payment handlers<br/>[payment_handler.go]"]
  node_payment_webhook["Payment webhooks"]
  node_payment_providers["Payment providers"]
end

subgraph group_operations["Operations"]
  node_database[("Application database")]
  node_redis[("Redis")]
  node_mihomo["Mihomo egress<br/>[manager.go]"]
  node_websearch["Web search<br/>[manager.go]"]
  node_image_storage["Image storage settings"]
  node_s3_storage["S3 image storage"]
end

node_client(("API client"))
node_upstream_ai["AI providers"]
node_user_actor(("Platform user"))
node_admin_actor(("Administrator"))
node_object_store[("S3-compatible storage")]

node_client -->|"sends API request"| node_gateway_handler
node_gateway_handler -->|"dispatches request"| node_openai_gateway
node_openai_gateway -->|"adapts protocol"| node_protocol_adapters
node_openai_gateway -->|"handles CC requests"| node_cc_pipeline
node_cc_pipeline -->|"forwards request"| node_upstream_ai
node_openai_gateway -->|"forwards request"| node_upstream_ai
node_admin_actor -->|"manages accounts"| node_account_admin
node_admin_actor -->|"manages keys"| node_api_keys
node_user_actor -->|"authenticates"| node_auth
node_admin_actor -->|"manages OAuth"| node_oauth_admin
node_user_actor -->|"initiates payment"| node_payment_handler
node_payment_handler -->|"requests payment"| node_payment_providers
node_payment_providers -->|"returns payment status"| node_payment_handler
node_payment_providers -->|"sends payment event"| node_payment_webhook
node_gateway_handler -->|"reads account data"| node_database
node_gateway_handler -->|"uses cache and limits"| node_redis
node_gateway_handler -.->|"uses configured egress"| node_mihomo
node_websearch -->|"reserves quota"| node_redis
node_admin_actor -->|"configures storage"| node_image_storage
node_image_storage -->|"creates uploader"| node_s3_storage
node_s3_storage -->|"uploads images"| node_object_store

click node_gateway_handler "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/gateway_handler.go"
click node_openai_gateway "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/openai_gateway_handler.go"
click node_cc_pipeline "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/service/openai_gateway_cc_pipeline.go"
click node_protocol_adapters "https://github.com/ranxi2001/sub2api/tree/production/backend/internal/pkg/apicompat"
click node_account_admin "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/admin/account_handler.go"
click node_api_keys "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/api_key_handler.go"
click node_auth "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/auth_handler.go"
click node_oauth_admin "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/admin/openai_oauth_handler.go"
click node_payment_handler "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/payment_handler.go"
click node_payment_webhook "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/payment_webhook_handler.go"
click node_payment_providers "https://github.com/ranxi2001/sub2api/tree/production/backend/internal/payment/provider"
click node_database "https://github.com/ranxi2001/sub2api/tree/production/backend/ent"
click node_mihomo "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/mihomo/manager.go"
click node_websearch "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/pkg/websearch/manager.go"
click node_image_storage "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/service/image_storage_settings.go"
click node_s3_storage "https://github.com/ranxi2001/sub2api/blob/production/backend/internal/repository/image_storage_s3.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_gateway_handler,node_openai_gateway,node_cc_pipeline,node_protocol_adapters,node_client,node_user_actor toneBlue
class node_account_admin,node_api_keys,node_auth,node_oauth_admin,node_object_store toneAmber
class node_payment_handler,node_payment_webhook,node_payment_providers toneMint
class node_database,node_redis,node_mihomo,node_websearch,node_image_storage,node_s3_storage toneRose
class node_upstream_ai,node_admin_actor toneIndigo
```

## Components

### API gateway

- [Gateway handlers](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/gateway_handler.go): `backend/internal/handler/gateway_handler.go`
- [OpenAI gateway](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/openai_gateway_handler.go): `backend/internal/handler/openai_gateway_handler.go`
- [CC pipeline](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/service/openai_gateway_cc_pipeline.go): `backend/internal/service/openai_gateway_cc_pipeline.go`
- [Protocol adapters](https://github.com/ranxi2001/sub2api/tree/production/backend/internal/pkg/apicompat): `backend/internal/pkg/apicompat`

### Accounts and access

- [Account management](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/admin/account_handler.go): `backend/internal/handler/admin/account_handler.go`
- [API keys](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/api_key_handler.go): `backend/internal/handler/api_key_handler.go`
- [User authentication](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/auth_handler.go): `backend/internal/handler/auth_handler.go`
- [OpenAI OAuth](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/admin/openai_oauth_handler.go): `backend/internal/handler/admin/openai_oauth_handler.go`

### Billing and payments

- [Payment handlers](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/payment_handler.go): `backend/internal/handler/payment_handler.go`
- [Payment webhooks](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/handler/payment_webhook_handler.go): `backend/internal/handler/payment_webhook_handler.go`
- [Payment providers](https://github.com/ranxi2001/sub2api/tree/production/backend/internal/payment/provider): `backend/internal/payment/provider`

### Operations

- [Application database](https://github.com/ranxi2001/sub2api/tree/production/backend/ent): `backend/ent`
- **Redis**
- [Mihomo egress](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/mihomo/manager.go): `backend/internal/mihomo/manager.go`
- [Web search](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/pkg/websearch/manager.go): `backend/internal/pkg/websearch/manager.go`
- [Image storage settings](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/service/image_storage_settings.go): `backend/internal/service/image_storage_settings.go`
- [S3 image storage](https://github.com/ranxi2001/sub2api/blob/production/backend/internal/repository/image_storage_s3.go): `backend/internal/repository/image_storage_s3.go`

### Other components

- **API client**
- **AI providers**
- **Platform user**
- **Administrator**
- **S3-compatible storage**

## Connections

- API client → Gateway handlers: sends API request
- Gateway handlers → OpenAI gateway: dispatches request
- OpenAI gateway → Protocol adapters: adapts protocol
- OpenAI gateway → CC pipeline: handles CC requests
- CC pipeline → AI providers: forwards request
- OpenAI gateway → AI providers: forwards request
- Administrator → Account management: manages accounts
- Administrator → API keys: manages keys
- Platform user → User authentication: authenticates
- Administrator → OpenAI OAuth: manages OAuth
- Platform user → Payment handlers: initiates payment
- Payment handlers → Payment providers: requests payment
- Payment providers → Payment handlers: returns payment status
- Payment providers → Payment webhooks: sends payment event
- Gateway handlers → Application database: reads account data
- Gateway handlers → Redis: uses cache and limits
- Gateway handlers → Mihomo egress: uses configured egress
- Web search → Redis: reserves quota
- Administrator → Image storage settings: configures storage
- Image storage settings → S3 image storage: creates uploader
- S3 image storage → S3-compatible storage: uploads images