# zanebeeai/wallhacks architecture

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

- Interactive diagram: https://gitdiagram.com/zanebeeai/wallhacks
- Repository: https://github.com/zanebeeai/wallhacks

## Overview

Wallhacks is a multi-sensor mmWave system whose main user workflow runs from radar detections through host-side fusion and tracking to live WebXR target pings and a confidence heatmap. The documented multi-headset mode adds master/slave registration and pose alignment. The graph emphasizes that deployment path while retaining the hardware host tooling and radar test utility. Some firmware and frontend details are documented but not sampled; their links are based on README statements, not source inspection.

Main entry points: [`hardware/wyfyre_array_mvp/python/main.py`](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/main.py) (Host runtime), [`hardware/wyfyre_array_mvp/python/fusion.py`](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/fusion.py) (Coordinate fusion), [`AR_tailscale_multi/server.py`](https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/server.py) (Multi-headset server), [`AR_tailscale_multi/index.html`](https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/index.html) (WebXR client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Radar hardware"]
  node_radars["Five-radar array"]
  node_node_a["ESP32 node A"]
  node_node_b["ESP32 node B"]
end

subgraph group_host["Host processing"]
  node_host_main["Host runtime<br/>[main.py]"]
  node_serial_rx["Serial receiver"]
  node_udp_rx["UDP receiver<br/>[transport_udp.py]"]
  node_dataset_logger["Dataset logger<br/>[dataset_logger.py]"]
  node_webcam["Webcam capture<br/>[webcam_stub.py]"]
end

subgraph group_fusion["Fusion pipeline"]
  node_config["Geometry and calibration<br/>[config_loader.py]"]
  node_models["Detection and track models<br/>[models.py]"]
  node_fusion["Coordinate fusion<br/>[fusion.py]"]
  node_tracking["Clustering and tracking<br/>[fusion.py]"]
  node_heatmap["Confidence heatmap<br/>[fusion.py]"]
  node_cv_feedback["CV feedback adapter<br/>[cv_feedback.py]"]
end

subgraph group_ar["AR collaboration"]
  node_ar_server["Multi-headset server<br/>[server.py]"]
  node_ar_fusion["AR fusion engine<br/>[fusion.py]"]
  node_ar_client["WebXR client<br/>[index.html]"]
end

subgraph group_diagnostics["Calibration and diagnostics"]
  node_calibrate["Calibration tool<br/>[calibrate.py]"]
  node_ld2450_test["LD2450 test interface<br/>[mapping.py]"]
  node_ld2450_protocol["LD2450 serial protocol<br/>[serial_protocol.py]"]
end

node_user(("Headset user"))

node_radars -->|"provide detections"| node_node_a
node_radars -->|"provide detections"| node_node_b
node_node_b -->|"relay via ESP-NOW"| node_node_a
node_node_a -->|"send JSON lines"| node_serial_rx
node_host_main -->|"starts receiver"| node_serial_rx
node_host_main -->|"selects transport"| node_udp_rx
node_host_main -->|"loads settings"| node_config
node_host_main -->|"processes detections"| node_fusion
node_host_main -->|"logs sessions"| node_dataset_logger
node_host_main -->|"captures video"| node_webcam
node_fusion -->|"reads geometry"| node_config
node_fusion -->|"creates results"| node_models
node_fusion -->|"associates tracks"| node_tracking
node_fusion -->|"builds occupancy"| node_heatmap
node_fusion -->|"adjusts confidence"| node_cv_feedback
node_host_main -.->|"serves live application"| node_ar_server
node_ar_server -->|"processes radar stream"| node_ar_fusion
node_ar_server -->|"streams WebSocket frames"| node_ar_client
node_user -->|"views AR and radar"| node_ar_client
node_ar_client -->|"registers role and pose"| node_ar_server
node_ar_server -->|"relays master pose"| node_ar_client
node_calibrate -->|"uses configuration"| node_config
node_ld2450_test -->|"uses serial protocol"| node_ld2450_protocol

click node_node_a "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/firmware/esp32_array_node_a/esp32_array_node_a.ino"
click node_node_b "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/firmware/esp32_array_node_b/esp32_array_node_b.ino"
click node_host_main "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/main.py"
click node_serial_rx "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/transport_serial.py"
click node_udp_rx "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/transport_udp.py"
click node_config "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/config_loader.py"
click node_models "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/models.py"
click node_fusion "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/fusion.py"
click node_tracking "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/fusion.py"
click node_heatmap "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/fusion.py"
click node_cv_feedback "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/cv_feedback.py"
click node_dataset_logger "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/dataset_logger.py"
click node_webcam "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/webcam_stub.py"
click node_ar_server "https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/server.py"
click node_ar_fusion "https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/fusion.py"
click node_ar_client "https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/index.html"
click node_calibrate "https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/calibrate.py"
click node_ld2450_test "https://github.com/zanebeeai/wallhacks/blob/main/hardware/ld2450_test/mapping.py"
click node_ld2450_protocol "https://github.com/zanebeeai/wallhacks/blob/main/hardware/ld2450_test/serial_protocol.py"

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_radars,node_node_a,node_node_b,node_user toneBlue
class node_host_main,node_serial_rx,node_udp_rx,node_dataset_logger,node_webcam toneAmber
class node_config,node_models,node_fusion,node_tracking,node_heatmap,node_cv_feedback toneMint
class node_ar_server,node_ar_fusion,node_ar_client toneRose
class node_calibrate,node_ld2450_test,node_ld2450_protocol toneIndigo
```

## Components

### Radar hardware

- **Five-radar array**
- [ESP32 node A](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/firmware/esp32_array_node_a/esp32_array_node_a.ino): `hardware/wyfyre_array_mvp/firmware/esp32_array_node_a/esp32_array_node_a.ino`
- [ESP32 node B](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/firmware/esp32_array_node_b/esp32_array_node_b.ino): `hardware/wyfyre_array_mvp/firmware/esp32_array_node_b/esp32_array_node_b.ino`

### Host processing

- [Host runtime](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/main.py): `hardware/wyfyre_array_mvp/python/main.py`
- [Serial receiver](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/transport_serial.py): `hardware/wyfyre_array_mvp/python/transport_serial.py`
- [UDP receiver](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/transport_udp.py): `hardware/wyfyre_array_mvp/python/transport_udp.py`
- [Dataset logger](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/dataset_logger.py): `hardware/wyfyre_array_mvp/python/dataset_logger.py`
- [Webcam capture](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/webcam_stub.py): `hardware/wyfyre_array_mvp/python/webcam_stub.py`

### Fusion pipeline

- [Geometry and calibration](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/config_loader.py): `hardware/wyfyre_array_mvp/python/config_loader.py`
- [Detection and track models](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/models.py): `hardware/wyfyre_array_mvp/python/models.py`
- [Coordinate fusion](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/fusion.py): `hardware/wyfyre_array_mvp/python/fusion.py`
- [Clustering and tracking](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/fusion.py): `hardware/wyfyre_array_mvp/python/fusion.py`
- [Confidence heatmap](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/fusion.py): `hardware/wyfyre_array_mvp/python/fusion.py`
- [CV feedback adapter](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/cv_feedback.py): `hardware/wyfyre_array_mvp/python/cv_feedback.py`

### AR collaboration

- [Multi-headset server](https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/server.py): `AR_tailscale_multi/server.py`
- [AR fusion engine](https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/fusion.py): `AR_tailscale_multi/fusion.py`
- [WebXR client](https://github.com/zanebeeai/wallhacks/blob/main/AR_tailscale_multi/index.html): `AR_tailscale_multi/index.html`

### Calibration and diagnostics

- [Calibration tool](https://github.com/zanebeeai/wallhacks/blob/main/hardware/wyfyre_array_mvp/python/calibrate.py): `hardware/wyfyre_array_mvp/python/calibrate.py`
- [LD2450 test interface](https://github.com/zanebeeai/wallhacks/blob/main/hardware/ld2450_test/mapping.py): `hardware/ld2450_test/mapping.py`
- [LD2450 serial protocol](https://github.com/zanebeeai/wallhacks/blob/main/hardware/ld2450_test/serial_protocol.py): `hardware/ld2450_test/serial_protocol.py`

### Other components

- **Headset user**

## Connections

- Five-radar array → ESP32 node A: provide detections (evidence: `README.md`)
- Five-radar array → ESP32 node B: provide detections (evidence: `README.md`)
- ESP32 node B → ESP32 node A: relay via ESP-NOW (evidence: `README.md`)
- ESP32 node A → Serial receiver: send JSON lines (evidence: `README.md`)
- Host runtime → Serial receiver: starts receiver (evidence: `hardware/wyfyre_array_mvp/python/main.py`)
- Host runtime → UDP receiver: selects transport (evidence: `hardware/wyfyre_array_mvp/python/main.py`)
- Host runtime → Geometry and calibration: loads settings (evidence: `hardware/wyfyre_array_mvp/python/main.py`)
- Host runtime → Coordinate fusion: processes detections (evidence: `hardware/wyfyre_array_mvp/python/main.py`)
- Host runtime → Dataset logger: logs sessions (evidence: `hardware/wyfyre_array_mvp/python/main.py`)
- Host runtime → Webcam capture: captures video (evidence: `hardware/wyfyre_array_mvp/python/main.py`)
- Coordinate fusion → Geometry and calibration: reads geometry (evidence: `hardware/wyfyre_array_mvp/python/fusion.py`)
- Coordinate fusion → Detection and track models: creates results
- Coordinate fusion → Clustering and tracking: associates tracks (evidence: `hardware/wyfyre_array_mvp/python/fusion.py`)
- Coordinate fusion → Confidence heatmap: builds occupancy (evidence: `hardware/wyfyre_array_mvp/python/fusion.py`)
- Coordinate fusion → CV feedback adapter: adjusts confidence (evidence: `hardware/wyfyre_array_mvp/python/fusion.py`)
- Host runtime → Multi-headset server: serves live application
- Multi-headset server → AR fusion engine: processes radar stream (evidence: `AR_tailscale_multi/server.py`)
- Multi-headset server → WebXR client: streams WebSocket frames (evidence: `README.md`)
- Headset user → WebXR client: views AR and radar (evidence: `README.md`)
- WebXR client → Multi-headset server: registers role and pose (evidence: `AR_tailscale_multi/server.py`)
- Multi-headset server → WebXR client: relays master pose (evidence: `README.md`)
- Calibration tool → Geometry and calibration: uses configuration
- LD2450 test interface → LD2450 serial protocol: uses serial protocol (evidence: `hardware/ld2450_test/mapping.py`)
