# orbitoo/zai2api architecture

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

- Interactive diagram: https://gitdiagram.com/orbitoo/zai2api
- Repository: https://github.com/orbitoo/zai2api

## Overview

zai2api is an OpenAI-compatible proxy for Z.ai. API clients send chat-completion or Responses requests; the server authenticates and normalizes them, assembles prompts, obtains upstream output, and returns OpenAI-shaped responses, including streaming. A separate admin UI supports account management, security settings, and logs. The account pool routes requests through stored or environment-provided accounts. Edges reflect sampled calls, imports listed in the source index, or README-documented capabilities; unsampled internals are represented only where the README or tree supports them.

Main entry points: [`src/zai2api/server.py`](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/server.py) (HTTP API server), [`src/zai2api/account_pool.py`](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/account_pool.py) (Account routing), [`src/zai2api/auth.py`](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/auth.py) (Authentication), [`src/zai2api/admin_page.py`](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/admin_page.py) (Admin UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Proxy API"]
  node_server["HTTP API server<br/>[server.py]"]
  node_prompt["Prompt assembly<br/>[prompt_assembly.py]"]
end

subgraph group_upstream["Z.ai integration"]
  node_pool["Account routing<br/>[account_pool.py]"]
  node_zai_client["Z.ai client<br/>[zai_client.py]"]
end

subgraph group_admin["Administration"]
  node_admin_page["Admin UI<br/>[admin_page.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_state["Configuration and state"]
  node_settings["Settings<br/>[config.py]"]
  node_db[("SQLite state<br/>[db.py]")]
end

node_api_client(("API client"))
node_zai(("Z.ai service"))
node_admin_browser(("Admin browser"))

node_api_client -->|"sends requests"| node_server
node_server -->|"checks credentials"| node_auth
node_server -->|"assembles prompts"| node_prompt
node_server -->|"routes completions"| node_pool
node_server -->|"records request logs"| node_db
node_server -->|"renders UI"| node_admin_page
node_server -->|"reads settings"| node_settings
node_pool -->|"creates clients"| node_zai_client
node_pool -->|"loads account state"| node_db
node_pool -->|"uses settings"| node_settings
node_zai_client -->|"authenticates and streams"| node_zai
node_auth -->|"reads and writes sessions"| node_db
node_auth -->|"reads credentials config"| node_settings
node_admin_browser -->|"uses interface"| node_admin_page
node_admin_page -->|"calls admin APIs"| node_server

click node_server "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/server.py"
click node_prompt "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/prompt_assembly.py"
click node_pool "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/account_pool.py"
click node_zai_client "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/zai_client.py"
click node_admin_page "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/admin_page.py"
click node_auth "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/auth.py"
click node_settings "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/config.py"
click node_db "https://github.com/orbitoo/zai2api/blob/master/src/zai2api/db.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_server,node_prompt,node_api_client,node_admin_browser toneBlue
class node_pool,node_zai_client toneAmber
class node_admin_page,node_auth toneMint
class node_settings,node_db toneRose
class node_zai toneIndigo
```

## Components

### Proxy API

- [HTTP API server](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/server.py): `src/zai2api/server.py`
- [Prompt assembly](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/prompt_assembly.py): `src/zai2api/prompt_assembly.py`

### Z.ai integration

- [Account routing](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/account_pool.py): `src/zai2api/account_pool.py`
- [Z.ai client](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/zai_client.py): `src/zai2api/zai_client.py`

### Administration

- [Admin UI](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/admin_page.py): `src/zai2api/admin_page.py`
- [Authentication](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/auth.py): `src/zai2api/auth.py`

### Configuration and state

- [Settings](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/config.py): `src/zai2api/config.py`
- [SQLite state](https://github.com/orbitoo/zai2api/blob/master/src/zai2api/db.py): `src/zai2api/db.py`

### Other components

- **API client**
- **Z.ai service**
- **Admin browser**

## Connections

- API client → HTTP API server: sends requests (evidence: `README.md`)
- HTTP API server → Authentication: checks credentials (evidence: `src/zai2api/server.py`)
- HTTP API server → Prompt assembly: assembles prompts (evidence: `src/zai2api/server.py`)
- HTTP API server → Account routing: routes completions (evidence: `src/zai2api/server.py`)
- HTTP API server → SQLite state: records request logs (evidence: `src/zai2api/server.py`)
- HTTP API server → Admin UI: renders UI (evidence: `src/zai2api/server.py`)
- HTTP API server → Settings: reads settings (evidence: `src/zai2api/server.py`)
- Account routing → Z.ai client: creates clients (evidence: `src/zai2api/account_pool.py`)
- Account routing → SQLite state: loads account state (evidence: `src/zai2api/account_pool.py`)
- Account routing → Settings: uses settings (evidence: `src/zai2api/account_pool.py`)
- Z.ai client → Z.ai service: authenticates and streams (evidence: `src/zai2api/zai_client.py`)
- Authentication → SQLite state: reads and writes sessions (evidence: `src/zai2api/auth.py`)
- Authentication → Settings: reads credentials config (evidence: `src/zai2api/auth.py`)
- Admin browser → Admin UI: uses interface (evidence: `src/zai2api/admin_page.py`)
- Admin UI → HTTP API server: calls admin APIs (evidence: `src/zai2api/admin_page.py`)
