# tworjaga/esp32watchdog architecture

> Architecture diagram of the GitHub repository tworjaga/esp32watchdog, 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/tworjaga/esp32watchdog
- Repository: https://github.com/tworjaga/esp32watchdog

## Overview

ESP32Watchdog is an autonomous, passive Wi-Fi threat monitor. Wireless traffic enters the scan task, which filters and parses packets and applies the DEAUTH, TWIN, and FLOOD detectors; alerts are queued for a dedicated SD-writing task. A separate UI task reads device state, displays status and alerts, drives the LED, and handles button input to change modes or restart. The README documents these responsibilities and relationships, but no source excerpts were provided, so implementation-level call details are unavailable.

Main entry points: [`ESP32Watchdog.ino`](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino) (Scan task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Packet Scanning"]
  node_scan_task["Scan task<br/>[ESP32Watchdog.ino]"]
  node_packet_pool["Packet pool<br/>[ESP32Watchdog.ino]"]
  node_channel_hop["Channel hopping<br/>[ESP32Watchdog.ino]"]
end

subgraph group_detect["Threat Detection"]
  node_deauth["DEAUTH detector<br/>[ESP32Watchdog.ino]"]
  node_twin["TWIN detector<br/>[ESP32Watchdog.ino]"]
  node_flood["FLOOD detector<br/>[ESP32Watchdog.ino]"]
  node_alert_queue["Alert queue<br/>[ESP32Watchdog.ino]"]
end

subgraph group_device["Device Output"]
  node_write_task["SD write task<br/>[ESP32Watchdog.ino]"]
  node_csv_logs[("CSV logs<br/>[ESP32Watchdog.ino]")]
  node_ui_task["UI task<br/>[ESP32Watchdog.ino]"]
  node_oled["OLED display<br/>[ESP32Watchdog.ino]"]
  node_led["Status LED<br/>[ESP32Watchdog.ino]"]
  node_button["Button<br/>[ESP32Watchdog.ino]"]
end

node_air(("Wi-Fi traffic"))
node_user(("Device user"))

node_air -->|"supplies frames"| node_scan_task
node_scan_task -->|"claims and releases"| node_packet_pool
node_scan_task -->|"checks frames"| node_deauth
node_scan_task -->|"checks frames"| node_twin
node_scan_task -->|"checks frames"| node_flood
node_scan_task -->|"advances channels"| node_channel_hop
node_deauth -->|"queues alerts"| node_alert_queue
node_twin -->|"queues alerts"| node_alert_queue
node_flood -->|"queues alerts"| node_alert_queue
node_write_task -->|"reads indices"| node_alert_queue
node_write_task -->|"writes rows"| node_csv_logs
node_ui_task -->|"draws status"| node_oled
node_ui_task -->|"drives patterns"| node_led
node_user -->|"presses"| node_button
node_button -->|"cycles mode"| node_ui_task

click node_scan_task "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_packet_pool "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_channel_hop "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_deauth "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_twin "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_flood "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_alert_queue "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_write_task "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_csv_logs "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_ui_task "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_oled "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_led "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"
click node_button "https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino"

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_scan_task,node_packet_pool,node_channel_hop,node_user toneBlue
class node_deauth,node_twin,node_flood,node_alert_queue toneAmber
class node_write_task,node_csv_logs,node_ui_task,node_oled,node_led,node_button toneMint
class node_air toneIndigo
```

## Components

### Packet Scanning

- [Scan task](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [Packet pool](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [Channel hopping](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`

### Threat Detection

- [DEAUTH detector](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [TWIN detector](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [FLOOD detector](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [Alert queue](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`

### Device Output

- [SD write task](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [CSV logs](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [UI task](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [OLED display](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [Status LED](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`
- [Button](https://github.com/tworjaga/esp32watchdog/blob/main/ESP32Watchdog.ino): `ESP32Watchdog.ino`

### Other components

- **Wi-Fi traffic**
- **Device user**

## Connections

- Wi-Fi traffic → Scan task: supplies frames (evidence: `README.md`)
- Scan task → Packet pool: claims and releases (evidence: `README.md`)
- Scan task → DEAUTH detector: checks frames (evidence: `README.md`)
- Scan task → TWIN detector: checks frames (evidence: `README.md`)
- Scan task → FLOOD detector: checks frames (evidence: `README.md`)
- Scan task → Channel hopping: advances channels (evidence: `README.md`)
- DEAUTH detector → Alert queue: queues alerts (evidence: `README.md`)
- TWIN detector → Alert queue: queues alerts (evidence: `README.md`)
- FLOOD detector → Alert queue: queues alerts (evidence: `README.md`)
- SD write task → Alert queue: reads indices (evidence: `README.md`)
- SD write task → CSV logs: writes rows (evidence: `README.md`)
- UI task → OLED display: draws status (evidence: `README.md`)
- UI task → Status LED: drives patterns (evidence: `README.md`)
- Device user → Button: presses (evidence: `README.md`)
- Button → UI task: cycles mode (evidence: `README.md`)
