# hobr/transition-ticket architecture

> Architecture diagram of the GitHub repository hobr/transition-ticket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hobr/transition-ticket
- Repository: https://github.com/hobr/transition-ticket

## Overview

##### Project type and purpose
- This is a command-line Python tool (“Transition Ticket”) whose goal is to automate the process of fetching Bilibili “back-in-stock” tickets.
- It orchestrates login, polling Bilibili APIs, handling Geetest captchas, and notifying the user via sound alerts.

##### File structure
- Top-level:
- cli.py – entry point
- interface/CLI – command definitions and argument parsing for “product,” “user,” “setting” commands
- util/ (Bilibili, Captcha, Config, Data, Info, Login, Notice, Request, Task) – core business logic modules
- geetest/ – embedded static HTML/JS/CSS to drive the Geetest captcha flow in a headless or browser-driven environment
- assets/alarm.wav – local notification asset
- cli.spec, pyproject.toml, requirements.txt, packaging/config scripts – build and deployment

##### README
- Confirms Python 3.11–3.14, uses PortAudio for audio alerts, runs as a CLI, uses a finite‐state‐machine (FSM) to drive the “run” flow (see assets/fsm.png).
- Describes manual installation, external dependencies (Edge browser for captcha), and build steps via PyInstaller.

##### Main components
a. CLI Layer
- cli.py
- interface/CLI/product.py, user.py, setting.py
b. Core Logic Layer (util packages)
- util/Login (handles authentication, browser-driven or credentials)
- util/Request (wraps HTTP calls to Bilibili endpoints)
- util/Captcha & geetest/ (handles loading and solving Geetest challenges)
- util/Task (polling loop or scheduler implementing the FSM)
- util/Notice (sound alerts via PortAudio using assets/alarm.wav)
- util/Config/Data/Info/Bilibili – support modules for configuration, parsing, and data models
c. External Services & Dependencies
- Bilibili ticket APIs (HTTP endpoints)
- Geetest captcha service (embedded front-end + JS hooks)
- PortAudio/native audio drivers
- PyPI (for pip installs, packaging via PyInstaller)

##### Relationships and data flows
- User invokes cli.py → CLI Layer parses commands → dispatches to Core Logic
- Core Logic uses util/Config to load settings, util/Login to authenticate
- Upon login success, util/Task FSM kicks in, util/Request polls Bilibili endpoints
- If Geetest challenge issued → util/Captcha + geetest/ front-end component handle solving → back to util/Request
- Upon ticket availability or errors → util/Notice emits alarm.wav via PortAudio
- Data (user credentials, settings, last-seen IDs) stored in util/Data or util/Config

##### Architectural patterns and principles
- Layered architecture (Interface → Core Logic → External Services)
- Adapter/Wrapper pattern for HTTP and audio subsystems
- Finite-state-machine for orchestrating the polling and retry logic
- Single process, modular Python packages for separation of concerns

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["CLI Entry Point (cli.py)"]:::cli
        P["Product Command"]:::cli
        U["User Command"]:::cli
        S["Setting Command"]:::cli
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        direction TB
        Login["Authentication Module\n(util/Login)"]:::core
        Request["HTTP Request Wrapper\n(util/Request)"]:::core
        Captcha["Captcha Handler\n(util/Captcha)"]:::core
        subgraph "Embedded Geetest Front-End"
            direction TB
            HTML["index.html"]:::core
            GTJS["gt.js"]:::core
            JQ["jquery.js"]:::core
            CSS["style.css"]:::core
        end
        Task["Task FSM\n[INIT→AUTHENTICATED→POLLING→CHALLENGE→NOTIFY]"]:::fsm
        Notice["Notification (Sound Alerts)\n(util/Notice + alarm.wav)"]:::core
        Config["Configuration Management\n(util/Config)"]:::core
        Data["Data Storage & Models\n(util/Data)"]:::core
        Info["Information Parsers\n(util/Info)"]:::core
        Bili["Bilibili API Adapters\n(util/Bilibili)"]:::core
    end

    %% External Services & Dependencies
    subgraph "External Services & Dependencies"
        direction TB
        API["Bilibili Ticket API"]:::ext
        GeoService["Geetest Captcha Service"]:::ext
        Audio["PortAudio / Audio Driver"]:::ext
        PyPI["PyPI / PyInstaller"]:::ext
    end

    %% Connections
    CLI -->|"invoke"| P
    CLI -->|"invoke"| U
    CLI -->|"invoke"| S
    CLI -->|"dispatch"| Login
    CLI -->|"dispatch"| Request
    CLI -->|"dispatch"| Captcha
    CLI -->|"dispatch"| Task
    CLI -->|"dispatch"| Notice

    Login -->|"uses creds"| Config
    Login -->|"auth flow"| GeoService
    Request -->|"HTTP Request"| API
    Request -->|"Solve if challenge"| Captcha
    Captcha -->|"load challenge"| HTML
    HTML -->|"load scripts"| GTJS
    HTML -->|"load scripts"| JQ
    HTML -->|"load styles"| CSS
    GTJS -->|"hook"| GeoService
    Task -->|"poll loop"| Request
    Task -->|"state change"| Task
    Task -->|"on ticket"| Notice
    Notice -->|"play alarm"| Audio
    Config -->|"read/write"| Data
    Data -->|"provide models"| Bili
    Info -->|"parse responses"| Bili
    Bili -->|"adapter"| Request

    %% External arrows
    Request -->|"HTTP Request"| API
    Captcha -->|"verify"| GeoService
    Notice -->|"audio output"| Audio
    CLI -.->|"build"| PyPI

    %% Click Events
    click CLI "https://github.com/hobr/transition-ticket/blob/dev/cli.py"
    click P "https://github.com/hobr/transition-ticket/blob/dev/interface/CLI/product.py"
    click U "https://github.com/hobr/transition-ticket/blob/dev/interface/CLI/user.py"
    click S "https://github.com/hobr/transition-ticket/blob/dev/interface/CLI/setting.py"
    click Login "https://github.com/hobr/transition-ticket/blob/dev/util/Login/__init__.py"
    click Request "https://github.com/hobr/transition-ticket/blob/dev/util/Request/__init__.py"
    click Captcha "https://github.com/hobr/transition-ticket/blob/dev/util/Captcha/__init__.py"
    click HTML "https://github.com/hobr/transition-ticket/blob/dev/geetest/index.html"
    click GTJS "https://github.com/hobr/transition-ticket/blob/dev/geetest/js/gt.js"
    click JQ "https://github.com/hobr/transition-ticket/blob/dev/geetest/js/jquery.js"
    click CSS "https://github.com/hobr/transition-ticket/blob/dev/geetest/css/style.css"
    click Task "https://github.com/hobr/transition-ticket/blob/dev/util/Task/__init__.py"
    click Notice "https://github.com/hobr/transition-ticket/blob/dev/util/Notice/__init__.py"
    click Config "https://github.com/hobr/transition-ticket/blob/dev/util/Config/__init__.py"
    click Data "https://github.com/hobr/transition-ticket/blob/dev/util/Data/__init__.py"
    click Info "https://github.com/hobr/transition-ticket/blob/dev/util/Info/__init__.py"
    click Bili "https://github.com/hobr/transition-ticket/blob/dev/util/Bilibili/__init__.py"
    click Notice "https://github.com/hobr/transition-ticket/blob/dev/assets/alarm.wav"

    %% Styles
    classDef cli fill:#e0ffe0,stroke:#008000,stroke-width:2px
    classDef core fill:#e0f0ff,stroke:#0050a0,stroke-width:2px
    classDef ext fill:#ffe0b3,stroke:#ff8000,stroke-width:2px
    classDef fsm fill:#cfefff,stroke:#0077be,stroke-width:2px,stroke-dasharray: 5 5
    class CLI,P,U,S cli
    class Login,Request,Captcha,HTML,GTJS,JQ,CSS,Task,Notice,Config,Data,Info,Bili core
    class API,GeoService,Audio,PyPI ext
    class Task fsm
```
