# basematter/mctpsalert architecture

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

- Interactive diagram: https://gitdiagram.com/basematter/mctpsalert
- Repository: https://github.com/basematter/mctpsalert

## Overview

MC TPS Alert pairs a NeoForge server mod with an AstrBot plugin. The mod periodically samples TPS, applies configured alert rules, and posts samples or alerts to the plugin; the plugin stores samples and offers a history-chart tool, while alert messages can be broadcast to configured groups. The excerpts show configuration, command dispatch, sampling, webhook handling, persistence, and chart generation. The alert-to-broadcast handoff is not visible in the sampled lines, so that relationship is marked unverified.

Main entry points: [`mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java`](https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java) (Mod registration), [`mctpsalert/src/main/java/com/basem/mctpsalert/TpsMonitor.java`](https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/TpsMonitor.java) (TPS monitor), [`astrbot_plugin_mctps_alert/main.py`](https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py) (Webhook endpoint), [`mctpsalert/src/main/java/com/basem/mctpsalert/ModCommands.java`](https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/ModCommands.java) (Debug commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mod["Minecraft server mod"]
  node_mod_init["Mod registration<br/>[MCTpsAlert.java]"]
  node_config["Server settings<br/>[Config.java]"]
  node_commands["Debug commands<br/>[ModCommands.java]"]
  node_monitor["TPS monitor<br/>[TpsMonitor.java]"]
end

subgraph group_plugin["AstrBot plugin"]
  node_webhook["Webhook endpoint<br/>[main.py]"]
end

subgraph group_data["History and charts"]
  node_history[("TPS history<br/>[main.py]")]
  node_chart_tool["History chart tool<br/>[main.py]"]
end

subgraph group_delivery["Message delivery"]
  node_broadcast["Group broadcast<br/>[main.py]"]
end

node_admin(("Server operator"))
node_spark["Spark API"]
node_user(("AstrBot user"))
node_groups["Target groups"]

node_admin -->|"configures"| node_mod_init
node_mod_init -->|"registers"| node_config
node_mod_init -->|"registers events"| node_monitor
node_mod_init -->|"registers events"| node_commands
node_commands -->|"dispatches"| node_monitor
node_monitor -->|"samples TPS"| node_spark
node_monitor -->|"posts events"| node_webhook
node_webhook -->|"stores samples"| node_history
node_user -.->|"requests chart"| node_chart_tool
node_chart_tool -->|"queries history"| node_history
node_chart_tool -.->|"sends message"| node_broadcast
node_broadcast -->|"broadcasts to"| node_groups
node_webhook -.->|"dispatches alerts"| node_broadcast

click node_mod_init "https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java"
click node_config "https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/Config.java"
click node_commands "https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/ModCommands.java"
click node_monitor "https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/TpsMonitor.java"
click node_webhook "https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py"
click node_history "https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py"
click node_chart_tool "https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py"
click node_broadcast "https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.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_mod_init,node_config,node_commands,node_monitor,node_user toneBlue
class node_webhook toneAmber
class node_history,node_chart_tool,node_admin,node_spark toneMint
class node_broadcast toneRose
class node_groups toneIndigo
```

## Components

### Minecraft server mod

- [Mod registration](https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java): `mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java`
- [Server settings](https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/Config.java): `mctpsalert/src/main/java/com/basem/mctpsalert/Config.java`
- [Debug commands](https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/ModCommands.java): `mctpsalert/src/main/java/com/basem/mctpsalert/ModCommands.java`
- [TPS monitor](https://github.com/basematter/mctpsalert/blob/1.21.1/mctpsalert/src/main/java/com/basem/mctpsalert/TpsMonitor.java): `mctpsalert/src/main/java/com/basem/mctpsalert/TpsMonitor.java`

### AstrBot plugin

- [Webhook endpoint](https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py): `astrbot_plugin_mctps_alert/main.py`

### History and charts

- [TPS history](https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py): `astrbot_plugin_mctps_alert/main.py`
- [History chart tool](https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py): `astrbot_plugin_mctps_alert/main.py`

### Message delivery

- [Group broadcast](https://github.com/basematter/mctpsalert/blob/1.21.1/astrbot_plugin_mctps_alert/main.py): `astrbot_plugin_mctps_alert/main.py`

### Other components

- **Server operator**
- **Spark API**
- **AstrBot user**
- **Target groups**

## Connections

- Server operator → Mod registration: configures
- Mod registration → Server settings: registers (evidence: `mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java`)
- Mod registration → TPS monitor: registers events (evidence: `mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java`)
- Mod registration → Debug commands: registers events (evidence: `mctpsalert/src/main/java/com/basem/mctpsalert/MCTpsAlert.java`)
- Debug commands → TPS monitor: dispatches (evidence: `mctpsalert/src/main/java/com/basem/mctpsalert/ModCommands.java`)
- TPS monitor → Spark API: samples TPS (evidence: `mctpsalert/src/main/java/com/basem/mctpsalert/TpsMonitor.java`)
- TPS monitor → Webhook endpoint: posts events (evidence: `mctpsalert/src/main/java/com/basem/mctpsalert/TpsMonitor.java`)
- Webhook endpoint → TPS history: stores samples (evidence: `astrbot_plugin_mctps_alert/main.py`)
- AstrBot user → History chart tool: requests chart
- History chart tool → TPS history: queries history (evidence: `astrbot_plugin_mctps_alert/main.py`)
- History chart tool → Group broadcast: sends message (evidence: `astrbot_plugin_mctps_alert/main.py`)
- Group broadcast → Target groups: broadcasts to (evidence: `astrbot_plugin_mctps_alert/main.py`)
- Webhook endpoint → Group broadcast: dispatches alerts (evidence: `astrbot_plugin_mctps_alert/main.py`)