# qzqmn/monitor architecture

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

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

## Overview

VPS Monitor is a self-hosted, multi-machine monitoring system: an Agent on each host samples machine and network metrics and reports them to a central Rust server, which stores current status and cumulative traffic for the dashboard. Administrators authenticate to manage agents, traffic settings, and alert channels. The README also documents latency and GeoIP capabilities; the sampled Agent excerpt shows GeoIP lookup but not latency-probe implementation, so no latency-probe wiring is asserted. The sampled sources establish report, persistence, auth, and notification flows; dashboard interactions are represented at the documented product level.

Main entry points: [`server/src/main.rs`](https://github.com/qzqmn/monitor/blob/main/server/src/main.rs) (HTTP routing), [`server/src/db.rs`](https://github.com/qzqmn/monitor/blob/main/server/src/db.rs) (Status and settings), [`server/src/notify.rs`](https://github.com/qzqmn/monitor/blob/main/server/src/notify.rs) (Alert checks), [`agent/src/main.rs`](https://github.com/qzqmn/monitor/blob/main/agent/src/main.rs) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Host Agent"]
  node_agent_runtime["Agent runtime<br/>[main.rs]"]
  node_metrics["Metric collection<br/>[main.rs]"]
  node_geoip["GeoIP lookup<br/>[main.rs]"]
end

subgraph group_server["Monitoring Server"]
  node_report_api["Report endpoint<br/>[api.rs]"]
  node_server_runtime["HTTP routing<br/>[main.rs]"]
  node_status_store[("Status and settings<br/>[db.rs]")]
  node_agent_admin["Agent management<br/>[agents.rs]"]
  node_admin_auth["Admin authentication<br/>[auth.rs]"]
  node_traffic_cycle["Traffic reset<br/>[db.rs]"]
end

subgraph group_admin["Admin and Dashboard"]
  node_dashboard["Status dashboard<br/>[index.html]"]
  node_admin_ui["Admin console<br/>[admin.html]"]
end

subgraph group_alerts["Alerts and Integrations"]
  node_alert_rules["Alert checks<br/>[notify.rs]"]
  node_telegram["Telegram"]
  node_webhook["Webhook receiver"]
end

node_host(("Monitored host"))
node_geo_service["ip-api.com"]
node_sqlite[("SQLite database")]
node_admin_user(("Administrator"))

node_host -->|"runs"| node_agent_runtime
node_agent_runtime -->|"collects"| node_metrics
node_agent_runtime -->|"looks up"| node_geoip
node_geoip -.->|"queries"| node_geo_service
node_agent_runtime -->|"reports metrics"| node_server_runtime
node_server_runtime -->|"dispatches"| node_report_api
node_report_api -->|"upserts status"| node_status_store
node_status_store -->|"reads and writes"| node_sqlite
node_report_api -->|"checks report alerts"| node_alert_rules
node_server_runtime -->|"checks offline"| node_alert_rules
node_server_runtime -->|"runs periodic reset"| node_traffic_cycle
node_traffic_cycle -->|"resets due traffic"| node_status_store
node_alert_rules -->|"loads settings and status"| node_status_store
node_alert_rules -.->|"sends alerts"| node_telegram
node_alert_rules -.->|"posts alerts"| node_webhook
node_admin_user -->|"views"| node_dashboard
node_admin_user -->|"manages"| node_admin_ui
node_dashboard -->|"requests status"| node_server_runtime
node_admin_ui -->|"calls admin APIs"| node_server_runtime
node_server_runtime -->|"dispatches auth"| node_admin_auth
node_admin_auth -->|"reads and writes sessions"| node_status_store
node_server_runtime -->|"dispatches management"| node_agent_admin
node_agent_admin -->|"manages agent records"| node_status_store
node_server_runtime -->|"serves status and settings"| node_status_store
node_server_runtime -->|"tests notifications"| node_alert_rules

click node_agent_runtime "https://github.com/qzqmn/monitor/blob/main/agent/src/main.rs"
click node_metrics "https://github.com/qzqmn/monitor/blob/main/agent/src/main.rs"
click node_geoip "https://github.com/qzqmn/monitor/blob/main/agent/src/main.rs"
click node_report_api "https://github.com/qzqmn/monitor/blob/main/server/src/api.rs"
click node_server_runtime "https://github.com/qzqmn/monitor/blob/main/server/src/main.rs"
click node_status_store "https://github.com/qzqmn/monitor/blob/main/server/src/db.rs"
click node_agent_admin "https://github.com/qzqmn/monitor/blob/main/server/src/agents.rs"
click node_admin_auth "https://github.com/qzqmn/monitor/blob/main/server/src/auth.rs"
click node_dashboard "https://github.com/qzqmn/monitor/blob/main/server/static/index.html"
click node_admin_ui "https://github.com/qzqmn/monitor/blob/main/server/static/admin.html"
click node_alert_rules "https://github.com/qzqmn/monitor/blob/main/server/src/notify.rs"
click node_traffic_cycle "https://github.com/qzqmn/monitor/blob/main/server/src/db.rs"

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_agent_runtime,node_metrics,node_geoip toneBlue
class node_report_api,node_server_runtime,node_status_store,node_agent_admin,node_admin_auth,node_traffic_cycle,node_sqlite toneAmber
class node_dashboard,node_admin_ui,node_geo_service toneMint
class node_alert_rules,node_telegram,node_webhook toneRose
class node_host,node_admin_user toneIndigo
```

## Components

### Host Agent

- [Agent runtime](https://github.com/qzqmn/monitor/blob/main/agent/src/main.rs): `agent/src/main.rs`
- [Metric collection](https://github.com/qzqmn/monitor/blob/main/agent/src/main.rs): `agent/src/main.rs`
- [GeoIP lookup](https://github.com/qzqmn/monitor/blob/main/agent/src/main.rs): `agent/src/main.rs`

### Monitoring Server

- [Report endpoint](https://github.com/qzqmn/monitor/blob/main/server/src/api.rs): `server/src/api.rs`
- [HTTP routing](https://github.com/qzqmn/monitor/blob/main/server/src/main.rs): `server/src/main.rs`
- [Status and settings](https://github.com/qzqmn/monitor/blob/main/server/src/db.rs): `server/src/db.rs`
- [Agent management](https://github.com/qzqmn/monitor/blob/main/server/src/agents.rs): `server/src/agents.rs`
- [Admin authentication](https://github.com/qzqmn/monitor/blob/main/server/src/auth.rs): `server/src/auth.rs`
- [Traffic reset](https://github.com/qzqmn/monitor/blob/main/server/src/db.rs): `server/src/db.rs`

### Admin and Dashboard

- [Status dashboard](https://github.com/qzqmn/monitor/blob/main/server/static/index.html): `server/static/index.html`
- [Admin console](https://github.com/qzqmn/monitor/blob/main/server/static/admin.html): `server/static/admin.html`

### Alerts and Integrations

- [Alert checks](https://github.com/qzqmn/monitor/blob/main/server/src/notify.rs): `server/src/notify.rs`
- **Telegram**
- **Webhook receiver**

### Other components

- **Monitored host**
- **ip-api.com**
- **SQLite database**
- **Administrator**

## Connections

- Monitored host → Agent runtime: runs
- Agent runtime → Metric collection: collects
- Agent runtime → GeoIP lookup: looks up
- GeoIP lookup → ip-api.com: queries
- Agent runtime → HTTP routing: reports metrics
- HTTP routing → Report endpoint: dispatches
- Report endpoint → Status and settings: upserts status
- Status and settings → SQLite database: reads and writes
- Report endpoint → Alert checks: checks report alerts
- HTTP routing → Alert checks: checks offline
- HTTP routing → Traffic reset: runs periodic reset
- Traffic reset → Status and settings: resets due traffic
- Alert checks → Status and settings: loads settings and status
- Alert checks → Telegram: sends alerts
- Alert checks → Webhook receiver: posts alerts
- Administrator → Status dashboard: views
- Administrator → Admin console: manages
- Status dashboard → HTTP routing: requests status
- Admin console → HTTP routing: calls admin APIs
- HTTP routing → Admin authentication: dispatches auth
- Admin authentication → Status and settings: reads and writes sessions
- HTTP routing → Agent management: dispatches management
- Agent management → Status and settings: manages agent records
- HTTP routing → Status and settings: serves status and settings
- HTTP routing → Alert checks: tests notifications