# pjialin/py12306 architecture

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

- Interactive diagram: https://gitdiagram.com/pjialin/py12306
- Repository: https://github.com/pjialin/py12306

## Overview

py12306 is a multi-account, distributed 12306 ticket-buying assistant. Its core workflow maintains user sessions, queries configured routes and dates for available seats, then submits an order; captcha handling and notifications support that flow. Configuration can change at runtime, while optional Redis coordination synchronizes cluster state and messages. The README also documents a web management interface. Some subsystem links are based on the SOURCE INDEX or README rather than complete excerpts; uncertain runtime wiring is omitted.

Main entry points: [`py12306/query/job.py`](https://github.com/pjialin/py12306/blob/master/py12306/query/job.py) (Availability search), [`py12306/app.py`](https://github.com/pjialin/py12306/blob/master/py12306/app.py) (Application runtime), [`py12306/cluster/cluster.py`](https://github.com/pjialin/py12306/blob/master/py12306/cluster/cluster.py) (Cluster coordinator), [`py12306/web/handler`](https://github.com/pjialin/py12306/tree/master/py12306/web/handler) (Web handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_app["Application runtime<br/>[app.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_booking["Ticket workflow"]
  node_query["Query coordinator<br/>[query.py]"]
  node_queryjob["Availability search<br/>[job.py]"]
  node_user["User coordinator<br/>[user.py]"]
  node_userjob["Account session<br/>[job.py]"]
  node_captcha["Captcha handling<br/>[auth_code.py]"]
  node_order["Order submission<br/>[order.py]"]
end

subgraph group_shared["Coordination and services"]
  node_request["HTTP session<br/>[request.py]"]
  node_api["12306 API endpoints<br/>[api.py]"]
  node_cluster["Cluster coordinator<br/>[cluster.py]"]
  node_redis[("Redis state<br/>[redis.py]")]
  node_events["Runtime events<br/>[event.py]"]
  node_cdn["CDN discovery<br/>[cdn.py]"]
  node_logs["Logging<br/>[base.py]"]
  node_notify["Notifications<br/>[notification.py]"]
end

subgraph group_management["Management interface"]
  node_web["Web server<br/>[web.py]"]
  node_handlers["Web handlers"]
end

node_operator(("Operator"))
node_browser(("Web user"))
node_rail["12306 service"]
node_notification_services["Notification services"]

node_operator -->|"starts"| node_app
node_app -->|"loads"| node_config
node_query -->|"creates jobs"| node_queryjob
node_queryjob -->|"queries availability"| node_rail
node_queryjob -->|"submits order"| node_order
node_queryjob -->|"gets passengers"| node_user
node_user -->|"creates sessions"| node_userjob
node_userjob -->|"uses captcha"| node_captcha
node_userjob -->|"authenticates"| node_rail
node_order -->|"submits booking"| node_rail
node_queryjob -->|"destroys completed job"| node_events
node_app -->|"tests notifications"| node_notify
node_notify -->|"sends messages"| node_notification_services
node_queryjob -->|"checks CDN"| node_cdn
node_queryjob -->|"requests tickets"| node_request
node_request -->|"sends HTTP"| node_rail
node_cluster -->|"uses Redis"| node_redis
node_cluster -->|"dispatches events"| node_events
node_app -->|"initializes when enabled"| node_cluster
node_app -->|"writes runtime logs"| node_logs
node_web -->|"registers handlers"| node_handlers
node_browser -->|"uses management UI"| node_web
node_handlers -->|"manages queries"| node_query
node_handlers -->|"manages users"| node_user
node_handlers -->|"reads logs"| node_logs
node_config -->|"syncs cluster config"| node_cluster
node_cluster -->|"syncs node messages"| node_logs

click node_app "https://github.com/pjialin/py12306/blob/master/py12306/app.py"
click node_config "https://github.com/pjialin/py12306/blob/master/py12306/config.py"
click node_query "https://github.com/pjialin/py12306/blob/master/py12306/query/query.py"
click node_queryjob "https://github.com/pjialin/py12306/blob/master/py12306/query/job.py"
click node_user "https://github.com/pjialin/py12306/blob/master/py12306/user/user.py"
click node_userjob "https://github.com/pjialin/py12306/blob/master/py12306/user/job.py"
click node_captcha "https://github.com/pjialin/py12306/blob/master/py12306/helpers/auth_code.py"
click node_order "https://github.com/pjialin/py12306/blob/master/py12306/order/order.py"
click node_request "https://github.com/pjialin/py12306/blob/master/py12306/helpers/request.py"
click node_api "https://github.com/pjialin/py12306/blob/master/py12306/helpers/api.py"
click node_cluster "https://github.com/pjialin/py12306/blob/master/py12306/cluster/cluster.py"
click node_redis "https://github.com/pjialin/py12306/blob/master/py12306/cluster/redis.py"
click node_events "https://github.com/pjialin/py12306/blob/master/py12306/helpers/event.py"
click node_cdn "https://github.com/pjialin/py12306/blob/master/py12306/helpers/cdn.py"
click node_logs "https://github.com/pjialin/py12306/blob/master/py12306/log/base.py"
click node_notify "https://github.com/pjialin/py12306/blob/master/py12306/helpers/notification.py"
click node_web "https://github.com/pjialin/py12306/blob/master/py12306/web/web.py"
click node_handlers "https://github.com/pjialin/py12306/tree/master/py12306/web/handler"

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_app,node_config,node_browser toneBlue
class node_query,node_queryjob,node_user,node_userjob,node_captcha,node_order toneAmber
class node_request,node_api,node_cluster,node_redis,node_events,node_cdn,node_logs,node_notify toneMint
class node_web,node_handlers toneRose
class node_operator,node_rail,node_notification_services toneIndigo
```

## Components

### Runtime orchestration

- [Application runtime](https://github.com/pjialin/py12306/blob/master/py12306/app.py): `py12306/app.py`
- [Runtime configuration](https://github.com/pjialin/py12306/blob/master/py12306/config.py): `py12306/config.py`

### Ticket workflow

- [Query coordinator](https://github.com/pjialin/py12306/blob/master/py12306/query/query.py): `py12306/query/query.py`
- [Availability search](https://github.com/pjialin/py12306/blob/master/py12306/query/job.py): `py12306/query/job.py`
- [User coordinator](https://github.com/pjialin/py12306/blob/master/py12306/user/user.py): `py12306/user/user.py`
- [Account session](https://github.com/pjialin/py12306/blob/master/py12306/user/job.py): `py12306/user/job.py`
- [Captcha handling](https://github.com/pjialin/py12306/blob/master/py12306/helpers/auth_code.py): `py12306/helpers/auth_code.py`
- [Order submission](https://github.com/pjialin/py12306/blob/master/py12306/order/order.py): `py12306/order/order.py`

### Coordination and services

- [HTTP session](https://github.com/pjialin/py12306/blob/master/py12306/helpers/request.py): `py12306/helpers/request.py`
- [12306 API endpoints](https://github.com/pjialin/py12306/blob/master/py12306/helpers/api.py): `py12306/helpers/api.py`
- [Cluster coordinator](https://github.com/pjialin/py12306/blob/master/py12306/cluster/cluster.py): `py12306/cluster/cluster.py`
- [Redis state](https://github.com/pjialin/py12306/blob/master/py12306/cluster/redis.py): `py12306/cluster/redis.py`
- [Runtime events](https://github.com/pjialin/py12306/blob/master/py12306/helpers/event.py): `py12306/helpers/event.py`
- [CDN discovery](https://github.com/pjialin/py12306/blob/master/py12306/helpers/cdn.py): `py12306/helpers/cdn.py`
- [Logging](https://github.com/pjialin/py12306/blob/master/py12306/log/base.py): `py12306/log/base.py`
- [Notifications](https://github.com/pjialin/py12306/blob/master/py12306/helpers/notification.py): `py12306/helpers/notification.py`

### Management interface

- [Web server](https://github.com/pjialin/py12306/blob/master/py12306/web/web.py): `py12306/web/web.py`
- [Web handlers](https://github.com/pjialin/py12306/tree/master/py12306/web/handler): `py12306/web/handler`

### Other components

- **Operator**
- **Web user**
- **12306 service**
- **Notification services**

## Connections

- Operator → Application runtime: starts
- Application runtime → Runtime configuration: loads (evidence: `py12306/app.py`)
- Query coordinator → Availability search: creates jobs (evidence: `py12306/query/query.py`)
- Availability search → 12306 service: queries availability (evidence: `py12306/query/job.py`)
- Availability search → Order submission: submits order (evidence: `py12306/query/job.py`)
- Availability search → User coordinator: gets passengers (evidence: `py12306/query/job.py`)
- User coordinator → Account session: creates sessions (evidence: `py12306/user/user.py`)
- Account session → Captcha handling: uses captcha (evidence: `py12306/user/job.py`)
- Account session → 12306 service: authenticates
- Order submission → 12306 service: submits booking
- Availability search → Runtime events: destroys completed job (evidence: `py12306/query/job.py`)
- Application runtime → Notifications: tests notifications (evidence: `py12306/app.py`)
- Notifications → Notification services: sends messages
- Availability search → CDN discovery: checks CDN (evidence: `py12306/query/job.py`)
- Availability search → HTTP session: requests tickets (evidence: `py12306/query/job.py`)
- HTTP session → 12306 service: sends HTTP (evidence: `py12306/helpers/request.py`)
- Cluster coordinator → Redis state: uses Redis (evidence: `py12306/cluster/cluster.py`)
- Cluster coordinator → Runtime events: dispatches events (evidence: `py12306/cluster/cluster.py`)
- Application runtime → Cluster coordinator: initializes when enabled (evidence: `py12306/app.py`)
- Application runtime → Logging: writes runtime logs (evidence: `py12306/app.py`)
- Web server → Web handlers: registers handlers (evidence: `py12306/web/web.py`)
- Web user → Web server: uses management UI (evidence: `README.md`)
- Web handlers → Query coordinator: manages queries (evidence: `py12306/web/handler/query.py`)
- Web handlers → User coordinator: manages users (evidence: `py12306/web/handler/user.py`)
- Web handlers → Logging: reads logs (evidence: `py12306/web/handler/log.py`)
- Runtime configuration → Cluster coordinator: syncs cluster config (evidence: `README.md`)
- Cluster coordinator → Logging: syncs node messages (evidence: `py12306/log/base.py`)
