# testersunshine/12306 architecture

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

- Interactive diagram: https://gitdiagram.com/testersunshine/12306
- Repository: https://github.com/testersunshine/12306

## Overview

12306 购票小助手 automates ticket search and booking. The principal workflow is configured launch, login and passenger loading, repeated availability checks, order submission, queue polling, then success notification; it also supports waitlist booking and automated CAPTCHA recognition. The architecture separates orchestration, railway-interface stages, networking, and notifications. Relationships are based on the README and SOURCE INDEX references; unsampled modules are represented only where documented, and external railway-service interaction is shown as unverified.

Main entry points: [`init/select_ticket_info.py`](https://github.com/testersunshine/12306/blob/master/init/select_ticket_info.py) (Booking coordinator), [`myUrllib/httpUtils.py`](https://github.com/testersunshine/12306/blob/master/myUrllib/httpUtils.py) (HTTP client), [`run.py`](https://github.com/testersunshine/12306/blob/master/run.py) (Command runner), [`inter/QueryOrderWaitTime.py`](https://github.com/testersunshine/12306/blob/master/inter/QueryOrderWaitTime.py) (Order wait polling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Booking orchestration"]
  node_runner["Command runner<br/>[run.py]"]
  node_booking["Booking coordinator"]
end

subgraph group_railway["Railway workflows"]
  node_login["Account login<br/>[login.py]"]
  node_cookie["Cookie acquisition<br/>[getCookie.py]"]
  node_availability["Ticket search<br/>[Query.py]"]
  node_passengers["Passenger lookup"]
  node_captcha["CAPTCHA retrieval<br/>[GetRandCode.py]"]
  node_facecheck["Waitlist eligibility<br/>[ChechFace.py]"]
  node_submit["Order submission"]
  node_fastsubmit["Fast submission"]
  node_queuecount["Queue status<br/>[GetQueueCount.py]"]
  node_confirm["Queue confirmation"]
  node_waittime["Order wait polling"]
end

subgraph group_network["Networking and verification"]
  node_recognition["Local recognition<br/>[localVerifyCode.py]"]
  node_http["HTTP client<br/>[httpUtils.py]"]
  node_proxy["Proxy selection<br/>[agency_tools.py]"]
  node_cdn["CDN filtering<br/>[cdn_utils.py]"]
end

subgraph group_support["Configuration and notifications"]
  node_endpoints["Endpoint definitions<br/>[urlConf.py]"]
  node_settings["Ticket settings<br/>[TickerConfig.py]"]
  node_email["Email notification<br/>[emailConf.py]"]
  node_serverchan["ServerChan notification<br/>[serverchanConf.py]"]
end

node_user(("Ticket seeker"))
node_railwayservice{{"12306 service"}}

node_user -->|"starts"| node_runner
node_runner -->|"runs"| node_booking
node_runner -->|"filters CDN"| node_cdn
node_booking -->|"logs in"| node_login
node_booking -->|"gets cookies"| node_cookie
node_booking -->|"loads passengers"| node_passengers
node_booking -->|"queries tickets"| node_availability
node_booking -->|"checks waitlist"| node_facecheck
node_booking -->|"submits order"| node_submit
node_availability -->|"sends requests"| node_http
node_captcha -->|"uses recognition"| node_recognition
node_captcha -->|"fetches image"| node_http
node_submit -.->|"delegates"| node_fastsubmit
node_fastsubmit -->|"gets queue count"| node_queuecount
node_queuecount -->|"confirms queue"| node_confirm
node_confirm -->|"polls order"| node_waittime
node_waittime -->|"sends success"| node_email
node_waittime -->|"sends success"| node_serverchan
node_http -->|"selects proxy"| node_proxy
node_cdn -->|"tests CDN"| node_http
node_booking -->|"reads settings"| node_settings
node_http -->|"uses endpoints"| node_endpoints
node_http -.->|"requests railway APIs"| node_railwayservice

click node_runner "https://github.com/testersunshine/12306/blob/master/run.py"
click node_booking "https://github.com/testersunshine/12306/blob/master/init/select_ticket_info.py"
click node_login "https://github.com/testersunshine/12306/blob/master/init/login.py"
click node_cookie "https://github.com/testersunshine/12306/blob/master/config/getCookie.py"
click node_availability "https://github.com/testersunshine/12306/blob/master/inter/Query.py"
click node_passengers "https://github.com/testersunshine/12306/blob/master/inter/GetPassengerDTOs.py"
click node_captcha "https://github.com/testersunshine/12306/blob/master/inter/GetRandCode.py"
click node_recognition "https://github.com/testersunshine/12306/blob/master/verify/localVerifyCode.py"
click node_facecheck "https://github.com/testersunshine/12306/blob/master/inter/ChechFace.py"
click node_submit "https://github.com/testersunshine/12306/blob/master/inter/SubmitOrderRequest.py"
click node_fastsubmit "https://github.com/testersunshine/12306/blob/master/inter/AutoSubmitOrderRequest.py"
click node_queuecount "https://github.com/testersunshine/12306/blob/master/inter/GetQueueCount.py"
click node_confirm "https://github.com/testersunshine/12306/blob/master/inter/ConfirmSingleForQueue.py"
click node_waittime "https://github.com/testersunshine/12306/blob/master/inter/QueryOrderWaitTime.py"
click node_http "https://github.com/testersunshine/12306/blob/master/myUrllib/httpUtils.py"
click node_proxy "https://github.com/testersunshine/12306/blob/master/agency/agency_tools.py"
click node_cdn "https://github.com/testersunshine/12306/blob/master/agency/cdn_utils.py"
click node_endpoints "https://github.com/testersunshine/12306/blob/master/config/urlConf.py"
click node_settings "https://github.com/testersunshine/12306/blob/master/TickerConfig.py"
click node_email "https://github.com/testersunshine/12306/blob/master/config/emailConf.py"
click node_serverchan "https://github.com/testersunshine/12306/blob/master/config/serverchanConf.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_runner,node_booking toneBlue
class node_login,node_cookie,node_availability,node_passengers,node_captcha,node_facecheck,node_submit,node_fastsubmit,node_queuecount,node_confirm,node_waittime toneAmber
class node_recognition,node_http,node_proxy,node_cdn toneMint
class node_endpoints,node_settings,node_email,node_serverchan toneRose
class node_user,node_railwayservice toneIndigo
```

## Components

### Booking orchestration

- [Command runner](https://github.com/testersunshine/12306/blob/master/run.py): `run.py`
- [Booking coordinator](https://github.com/testersunshine/12306/blob/master/init/select_ticket_info.py): `init/select_ticket_info.py`

### Railway workflows

- [Account login](https://github.com/testersunshine/12306/blob/master/init/login.py): `init/login.py`
- [Cookie acquisition](https://github.com/testersunshine/12306/blob/master/config/getCookie.py): `config/getCookie.py`
- [Ticket search](https://github.com/testersunshine/12306/blob/master/inter/Query.py): `inter/Query.py`
- [Passenger lookup](https://github.com/testersunshine/12306/blob/master/inter/GetPassengerDTOs.py): `inter/GetPassengerDTOs.py`
- [CAPTCHA retrieval](https://github.com/testersunshine/12306/blob/master/inter/GetRandCode.py): `inter/GetRandCode.py`
- [Waitlist eligibility](https://github.com/testersunshine/12306/blob/master/inter/ChechFace.py): `inter/ChechFace.py`
- [Order submission](https://github.com/testersunshine/12306/blob/master/inter/SubmitOrderRequest.py): `inter/SubmitOrderRequest.py`
- [Fast submission](https://github.com/testersunshine/12306/blob/master/inter/AutoSubmitOrderRequest.py): `inter/AutoSubmitOrderRequest.py`
- [Queue status](https://github.com/testersunshine/12306/blob/master/inter/GetQueueCount.py): `inter/GetQueueCount.py`
- [Queue confirmation](https://github.com/testersunshine/12306/blob/master/inter/ConfirmSingleForQueue.py): `inter/ConfirmSingleForQueue.py`
- [Order wait polling](https://github.com/testersunshine/12306/blob/master/inter/QueryOrderWaitTime.py): `inter/QueryOrderWaitTime.py`

### Networking and verification

- [Local recognition](https://github.com/testersunshine/12306/blob/master/verify/localVerifyCode.py): `verify/localVerifyCode.py`
- [HTTP client](https://github.com/testersunshine/12306/blob/master/myUrllib/httpUtils.py): `myUrllib/httpUtils.py`
- [Proxy selection](https://github.com/testersunshine/12306/blob/master/agency/agency_tools.py): `agency/agency_tools.py`
- [CDN filtering](https://github.com/testersunshine/12306/blob/master/agency/cdn_utils.py): `agency/cdn_utils.py`

### Configuration and notifications

- [Endpoint definitions](https://github.com/testersunshine/12306/blob/master/config/urlConf.py): `config/urlConf.py`
- [Ticket settings](https://github.com/testersunshine/12306/blob/master/TickerConfig.py): `TickerConfig.py`
- [Email notification](https://github.com/testersunshine/12306/blob/master/config/emailConf.py): `config/emailConf.py`
- [ServerChan notification](https://github.com/testersunshine/12306/blob/master/config/serverchanConf.py): `config/serverchanConf.py`

### Other components

- **Ticket seeker**
- **12306 service**

## Connections

- Ticket seeker → Command runner: starts (evidence: `README.md`)
- Command runner → Booking coordinator: runs (evidence: `run.py`)
- Command runner → CDN filtering: filters CDN (evidence: `run.py`)
- Booking coordinator → Account login: logs in (evidence: `init/select_ticket_info.py`)
- Booking coordinator → Cookie acquisition: gets cookies (evidence: `init/select_ticket_info.py`)
- Booking coordinator → Passenger lookup: loads passengers (evidence: `init/select_ticket_info.py`)
- Booking coordinator → Ticket search: queries tickets (evidence: `init/select_ticket_info.py`)
- Booking coordinator → Waitlist eligibility: checks waitlist (evidence: `init/select_ticket_info.py`)
- Booking coordinator → Order submission: submits order (evidence: `init/select_ticket_info.py`)
- Ticket search → HTTP client: sends requests (evidence: `inter/Query.py`)
- CAPTCHA retrieval → Local recognition: uses recognition (evidence: `inter/GetRandCode.py`)
- CAPTCHA retrieval → HTTP client: fetches image (evidence: `inter/GetRandCode.py`)
- Order submission → Fast submission: delegates
- Fast submission → Queue status: gets queue count (evidence: `inter/AutoSubmitOrderRequest.py`)
- Queue status → Queue confirmation: confirms queue (evidence: `inter/GetQueueCount.py`)
- Queue confirmation → Order wait polling: polls order (evidence: `inter/ConfirmSingleForQueue.py`)
- Order wait polling → Email notification: sends success (evidence: `inter/QueryOrderWaitTime.py`)
- Order wait polling → ServerChan notification: sends success (evidence: `inter/QueryOrderWaitTime.py`)
- HTTP client → Proxy selection: selects proxy (evidence: `myUrllib/httpUtils.py`)
- CDN filtering → HTTP client: tests CDN (evidence: `agency/cdn_utils.py`)
- Booking coordinator → Ticket settings: reads settings (evidence: `TickerConfig.py`)
- HTTP client → Endpoint definitions: uses endpoints (evidence: `inter/Query.py`)
- HTTP client → 12306 service: requests railway APIs
