# ruoqian04/pkuautoelective architecture

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

- Interactive diagram: https://gitdiagram.com/ruoqian04/pkuautoelective
- Repository: https://github.com/ruoqian04/pkuautoelective

## Overview

##### Project type and purpose
- PKUAutoElective is a Python-based CLI automation tool (“open-source tool”) whose purpose is to automate the “补退选” phase of Peking University’s course-selection website.
- It logs into the IAAA login portal, navigates to the elective portal, solves captchas via a trained CNN model, applies user-defined selection rules, submits course-add/drop requests in a loop, and (optionally) exposes a monitoring HTTP interface via Flask.

##### File structure
- Top-level files:
- Docker definitions (Docker/latest.Dockerfile, monitor.Dockerfile) & DOCKER.md
- Config sample (config.sample.ini), requirements.txt, model weights (model/cnn.*.pt)
- Entry point: main.py
- Package directory `autoelective/`:
- cli.py – parses command-line args
- client.py – HTTP clients for IAAA and elective site
- captcha/ – CNN model loader & image processor/recognizer
- parser.py – HTML parsing (lxml)
- loop.py – main selection loop orchestrator
- monitor.py – Flask server exposing runtime stats
- hook.py, rule.py – extensibility points for user-defined rules
- config.py, const.py, environ.py – configuration & constants
- logger.py, utils.py, exceptions.py – support utilities
- Test directory: test/test_cnn.py validates the captcha module
- Deployment/Dev: Docker folder + GitHub workflows

##### README for additional insights
- Core sequence:
1. Read config.ini
2. Login to IAAA (with random User-Agent)
3. Navigate to elective page, fetch captcha image
4. Recognize captcha via CNN model (PyTorch + OpenCV + Pillow)
5. Build and submit POST request to add/drop courses
6. Loop with configurable interval, apply mutex/delay rules
7. Optionally, spawn a Flask monitor on a given port
- Extensibility: custom User-Agent pool, rule definitions, multi-process support

- Rectangles for internal modules
- Annotations: loop interval, thread vs. process, retry logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Layer
    subgraph "Configuration"
        ConfigLoader["Config Loader"]:::config
        Const["Constants"]:::config
        Env["Environment"]:::config
        SampleConfig["config.sample.ini"]:::asset
    end

    %% CLI Layer
    subgraph "CLI"
        CLIEntry["main.py / cli.py"]:::cli
    end

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        Orchestrator["Selection Loop"]:::core
    end

    %% Client Layer
    subgraph "Clients"
        subgraph "Authentication"
            IAAAClient["IAAA Client"]:::client
        end
        subgraph "Elective Domain"
            ElectiveClient["Elective Client"]:::client
        end
    end

    %% Parser Module
    Parser["HTML Parser"]:::parser

    %% Captcha Module
    subgraph "Captcha Module"
        Loader["CNN Loader"]:::captcha
        Processor["Image Processor"]:::captcha
        Recognizer["Recognizer Interface"]:::captcha
        Model["model/cnn.20210311.1.pt"]:::asset
    end

    %% Rule Engine & Hooks
    subgraph "Rule Engine & Hooks"
        Hooks["Hooks"]:::rule
        Rules["Rule Engine"]:::rule
    end

    %% Monitoring (optional)
    subgraph "Monitoring (optional)"
        Monitor["Flask Monitor"]:::monitor
    end

    %% Logging & Utilities
    subgraph "Logging & Utilities"
        Logger["logger.py"]:::support
        Utils["utils.py"]:::support
        Exceptions["exceptions.py"]:::support
    end

    %% Project Assets
    subgraph "Project Assets"
        Req["requirements.txt"]:::asset
        DockerLatest["Docker/latest.Dockerfile"]:::asset
        DOCKERmd["DOCKER.md"]:::asset
    end

    %% External Services
    IAAAPortal["IAAA Portal"]:::external
    ElectivePortal["elective.pku.edu.cn"]:::external

    %% Data Flows
    SampleConfig --> ConfigLoader
    Const --> ConfigLoader
    Env --> ConfigLoader
    ConfigLoader --> Orchestrator

    CLIEntry --> Orchestrator

    Orchestrator --> IAAAClient
    IAAAClient -->|"login"| IAAAPortal
    IAAAClient --> ElectiveClient
    ElectiveClient --> Parser
    Parser --> Processor
    Processor --> Recognizer
    Recognizer --> Orchestrator

    Orchestrator --> Hooks
    Hooks --> Rules
    Rules --> Orchestrator

    ElectiveClient -->|"POST requests"| ElectivePortal

    Orchestrator --> Monitor

    Orchestrator --> Logger
    Orchestrator --> Exceptions
    IAAAClient --> Exceptions
    ElectiveClient --> Exceptions

    %% Click Events
    click ConfigLoader "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/config.py"
    click Const "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/const.py"
    click Env "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/environ.py"
    click SampleConfig "https://github.com/ruoqian04/pkuautoelective/blob/master/config.sample.ini"
    click CLIEntry "https://github.com/ruoqian04/pkuautoelective/blob/master/main.py"
    click CLIEntry "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/cli.py"
    click Orchestrator "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/loop.py"
    click IAAAClient "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/iaaa.py"
    click ElectiveClient "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/client.py"
    click ElectiveClient "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/elective.py"
    click ElectiveClient "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/course.py"
    click Parser "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/parser.py"
    click Loader "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/captcha/cnn.py"
    click Processor "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/captcha/processor.py"
    click Recognizer "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/captcha/recognizer.py"
    click Model "https://github.com/ruoqian04/pkuautoelective/blob/master/model/cnn.20210311.1.pt"
    click Hooks "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/hook.py"
    click Rules "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/rule.py"
    click Monitor "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/monitor.py"
    click Monitor "https://github.com/ruoqian04/pkuautoelective/blob/master/Docker/monitor.Dockerfile"
    click Logger "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/logger.py"
    click Utils "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/utils.py"
    click Exceptions "https://github.com/ruoqian04/pkuautoelective/blob/master/autoelective/exceptions.py"
    click Req "https://github.com/ruoqian04/pkuautoelective/blob/master/requirements.txt"
    click DockerLatest "https://github.com/ruoqian04/pkuautoelective/blob/master/Docker/latest.Dockerfile"
    click DOCKERmd "https://github.com/ruoqian04/pkuautoelective/blob/master/DOCKER.md"

    %% Styles
    classDef config fill:#f9f,stroke:#333,stroke-width:1px
    classDef cli fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px
    classDef client fill:#ffb,stroke:#333,stroke-width:1px
    classDef parser fill:#fbf,stroke:#333,stroke-width:1px
    classDef captcha fill:#fbb,stroke:#333,stroke-width:1px
    classDef rule fill:#ff9,stroke:#333,stroke-width:1px
    classDef monitor fill:#9ff,stroke:#333,stroke-width:1px
    classDef support fill:#ddd,stroke:#333,stroke-width:1px
    classDef asset fill:#afa,stroke:#333,stroke-width:1px
    classDef external fill:#fff,stroke-dasharray: 2 2,stroke:#999
```
