# soxft/busuanzi architecture

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

- Interactive diagram: https://gitdiagram.com/soxft/busuanzi
- Repository: https://github.com/soxft/busuanzi

## Overview

Busuanzi is a self-hosted visitor-statistics service. A website visitor’s browser runs the supplied counter script; the service identifies the visitor, derives site/page keys, updates or reads UV/PV counts in Redis, and returns counts to the client. The API also supports write-only and JSONP modes, while the server serves scripts and a status page. The README documents Pjax compatibility, migration support, and privacy-oriented hashing; source excerpts do not show all client-side or migration details, so those connections are documented at capability level rather than expanded into guessed internals.

Main entry points: [`process/webutil/route.go`](https://github.com/soxft/busuanzi/blob/main/process/webutil/route.go) (HTTP routes), [`main.go`](https://github.com/soxft/busuanzi/blob/main/main.go) (Service startup), [`core/count.go`](https://github.com/soxft/busuanzi/blob/main/core/count.go) (UV/PV operations), [`process/redisutil/redisutil.go`](https://github.com/soxft/busuanzi/blob/main/process/redisutil/redisutil.go) (Redis client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and clients"]
  node_client["Counter scripts<br/>[busuanzi.ts]"]
  node_pjax["Pjax clients"]
  node_router["HTTP routes<br/>[route.go]"]
  node_webinit["Web server<br/>[webutil.go]"]
  node_index["Status page<br/>[index.go]"]
  node_ping["Health endpoint<br/>[ping.go]"]
end

subgraph group_api["Request handling"]
  node_identity["Visitor identity<br/>[identity.go]"]
  node_token["Identity tokens<br/>[token.go]"]
  node_api["Count API<br/>[api.go]"]
  node_cors["CORS policy<br/>[cors.go]"]
end

subgraph group_counting["Counting domain"]
  node_counter["UV/PV operations<br/>[count.go]"]
  node_expiry["Key expiration<br/>[expire.go]"]
  node_hash["Privacy hashing<br/>[hash.go]"]
end

subgraph group_infra["Runtime and storage"]
  node_config["Configuration<br/>[config.go]"]
  node_startup["Service startup<br/>[main.go]"]
  node_redisclient["Redis client<br/>[redisutil.go]"]
  node_redis[("Redis data store")]
end

node_visitor(("Website visitor"))
node_migration[("Original Busuanzi data")]

node_visitor -->|"uses"| node_client
node_visitor -.->|"uses"| node_pjax
node_client -.->|"requests counts"| node_router
node_pjax -.->|"requests counts"| node_router
node_webinit -->|"registers routes"| node_router
node_router -->|"dispatches API"| node_api
node_router -->|"applies identity"| node_identity
node_router -->|"serves page"| node_index
node_router -->|"dispatches ping"| node_ping
node_router -->|"serves script"| node_client
node_identity -->|"checks and signs"| node_token
node_identity -->|"derives identity"| node_hash
node_api -->|"counts or reads"| node_counter
node_counter -->|"hashes keys"| node_hash
node_counter -->|"reads and writes"| node_redisclient
node_counter -->|"schedules expiration"| node_expiry
node_expiry -->|"expires keys"| node_redisclient
node_redisclient -->|"connects"| node_redis
node_startup -->|"initializes"| node_config
node_startup -->|"initializes"| node_redisclient
node_startup -->|"initializes"| node_expiry
node_startup -->|"starts"| node_webinit
node_webinit -->|"applies middleware"| node_cors
node_cors -->|"reads version"| node_config
node_migration -.->|"imports counts"| node_redis

click node_client "https://github.com/soxft/busuanzi/blob/main/dist/busuanzi.ts"
click node_pjax "https://github.com/soxft/busuanzi/blob/main/dist/busuanzi.pjax.lite.ts"
click node_router "https://github.com/soxft/busuanzi/blob/main/process/webutil/route.go"
click node_webinit "https://github.com/soxft/busuanzi/blob/main/process/webutil/webutil.go"
click node_index "https://github.com/soxft/busuanzi/blob/main/app/controller/index.go"
click node_ping "https://github.com/soxft/busuanzi/blob/main/app/controller/ping.go"
click node_identity "https://github.com/soxft/busuanzi/blob/main/app/middleware/identity.go"
click node_token "https://github.com/soxft/busuanzi/blob/main/library/jwtutil/token.go"
click node_api "https://github.com/soxft/busuanzi/blob/main/app/controller/api.go"
click node_cors "https://github.com/soxft/busuanzi/blob/main/app/middleware/cors.go"
click node_counter "https://github.com/soxft/busuanzi/blob/main/core/count.go"
click node_expiry "https://github.com/soxft/busuanzi/blob/main/core/expire.go"
click node_hash "https://github.com/soxft/busuanzi/blob/main/library/tool/hash.go"
click node_config "https://github.com/soxft/busuanzi/blob/main/config/config.go"
click node_startup "https://github.com/soxft/busuanzi/blob/main/main.go"
click node_redisclient "https://github.com/soxft/busuanzi/blob/main/process/redisutil/redisutil.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_client,node_pjax,node_router,node_webinit,node_index,node_ping toneBlue
class node_identity,node_token,node_api,node_cors,node_migration toneAmber
class node_counter,node_expiry,node_hash toneMint
class node_config,node_startup,node_redisclient,node_redis toneRose
class node_visitor toneIndigo
```

## Components

### Web and clients

- [Counter scripts](https://github.com/soxft/busuanzi/blob/main/dist/busuanzi.ts): `dist/busuanzi.ts`
- [Pjax clients](https://github.com/soxft/busuanzi/blob/main/dist/busuanzi.pjax.lite.ts): `dist/busuanzi.pjax.lite.ts`
- [HTTP routes](https://github.com/soxft/busuanzi/blob/main/process/webutil/route.go): `process/webutil/route.go`
- [Web server](https://github.com/soxft/busuanzi/blob/main/process/webutil/webutil.go): `process/webutil/webutil.go`
- [Status page](https://github.com/soxft/busuanzi/blob/main/app/controller/index.go): `app/controller/index.go`
- [Health endpoint](https://github.com/soxft/busuanzi/blob/main/app/controller/ping.go): `app/controller/ping.go`

### Request handling

- [Visitor identity](https://github.com/soxft/busuanzi/blob/main/app/middleware/identity.go): `app/middleware/identity.go`
- [Identity tokens](https://github.com/soxft/busuanzi/blob/main/library/jwtutil/token.go): `library/jwtutil/token.go`
- [Count API](https://github.com/soxft/busuanzi/blob/main/app/controller/api.go): `app/controller/api.go`
- [CORS policy](https://github.com/soxft/busuanzi/blob/main/app/middleware/cors.go): `app/middleware/cors.go`

### Counting domain

- [UV/PV operations](https://github.com/soxft/busuanzi/blob/main/core/count.go): `core/count.go`
- [Key expiration](https://github.com/soxft/busuanzi/blob/main/core/expire.go): `core/expire.go`
- [Privacy hashing](https://github.com/soxft/busuanzi/blob/main/library/tool/hash.go): `library/tool/hash.go`

### Runtime and storage

- [Configuration](https://github.com/soxft/busuanzi/blob/main/config/config.go): `config/config.go`
- [Service startup](https://github.com/soxft/busuanzi/blob/main/main.go): `main.go`
- [Redis client](https://github.com/soxft/busuanzi/blob/main/process/redisutil/redisutil.go): `process/redisutil/redisutil.go`
- **Redis data store**

### Other components

- **Website visitor**
- **Original Busuanzi data**

## Connections

- Website visitor → Counter scripts: uses (evidence: `README.md`)
- Website visitor → Pjax clients: uses (evidence: `README.md`)
- Counter scripts → HTTP routes: requests counts
- Pjax clients → HTTP routes: requests counts
- Web server → HTTP routes: registers routes (evidence: `process/webutil/webutil.go`)
- HTTP routes → Count API: dispatches API (evidence: `process/webutil/route.go`)
- HTTP routes → Visitor identity: applies identity (evidence: `process/webutil/route.go`)
- HTTP routes → Status page: serves page (evidence: `process/webutil/route.go`)
- HTTP routes → Health endpoint: dispatches ping (evidence: `process/webutil/route.go`)
- HTTP routes → Counter scripts: serves script (evidence: `process/webutil/route.go`)
- Visitor identity → Identity tokens: checks and signs (evidence: `app/middleware/identity.go`)
- Visitor identity → Privacy hashing: derives identity (evidence: `app/middleware/identity.go`)
- Count API → UV/PV operations: counts or reads (evidence: `app/controller/api.go`)
- UV/PV operations → Privacy hashing: hashes keys (evidence: `core/count.go`)
- UV/PV operations → Redis client: reads and writes (evidence: `core/count.go`)
- UV/PV operations → Key expiration: schedules expiration (evidence: `core/count.go`)
- Key expiration → Redis client: expires keys (evidence: `core/expire.go`)
- Redis client → Redis data store: connects (evidence: `process/redisutil/redisutil.go`)
- Service startup → Configuration: initializes (evidence: `main.go`)
- Service startup → Redis client: initializes (evidence: `main.go`)
- Service startup → Key expiration: initializes (evidence: `main.go`)
- Service startup → Web server: starts (evidence: `main.go`)
- Web server → CORS policy: applies middleware (evidence: `process/webutil/webutil.go`)
- CORS policy → Configuration: reads version (evidence: `app/middleware/cors.go`)
- Original Busuanzi data → Redis data store: imports counts (evidence: `README.md`)
