# alkali210/xmu-rollcall-bot architecture

> Architecture diagram of the GitHub repository alkali210/xmu-rollcall-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alkali210/xmu-rollcall-bot
- Repository: https://github.com/alkali210/xmu-rollcall-bot

## Overview

XMU Rollcall Bot automates Tronclass attendance through either a Python CLI monitor or a browser userscript. The CLI workflow selects an account, polls for pending rollcalls, waits for configured classmate participation, then submits numeric or radar attendance and reports the outcome. The repository also includes a standalone browser schedule-to-ICS exporter. Some wiring is documented but its implementation was not sampled, so uncertain links are omitted.

Main entry points: [`xmu-rollcall-cli/xmu_rollcall/monitor.py`](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/monitor.py) (Rollcall monitor), [`xmu-rollcall-cli/xmu_rollcall/rollcall_handler.py`](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/rollcall_handler.py) (Rollcall handler), [`xmu-rollcall-cli/xmu_rollcall/cli.py`](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/cli.py) (CLI commands), [`scripts/schedule/jw-schedule-export.user.js`](https://github.com/alkali210/xmu-rollcall-bot/blob/main/scripts/schedule/jw-schedule-export.user.js) (Schedule exporter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_monitor["Rollcall monitor<br/>[monitor.py]"]
  node_network["Retry policy<br/>[network.py]"]
  node_tui["Terminal interface<br/>[tui.py]"]
end

subgraph group_attendance["Attendance handling"]
  node_handler["Rollcall handler"]
  node_verify["Attendance submission<br/>[verify.py]"]
end

subgraph group_state["Account state"]
  node_config["Account configuration<br/>[config.py]"]
  node_secure[("Encrypted account store<br/>[secure_store.py]")]
  node_logs["Activity logs<br/>[logging_config.py]"]
end

subgraph group_browser["Browser tools"]
  node_helper["Rollcall userscript"]
  node_schedule["Schedule exporter"]
  node_ics["ICS calendar file"]
end

node_student(("Student"))
node_tronclass["Tronclass service"]
node_classmates["Class attendance data"]
node_browser(("Browser user"))
node_jw["XMU teaching system"]

node_student -->|"runs commands"| node_cli
node_cli -->|"manages accounts"| node_config
node_cli -->|"starts monitoring"| node_monitor
node_cli -->|"presents menus"| node_tui
node_config -->|"stores credentials"| node_secure
node_monitor -->|"polls rollcalls"| node_tronclass
node_monitor -->|"classifies failures"| node_network
node_monitor -->|"dispatches detected rollcalls"| node_handler
node_monitor -->|"updates dashboard"| node_tui
node_monitor -->|"records activity"| node_logs
node_handler -->|"reads answer settings"| node_config
node_handler -->|"fetches signed counts"| node_classmates
node_handler -->|"submits attendance"| node_verify
node_handler -->|"updates rollcall status"| node_tui
node_verify -->|"requests codes and submits"| node_tronclass
node_browser -->|"runs helper"| node_helper
node_helper -->|"polls and submits codes"| node_tronclass
node_browser -->|"exports schedule"| node_schedule
node_schedule -->|"reads course schedule"| node_jw
node_schedule -->|"downloads calendar"| node_ics

click node_cli "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/cli.py"
click node_monitor "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/monitor.py"
click node_network "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/network.py"
click node_handler "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/rollcall_handler.py"
click node_verify "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/verify.py"
click node_tui "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/tui.py"
click node_config "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/config.py"
click node_secure "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/secure_store.py"
click node_logs "https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/logging_config.py"
click node_helper "https://github.com/alkali210/xmu-rollcall-bot/blob/main/scripts/rollcall/xmu-rollcall.user.js"
click node_schedule "https://github.com/alkali210/xmu-rollcall-bot/blob/main/scripts/schedule/jw-schedule-export.user.js"

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_cli,node_monitor,node_network,node_tui,node_browser toneBlue
class node_handler,node_verify toneAmber
class node_config,node_secure,node_logs toneMint
class node_helper,node_schedule,node_ics toneRose
class node_student,node_tronclass,node_classmates,node_jw toneIndigo
```

## Components

### CLI workflow

- [CLI commands](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/cli.py): `xmu-rollcall-cli/xmu_rollcall/cli.py`
- [Rollcall monitor](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/monitor.py): `xmu-rollcall-cli/xmu_rollcall/monitor.py`
- [Retry policy](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/network.py): `xmu-rollcall-cli/xmu_rollcall/network.py`
- [Terminal interface](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/tui.py): `xmu-rollcall-cli/xmu_rollcall/tui.py`

### Attendance handling

- [Rollcall handler](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/rollcall_handler.py): `xmu-rollcall-cli/xmu_rollcall/rollcall_handler.py`
- [Attendance submission](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/verify.py): `xmu-rollcall-cli/xmu_rollcall/verify.py`

### Account state

- [Account configuration](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/config.py): `xmu-rollcall-cli/xmu_rollcall/config.py`
- [Encrypted account store](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/secure_store.py): `xmu-rollcall-cli/xmu_rollcall/secure_store.py`
- [Activity logs](https://github.com/alkali210/xmu-rollcall-bot/blob/main/xmu-rollcall-cli/xmu_rollcall/logging_config.py): `xmu-rollcall-cli/xmu_rollcall/logging_config.py`

### Browser tools

- [Rollcall userscript](https://github.com/alkali210/xmu-rollcall-bot/blob/main/scripts/rollcall/xmu-rollcall.user.js): `scripts/rollcall/xmu-rollcall.user.js`
- [Schedule exporter](https://github.com/alkali210/xmu-rollcall-bot/blob/main/scripts/schedule/jw-schedule-export.user.js): `scripts/schedule/jw-schedule-export.user.js`
- **ICS calendar file**

### Other components

- **Student**
- **Tronclass service**
- **Class attendance data**
- **Browser user**
- **XMU teaching system**

## Connections

- Student → CLI commands: runs commands
- CLI commands → Account configuration: manages accounts
- CLI commands → Rollcall monitor: starts monitoring
- CLI commands → Terminal interface: presents menus
- Account configuration → Encrypted account store: stores credentials
- Rollcall monitor → Tronclass service: polls rollcalls
- Rollcall monitor → Retry policy: classifies failures
- Rollcall monitor → Rollcall handler: dispatches detected rollcalls
- Rollcall monitor → Terminal interface: updates dashboard
- Rollcall monitor → Activity logs: records activity
- Rollcall handler → Account configuration: reads answer settings
- Rollcall handler → Class attendance data: fetches signed counts
- Rollcall handler → Attendance submission: submits attendance
- Rollcall handler → Terminal interface: updates rollcall status
- Attendance submission → Tronclass service: requests codes and submits
- Browser user → Rollcall userscript: runs helper
- Rollcall userscript → Tronclass service: polls and submits codes
- Browser user → Schedule exporter: exports schedule
- Schedule exporter → XMU teaching system: reads course schedule
- Schedule exporter → ICS calendar file: downloads calendar