# sshwy/pku3b architecture

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

- Interactive diagram: https://gitdiagram.com/sshwy/pku3b
- Repository: https://github.com/sshwy/pku3b

## Overview

1. **What this repo is**
   - `pku3b` is a single Rust CLI binary for PKU’s teaching platform (`course.pku.edu.cn`).
   - The runtime is centered on authenticated HTTP scraping/API calls plus local file handling for downloads, uploads, and video processing.

2. **Top-level control flow**
   - `src/main.rs` is the entrypoint.
   - `src/cli/` defines the command-line surface and dispatches to feature-specific subcommands such as assignment, course table, announcement, video, syllabus/selection, Bark, and TT识图.
   - Each subcommand is a boundary between user interaction and the domain API layer.

3. **Domain API layer**
   - `src/api/` is the main integration layer.
   - It is split into high-level modules like `blackboard`, `portal`, `syllabus`, `thesis_lib`, and `drm_lib`, which represent different teaching-site subsystems.
   - These modules provide task-oriented operations used by the CLI: list/query items, download attachments, submit work, inspect schedules, list announcements, fetch video metadata, and perform course-selection actions.

4. **Low-level protocol boundary**
   - `src/api/low_level/` contains the request/response plumbing for each backend area.
   - This layer likely owns endpoint paths, cookies/session handling, parsing, and any PKU-specific quirks.
   - The higher-level API modules wrap this low-level layer so the CLI can work with domain concepts instead of raw HTTP payloads.

5. **Authentication and configuration**
   - `src/config.rs` and the `init/config` CLI commands manage persisted credentials and settings.
   - The tool expects a one-time login initialization, then reuses stored config for later commands.
   - This is the main state boundary between “local machine” and “remote PKU service”.

6. **Course selection workflow**
   - `src/api/syllabus.rs` and the `syllabus` CLI subcommand implement the “quick course selection” loop.
   - This flow can repeatedly poll/select courses and report success/failure.
   - It optionally triggers Bark notifications, so selection is the most stateful and time-sensitive subsystem in the repo.

7. **Assignment workflow**
   - `src/api/blackboard.rs` plus `src/cli/cmd_assignment.rs` cover assignment listing, attachment download, and submission.
   - File uploads likely use `src/multipart.rs`, which is the local abstraction for constructing multipart form bodies.
   - This subsystem is where local files cross the network boundary into the teaching platform.

8. **Video workflow**
   - `src/cli/cmd_video.rs` and the portal/video API modules handle course replay listings and downloads.
   - The README states that playback download depends on external `ffmpeg`, so the tool downloads source media and then converts/remuxes it into MP4 locally.
   - This creates a two-step flow: remote media retrieval, then local media processing.

9. **Announcements, timetable, and other read-only queries**
   - `src/api/portal.rs`, `src/cli/cmd_announcement.rs`, and `src/cli/cmd_course_table.rs` expose read-only views such as announcements, detail pages, and personal schedules.
   - These paths are primarily fetch-and-render flows with minimal local state.

10. **Captcha / external helper service**
    - `src/ttshitu.rs` and `src/cli/cmd_ttshitu.rs` integrate a TT识图 account for image-captcha solving.
    - This is an optional external dependency used to unblock login/selection-related flows when captcha is required.

11. **Notification integration**
    - `src/cli/cmd_bark.rs` integrates with Bark for push notifications to iPhone/iPad.
    - Bark is not part of the core teaching-site flow; it is an optional side channel used mainly for course-selection status events.

12. **Utility and support modules**
    - `src/qs.rs`, `src/pdf.rs`, `src/utils.rs`, `src/walkdir.rs`, and `src/multipart.rs` provide shared helpers for query-string handling, PDF/file processing, filesystem traversal, and request bodies.
    - These are cross-cutting utilities consumed by multiple subcommands and API modules.

13. **Operational/runtime dependencies**
    - The binary is Rust-based and managed with Cargo; `.github/workflows/` covers formatting and release automation.
    - `build.rs` and `assets/` support packaging and distribution, including a Windows install script and demo artifacts, but they are not part of the core runtime architecture.

14. **Key architectural boundary to draw**
    - On one side: the local CLI, config store, file system, and optional external tools/services (`ffmpeg`, Bark, TT识图).
    - On the other side: PKU teaching platform subsystems accessed through a layered API (`low_level` transport/parsing, then domain modules, then CLI commands).
    - Most features are thin orchestrations around that boundary rather than independent services.

Main entry points: [`src/cli/mod.rs`](https://github.com/sshwy/pku3b/blob/master/src/cli/mod.rs) (CLI), [`src/api/portal.rs`](https://github.com/sshwy/pku3b/blob/master/src/api/portal.rs) (Portal), [`src/api/mod.rs`](https://github.com/sshwy/pku3b/blob/master/src/api/mod.rs) (API), [`src/api/low_level.rs`](https://github.com/sshwy/pku3b/blob/master/src/api/low_level.rs) (Low level)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local runtime"]
  node_main(("Main<br/>entrypoint<br/>[main.rs]"))
  node_cli_mod["CLI<br/>command dispatch<br/>[mod.rs]"]
  node_cmd_assignment["Assignment<br/>subcommand<br/>[cmd_assignment.rs]"]
  node_cmd_course_table["Course table<br/>subcommand"]
  node_cmd_announcement["Announcement<br/>subcommand"]
  node_cmd_syllabus["Selection<br/>subcommand<br/>[cmd_syllabus.rs]"]
  node_cmd_video["Video<br/>subcommand<br/>[cmd_video.rs]"]
  node_cmd_thesis_lib["Thesis lib<br/>subcommand<br/>[cmd_thesis_lib.rs]"]
  node_cmd_bark["Bark<br/>subcommand<br/>[cmd_bark.rs]"]
  node_cmd_ttshitu["TT识图<br/>subcommand<br/>[cmd_ttshitu.rs]"]
  node_config[("Config<br/>persisted settings<br/>[config.rs]")]
  node_multipart["Multipart<br/>upload body<br/>[multipart.rs]"]
  node_pdf["PDF<br/>file processing<br/>[pdf.rs]"]
  node_utils{{"Utils<br/>helpers<br/>[utils.rs]"}}
end

subgraph group_platform["PKU platform"]
  node_api_mod["API<br/>integration layer<br/>[mod.rs]"]
  node_low_level["Low level<br/>transport/parsing<br/>[low_level.rs]"]
  node_blackboard["Blackboard<br/>domain API<br/>[blackboard.rs]"]
  node_portal["Portal<br/>domain API<br/>[portal.rs]"]
  node_syllabus["Syllabus<br/>domain API<br/>[syllabus.rs]"]
  node_thesis_lib["Thesis lib<br/>domain API<br/>[thesis_lib.rs]"]
  node_drm_lib["DRM lib<br/>domain API<br/>[drm_lib.rs]"]
end

subgraph group_external["External services"]
  node_ttshitu(("TT识图<br/>captcha service<br/>[ttshitu.rs]"))
end

node_main -->|"starts"| node_cli_mod
node_main -->|"loads"| node_config
node_cli_mod -->|"routes"| node_cmd_assignment
node_cli_mod -->|"routes"| node_cmd_course_table
node_cli_mod -->|"routes"| node_cmd_announcement
node_cli_mod -->|"routes"| node_cmd_syllabus
node_cli_mod -->|"routes"| node_cmd_video
node_cli_mod -->|"routes"| node_cmd_thesis_lib
node_cli_mod -->|"routes"| node_cmd_bark
node_cli_mod -->|"routes"| node_cmd_ttshitu
node_cmd_assignment -->|"uses"| node_blackboard
node_cmd_assignment -->|"uploads"| node_multipart
node_cmd_course_table -->|"queries"| node_portal
node_cmd_announcement -->|"queries"| node_portal
node_cmd_video -->|"queries"| node_portal
node_cmd_syllabus -->|"drives"| node_syllabus
node_cmd_syllabus -.->|"optional captcha"| node_ttshitu
node_cmd_syllabus -->|"reads state"| node_config
node_cmd_thesis_lib -->|"uses"| node_thesis_lib
node_cmd_bark -->|"stores token"| node_config
node_cmd_ttshitu -->|"uses"| node_ttshitu
node_api_mod -->|"wraps"| node_low_level
node_api_mod -->|"exposes"| node_blackboard
node_api_mod -->|"exposes"| node_portal
node_api_mod -->|"exposes"| node_syllabus
node_api_mod -->|"exposes"| node_thesis_lib
node_api_mod -->|"exposes"| node_drm_lib
node_blackboard -->|"delegates"| node_low_level
node_portal -->|"delegates"| node_low_level
node_syllabus -->|"delegates"| node_low_level
node_thesis_lib -->|"delegates"| node_low_level
node_drm_lib -->|"delegates"| node_low_level
node_portal -.->|"processes"| node_pdf
node_blackboard -.->|"shares helpers"| node_utils
node_portal -.->|"shares helpers"| node_utils

click node_main "https://github.com/sshwy/pku3b/blob/master/src/main.rs"
click node_cli_mod "https://github.com/sshwy/pku3b/blob/master/src/cli/mod.rs"
click node_cmd_assignment "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_assignment.rs"
click node_cmd_course_table "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_course_table.rs"
click node_cmd_announcement "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_announcement.rs"
click node_cmd_syllabus "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_syllabus.rs"
click node_cmd_video "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_video.rs"
click node_cmd_thesis_lib "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_thesis_lib.rs"
click node_cmd_bark "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_bark.rs"
click node_cmd_ttshitu "https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_ttshitu.rs"
click node_config "https://github.com/sshwy/pku3b/blob/master/src/config.rs"
click node_multipart "https://github.com/sshwy/pku3b/blob/master/src/multipart.rs"
click node_pdf "https://github.com/sshwy/pku3b/blob/master/src/pdf.rs"
click node_utils "https://github.com/sshwy/pku3b/blob/master/src/utils.rs"
click node_api_mod "https://github.com/sshwy/pku3b/blob/master/src/api/mod.rs"
click node_low_level "https://github.com/sshwy/pku3b/blob/master/src/api/low_level.rs"
click node_blackboard "https://github.com/sshwy/pku3b/blob/master/src/api/blackboard.rs"
click node_portal "https://github.com/sshwy/pku3b/blob/master/src/api/portal.rs"
click node_syllabus "https://github.com/sshwy/pku3b/blob/master/src/api/syllabus.rs"
click node_thesis_lib "https://github.com/sshwy/pku3b/blob/master/src/api/thesis_lib.rs"
click node_drm_lib "https://github.com/sshwy/pku3b/blob/master/src/api/drm_lib.rs"
click node_ttshitu "https://github.com/sshwy/pku3b/blob/master/src/ttshitu.rs"

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_main,node_cli_mod,node_cmd_assignment,node_cmd_course_table,node_cmd_announcement,node_cmd_syllabus,node_cmd_video,node_cmd_thesis_lib,node_cmd_bark,node_cmd_ttshitu,node_config,node_multipart,node_pdf,node_utils toneBlue
class node_api_mod,node_low_level,node_blackboard,node_portal,node_syllabus,node_thesis_lib,node_drm_lib toneAmber
class node_ttshitu toneMint
```

## Components

### Local runtime

CLI entrypoint, config, file handling, and helper modules on the machine.

- [Main](https://github.com/sshwy/pku3b/blob/master/src/main.rs): entrypoint · CLI process startup and top-level wiring. · `src/main.rs`
- [CLI](https://github.com/sshwy/pku3b/blob/master/src/cli/mod.rs): command dispatch · Command-line surface and subcommand routing. · `src/cli/mod.rs`
- [Assignment](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_assignment.rs): subcommand · Assignment listing, download, and submission flows. · `src/cli/cmd_assignment.rs`
- [Course table](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_course_table.rs): subcommand · Personal timetable and schedule views. · `src/cli/cmd_course_table.rs`
- [Announcement](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_announcement.rs): subcommand · Read-only announcement and detail queries. · `src/cli/cmd_announcement.rs`
- [Selection](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_syllabus.rs): subcommand · Quick course selection workflow and polling loop. · `src/cli/cmd_syllabus.rs`
- [Video](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_video.rs): subcommand · Replay listing and download workflow. · `src/cli/cmd_video.rs`
- [Thesis lib](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_thesis_lib.rs): subcommand · Library/thesis-related queries and actions. · `src/cli/cmd_thesis_lib.rs`
- [Bark](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_bark.rs): subcommand · Push notification integration for selection status. · `src/cli/cmd_bark.rs`
- [TT识图](https://github.com/sshwy/pku3b/blob/master/src/cli/cmd_ttshitu.rs): subcommand · Captcha-solving integration for login and selection flows. · `src/cli/cmd_ttshitu.rs`
- [Config](https://github.com/sshwy/pku3b/blob/master/src/config.rs): persisted settings · Stored credentials and runtime settings. · `src/config.rs`
- [Multipart](https://github.com/sshwy/pku3b/blob/master/src/multipart.rs): upload body · Local multipart request-body construction. · `src/multipart.rs`
- [PDF](https://github.com/sshwy/pku3b/blob/master/src/pdf.rs): file processing · PDF and document handling helpers. · `src/pdf.rs`
- [Utils](https://github.com/sshwy/pku3b/blob/master/src/utils.rs): helpers · Shared utility functions used across features. · `src/utils.rs`

### PKU platform

Layered API integration for the teaching platform backends.

- [API](https://github.com/sshwy/pku3b/blob/master/src/api/mod.rs): integration layer · High-level domain API facade over the PKU platform. · `src/api/mod.rs`
- [Low level](https://github.com/sshwy/pku3b/blob/master/src/api/low_level.rs): transport/parsing · Backend request/response plumbing and site-specific quirks. · `src/api/low_level.rs`
- [Blackboard](https://github.com/sshwy/pku3b/blob/master/src/api/blackboard.rs): domain API · Assignments, attachments, and submissions. · `src/api/blackboard.rs`
- [Portal](https://github.com/sshwy/pku3b/blob/master/src/api/portal.rs): domain API · Announcements, schedules, and replay/course pages. · `src/api/portal.rs`
- [Syllabus](https://github.com/sshwy/pku3b/blob/master/src/api/syllabus.rs): domain API · Course-selection polling and selection actions. · `src/api/syllabus.rs`
- [Thesis lib](https://github.com/sshwy/pku3b/blob/master/src/api/thesis_lib.rs): domain API · Thesis/library-specific backend operations. · `src/api/thesis_lib.rs`
- [DRM lib](https://github.com/sshwy/pku3b/blob/master/src/api/drm_lib.rs): domain API · DRM-protected library or media backend operations. · `src/api/drm_lib.rs`

### External services

Optional third-party helpers used by some workflows.

- [TT识图](https://github.com/sshwy/pku3b/blob/master/src/ttshitu.rs): captcha service · External captcha-solving account/service integration. · `src/ttshitu.rs`

## Connections

- Main → CLI: starts · Entrypoint hands off to CLI dispatch.
- Main → Config: loads · Initializes persisted settings and credentials.
- CLI → Assignment: routes · Dispatches assignment commands.
- CLI → Course table: routes · Dispatches timetable commands.
- CLI → Announcement: routes · Dispatches announcement commands.
- CLI → Selection: routes · Dispatches course-selection commands.
- CLI → Video: routes · Dispatches video commands.
- CLI → Thesis lib: routes · Dispatches thesis/library commands.
- CLI → Bark: routes · Dispatches Bark notification setup/usage.
- CLI → TT识图: routes · Dispatches TT识图 integration commands.
- Assignment → Blackboard: uses · Assignment workflow is driven by the Blackboard API.
- Assignment → Multipart: uploads · Builds multipart bodies for file submission.
- Course table → Portal: queries · Fetches schedule and timetable data.
- Announcement → Portal: queries · Fetches announcements and detail pages.
- Video → Portal: queries · Uses portal/video endpoints for replay listings and downloads.
- Selection → Syllabus: drives · Runs the selection loop against syllabus APIs.
- Selection → TT识图: optional captcha · Can invoke captcha solving when needed.
- Selection → Config: reads state · Uses stored credentials and selection settings.
- Thesis lib → Thesis lib: uses · Delegates library/thesis operations to API.
- Bark → Config: stores token · Persists Bark endpoint or token settings.
- TT识图 → TT识图: uses · Wraps the external captcha service.
- API → Low level: wraps · High-level APIs are built on the low-level transport layer.
- API → Blackboard: exposes · Re-exports or organizes Blackboard capabilities.
- API → Portal: exposes · Re-exports or organizes portal capabilities.
- API → Syllabus: exposes · Re-exports or organizes selection capabilities.
- API → Thesis lib: exposes · Re-exports or organizes thesis/library capabilities.
- API → DRM lib: exposes · Re-exports or organizes DRM/library capabilities.
- Blackboard → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Portal → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Syllabus → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Thesis lib → Low level: delegates · Uses shared request/session plumbing for backend calls.
- DRM lib → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Portal → PDF: processes · Video/document workflows may produce or transform local files.
- Blackboard → Utils: shares helpers · Common parsing and filesystem helpers are reused here.
- Portal → Utils: shares helpers · Common parsing and filesystem helpers are reused here.
