# polarpatch/bluewatch-cyd-radar architecture

> Architecture diagram of the GitHub repository polarpatch/bluewatch-cyd-radar, 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/polarpatch/bluewatch-cyd-radar
- Repository: https://github.com/polarpatch/bluewatch-cyd-radar

## Overview

BlueWatch CYD Radar is ESP32 display firmware for viewing nearby devices from a BlueWatch server, with local BLE scanning as a fallback. The user workflow is touch-driven: browse a filtered device list, open a device’s details, or switch to a live signal radar. The firmware fetches list, detail, and radar data over Wi-Fi, or adapts local scan results for the same views. Board-specific headers supply display and touch hardware support. The excerpts show the central implementation, but not all of its refresh and rendering code; uncertain internal links are omitted.

Main entry points: [`src/main.cpp`](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp) (Firmware controller), [`src/ble_scan.cpp`](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/ble_scan.cpp) (BLE scanner), [`src/config.example.h`](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/config.example.h) (Runtime configuration), [`include/board_2432s028.h`](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/include/board_2432s028.h) (2432S028 support)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_views["Device Views"]
  node_list["Device list<br/>[main.cpp]"]
  node_details["Device details<br/>[main.cpp]"]
  node_radar["Live radar<br/>[main.cpp]"]
end

subgraph group_sources["Data Sources"]
  node_server{{"BlueWatch server"}}
  node_local_adapter["Local scan adapter<br/>[main.cpp]"]
  node_scanner["BLE scanner<br/>[ble_scan.cpp]"]
  node_classifier["Lite classifier<br/>[ble_scan.cpp]"]
  node_scan_table[("Scan table<br/>[ble_scan.cpp]")]
end

subgraph group_firmware["Firmware Core"]
  node_controller["Firmware controller<br/>[main.cpp]"]
  node_filters["View filters<br/>[main.cpp]"]
  node_preferences["Saved preferences<br/>[main.cpp]"]
  node_config["Runtime configuration<br/>[config.example.h]"]
end

subgraph group_hardware["Board Hardware"]
  node_board_small["2432S028 support<br/>[board_2432s028.h]"]
  node_board_large["3248S035C support<br/>[board_3248s035c.h]"]
end

node_user(("Board user"))

node_user -->|"touches"| node_controller
node_controller -->|"fetches list"| node_server
node_controller -->|"fetches details"| node_server
node_controller -->|"fetches radar"| node_server
node_controller -->|"builds local data"| node_local_adapter
node_local_adapter -->|"reads snapshots"| node_scanner
node_scanner -->|"classifies advertisements"| node_classifier
node_scanner -->|"updates"| node_scan_table
node_controller -->|"renders"| node_list
node_controller -->|"renders"| node_details
node_controller -->|"renders"| node_radar
node_controller -->|"applies"| node_filters
node_filters -->|"persists"| node_preferences
node_controller -.->|"uses"| node_board_small
node_controller -.->|"uses"| node_board_large
node_controller -.->|"reads settings"| node_config

click node_controller "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp"
click node_list "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp"
click node_details "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp"
click node_radar "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp"
click node_filters "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp"
click node_preferences "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp"
click node_local_adapter "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp"
click node_scanner "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/ble_scan.cpp"
click node_classifier "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/ble_scan.cpp"
click node_scan_table "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/ble_scan.cpp"
click node_board_small "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/include/board_2432s028.h"
click node_board_large "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/include/board_3248s035c.h"
click node_config "https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/config.example.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_list,node_details,node_radar,node_user toneBlue
class node_server,node_local_adapter,node_scanner,node_classifier,node_scan_table toneAmber
class node_controller,node_filters,node_preferences,node_config toneMint
class node_board_small,node_board_large toneRose
```

## Components

### Device Views

- [Device list](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp): `src/main.cpp`
- [Device details](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp): `src/main.cpp`
- [Live radar](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp): `src/main.cpp`

### Data Sources

- **BlueWatch server**
- [Local scan adapter](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp): `src/main.cpp`
- [BLE scanner](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/ble_scan.cpp): `src/ble_scan.cpp`
- [Lite classifier](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/ble_scan.cpp): `src/ble_scan.cpp`
- [Scan table](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/ble_scan.cpp): `src/ble_scan.cpp`

### Firmware Core

- [Firmware controller](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp): `src/main.cpp`
- [View filters](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp): `src/main.cpp`
- [Saved preferences](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/main.cpp): `src/main.cpp`
- [Runtime configuration](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/src/config.example.h): `src/config.example.h`

### Board Hardware

- [2432S028 support](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/include/board_2432s028.h): `include/board_2432s028.h`
- [3248S035C support](https://github.com/polarpatch/bluewatch-cyd-radar/blob/main/include/board_3248s035c.h): `include/board_3248s035c.h`

### Other components

- **Board user**

## Connections

- Board user → Firmware controller: touches (evidence: `README.md`)
- Firmware controller → BlueWatch server: fetches list (evidence: `src/main.cpp`)
- Firmware controller → BlueWatch server: fetches details (evidence: `src/main.cpp`)
- Firmware controller → BlueWatch server: fetches radar (evidence: `src/main.cpp`)
- Firmware controller → Local scan adapter: builds local data (evidence: `src/main.cpp`)
- Local scan adapter → BLE scanner: reads snapshots (evidence: `src/main.cpp`)
- BLE scanner → Lite classifier: classifies advertisements (evidence: `src/ble_scan.cpp`)
- BLE scanner → Scan table: updates (evidence: `src/ble_scan.cpp`)
- Firmware controller → Device list: renders (evidence: `README.md`)
- Firmware controller → Device details: renders (evidence: `README.md`)
- Firmware controller → Live radar: renders (evidence: `README.md`)
- Firmware controller → View filters: applies (evidence: `src/main.cpp`)
- View filters → Saved preferences: persists (evidence: `src/main.cpp`)
- Firmware controller → 2432S028 support: uses (evidence: `src/main.cpp`)
- Firmware controller → 3248S035C support: uses (evidence: `src/main.cpp`)
- Firmware controller → Runtime configuration: reads settings
