# qqlishili/zcode2api architecture

> Architecture diagram of the GitHub repository qqlishili/zcode2api, 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/qqlishili/zcode2api
- Repository: https://github.com/qqlishili/zcode2api

## Overview

zcode2api is a self-hosted account-management console and dual-protocol AI gateway. Client requests enter the gateway, are authenticated and translated as needed, then routed through the account pool to an upstream provider; responses and request activity return through that gateway. Separate operational workflows cover account onboarding, OAuth, device/install identity, quota monitoring, and time-limited plan claims. The graph follows README capabilities and sampled routes/lifecycle wiring; several unsampled subsystems use their documented paths, with uncertain internal call links omitted.

Main entry points: [`app/routes/gateway.py`](https://github.com/qqlishili/zcode2api/blob/main/app/routes/gateway.py) (Gateway routes), [`app/routes/admin_api.py`](https://github.com/qqlishili/zcode2api/blob/main/app/routes/admin_api.py) (Admin API), [`app/main.py`](https://github.com/qqlishili/zcode2api/blob/main/app/main.py) (Application lifecycle), [`app/store.py`](https://github.com/qqlishili/zcode2api/blob/main/app/store.py) (Account store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API gateway"]
  node_gateway_routes["Gateway routes<br/>[gateway.py]"]
  node_auth["Gateway auth<br/>[auth_admin.py]"]
  node_compat["OpenAI translation<br/>[openai_compat.py]"]
  node_body["Header cleaning<br/>[body_transform.py]"]
  node_agent["Upstream client<br/>[agent.py]"]
end

subgraph group_accounts["Account operations"]
  node_store[("Account store<br/>[store.py]")]
  node_models["Account state<br/>[models.py]"]
  node_fingerprint["Device fingerprints<br/>[fingerprint.py]"]
  node_install["Install sequence<br/>[install.py]"]
  node_oauth["OAuth login<br/>[oauth.py]"]
  node_claim["Plan claims<br/>[claim.py]"]
  node_quota["Quota monitor<br/>[quota.py]"]
end

subgraph group_console["Admin console"]
  node_admin["Admin API<br/>[admin_api.py]"]
  node_pages["Admin pages<br/>[pages.py]"]
  node_admin_ui["Admin interface<br/>[accounts.html]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_runtime["Runtime services"]
  node_captcha["Captcha manager<br/>[captcha.py]"]
  node_solver["Captcha solver<br/>[solver.js]"]
  node_sentinel["Activity sentinel<br/>[sentinel.py]"]
  node_reqlog[("Request monitoring<br/>[reqlog.py]")]
  node_app["Application lifecycle<br/>[main.py]"]
end

node_clients(("API clients"))
node_providers(("AI providers"))
node_aliyun(("Aliyun captcha"))

node_clients -->|"submit requests"| node_gateway_routes
node_gateway_routes -->|"checks access"| node_auth
node_gateway_routes -->|"translates OpenAI"| node_compat
node_gateway_routes -->|"cleans headers"| node_body
node_gateway_routes -->|"selects accounts"| node_store
node_gateway_routes -->|"forwards requests"| node_agent
node_agent -->|"calls upstream"| node_providers
node_gateway_routes -->|"gets verification"| node_captcha
node_gateway_routes -->|"records activity"| node_reqlog
node_store -->|"loads state"| node_models
node_cli -->|"starts login"| node_oauth
node_oauth -->|"authorizes"| node_providers
node_cli -->|"adds accounts"| node_store
node_admin_ui -->|"loads pages"| node_pages
node_admin_ui -->|"calls admin APIs"| node_admin
node_admin -->|"requires credentials"| node_auth
node_admin -->|"manages accounts"| node_store
node_admin -->|"refreshes quotas"| node_quota
node_admin -->|"requests claims"| node_claim
node_claim -->|"claims plans"| node_providers
node_quota -->|"fetches quotas"| node_providers
node_captcha -->|"invokes process"| node_solver
node_solver -->|"solves challenge"| node_aliyun
node_app -->|"starts monitor"| node_quota
node_app -->|"starts manager"| node_captcha
node_app -->|"starts sentinel"| node_sentinel
node_app -->|"runs startup sequence"| node_install
node_app -->|"backfills account data"| node_store
node_admin -->|"rotates profiles"| node_fingerprint
node_install -->|"reports activation"| node_providers

click node_gateway_routes "https://github.com/qqlishili/zcode2api/blob/main/app/routes/gateway.py"
click node_auth "https://github.com/qqlishili/zcode2api/blob/main/app/auth_admin.py"
click node_compat "https://github.com/qqlishili/zcode2api/blob/main/app/openai_compat.py"
click node_body "https://github.com/qqlishili/zcode2api/blob/main/app/body_transform.py"
click node_agent "https://github.com/qqlishili/zcode2api/blob/main/app/agent.py"
click node_store "https://github.com/qqlishili/zcode2api/blob/main/app/store.py"
click node_models "https://github.com/qqlishili/zcode2api/blob/main/app/models.py"
click node_fingerprint "https://github.com/qqlishili/zcode2api/blob/main/app/fingerprint.py"
click node_install "https://github.com/qqlishili/zcode2api/blob/main/app/install.py"
click node_oauth "https://github.com/qqlishili/zcode2api/blob/main/app/oauth.py"
click node_claim "https://github.com/qqlishili/zcode2api/blob/main/app/claim.py"
click node_quota "https://github.com/qqlishili/zcode2api/blob/main/app/quota.py"
click node_captcha "https://github.com/qqlishili/zcode2api/blob/main/app/captcha.py"
click node_solver "https://github.com/qqlishili/zcode2api/blob/main/captcha_node/solver.js"
click node_sentinel "https://github.com/qqlishili/zcode2api/blob/main/app/sentinel.py"
click node_reqlog "https://github.com/qqlishili/zcode2api/blob/main/app/reqlog.py"
click node_app "https://github.com/qqlishili/zcode2api/blob/main/app/main.py"
click node_admin "https://github.com/qqlishili/zcode2api/blob/main/app/routes/admin_api.py"
click node_pages "https://github.com/qqlishili/zcode2api/blob/main/app/routes/pages.py"
click node_admin_ui "https://github.com/qqlishili/zcode2api/blob/main/frontend/admin/accounts.html"
click node_cli "https://github.com/qqlishili/zcode2api/blob/main/cli.py"

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_routes,node_auth,node_compat,node_body,node_agent,node_clients toneBlue
class node_store,node_models,node_fingerprint,node_install,node_oauth,node_claim,node_quota toneAmber
class node_admin,node_pages,node_admin_ui,node_cli toneMint
class node_captcha,node_solver,node_sentinel,node_reqlog,node_app toneRose
class node_providers,node_aliyun toneIndigo
```

## Components

### API gateway

- [Gateway routes](https://github.com/qqlishili/zcode2api/blob/main/app/routes/gateway.py): `app/routes/gateway.py`
- [Gateway auth](https://github.com/qqlishili/zcode2api/blob/main/app/auth_admin.py): `app/auth_admin.py`
- [OpenAI translation](https://github.com/qqlishili/zcode2api/blob/main/app/openai_compat.py): `app/openai_compat.py`
- [Header cleaning](https://github.com/qqlishili/zcode2api/blob/main/app/body_transform.py): `app/body_transform.py`
- [Upstream client](https://github.com/qqlishili/zcode2api/blob/main/app/agent.py): `app/agent.py`

### Account operations

- [Account store](https://github.com/qqlishili/zcode2api/blob/main/app/store.py): `app/store.py`
- [Account state](https://github.com/qqlishili/zcode2api/blob/main/app/models.py): `app/models.py`
- [Device fingerprints](https://github.com/qqlishili/zcode2api/blob/main/app/fingerprint.py): `app/fingerprint.py`
- [Install sequence](https://github.com/qqlishili/zcode2api/blob/main/app/install.py): `app/install.py`
- [OAuth login](https://github.com/qqlishili/zcode2api/blob/main/app/oauth.py): `app/oauth.py`
- [Plan claims](https://github.com/qqlishili/zcode2api/blob/main/app/claim.py): `app/claim.py`
- [Quota monitor](https://github.com/qqlishili/zcode2api/blob/main/app/quota.py): `app/quota.py`

### Admin console

- [Admin API](https://github.com/qqlishili/zcode2api/blob/main/app/routes/admin_api.py): `app/routes/admin_api.py`
- [Admin pages](https://github.com/qqlishili/zcode2api/blob/main/app/routes/pages.py): `app/routes/pages.py`
- [Admin interface](https://github.com/qqlishili/zcode2api/blob/main/frontend/admin/accounts.html): `frontend/admin/accounts.html`
- [CLI](https://github.com/qqlishili/zcode2api/blob/main/cli.py): `cli.py`

### Runtime services

- [Captcha manager](https://github.com/qqlishili/zcode2api/blob/main/app/captcha.py): `app/captcha.py`
- [Captcha solver](https://github.com/qqlishili/zcode2api/blob/main/captcha_node/solver.js): `captcha_node/solver.js`
- [Activity sentinel](https://github.com/qqlishili/zcode2api/blob/main/app/sentinel.py): `app/sentinel.py`
- [Request monitoring](https://github.com/qqlishili/zcode2api/blob/main/app/reqlog.py): `app/reqlog.py`
- [Application lifecycle](https://github.com/qqlishili/zcode2api/blob/main/app/main.py): `app/main.py`

### Other components

- **API clients**
- **AI providers**
- **Aliyun captcha**

## Connections

- API clients → Gateway routes: submit requests
- Gateway routes → Gateway auth: checks access
- Gateway routes → OpenAI translation: translates OpenAI
- Gateway routes → Header cleaning: cleans headers
- Gateway routes → Account store: selects accounts
- Gateway routes → Upstream client: forwards requests
- Upstream client → AI providers: calls upstream
- Gateway routes → Captcha manager: gets verification
- Gateway routes → Request monitoring: records activity
- Account store → Account state: loads state
- CLI → OAuth login: starts login
- OAuth login → AI providers: authorizes
- CLI → Account store: adds accounts
- Admin interface → Admin pages: loads pages
- Admin interface → Admin API: calls admin APIs
- Admin API → Gateway auth: requires credentials
- Admin API → Account store: manages accounts
- Admin API → Quota monitor: refreshes quotas
- Admin API → Plan claims: requests claims
- Plan claims → AI providers: claims plans
- Quota monitor → AI providers: fetches quotas
- Captcha manager → Captcha solver: invokes process
- Captcha solver → Aliyun captcha: solves challenge
- Application lifecycle → Quota monitor: starts monitor
- Application lifecycle → Captcha manager: starts manager
- Application lifecycle → Activity sentinel: starts sentinel
- Application lifecycle → Install sequence: runs startup sequence
- Application lifecycle → Account store: backfills account data
- Admin API → Device fingerprints: rotates profiles
- Install sequence → AI providers: reports activation