# hieupeakday0109-ai/scann-the-device architecture

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

- Interactive diagram: https://gitdiagram.com/hieupeakday0109-ai/scann-the-device
- Repository: https://github.com/hieupeakday0109-ai/scann-the-device

## Overview

FieldWatch is a Windows desktop RF situational-awareness monitor. The user launches the Qt interface, which starts BLE scanning and periodically polls Wi-Fi; BLE advertisements are decoded and fed into alerting, storage, optional CoT broadcast, and a selected-device proximity radar. GPS supplies coordinates for observations. The README also documents GeoJSON/CSV reporting and CoT interoperability. The graph follows the sampled UI wiring and scanner/parser calls; unsampled implementation details are represented only where the README documents the capability.

Main entry points: [`ui/main_window.py`](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/ui/main_window.py) (Monitoring UI), [`core/ble/scanner.py`](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/ble/scanner.py) (BLE Scanner), [`core/location/gps_serial.py`](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/location/gps_serial.py) (Serial NMEA GPS), [`main.py`](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/main.py) (Application Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Interface"]
  node_entry["Application Entry<br/>[main.py]"]
  node_window["Monitoring UI<br/>[main_window.py]"]
  node_theme["Tactical Styling<br/>[styles.py]"]
end

subgraph group_sensing["RF &amp; Location Sensing"]
  node_ble["BLE Scanner<br/>[scanner.py]"]
  node_decoder["Advertisement Decoder<br/>[parsers.py]"]
  node_wifi["Native Wi-Fi Scanner<br/>[native_wifi.py]"]
  node_gps["Serial NMEA GPS<br/>[gps_serial.py]"]
end

subgraph group_analysis["Detection &amp; Tracking"]
  node_alerts["Threat Detection<br/>[alert_engine.py]"]
  node_radar["Proximity Radar<br/>[radar_tracker.py]"]
end

subgraph group_outputs["Persistence &amp; Interoperability"]
  node_database[("Signal Store &amp; Export<br/>[storage.py]")]
  node_cot["CoT Broadcaster<br/>[cot_broadcaster.py]"]
end

node_operator(("Field Operator"))
node_windows{{"Windows Radio &amp; Serial Devices"}}
node_tak(("WinTAK / ATAK"))

node_operator -->|"launches"| node_entry
node_entry -->|"runs"| node_window
node_window -->|"applies stylesheet"| node_theme
node_window -->|"starts scanner"| node_ble
node_ble -->|"decodes payload"| node_decoder
node_ble -->|"reports advertisements"| node_window
node_window -->|"polls networks"| node_wifi
node_window -->|"reads coordinates"| node_gps
node_window -->|"selects serial port"| node_gps
node_windows -.->|"provides radio data"| node_ble
node_windows -.->|"provides radio data"| node_wifi
node_windows -.->|"provides NMEA stream"| node_gps
node_window -->|"registers packets"| node_alerts
node_window -->|"updates selected target"| node_radar
node_window -->|"writes observations"| node_database
node_window -->|"requests exports"| node_database
node_window -->|"broadcasts detected targets"| node_cot
node_cot -->|"sends CoT multicast"| node_tak

click node_entry "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/main.py"
click node_window "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/ui/main_window.py"
click node_theme "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/ui/styles.py"
click node_ble "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/ble/scanner.py"
click node_decoder "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/ble/parsers.py"
click node_wifi "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/wifi/native_wifi.py"
click node_gps "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/location/gps_serial.py"
click node_alerts "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/engine/alert_engine.py"
click node_radar "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/engine/radar_tracker.py"
click node_database "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/export/storage.py"
click node_cot "https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/export/cot_broadcaster.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_entry,node_window,node_theme toneBlue
class node_ble,node_decoder,node_wifi,node_gps toneAmber
class node_alerts,node_radar toneMint
class node_database,node_cot toneRose
class node_operator,node_windows,node_tak toneIndigo
```

## Components

### Desktop Interface

- [Application Entry](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/main.py): `main.py`
- [Monitoring UI](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/ui/main_window.py): `ui/main_window.py`
- [Tactical Styling](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/ui/styles.py): `ui/styles.py`

### RF & Location Sensing

- [BLE Scanner](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/ble/scanner.py): `core/ble/scanner.py`
- [Advertisement Decoder](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/ble/parsers.py): `core/ble/parsers.py`
- [Native Wi-Fi Scanner](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/wifi/native_wifi.py): `core/wifi/native_wifi.py`
- [Serial NMEA GPS](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/location/gps_serial.py): `core/location/gps_serial.py`

### Detection & Tracking

- [Threat Detection](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/engine/alert_engine.py): `core/engine/alert_engine.py`
- [Proximity Radar](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/engine/radar_tracker.py): `core/engine/radar_tracker.py`

### Persistence & Interoperability

- [Signal Store & Export](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/export/storage.py): `core/export/storage.py`
- [CoT Broadcaster](https://github.com/hieupeakday0109-ai/scann-the-device/blob/main/core/export/cot_broadcaster.py): `core/export/cot_broadcaster.py`

### Other components

- **Field Operator**
- **Windows Radio & Serial Devices**
- **WinTAK / ATAK**

## Connections

- Field Operator → Application Entry: launches (evidence: `README.md`)
- Application Entry → Monitoring UI: runs (evidence: `main.py`)
- Monitoring UI → Tactical Styling: applies stylesheet (evidence: `ui/main_window.py`)
- Monitoring UI → BLE Scanner: starts scanner (evidence: `ui/main_window.py`)
- BLE Scanner → Advertisement Decoder: decodes payload (evidence: `core/ble/scanner.py`)
- BLE Scanner → Monitoring UI: reports advertisements (evidence: `ui/main_window.py`)
- Monitoring UI → Native Wi-Fi Scanner: polls networks (evidence: `ui/main_window.py`)
- Monitoring UI → Serial NMEA GPS: reads coordinates (evidence: `ui/main_window.py`)
- Monitoring UI → Serial NMEA GPS: selects serial port (evidence: `ui/main_window.py`)
- Windows Radio & Serial Devices → BLE Scanner: provides radio data (evidence: `README.md`)
- Windows Radio & Serial Devices → Native Wi-Fi Scanner: provides radio data (evidence: `README.md`)
- Windows Radio & Serial Devices → Serial NMEA GPS: provides NMEA stream (evidence: `README.md`)
- Monitoring UI → Threat Detection: registers packets (evidence: `ui/main_window.py`)
- Monitoring UI → Proximity Radar: updates selected target (evidence: `ui/main_window.py`)
- Monitoring UI → Signal Store & Export: writes observations (evidence: `ui/main_window.py`)
- Monitoring UI → Signal Store & Export: requests exports (evidence: `ui/main_window.py`)
- Monitoring UI → CoT Broadcaster: broadcasts detected targets (evidence: `ui/main_window.py`)
- CoT Broadcaster → WinTAK / ATAK: sends CoT multicast (evidence: `core/export/cot_broadcaster.py`)
