# paicni/cfbox architecture

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

- Interactive diagram: https://gitdiagram.com/paicni/cfbox
- Repository: https://github.com/paicni/cfbox

## Overview

CFBox is a single-file Cloudflare Workers/Pages proxy subscription manager. The main workflow is: a user visits the configured path, authenticates with a UUID, configures settings in the panel, and receives a subscription tailored to enabled protocols and client type. The same Worker also provides preferred-IP management, network tests, and status reporting. The source is a 463 KB monolith; the graph separates documented responsibilities, but the excerpts do not reveal all internal call boundaries, so subsystem links follow README-documented behavior.

Main entry points: [`CFBox明文版.js`](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js) (Worker request handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_worker["Worker request handler<br/>[CFBox明文版.js]"]
  node_auth["UUID and path auth<br/>[CFBox明文版.js]"]
  node_kv[("Configuration KV<br/>[CFBox明文版.js]")]
end

subgraph group_subscription["Subscription generation"]
  node_subscription["Subscription output<br/>[CFBox明文版.js]"]
  node_protocols["VLESS Trojan xhttp<br/>[CFBox明文版.js]"]
  node_preferred["Preferred sources<br/>[CFBox明文版.js]"]
  node_clientformat["Client formatting<br/>[CFBox明文版.js]"]
end

subgraph group_panel["Panel and management"]
  node_panel["Configuration panel<br/>[CFBox明文版.js]"]
  node_api["Preferred IP API<br/>[CFBox明文版.js]"]
  node_status["System and ECH status<br/>[CFBox明文版.js]"]
  node_tests["Network tests<br/>[CFBox明文版.js]"]
end

subgraph group_network["Network integrations"]
  node_cloudflare["Cloudflare runtime"]
  node_preferred_services["Preferred IP sources"]
  node_ip_lookup["IP region services"]
  node_speedtest["Google speed test"]
  node_media_tests["Media and AI services"]
end

node_user(("User"))

node_user -->|"sends request"| node_worker
node_worker -->|"checks access"| node_auth
node_auth -->|"admits user"| node_panel
node_auth -->|"admits request"| node_subscription
node_panel -->|"reads and saves"| node_kv
node_worker -->|"loads configuration"| node_kv
node_worker -->|"serves subscription"| node_subscription
node_subscription -->|"generates protocols"| node_protocols
node_subscription -->|"merges sources"| node_preferred
node_subscription -->|"formats by client"| node_clientformat
node_worker -->|"routes API"| node_api
node_api -->|"manages preferred IPs"| node_kv
node_panel -->|"checks status"| node_status
node_panel -->|"starts tests"| node_tests
node_preferred -->|"fetches sources"| node_preferred_services
node_worker -->|"runs on"| node_cloudflare
node_status -->|"detects region"| node_ip_lookup
node_tests -->|"measures speed"| node_speedtest
node_tests -->|"checks access"| node_media_tests

click node_worker "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_auth "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_kv "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_subscription "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_protocols "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_preferred "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_clientformat "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_panel "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_api "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_status "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js"
click node_tests "https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.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_worker,node_auth,node_kv,node_user toneBlue
class node_subscription,node_protocols,node_preferred,node_clientformat toneAmber
class node_panel,node_api,node_status,node_tests toneMint
class node_cloudflare,node_preferred_services,node_ip_lookup,node_speedtest,node_media_tests toneRose
```

## Components

### Request handling

- [Worker request handler](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [UUID and path auth](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [Configuration KV](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`

### Subscription generation

- [Subscription output](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [VLESS Trojan xhttp](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [Preferred sources](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [Client formatting](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`

### Panel and management

- [Configuration panel](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [Preferred IP API](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [System and ECH status](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`
- [Network tests](https://github.com/paicni/cfbox/blob/main/CFBox%E6%98%8E%E6%96%87%E7%89%88.js): `CFBox明文版.js`

### Network integrations

- **Cloudflare runtime**
- **Preferred IP sources**
- **IP region services**
- **Google speed test**
- **Media and AI services**

### Other components

- **User**

## Connections

- User → Worker request handler: sends request (evidence: `README.md`)
- Worker request handler → UUID and path auth: checks access (evidence: `README.md`)
- UUID and path auth → Configuration panel: admits user (evidence: `README.md`)
- UUID and path auth → Subscription output: admits request (evidence: `README.md`)
- Configuration panel → Configuration KV: reads and saves (evidence: `README.md`)
- Worker request handler → Configuration KV: loads configuration (evidence: `README.md`)
- Worker request handler → Subscription output: serves subscription (evidence: `README.md`)
- Subscription output → VLESS Trojan xhttp: generates protocols (evidence: `README.md`)
- Subscription output → Preferred sources: merges sources (evidence: `README.md`)
- Subscription output → Client formatting: formats by client (evidence: `README.md`)
- Worker request handler → Preferred IP API: routes API (evidence: `README.md`)
- Preferred IP API → Configuration KV: manages preferred IPs (evidence: `README.md`)
- Configuration panel → System and ECH status: checks status (evidence: `CFBox明文版.js`)
- Configuration panel → Network tests: starts tests (evidence: `README.md`)
- Preferred sources → Preferred IP sources: fetches sources (evidence: `README.md`)
- Worker request handler → Cloudflare runtime: runs on (evidence: `README.md`)
- System and ECH status → IP region services: detects region (evidence: `README.md`)
- Network tests → Google speed test: measures speed (evidence: `README.md`)
- Network tests → Media and AI services: checks access (evidence: `README.md`)