# ideagrey/millie architecture

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

- Interactive diagram: https://gitdiagram.com/ideagrey/millie
- Repository: https://github.com/ideagrey/millie

## Overview

MILLIE combines an Android field unit for passive WiFi/BLE surveillance with an optional ESP32 CYD sniffer and a Raspberry Pi component that can scan locally, ingest sensor data, sync with the phone, and expose a hub dashboard. The main workflow is signal capture, transfer to the phone, and live device/radar presentation; the Pi also archives phone snapshots and sensor events. The README documents phone capabilities not represented in sampled Android source, so those branches are shown at the app level. Evidence for unsampled implementations and wiring is limited to the README and SOURCE INDEX.

Main entry points: [`millie-pi/millie_pi/__main__.py`](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/__main__.py) (Pi runtime entry), [`millie-pi/millie_pi/hub_server.py`](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/hub_server.py) (Hub API), [`millie-pi/millie_pi/phone_client.py`](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/phone_client.py) (Phone API client), [`millie-pi/millie_pi/sync_worker.py`](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/sync_worker.py) (Phone and ESP sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_phone["Android field unit"]
  node_phone_app["MILLIE phone app<br/>[MILLIE CYD.ino]"]
  node_phone_capture["Phone detection<br/>[MILLIE CYD.ino]"]
  node_classification["Device classification<br/>[MILLIE CYD.ino]"]
  node_radar["Radar and details<br/>[MILLIE CYD.ino]"]
  node_phone_export["Export and protection<br/>[MILLIE CYD.ino]"]
end

subgraph group_pi_sensor["Pi sensing"]
  node_pi_cli["Pi runtime entry<br/>[__main__.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_active_node["Active RF node<br/>[active_node.py]"]
  node_rf_scanner["WiFi and BLE scanner<br/>[rf_scanner.py]"]
  node_rf_script["RF scan script<br/>[rf-scan.sh]"]
end

subgraph group_pi_hub["Pi hub"]
  node_phone_client["Phone API client<br/>[phone_client.py]"]
  node_sync_worker["Phone and ESP sync<br/>[sync_worker.py]"]
  node_esp_reader["CYD serial reader<br/>[esp_reader.py]"]
  node_storage[("Hub archive<br/>[storage.py]")]
  node_hub_server["Hub API<br/>[hub_server.py]"]
  node_hub_page["Hub dashboard<br/>[hub.html]"]
end

subgraph group_hardware["External sensors"]
  node_cyd["ESP32 CYD<br/>[MILLIE CYD.ino]"]
end

node_field_user(("Field user"))
node_browser(("Dashboard user"))

node_field_user -->|"uses"| node_phone_app
node_phone_app -->|"captures signals"| node_phone_capture
node_phone_capture -->|"classifies devices"| node_classification
node_classification -->|"displays findings"| node_radar
node_phone_app -->|"offers"| node_phone_export
node_pi_cli -->|"loads"| node_config
node_pi_cli -->|"starts"| node_active_node
node_pi_cli -->|"creates"| node_phone_client
node_pi_cli -->|"runs diagnostics"| node_rf_scanner
node_active_node -->|"scans and drains"| node_rf_scanner
node_active_node -->|"pushes events"| node_phone_client
node_rf_scanner -->|"invokes"| node_rf_script
node_sync_worker -->|"fetches phone data"| node_phone_client
node_sync_worker -->|"archives sync data"| node_storage
node_sync_worker -->|"starts optional ingest"| node_esp_reader
node_esp_reader -->|"delivers sensor events"| node_storage
node_hub_server -->|"reads hub data"| node_storage
node_hub_server -->|"proxies commands"| node_phone_client
node_hub_server -->|"serves"| node_hub_page
node_browser -.->|"requests dashboard"| node_hub_server
node_cyd -->|"captures hidden probes"| node_phone_capture
node_browser -.->|"views"| node_hub_page

click node_phone_app "https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino"
click node_phone_capture "https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino"
click node_classification "https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino"
click node_radar "https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino"
click node_phone_export "https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino"
click node_pi_cli "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/__main__.py"
click node_config "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/config.py"
click node_active_node "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/active_node.py"
click node_rf_scanner "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/rf_scanner.py"
click node_rf_script "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/rf-scan.sh"
click node_phone_client "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/phone_client.py"
click node_sync_worker "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/sync_worker.py"
click node_esp_reader "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/esp_reader.py"
click node_storage "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/storage.py"
click node_hub_server "https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/hub_server.py"
click node_hub_page "https://github.com/ideagrey/millie/blob/main/millie-pi/static/hub.html"
click node_cyd "https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.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_phone_app,node_phone_capture,node_classification,node_radar,node_phone_export,node_field_user,node_browser toneBlue
class node_pi_cli,node_config,node_active_node,node_rf_scanner,node_rf_script toneAmber
class node_phone_client,node_sync_worker,node_esp_reader,node_storage,node_hub_server,node_hub_page toneMint
class node_cyd toneRose
```

## Components

### Android field unit

- [MILLIE phone app](https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino): `MILLIE CYD.ino`
- [Phone detection](https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino): `MILLIE CYD.ino`
- [Device classification](https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino): `MILLIE CYD.ino`
- [Radar and details](https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino): `MILLIE CYD.ino`
- [Export and protection](https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino): `MILLIE CYD.ino`

### Pi sensing

- [Pi runtime entry](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/__main__.py): `millie-pi/millie_pi/__main__.py`
- [Configuration](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/config.py): `millie-pi/millie_pi/config.py`
- [Active RF node](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/active_node.py): `millie-pi/millie_pi/active_node.py`
- [WiFi and BLE scanner](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/rf_scanner.py): `millie-pi/millie_pi/rf_scanner.py`
- [RF scan script](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/rf-scan.sh): `millie-pi/millie_pi/rf-scan.sh`

### Pi hub

- [Phone API client](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/phone_client.py): `millie-pi/millie_pi/phone_client.py`
- [Phone and ESP sync](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/sync_worker.py): `millie-pi/millie_pi/sync_worker.py`
- [CYD serial reader](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/esp_reader.py): `millie-pi/millie_pi/esp_reader.py`
- [Hub archive](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/storage.py): `millie-pi/millie_pi/storage.py`
- [Hub API](https://github.com/ideagrey/millie/blob/main/millie-pi/millie_pi/hub_server.py): `millie-pi/millie_pi/hub_server.py`
- [Hub dashboard](https://github.com/ideagrey/millie/blob/main/millie-pi/static/hub.html): `millie-pi/static/hub.html`

### External sensors

- [ESP32 CYD](https://github.com/ideagrey/millie/blob/main/MILLIE%20CYD.ino): `MILLIE CYD.ino`

### Other components

- **Field user**
- **Dashboard user**

## Connections

- Field user → MILLIE phone app: uses (evidence: `README`)
- MILLIE phone app → Phone detection: captures signals (evidence: `README`)
- Phone detection → Device classification: classifies devices (evidence: `README`)
- Device classification → Radar and details: displays findings (evidence: `README`)
- MILLIE phone app → Export and protection: offers (evidence: `README`)
- Pi runtime entry → Configuration: loads (evidence: `millie-pi/millie_pi/__main__.py`)
- Pi runtime entry → Active RF node: starts (evidence: `millie-pi/millie_pi/__main__.py`)
- Pi runtime entry → Phone API client: creates (evidence: `millie-pi/millie_pi/__main__.py`)
- Pi runtime entry → WiFi and BLE scanner: runs diagnostics (evidence: `millie-pi/millie_pi/__main__.py`)
- Active RF node → WiFi and BLE scanner: scans and drains (evidence: `millie-pi/millie_pi/active_node.py`)
- Active RF node → Phone API client: pushes events (evidence: `millie-pi/millie_pi/active_node.py`)
- WiFi and BLE scanner → RF scan script: invokes (evidence: `millie-pi/millie_pi/rf_scanner.py`)
- Phone and ESP sync → Phone API client: fetches phone data (evidence: `millie-pi/millie_pi/sync_worker.py`)
- Phone and ESP sync → Hub archive: archives sync data (evidence: `millie-pi/millie_pi/sync_worker.py`)
- Phone and ESP sync → CYD serial reader: starts optional ingest (evidence: `millie-pi/millie_pi/sync_worker.py`)
- CYD serial reader → Hub archive: delivers sensor events (evidence: `millie-pi/millie_pi/sync_worker.py`)
- Hub API → Hub archive: reads hub data (evidence: `millie-pi/millie_pi/hub_server.py`)
- Hub API → Phone API client: proxies commands (evidence: `millie-pi/millie_pi/hub_server.py`)
- Hub API → Hub dashboard: serves (evidence: `millie-pi/millie_pi/hub_server.py`)
- Dashboard user → Hub API: requests dashboard
- ESP32 CYD → Phone detection: captures hidden probes (evidence: `README`)
- Dashboard user → Hub dashboard: views
