# ubs9796/uptime-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/ubs9796/uptime-monitor
- Repository: https://github.com/ubs9796/uptime-monitor

## Overview

Uptime Monitor manages monitored URLs through a CLI: operators add or remove sites, run a check cycle, and view status in a read-only dashboard. A cycle first probes connectivity, then checks each site's HTTP availability and (for HTTPS) certificate expiry, persists history and changed state, and dispatches alerts for transitions. SQLite supports both the CLI cycle and dashboard; Telegram is attempted before an optional HTTPS webhook. The excerpts show these main calls and reads; external service interactions are represented from the documented behavior and notifier implementation.

Main entry points: [`runner.py`](https://github.com/ubs9796/uptime-monitor/blob/main/runner.py) (Check cycle), [`storage.py`](https://github.com/ubs9796/uptime-monitor/blob/main/storage.py) (SQLite state and history), [`notifier.py`](https://github.com/ubs9796/uptime-monitor/blob/main/notifier.py) (Alert delivery), [`dashboard.py`](https://github.com/ubs9796/uptime-monitor/blob/main/dashboard.py) (Read-only dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Monitor operations"]
  node_cli["Monitor CLI<br/>[runner.py]"]
  node_cycle["Check cycle<br/>[runner.py]"]
end

subgraph group_checking["Availability checks"]
  node_url_validation["URL validation<br/>[checker.py]"]
  node_connectivity["Connectivity probe<br/>[checker.py]"]
  node_http_check["HTTP status check<br/>[checker.py]"]
  node_tls_check["TLS expiry check<br/>[checker.py]"]
end

subgraph group_persistence["State and history"]
  node_state_logic["Transition detection<br/>[storage.py]"]
  node_sqlite[("SQLite state and history<br/>[storage.py]")]
end

subgraph group_presentation["Status and alerts"]
  node_dashboard["Read-only dashboard<br/>[dashboard.py]"]
  node_alert_format["Alert formatting<br/>[notifier.py]"]
  node_alert_dispatch["Alert delivery<br/>[notifier.py]"]
end

node_operator(("Operator"))
node_websites(("Monitored websites"))
node_telegram{{"Telegram API"}}
node_webhook{{"HTTPS webhook"}}

node_operator -->|"runs commands"| node_cli
node_cli -->|"starts cycle"| node_cycle
node_cycle -->|"probes first"| node_connectivity
node_cycle -->|"loads sites"| node_sqlite
node_cycle -->|"checks URLs"| node_http_check
node_cycle -->|"checks HTTPS expiry"| node_tls_check
node_cycle -->|"records results"| node_state_logic
node_state_logic -->|"appends history"| node_sqlite
node_cli -->|"manages sites"| node_sqlite
node_sqlite -->|"validates site URLs"| node_url_validation
node_cycle -->|"formats changed alerts"| node_alert_format
node_cycle -->|"sends changed alerts"| node_alert_dispatch
node_alert_dispatch -->|"tries first"| node_telegram
node_alert_dispatch -->|"falls back"| node_webhook
node_operator -->|"views status"| node_dashboard
node_dashboard -->|"reads site state"| node_sqlite
node_cycle -->|"checks each site"| node_websites

click node_cli "https://github.com/ubs9796/uptime-monitor/blob/main/runner.py"
click node_cycle "https://github.com/ubs9796/uptime-monitor/blob/main/runner.py"
click node_url_validation "https://github.com/ubs9796/uptime-monitor/blob/main/checker.py"
click node_connectivity "https://github.com/ubs9796/uptime-monitor/blob/main/checker.py"
click node_http_check "https://github.com/ubs9796/uptime-monitor/blob/main/checker.py"
click node_tls_check "https://github.com/ubs9796/uptime-monitor/blob/main/checker.py"
click node_state_logic "https://github.com/ubs9796/uptime-monitor/blob/main/storage.py"
click node_sqlite "https://github.com/ubs9796/uptime-monitor/blob/main/storage.py"
click node_dashboard "https://github.com/ubs9796/uptime-monitor/blob/main/dashboard.py"
click node_alert_format "https://github.com/ubs9796/uptime-monitor/blob/main/notifier.py"
click node_alert_dispatch "https://github.com/ubs9796/uptime-monitor/blob/main/notifier.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_cli,node_cycle toneBlue
class node_url_validation,node_connectivity,node_http_check,node_tls_check toneAmber
class node_state_logic,node_sqlite,node_telegram,node_webhook toneMint
class node_dashboard,node_alert_format,node_alert_dispatch toneRose
class node_operator,node_websites toneIndigo
```

## Components

### Monitor operations

- [Monitor CLI](https://github.com/ubs9796/uptime-monitor/blob/main/runner.py): `runner.py`
- [Check cycle](https://github.com/ubs9796/uptime-monitor/blob/main/runner.py): `runner.py`

### Availability checks

- [URL validation](https://github.com/ubs9796/uptime-monitor/blob/main/checker.py): `checker.py`
- [Connectivity probe](https://github.com/ubs9796/uptime-monitor/blob/main/checker.py): `checker.py`
- [HTTP status check](https://github.com/ubs9796/uptime-monitor/blob/main/checker.py): `checker.py`
- [TLS expiry check](https://github.com/ubs9796/uptime-monitor/blob/main/checker.py): `checker.py`

### State and history

- [Transition detection](https://github.com/ubs9796/uptime-monitor/blob/main/storage.py): `storage.py`
- [SQLite state and history](https://github.com/ubs9796/uptime-monitor/blob/main/storage.py): `storage.py`

### Status and alerts

- [Read-only dashboard](https://github.com/ubs9796/uptime-monitor/blob/main/dashboard.py): `dashboard.py`
- [Alert formatting](https://github.com/ubs9796/uptime-monitor/blob/main/notifier.py): `notifier.py`
- [Alert delivery](https://github.com/ubs9796/uptime-monitor/blob/main/notifier.py): `notifier.py`

### Other components

- **Operator**
- **Monitored websites**
- **Telegram API**
- **HTTPS webhook**

## Connections

- Operator → Monitor CLI: runs commands (evidence: `README.md`)
- Monitor CLI → Check cycle: starts cycle (evidence: `runner.py`)
- Check cycle → Connectivity probe: probes first (evidence: `runner.py`)
- Check cycle → SQLite state and history: loads sites (evidence: `runner.py`)
- Check cycle → HTTP status check: checks URLs (evidence: `runner.py`)
- Check cycle → TLS expiry check: checks HTTPS expiry (evidence: `runner.py`)
- Check cycle → Transition detection: records results (evidence: `runner.py`)
- Transition detection → SQLite state and history: appends history (evidence: `storage.py`)
- Monitor CLI → SQLite state and history: manages sites (evidence: `runner.py`)
- SQLite state and history → URL validation: validates site URLs (evidence: `storage.py`)
- Check cycle → Alert formatting: formats changed alerts (evidence: `runner.py`)
- Check cycle → Alert delivery: sends changed alerts (evidence: `runner.py`)
- Alert delivery → Telegram API: tries first (evidence: `notifier.py`)
- Alert delivery → HTTPS webhook: falls back (evidence: `notifier.py`)
- Operator → Read-only dashboard: views status (evidence: `README.md`)
- Read-only dashboard → SQLite state and history: reads site state (evidence: `dashboard.py`)
- Check cycle → Monitored websites: checks each site (evidence: `runner.py`)