# chaoticmindv/zai2api architecture

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

## Overview

nodez2ai is a Node.js gateway that exposes OpenAI-compatible chat and model endpoints, forwards requests to Z.AI, and provides a web dashboard. Its main flow is client request → HTTP routes → Z.AI session/request handling → streamed or complete response; chat sessions retain conversation state, and tool calls and reasoning are adapted for the upstream model. A separate token lifecycle collects device tokens, stores them in SQLite, and replenishes the pool in the background. The route excerpt is partial, so some links—especially tool handling and worker startup—are not directly verified.

Main entry points: [`src/index.js`](https://github.com/chaoticmindv/zai2api/blob/main/src/index.js) (HTTP Routes), [`src/zai.js`](https://github.com/chaoticmindv/zai2api/blob/main/src/zai.js) (Z.AI Session), [`src/collector.js`](https://github.com/chaoticmindv/zai2api/blob/main/src/collector.js) (Device Token Collector), [`src/db.js`](https://github.com/chaoticmindv/zai2api/blob/main/src/db.js) (SQLite Token Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Gateway API"]
  node_routes["HTTP Routes<br/>[index.js]"]
  node_dashboard["Web Dashboard<br/>[dashboard.js]"]
end

subgraph group_upstream["Z.AI Integration"]
  node_session["Z.AI Session<br/>[zai.js]"]
  node_conversations["Conversation Store<br/>[zai.js]"]
  node_tool_adapter["Tool and Reasoning Adapter<br/>[tools.js]"]
  node_captcha["Captcha Verification<br/>[captcha.js]"]
end

subgraph group_tokens["Token Lifecycle"]
  node_collector["Device Token Collector<br/>[collector.js]"]
  node_worker["Token Replenishment Worker<br/>[worker.js]"]
  node_token_store[("SQLite Token Store<br/>[db.js]")]
end

subgraph group_state["Configuration and State"]
  node_config["Runtime Configuration<br/>[config.js]"]
end

node_client(("API Client"))
node_zai_service["Z.AI Service"]
node_browser["Playwright Browser"]
node_aliyun["Aliyun Captcha"]

node_client -->|"sends requests"| node_routes
node_routes -->|"returns responses"| node_client
node_routes -->|"forwards chat"| node_session
node_routes -->|"tracks sessions"| node_conversations
node_routes -->|"renders page"| node_dashboard
node_routes -.->|"adapts tool calls"| node_tool_adapter
node_session -->|"sends chat"| node_zai_service
node_session -->|"computes captcha"| node_captcha
node_session -->|"splits reasoning"| node_tool_adapter
node_captcha -->|"verifies captcha"| node_aliyun
node_worker -->|"collects batches"| node_collector
node_worker -->|"checks pool"| node_token_store
node_collector -->|"harvests tokens"| node_browser
node_collector -->|"stores tokens"| node_token_store
node_session -.->|"uses tokens"| node_token_store
node_routes -->|"reads settings"| node_config
node_session -->|"reads settings"| node_config

click node_routes "https://github.com/chaoticmindv/zai2api/blob/main/src/index.js"
click node_dashboard "https://github.com/chaoticmindv/zai2api/blob/main/src/dashboard.js"
click node_session "https://github.com/chaoticmindv/zai2api/blob/main/src/zai.js"
click node_conversations "https://github.com/chaoticmindv/zai2api/blob/main/src/zai.js"
click node_tool_adapter "https://github.com/chaoticmindv/zai2api/blob/main/src/tools.js"
click node_captcha "https://github.com/chaoticmindv/zai2api/blob/main/src/captcha.js"
click node_collector "https://github.com/chaoticmindv/zai2api/blob/main/src/collector.js"
click node_worker "https://github.com/chaoticmindv/zai2api/blob/main/src/worker.js"
click node_token_store "https://github.com/chaoticmindv/zai2api/blob/main/src/db.js"
click node_config "https://github.com/chaoticmindv/zai2api/blob/main/src/config.js"

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_routes,node_dashboard,node_client,node_browser toneBlue
class node_session,node_conversations,node_tool_adapter,node_captcha toneAmber
class node_collector,node_worker,node_token_store toneMint
class node_config toneRose
class node_zai_service,node_aliyun toneIndigo
```

## Components

### Gateway API

- [HTTP Routes](https://github.com/chaoticmindv/zai2api/blob/main/src/index.js): `src/index.js`
- [Web Dashboard](https://github.com/chaoticmindv/zai2api/blob/main/src/dashboard.js): `src/dashboard.js`

### Z.AI Integration

- [Z.AI Session](https://github.com/chaoticmindv/zai2api/blob/main/src/zai.js): `src/zai.js`
- [Conversation Store](https://github.com/chaoticmindv/zai2api/blob/main/src/zai.js): `src/zai.js`
- [Tool and Reasoning Adapter](https://github.com/chaoticmindv/zai2api/blob/main/src/tools.js): `src/tools.js`
- [Captcha Verification](https://github.com/chaoticmindv/zai2api/blob/main/src/captcha.js): `src/captcha.js`

### Token Lifecycle

- [Device Token Collector](https://github.com/chaoticmindv/zai2api/blob/main/src/collector.js): `src/collector.js`
- [Token Replenishment Worker](https://github.com/chaoticmindv/zai2api/blob/main/src/worker.js): `src/worker.js`
- [SQLite Token Store](https://github.com/chaoticmindv/zai2api/blob/main/src/db.js): `src/db.js`

### Configuration and State

- [Runtime Configuration](https://github.com/chaoticmindv/zai2api/blob/main/src/config.js): `src/config.js`

### Other components

- **API Client**
- **Z.AI Service**
- **Playwright Browser**
- **Aliyun Captcha**

## Connections

- API Client → HTTP Routes: sends requests (evidence: `README.md`)
- HTTP Routes → API Client: returns responses (evidence: `README.md`)
- HTTP Routes → Z.AI Session: forwards chat (evidence: `src/index.js`)
- HTTP Routes → Conversation Store: tracks sessions (evidence: `src/index.js`)
- HTTP Routes → Web Dashboard: renders page (evidence: `src/index.js`)
- HTTP Routes → Tool and Reasoning Adapter: adapts tool calls (evidence: `src/index.js`)
- Z.AI Session → Z.AI Service: sends chat (evidence: `README.md`)
- Z.AI Session → Captcha Verification: computes captcha (evidence: `src/zai.js`)
- Z.AI Session → Tool and Reasoning Adapter: splits reasoning (evidence: `src/zai.js`)
- Captcha Verification → Aliyun Captcha: verifies captcha (evidence: `src/captcha.js`)
- Token Replenishment Worker → Device Token Collector: collects batches (evidence: `src/worker.js`)
- Token Replenishment Worker → SQLite Token Store: checks pool (evidence: `src/worker.js`)
- Device Token Collector → Playwright Browser: harvests tokens (evidence: `src/collector.js`)
- Device Token Collector → SQLite Token Store: stores tokens (evidence: `src/collector.js`)
- Z.AI Session → SQLite Token Store: uses tokens
- HTTP Routes → Runtime Configuration: reads settings (evidence: `src/index.js`)
- Z.AI Session → Runtime Configuration: reads settings (evidence: `src/zai.js`)
