# buddykang/fudan_dorm_monitor architecture

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

- Interactive diagram: https://gitdiagram.com/buddykang/fudan_dorm_monitor
- Repository: https://github.com/buddykang/fudan_dorm_monitor

## Overview

This is a read-only dorm-room availability monitor. Its principal workflow is: load settings, use a persistent browser session to access the housing portal, discover building pages, classify each page as sold out, available, or unknown, then record state and alert when availability is detected. The README also documents evidence capture and optional notification channels. Most runtime behavior resides in monitor.py; the excerpts do not show every orchestration detail, so uncertain internal calls are omitted.

Main entry points: [`monitor.py`](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py) (Dorm monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["CLI entry<br/>[monitor.py]"]
  node_settings["Settings<br/>[monitor.py]"]
  node_monitor["Dorm monitor<br/>[monitor.py]"]
  node_browser["Persistent browser<br/>[monitor.py]"]
  node_captcha["CAPTCHA OCR<br/>[monitor.py]"]
end

subgraph group_monitoring["Availability checks"]
  node_buildings["Building discovery<br/>[monitor.py]"]
  node_pagecheck["Page status check<br/>[monitor.py]"]
end

subgraph group_outputs["State and alerts"]
  node_state[("Monitor state")]
  node_evidence["Page evidence"]
  node_logs["Logs"]
  node_notifier["Notifier<br/>[monitor.py]"]
end

node_user(("Operator"))
node_portal["Housing portal"]
node_desktop["Desktop notifications"]
node_telegram["Telegram"]
node_webhook["Webhook endpoint"]

node_user -->|"runs"| node_main
node_main -->|"loads"| node_settings
node_main -->|"starts"| node_monitor
node_monitor -->|"loads and saves"| node_state
node_monitor -->|"checks periodically"| node_browser
node_browser -->|"accesses pages"| node_portal
node_monitor -->|"requests recognition"| node_captcha
node_browser -->|"supplies image"| node_captcha
node_monitor -->|"discovers"| node_buildings
node_browser -->|"provides page"| node_buildings
node_monitor -->|"checks buildings"| node_pagecheck
node_browser -->|"provides content"| node_pagecheck
node_monitor -->|"saves suspected availability"| node_evidence
node_monitor -->|"requests alerts"| node_notifier
node_notifier -->|"writes"| node_logs
node_notifier -.->|"notifies"| node_desktop
node_notifier -.->|"sends message"| node_telegram
node_notifier -.->|"posts alert"| node_webhook

click node_main "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"
click node_settings "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"
click node_monitor "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"
click node_browser "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"
click node_captcha "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"
click node_buildings "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"
click node_pagecheck "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"
click node_notifier "https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py"

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_settings,node_monitor,node_browser,node_captcha toneBlue
class node_buildings,node_pagecheck toneAmber
class node_state,node_evidence,node_logs,node_notifier,node_webhook toneMint
class node_user,node_portal,node_desktop,node_telegram toneIndigo
```

## Components

### Runtime

- [CLI entry](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`
- [Settings](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`
- [Dorm monitor](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`
- [Persistent browser](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`
- [CAPTCHA OCR](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`

### Availability checks

- [Building discovery](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`
- [Page status check](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`

### State and alerts

- **Monitor state**
- **Page evidence**
- **Logs**
- [Notifier](https://github.com/buddykang/fudan_dorm_monitor/blob/main/monitor.py): `monitor.py`

### Other components

- **Operator**
- **Housing portal**
- **Desktop notifications**
- **Telegram**
- **Webhook endpoint**

## Connections

- Operator → CLI entry: runs
- CLI entry → Settings: loads
- CLI entry → Dorm monitor: starts
- Dorm monitor → Monitor state: loads and saves
- Dorm monitor → Persistent browser: checks periodically
- Persistent browser → Housing portal: accesses pages
- Dorm monitor → CAPTCHA OCR: requests recognition
- Persistent browser → CAPTCHA OCR: supplies image
- Dorm monitor → Building discovery: discovers
- Persistent browser → Building discovery: provides page
- Dorm monitor → Page status check: checks buildings
- Persistent browser → Page status check: provides content
- Dorm monitor → Page evidence: saves suspected availability
- Dorm monitor → Notifier: requests alerts
- Notifier → Logs: writes
- Notifier → Desktop notifications: notifies
- Notifier → Telegram: sends message
- Notifier → Webhook endpoint: posts alert