# soyboitech/beacons architecture

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

- Interactive diagram: https://gitdiagram.com/soyboitech/beacons
- Repository: https://github.com/soyboitech/beacons

## Overview

Beacons is a passive surveillance-device detector spanning embedded firmware and iOS/Android clients. The main flow is board radio scanning and signature recognition, then detection logging and encrypted Bluetooth delivery to a phone for live viewing, history, maps, alerts, and optional user-initiated contribution. Firmware also supports signed updates and, on Mesh-Detect, Meshtastic alerts. The graph reflects documented and indexed relationships; unsampled app screens and firmware stages are represented only where README or tree evidence supports them.

Main entry points: [`firmware/lib/acab_core/acab_ble_service.cpp`](https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/acab_ble_service.cpp) (Encrypted BLE link), [`firmware/src/mesh-detect/main.cpp`](https://github.com/soyboitech/beacons/blob/main/firmware/src/mesh-detect/main.cpp) (Mesh runtime), [`ios/Beacons/Views`](https://github.com/soyboitech/beacons/tree/main/ios/Beacons/Views) (iOS app views), [`ios/Beacons/BLE/BLEManager.swift`](https://github.com/soyboitech/beacons/blob/main/ios/Beacons/BLE/BLEManager.swift) (iOS BLE manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Detector firmware"]
  node_scanner["Radio scanning<br/>[acab_scanner.cpp]"]
  node_recognizers["Detection signatures"]
  node_detection["Detection records<br/>[detection.h]"]
  node_detlog[("Offline log<br/>[det_log.cpp]")]
  node_ble_service["Encrypted BLE link"]
  node_beacon_main["Beacon runtime<br/>[main.cpp]"]
  node_mesh_main["Mesh runtime<br/>[main.cpp]"]
end

subgraph group_mobile["Mobile apps"]
  node_ios_ble["iOS BLE manager<br/>[BLEManager.swift]"]
  node_ios_detection["Detection model<br/>[Detection.swift]"]
  node_ios_views["iOS app views"]
  node_ios_map["Map and ALPR<br/>[MapTabView.swift]"]
  node_android_activity["Android app entry<br/>[MainActivity.kt]"]
  node_android_ble["Android BLE manager<br/>[AcabBleManager.kt]"]
  node_android_ui["Android app screens"]
  node_android_device["Device controls<br/>[DeviceScreen.kt]"]
end

subgraph group_updates["Firmware updates"]
  node_ios_updates["iOS update flows"]
  node_android_update["Android DFU"]
end

subgraph group_mesh["Mesh alerts"]
  node_mesh_link["Meshtastic transport<br/>[mesh_link.cpp]"]
end

node_owner(("Board user"))
node_phone_user(("Phone user"))
node_external_mesh["Meshtastic node"]

node_beacon_main -.->|"starts scanning"| node_scanner
node_mesh_main -.->|"starts scanning"| node_scanner
node_scanner -.->|"matches broadcasts"| node_recognizers
node_recognizers -.->|"creates detections"| node_detection
node_beacon_main -.->|"starts link"| node_ble_service
node_mesh_main -->|"starts link"| node_ble_service
node_ble_service -->|"replays history"| node_detlog
node_ble_service -->|"notifies detections"| node_detection
node_mesh_main -.->|"sends alerts"| node_mesh_link
node_mesh_link -.->|"transmits alerts"| node_external_mesh
node_phone_user -.->|"uses"| node_ios_views
node_phone_user -.->|"uses"| node_android_activity
node_ios_ble -->|"exchanges data"| node_ble_service
node_android_ble -.->|"exchanges data"| node_ble_service
node_ios_ble -->|"ingests sightings"| node_ios_detection
node_ios_ble -.->|"provides app state"| node_ios_views
node_ios_views -.->|"shows mapped detections"| node_ios_map
node_android_activity -->|"initializes manager"| node_android_ble
node_android_activity -->|"hosts app"| node_android_ui
node_android_ui -.->|"shows controls"| node_android_device
node_android_ble -.->|"exchanges data"| node_ble_service
node_ios_views -.->|"requests updates"| node_ios_updates
node_android_device -.->|"requests updates"| node_android_update
node_ios_updates -->|"updates board"| node_ble_service
node_android_update -.->|"updates board"| node_ble_service
node_owner -.->|"operates board"| node_beacon_main
node_owner -.->|"operates board"| node_mesh_main

click node_scanner "https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/acab_scanner.cpp"
click node_recognizers "https://github.com/soyboitech/beacons/tree/main/firmware/lib/acab_core"
click node_detection "https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/detection.h"
click node_detlog "https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/det_log.cpp"
click node_ble_service "https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/acab_ble_service.cpp"
click node_beacon_main "https://github.com/soyboitech/beacons/blob/main/firmware/src/beacon-board/main.cpp"
click node_mesh_main "https://github.com/soyboitech/beacons/blob/main/firmware/src/mesh-detect/main.cpp"
click node_mesh_link "https://github.com/soyboitech/beacons/blob/main/firmware/src/mesh-detect/mesh_link.cpp"
click node_ios_ble "https://github.com/soyboitech/beacons/blob/main/ios/Beacons/BLE/BLEManager.swift"
click node_ios_detection "https://github.com/soyboitech/beacons/blob/main/ios/Beacons/Models/Detection.swift"
click node_ios_views "https://github.com/soyboitech/beacons/tree/main/ios/Beacons/Views"
click node_ios_map "https://github.com/soyboitech/beacons/blob/main/ios/Beacons/Views/MapTabView.swift"
click node_ios_updates "https://github.com/soyboitech/beacons/blob/main/ios/Beacons/BLE/BLEManager%2BOTA.swift"
click node_android_activity "https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/MainActivity.kt"
click node_android_ble "https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/ble/AcabBleManager.kt"
click node_android_ui "https://github.com/soyboitech/beacons/tree/main/android/app/src/main/java/tech/acab/app/ui"
click node_android_device "https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/ui/DeviceScreen.kt"
click node_android_update "https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/ble/NrfDfuCoordinator.kt"

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_scanner,node_recognizers,node_detection,node_detlog,node_ble_service,node_beacon_main,node_mesh_main,node_owner,node_phone_user toneBlue
class node_ios_ble,node_ios_detection,node_ios_views,node_ios_map,node_android_activity,node_android_ble,node_android_ui,node_android_device toneAmber
class node_ios_updates,node_android_update toneMint
class node_mesh_link toneRose
class node_external_mesh toneIndigo
```

## Components

### Detector firmware

- [Radio scanning](https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/acab_scanner.cpp): `firmware/lib/acab_core/acab_scanner.cpp`
- [Detection signatures](https://github.com/soyboitech/beacons/tree/main/firmware/lib/acab_core): `firmware/lib/acab_core`
- [Detection records](https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/detection.h): `firmware/lib/acab_core/detection.h`
- [Offline log](https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/det_log.cpp): `firmware/lib/acab_core/det_log.cpp`
- [Encrypted BLE link](https://github.com/soyboitech/beacons/blob/main/firmware/lib/acab_core/acab_ble_service.cpp): `firmware/lib/acab_core/acab_ble_service.cpp`
- [Beacon runtime](https://github.com/soyboitech/beacons/blob/main/firmware/src/beacon-board/main.cpp): `firmware/src/beacon-board/main.cpp`
- [Mesh runtime](https://github.com/soyboitech/beacons/blob/main/firmware/src/mesh-detect/main.cpp): `firmware/src/mesh-detect/main.cpp`

### Mobile apps

- [iOS BLE manager](https://github.com/soyboitech/beacons/blob/main/ios/Beacons/BLE/BLEManager.swift): `ios/Beacons/BLE/BLEManager.swift`
- [Detection model](https://github.com/soyboitech/beacons/blob/main/ios/Beacons/Models/Detection.swift): `ios/Beacons/Models/Detection.swift`
- [iOS app views](https://github.com/soyboitech/beacons/tree/main/ios/Beacons/Views): `ios/Beacons/Views`
- [Map and ALPR](https://github.com/soyboitech/beacons/blob/main/ios/Beacons/Views/MapTabView.swift): `ios/Beacons/Views/MapTabView.swift`
- [Android app entry](https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/MainActivity.kt): `android/app/src/main/java/tech/acab/app/MainActivity.kt`
- [Android BLE manager](https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/ble/AcabBleManager.kt): `android/app/src/main/java/tech/acab/app/ble/AcabBleManager.kt`
- [Android app screens](https://github.com/soyboitech/beacons/tree/main/android/app/src/main/java/tech/acab/app/ui): `android/app/src/main/java/tech/acab/app/ui`
- [Device controls](https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/ui/DeviceScreen.kt): `android/app/src/main/java/tech/acab/app/ui/DeviceScreen.kt`

### Firmware updates

- [iOS update flows](https://github.com/soyboitech/beacons/blob/main/ios/Beacons/BLE/BLEManager%2BOTA.swift): `ios/Beacons/BLE/BLEManager+OTA.swift`
- [Android DFU](https://github.com/soyboitech/beacons/blob/main/android/app/src/main/java/tech/acab/app/ble/NrfDfuCoordinator.kt): `android/app/src/main/java/tech/acab/app/ble/NrfDfuCoordinator.kt`

### Mesh alerts

- [Meshtastic transport](https://github.com/soyboitech/beacons/blob/main/firmware/src/mesh-detect/mesh_link.cpp): `firmware/src/mesh-detect/mesh_link.cpp`

### Other components

- **Board user**
- **Phone user**
- **Meshtastic node**

## Connections

- Beacon runtime → Radio scanning: starts scanning (evidence: `firmware/src/beacon-board/main.cpp`)
- Mesh runtime → Radio scanning: starts scanning (evidence: `firmware/src/mesh-detect/main.cpp`)
- Radio scanning → Detection signatures: matches broadcasts
- Detection signatures → Detection records: creates detections (evidence: `firmware/lib/acab_core/acab_ble_service.h`)
- Beacon runtime → Encrypted BLE link: starts link (evidence: `firmware/src/beacon-board/main.cpp`)
- Mesh runtime → Encrypted BLE link: starts link (evidence: `firmware/src/mesh-detect/main.cpp`)
- Encrypted BLE link → Offline log: replays history
- Encrypted BLE link → Detection records: notifies detections
- Mesh runtime → Meshtastic transport: sends alerts (evidence: `firmware/src/mesh-detect/main.cpp`)
- Meshtastic transport → Meshtastic node: transmits alerts
- Phone user → iOS app views: uses
- Phone user → Android app entry: uses
- iOS BLE manager → Encrypted BLE link: exchanges data
- Android BLE manager → Encrypted BLE link: exchanges data
- iOS BLE manager → Detection model: ingests sightings (evidence: `ios/Beacons/BLE/BLEManager.swift`)
- iOS BLE manager → iOS app views: provides app state
- iOS app views → Map and ALPR: shows mapped detections
- Android app entry → Android BLE manager: initializes manager (evidence: `android/app/src/main/java/tech/acab/app/MainActivity.kt`)
- Android app entry → Android app screens: hosts app (evidence: `android/app/src/main/java/tech/acab/app/MainActivity.kt`)
- Android app screens → Device controls: shows controls
- Android BLE manager → Encrypted BLE link: exchanges data
- iOS app views → iOS update flows: requests updates
- Device controls → Android DFU: requests updates
- iOS update flows → Encrypted BLE link: updates board
- Android DFU → Encrypted BLE link: updates board
- Board user → Beacon runtime: operates board
- Board user → Mesh runtime: operates board
