# burhanabdullah/xmon-grid architecture

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

- Interactive diagram: https://gitdiagram.com/burhanabdullah/xmon-grid
- Repository: https://github.com/burhanabdullah/xmon-grid

## Overview

XMON-Grid is a research implementation for detecting topology attacks in SCADA-monitored transmission systems, using canonical IEEE network data and seeded synthetic measurements. Its documented workflow generates scenario data, evaluates NIS, CUSUM, and timing-jitter detector streams, and combines their votes with a strict majority quorum; sequential accumulation is evaluated separately. The graph also shows the model, topology, mitigation, agent, and experiment layers. README claims establish detector roles and quorum semantics; sampled source confirms benchmark generation and physical modeling, but does not expose all runtime wiring.

Main entry points: [`core/consensus.py`](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/consensus.py) (Quorum Consensus), [`agents/coordinator.py`](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/coordinator.py) (Coordinator), [`core/grid_topology.py`](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/grid_topology.py) (Grid Model), [`core/data_pipeline.py`](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/data_pipeline.py) (Scenario Dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_benchmark["Grid Benchmark"]
  node_case_data[("IEEE Case Data<br/>[grid_topology.py]")]
  node_grid_model["Grid Model<br/>[grid_topology.py]"]
  node_dataset["Scenario Dataset<br/>[data_pipeline.py]"]
end

subgraph group_detection["Detection And Response"]
  node_estimator["State Estimator<br/>[xmon_model.py]"]
  node_nis["NIS Stream<br/>[xmon_model.py]"]
  node_cusum["CUSUM Stream"]
  node_jitter["Timing Jitter<br/>[fusion_detector.py]"]
  node_sequential["Sequential Accumulation"]
  node_quorum["Quorum Consensus<br/>[consensus.py]"]
  node_mitigation["Mitigation<br/>[mitigation.py]"]
end

subgraph group_agents["Agent Coordination"]
  node_coordinator["Coordinator<br/>[coordinator.py]"]
  node_monitor["Monitor<br/>[monitor.py]"]
  node_auditor["Auditor<br/>[auditor.py]"]
  node_protector["Protector<br/>[protector.py]"]
end

subgraph group_research["Evaluation"]
  node_experiments["Experiment Runs"]
  node_validation["Physical Validation"]
  node_visualization["Attack Visualization<br/>[plot_all_cases.py]"]
end

node_operator(("Researcher"))

node_operator -->|"runs experiments"| node_experiments
node_case_data -->|"builds topology"| node_grid_model
node_grid_model -->|"supplies model"| node_dataset
node_dataset -->|"provides measurements"| node_estimator
node_estimator -->|"computes NIS"| node_nis
node_nis -->|"votes"| node_quorum
node_cusum -->|"votes"| node_quorum
node_jitter -->|"votes"| node_quorum
node_sequential -->|"evaluated separately"| node_experiments
node_quorum -->|"informs response"| node_mitigation
node_coordinator -->|"coordinates"| node_monitor
node_coordinator -->|"coordinates"| node_auditor
node_coordinator -->|"coordinates"| node_protector
node_experiments -->|"evaluates scenarios"| node_dataset
node_validation -->|"checks physics"| node_grid_model
node_visualization -->|"uses grid cases"| node_case_data

click node_case_data "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/grid_topology.py"
click node_grid_model "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/grid_topology.py"
click node_dataset "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/data_pipeline.py"
click node_estimator "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/xmon_model.py"
click node_nis "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/xmon_model.py"
click node_cusum "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/sequential_detector.py"
click node_jitter "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/fusion_detector.py"
click node_sequential "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/sequential_detector.py"
click node_quorum "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/consensus.py"
click node_mitigation "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/mitigation.py"
click node_coordinator "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/coordinator.py"
click node_monitor "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/monitor.py"
click node_auditor "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/auditor.py"
click node_protector "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/protector.py"
click node_experiments "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/run_full_macpr_experiment.py"
click node_validation "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/validation/real_physical_validation.py"
click node_visualization "https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/visualization/plot_all_cases.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_case_data,node_grid_model,node_dataset toneBlue
class node_estimator,node_nis,node_cusum,node_jitter,node_sequential,node_quorum,node_mitigation toneAmber
class node_coordinator,node_monitor,node_auditor,node_protector toneMint
class node_experiments,node_validation,node_visualization toneRose
class node_operator toneIndigo
```

## Components

### Grid Benchmark

- [IEEE Case Data](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/grid_topology.py): `core/grid_topology.py`
- [Grid Model](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/grid_topology.py): `core/grid_topology.py`
- [Scenario Dataset](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/data_pipeline.py): `core/data_pipeline.py`

### Detection And Response

- [State Estimator](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/xmon_model.py): `core/xmon_model.py`
- [NIS Stream](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/xmon_model.py): `core/xmon_model.py`
- [CUSUM Stream](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/sequential_detector.py): `experiments/sequential_detector.py`
- [Timing Jitter](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/fusion_detector.py): `experiments/fusion_detector.py`
- [Sequential Accumulation](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/sequential_detector.py): `experiments/sequential_detector.py`
- [Quorum Consensus](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/consensus.py): `core/consensus.py`
- [Mitigation](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/core/mitigation.py): `core/mitigation.py`

### Agent Coordination

- [Coordinator](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/coordinator.py): `agents/coordinator.py`
- [Monitor](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/monitor.py): `agents/monitor.py`
- [Auditor](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/auditor.py): `agents/auditor.py`
- [Protector](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/agents/protector.py): `agents/protector.py`

### Evaluation

- [Experiment Runs](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/experiments/run_full_macpr_experiment.py): `experiments/run_full_macpr_experiment.py`
- [Physical Validation](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/validation/real_physical_validation.py): `validation/real_physical_validation.py`
- [Attack Visualization](https://github.com/burhanabdullah/xmon-grid/blob/xmon-main/visualization/plot_all_cases.py): `visualization/plot_all_cases.py`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment Runs: runs experiments
- IEEE Case Data → Grid Model: builds topology
- Grid Model → Scenario Dataset: supplies model
- Scenario Dataset → State Estimator: provides measurements
- State Estimator → NIS Stream: computes NIS
- NIS Stream → Quorum Consensus: votes
- CUSUM Stream → Quorum Consensus: votes
- Timing Jitter → Quorum Consensus: votes
- Sequential Accumulation → Experiment Runs: evaluated separately
- Quorum Consensus → Mitigation: informs response
- Coordinator → Monitor: coordinates
- Coordinator → Auditor: coordinates
- Coordinator → Protector: coordinates
- Experiment Runs → Scenario Dataset: evaluates scenarios
- Physical Validation → Grid Model: checks physics
- Attack Visualization → IEEE Case Data: uses grid cases