# aoi-cn/jksb-sysu architecture

> Architecture diagram of the GitHub repository aoi-cn/jksb-sysu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aoi-cn/jksb-sysu
- Repository: https://github.com/aoi-cn/jksb-sysu

## Overview

##### Main Components
a. GitHub Actions Workflow:
- Component: .github/workflows/jksb.yml
- Role: Acts as the scheduler; triggers the Python script execution based on a cron schedule. It separates deployment configuration and scheduling from the business logic.
b. Python Automation Scripts:
- Components: jksb_sysu.py and util.py
- Role: jksb_sysu.py contains the core automation logic that logs in to the SYSU authentication system, reuses previous submission data, and submits the health report. util.py likely contains helper functions such as email sending or OCR-related utilities.
c. External Dependencies and Technologies:
- Selenium: Automates browser interactions.
- Firefox: Browser used by Selenium, potentially in headless mode.
- ddddocr: Provides OCR functionality to possibly handle any image captcha challenges.
- geckodriver.exe: The driver used by Selenium to control Firefox (note the presence of a Windows executable).
- Email Service: Sends the report result as an email. Although the exact email API isn’t detailed, the README indicates that emails are used for notification purposes.
d. Configuration and Secrets:
- GitHub Secrets: NETID and PASSWORD are stored securely in the repository’s Settings.
- requirements.txt: Lists all the Python package dependencies.
- README.md: Contains usage instructions, scheduling configuration, and workflow details.

##### Relationships and Data Flow
- The GitHub Actions scheduler (jksb.yml) triggers the workflow based on a predefined cron schedule.
- Once triggered, the GitHub runner loads the Python environment and executes the main script (jksb_sysu.py).
- The Python script retrieves sensitive credentials (NETID and PASSWORD) from GitHub Secrets, logs into the Central Identity Authentication Service of SYSU, and submits the health report.
- The script reuses data from the previous submission, ensuring minimal user intervention.
- After submission, the script uses email notification to send the report result. The email sending logic is likely encapsulated in util.py.
- External dependencies (Selenium + Firefox + ddddocr) are utilized within the Python script to navigate the web interface and solve any OCR challenges.

##### Architectural Patterns and Design Principles
- The project follows a separation of concerns: Workflow scheduling is isolated from the application logic (the Python code).
- It uses external configuration (GitHub Secrets) to handle sensitive data.
- The design leverages automation patterns, particularly “cron-job as a service” via GitHub Actions, eliminating the need for dedicated servers.

- GitHub Repository (with file tree elements such as README, .github/workflows, jksb_sysu.py, util.py, requirements.txt)
- GitHub Actions Workflow (Scheduled via cron; initiates automation)
- Python Automation Engine (jksb_sysu.py + util.py)
- Dependencies: Selenium, Firefox, ddddocr, geckodriver.exe
- Uses credentials via GitHub Secrets (NETID, PASSWORD)
- External Systems:
- SYSU Central Identity Authentication Service (for login and report submission)
- Email Service/Notification System (sends report results to user)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GitHub Repository File Tree
    subgraph "GitHub Repository"
        README["README.md"]:::doc
        ActionsFile[".github/workflows/jksb.yml"]:::workflowFile
        MainScript["jksb_sysu.py"]:::script
        UtilScript["util.py"]:::script
        Requirements["requirements.txt"]:::config
    end

    %% Core Automation Components
    GAW["GitHub Actions Workflow (cron trigger)"]:::scheduler
    PAE["Python Automation Engine"]:::engine
    Secrets["GitHub Secrets (NETID, PASSWORD)"]:::secrets

    %% Automation Dependencies
    subgraph "Automation Dependencies"
        Selenium["Selenium/Firefox+ddddocr"]:::dependency
        Geckodriver["geckodriver.exe"]:::dependency
    end

    %% External Systems
    subgraph "External Systems"
        SYSU["SYSU Central Identity Authentication Service"]:::external
        Email["Email Service/Notification"]:::external
    end

    %% Relationships within Repository Files to Components
    ActionsFile -->|"defines"| GAW
    MainScript -->|"part of"| PAE
    UtilScript -->|"part of"| PAE
    Requirements -->|"dependency list"| PAE
    README -->|"documentation"| PAE

    %% Workflow and Data Flow
    GAW -->|"Trigger(cron)"| PAE
    Secrets -->|"Provides_credentials"| PAE
    PAE -->|"Submits_health_report"| SYSU
    PAE -->|"Sends_email_notification"| Email
    PAE -->|"Uses_for_Web_Automation"| Selenium
    Selenium -->|"Uses_driver"| Geckodriver

    %% Click Events
    click ActionsFile "https://github.com/aoi-cn/jksb-sysu/blob/main/.github/workflows/jksb.yml"
    click MainScript "https://github.com/aoi-cn/jksb-sysu/blob/main/jksb_sysu.py"
    click UtilScript "https://github.com/aoi-cn/jksb-sysu/blob/main/util.py"
    click Geckodriver "https://github.com/aoi-cn/jksb-sysu/blob/main/geckodriver.exe"
    click Requirements "https://github.com/aoi-cn/jksb-sysu/blob/main/requirements.txt"
    click README "https://github.com/aoi-cn/jksb-sysu/blob/main/README.md"

    %% Style Classes
    classDef scheduler fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef engine fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef dependency fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef secrets fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef doc fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef workflowFile fill:#E6E6FA,stroke:#000,stroke-width:1px;
    classDef script fill:#F5DEB3,stroke:#000,stroke-width:1px;
    classDef config fill:#FFE4E1,stroke:#000,stroke-width:1px;
```
