# qxsazz/model-gate-sub2api architecture

> Architecture diagram of the GitHub repository qxsazz/model-gate-sub2api, 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/qxsazz/model-gate-sub2api
- Repository: https://github.com/qxsazz/model-gate-sub2api

## Overview

Sub2API is an AI API gateway that distributes subscription-backed quota across upstream model providers. The principal workflow is a client API request entering the gateway, being handled through its OpenAI-compatible request path, and reaching an upstream provider; account, usage, and subscription state support that service. Separate product areas cover user authentication, administrative account and channel management, payments, channel monitoring, web search, and image results/storage. The tree and README establish these capabilities, but sampled excerpts do not expose the full routing or service wiring, so uncertain links are omitted.

Main entry points: [`backend/internal/handler`](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/handler) (Gateway Handlers), [`backend/ent/schema`](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/ent/schema) (Identity Records), [`backend/internal/service/openai_gateway_cc_pipeline.go`](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/service/openai_gateway_cc_pipeline.go) (OpenAI Pipeline), [`backend/internal/service/image_storage.go`](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/service/image_storage.go) (Image Result Uploader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["AI Gateway"]
  node_gateway_handlers["Gateway Handlers"]
  node_gateway_pipeline["OpenAI Pipeline"]
  node_compatibility["API Compatibility"]
  node_upstream{{"Model Providers"}}
end

subgraph group_identity["Accounts & Access"]
  node_auth_handler["Authentication<br/>[auth_handler.go]"]
  node_oauth_handler["OpenAI OAuth Admin"]
  node_identity_store[("Identity Records")]
end

subgraph group_operations["Administration"]
  node_admin_handlers["Admin APIs"]
  node_monitoring["Channel Monitoring"]
  node_monitor_templates["Monitor Templates"]
  node_business_store[("Platform Records")]
end

subgraph group_commerce["Plans &amp; Payments"]
  node_subscription_handler["Subscriptions"]
  node_payment_handler["Payment APIs<br/>[payment_handler.go]"]
  node_payment_providers{{"Payment Providers"}}
end

subgraph group_capabilities["Extended Services"]
  node_websearch["Web Search<br/>[manager.go]"]
  node_image_tasks["Image Tasks"]
  node_image_uploader["Image Result Uploader<br/>[image_storage.go]"]
  node_s3_storage["S3 Image Storage"]
end

node_client(("API Client"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]
node_object_store[("S3-Compatible Store")]

node_client -->|"sends API request"| node_gateway_handlers
node_gateway_handlers -->|"handles requests"| node_gateway_pipeline
node_gateway_pipeline -->|"sends upstream request"| node_upstream
node_gateway_handlers -->|"adapts API formats"| node_compatibility
node_auth_handler -->|"manages identity data"| node_identity_store
node_oauth_handler -->|"creates account records"| node_identity_store
node_admin_handlers -->|"manages platform data"| node_business_store
node_monitor_templates -->|"manages templates"| node_monitoring
node_subscription_handler -->|"manages subscriptions"| node_business_store
node_payment_handler -->|"dispatches payments"| node_payment_providers
node_image_tasks -->|"stores results"| node_image_uploader
node_image_uploader -->|"uploads image bytes"| node_s3_storage
node_s3_storage -->|"writes objects"| node_object_store
node_business_store -->|"persists records"| node_postgres
node_identity_store -->|"persists identity data"| node_postgres
node_websearch -->|"tracks provider quota"| node_redis

click node_gateway_handlers "https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/handler"
click node_gateway_pipeline "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/service/openai_gateway_cc_pipeline.go"
click node_compatibility "https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/pkg/apicompat"
click node_auth_handler "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/auth_handler.go"
click node_oauth_handler "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/admin/openai_oauth_handler.go"
click node_identity_store "https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/ent/schema"
click node_admin_handlers "https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/handler/admin"
click node_monitoring "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/channel_monitor_v2_handler.go"
click node_monitor_templates "https://github.com/qxsazz/model-gate-sub2api/blob/main/frontend/src/components/admin/monitor/MonitorTemplateManagerDialog.vue"
click node_business_store "https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/ent/schema"
click node_subscription_handler "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/subscription_handler.go"
click node_payment_handler "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/payment_handler.go"
click node_payment_providers "https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/payment/provider"
click node_websearch "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/pkg/websearch/manager.go"
click node_image_tasks "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/image_task_handler.go"
click node_image_uploader "https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/service/image_storage.go"
click node_s3_storage "https://github.com/qxsazz/model-gate-sub2api/blob/main/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_handlers,node_gateway_pipeline,node_compatibility,node_upstream,node_client toneBlue
class node_auth_handler,node_oauth_handler,node_identity_store,node_postgres,node_redis,node_object_store toneAmber
class node_admin_handlers,node_monitoring,node_monitor_templates,node_business_store toneMint
class node_subscription_handler,node_payment_handler,node_payment_providers toneRose
class node_websearch,node_image_tasks,node_image_uploader,node_s3_storage toneIndigo
```

## Components

### AI Gateway

- [Gateway Handlers](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/handler): `backend/internal/handler`
- [OpenAI Pipeline](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/service/openai_gateway_cc_pipeline.go): `backend/internal/service/openai_gateway_cc_pipeline.go`
- [API Compatibility](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/pkg/apicompat): `backend/internal/pkg/apicompat`
- **Model Providers**

### Accounts & Access

- [Authentication](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/auth_handler.go): `backend/internal/handler/auth_handler.go`
- [OpenAI OAuth Admin](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/admin/openai_oauth_handler.go): `backend/internal/handler/admin/openai_oauth_handler.go`
- [Identity Records](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/ent/schema): `backend/ent/schema`

### Administration

- [Admin APIs](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/handler/admin): `backend/internal/handler/admin`
- [Channel Monitoring](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/channel_monitor_v2_handler.go): `backend/internal/handler/channel_monitor_v2_handler.go`
- [Monitor Templates](https://github.com/qxsazz/model-gate-sub2api/blob/main/frontend/src/components/admin/monitor/MonitorTemplateManagerDialog.vue): `frontend/src/components/admin/monitor/MonitorTemplateManagerDialog.vue`
- [Platform Records](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/ent/schema): `backend/ent/schema`

### Plans & Payments

- [Subscriptions](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/subscription_handler.go): `backend/internal/handler/subscription_handler.go`
- [Payment APIs](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/payment_handler.go): `backend/internal/handler/payment_handler.go`
- [Payment Providers](https://github.com/qxsazz/model-gate-sub2api/tree/main/backend/internal/payment/provider): `backend/internal/payment/provider`

### Extended Services

- [Web Search](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/pkg/websearch/manager.go): `backend/internal/pkg/websearch/manager.go`
- [Image Tasks](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/handler/image_task_handler.go): `backend/internal/handler/image_task_handler.go`
- [Image Result Uploader](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/service/image_storage.go): `backend/internal/service/image_storage.go`
- [S3 Image Storage](https://github.com/qxsazz/model-gate-sub2api/blob/main/backend/internal/repository/image_storage_s3.go): `backend/internal/repository/image_storage_s3.go`

### Other components

- **API Client**
- **PostgreSQL**
- **Redis**
- **S3-Compatible Store**

## Connections

- API Client → Gateway Handlers: sends API request
- Gateway Handlers → OpenAI Pipeline: handles requests
- OpenAI Pipeline → Model Providers: sends upstream request
- Gateway Handlers → API Compatibility: adapts API formats
- Authentication → Identity Records: manages identity data
- OpenAI OAuth Admin → Identity Records: creates account records
- Admin APIs → Platform Records: manages platform data
- Monitor Templates → Channel Monitoring: manages templates
- Subscriptions → Platform Records: manages subscriptions
- Payment APIs → Payment Providers: dispatches payments
- Image Tasks → Image Result Uploader: stores results
- Image Result Uploader → S3 Image Storage: uploads image bytes
- S3 Image Storage → S3-Compatible Store: writes objects
- Platform Records → PostgreSQL: persists records
- Identity Records → PostgreSQL: persists identity data
- Web Search → Redis: tracks provider quota