# paulloth1/esp32-smart-glass-canary architecture

> Architecture diagram of the GitHub repository paulloth1/esp32-smart-glass-canary, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulloth1/esp32-smart-glass-canary
- Repository: https://github.com/paulloth1/esp32-smart-glass-canary

## Overview

Smart Glass Canary is ESP32 firmware that scans nearby BLE advertisements and warns when scored signals suggest camera-equipped eyewear. Its main workflow is advertisement matching and threshold-based detection, followed by local indicators and optional network alerts. Users provision Wi-Fi over USB serial; once connected, the device also offers a read-only status page. The excerpts establish the scoring rules, configuration, provisioning, and web UI, but do not show the main sketch’s runtime wiring, so those links are left unverified.

Main entry points: [`firmware/firmware.ino`](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/firmware.ino) (Firmware runtime), [`firmware/provisioning.h`](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/provisioning.h) (Wi-Fi provisioning and reset), [`firmware/signatures.h`](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/signatures.h) (Vendor signature rules), [`firmware/webui.h`](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/webui.h) (Read-only status page and API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["BLE Detection"]
  node_signatures["Vendor signature rules<br/>[signatures.h]"]
end

subgraph group_device["Device Runtime"]
  node_runtime["Firmware runtime<br/>[firmware.ino]"]
  node_config["Detection and device settings<br/>[config.h]"]
  node_indicators["LED and buzzer"]
end

subgraph group_connectivity["Setup and Network"]
  node_provision["Wi-Fi provisioning and reset<br/>[provisioning.h]"]
  node_nvs[("Credential storage")]
  node_wifi["Wi-Fi network"]
end

subgraph group_visibility["Status and Alerts"]
  node_webui["Read-only status page and API<br/>[webui.h]"]
  node_webhook["Webhook receiver"]
  node_mqtt["MQTT broker"]
end

node_user(("Device user"))
node_advertisers(("Nearby BLE advertisers"))

node_advertisers -.->|"advertise to"| node_runtime
node_runtime -.->|"scores against"| node_signatures
node_signatures -->|"uses thresholds"| node_config
node_user -->|"provides Wi-Fi"| node_provision
node_provision -->|"loads and saves"| node_nvs
node_runtime -.->|"loads settings"| node_provision
node_runtime -.->|"connects to"| node_wifi
node_runtime -->|"signals alerts"| node_indicators
node_runtime -->|"publishes alerts"| node_mqtt
node_runtime -.->|"posts alerts"| node_webhook
node_runtime -.->|"serves status"| node_webui
node_webui -->|"serves over"| node_wifi

click node_runtime "https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/firmware.ino"
click node_config "https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/config.h"
click node_signatures "https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/signatures.h"
click node_provision "https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/provisioning.h"
click node_webui "https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/webui.h"

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_signatures,node_user toneBlue
class node_runtime,node_config,node_indicators toneAmber
class node_provision,node_nvs,node_wifi toneMint
class node_webui,node_webhook,node_mqtt toneRose
class node_advertisers toneIndigo
```

## Components

### BLE Detection

- [Vendor signature rules](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/signatures.h): `firmware/signatures.h`

### Device Runtime

- [Firmware runtime](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/firmware.ino): `firmware/firmware.ino`
- [Detection and device settings](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/config.h): `firmware/config.h`
- **LED and buzzer**

### Setup and Network

- [Wi-Fi provisioning and reset](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/provisioning.h): `firmware/provisioning.h`
- **Credential storage**
- **Wi-Fi network**

### Status and Alerts

- [Read-only status page and API](https://github.com/paulloth1/esp32-smart-glass-canary/blob/main/firmware/webui.h): `firmware/webui.h`
- **Webhook receiver**
- **MQTT broker**

### Other components

- **Device user**
- **Nearby BLE advertisers**

## Connections

- Nearby BLE advertisers → Firmware runtime: advertise to
- Firmware runtime → Vendor signature rules: scores against
- Vendor signature rules → Detection and device settings: uses thresholds (evidence: `firmware/signatures.h`)
- Device user → Wi-Fi provisioning and reset: provides Wi-Fi (evidence: `README.md`)
- Wi-Fi provisioning and reset → Credential storage: loads and saves (evidence: `firmware/provisioning.h`)
- Firmware runtime → Wi-Fi provisioning and reset: loads settings
- Firmware runtime → Wi-Fi network: connects to
- Firmware runtime → LED and buzzer: signals alerts (evidence: `README.md`)
- Firmware runtime → MQTT broker: publishes alerts (evidence: `README.md`)
- Firmware runtime → Webhook receiver: posts alerts
- Firmware runtime → Read-only status page and API: serves status
- Read-only status page and API → Wi-Fi network: serves over (evidence: `firmware/webui.h`)
