# vishalbabu-09/spidey-mesh-hackverse architecture

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

- Interactive diagram: https://gitdiagram.com/vishalbabu-09/spidey-mesh-hackverse
- Repository: https://github.com/vishalbabu-09/spidey-mesh-hackverse

## Overview

Spidey-Mesh combines ESP8266 worker telemetry sent over ESP-NOW to a master, which forwards it over local Wi-Fi/TCP to a Raspberry Pi gateway, with a separate web simulator for mesh quality and gateway failover experiments. The simulator flow is web UI/API → simulation orchestrator → topology, channel scoring, and gateway election. Hardware links are documented in the README; simulator module relationships are limited to those shown in excerpts or documented there, so unsampled details are not expanded.

Main entry points: [`esp32_mesh_simulator/simulation.py`](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/simulation.py) (Simulation orchestrator), [`esp32_mesh_simulator/app.py`](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/app.py) (Flask API), [`Master_esp.cpp`](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/Master_esp.cpp) (ESP8266 master), [`esp32_mesh_simulator/gateway.py`](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/gateway.py) (Gateway election)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Embedded telemetry"]
  node_worker1["Worker 1<br/>[Slave1.cpp]"]
  node_worker2["Worker 2<br/>[Slave2.cpp]"]
  node_master["ESP8266 master<br/>[Master_esp.cpp]"]
end

subgraph group_simulator["Mesh simulation"]
  node_simulation["Simulation orchestrator<br/>[simulation.py]"]
  node_mesh["Topology model<br/>[mesh.py]"]
  node_quality["Channel scoring<br/>[channel_quality.py]"]
  node_election["Gateway election<br/>[gateway.py]"]
end

subgraph group_web["Simulator interface"]
  node_webui["Dashboard UI<br/>[script.js]"]
  node_flask["Flask API<br/>[app.py]"]
  node_dashboard["Dashboard page<br/>[index.html]"]
end

node_pi(("Raspberry Pi gateway"))
node_browser(("User browser"))

node_worker1 -->|"sends telemetry"| node_master
node_worker2 -->|"sends telemetry"| node_master
node_master -->|"forwards telemetry"| node_pi
node_browser -->|"uses dashboard"| node_webui
node_webui -->|"calls API"| node_flask
node_flask -->|"renders page"| node_dashboard
node_flask -->|"delegates operations"| node_simulation
node_simulation -->|"uses topology model"| node_mesh
node_simulation -->|"evaluates channels"| node_quality
node_simulation -->|"runs failover"| node_election
node_election -->|"ranks candidates"| node_quality

click node_worker1 "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/Slave1.cpp"
click node_worker2 "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/Slave2.cpp"
click node_master "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/Master_esp.cpp"
click node_webui "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/static/script.js"
click node_flask "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/app.py"
click node_simulation "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/simulation.py"
click node_mesh "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/mesh.py"
click node_quality "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/channel_quality.py"
click node_election "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/gateway.py"
click node_dashboard "https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/templates/index.html"

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_worker1,node_worker2,node_master,node_browser toneBlue
class node_simulation,node_mesh,node_quality,node_election toneAmber
class node_webui,node_flask,node_dashboard toneMint
class node_pi toneIndigo
```

## Components

### Embedded telemetry

- [Worker 1](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/Slave1.cpp): `Slave1.cpp`
- [Worker 2](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/Slave2.cpp): `Slave2.cpp`
- [ESP8266 master](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/Master_esp.cpp): `Master_esp.cpp`

### Mesh simulation

- [Simulation orchestrator](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/simulation.py): `esp32_mesh_simulator/simulation.py`
- [Topology model](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/mesh.py): `esp32_mesh_simulator/mesh.py`
- [Channel scoring](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/channel_quality.py): `esp32_mesh_simulator/channel_quality.py`
- [Gateway election](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/gateway.py): `esp32_mesh_simulator/gateway.py`

### Simulator interface

- [Dashboard UI](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/static/script.js): `esp32_mesh_simulator/static/script.js`
- [Flask API](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/app.py): `esp32_mesh_simulator/app.py`
- [Dashboard page](https://github.com/vishalbabu-09/spidey-mesh-hackverse/blob/main/esp32_mesh_simulator/templates/index.html): `esp32_mesh_simulator/templates/index.html`

### Other components

- **Raspberry Pi gateway**
- **User browser**

## Connections

- Worker 1 → ESP8266 master: sends telemetry (evidence: `README.md`)
- Worker 2 → ESP8266 master: sends telemetry (evidence: `README.md`)
- ESP8266 master → Raspberry Pi gateway: forwards telemetry (evidence: `README.md`)
- User browser → Dashboard UI: uses dashboard (evidence: `README.md`)
- Dashboard UI → Flask API: calls API (evidence: `esp32_mesh_simulator/static/script.js`)
- Flask API → Dashboard page: renders page (evidence: `esp32_mesh_simulator/app.py`)
- Flask API → Simulation orchestrator: delegates operations (evidence: `esp32_mesh_simulator/app.py`)
- Simulation orchestrator → Topology model: uses topology model (evidence: `README.md`)
- Simulation orchestrator → Channel scoring: evaluates channels (evidence: `README.md`)
- Simulation orchestrator → Gateway election: runs failover (evidence: `README.md`)
- Gateway election → Channel scoring: ranks candidates (evidence: `esp32_mesh_simulator/gateway.py`)
