# cis-c0/rfsentinel architecture

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

- Interactive diagram: https://gitdiagram.com/cis-c0/rfsentinel
- Repository: https://github.com/cis-c0/rfsentinel

## Overview

RF Sentinel is an Android receive-only surveillance and radio-awareness app. The main workflow is passive radio scanning, signature-based identification and tracking, then presenting device alerts and locations to the user. The tree and README also document navigation, camera awareness, external radio hardware, Sentinel Link sharing, and Android Auto. Edges rely on README statements and the SOURCE INDEX references; unsampled subsystem connections are omitted where callers are not evidenced.

Main entry points: [`app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt`](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt) (Scan service), [`app/src/main/java/com/rfsentinel/app/MainActivity.kt`](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/MainActivity.kt) (Main screen), [`app/src/main/java/com/rfsentinel/app/service/DeviceRegistry.kt`](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/DeviceRegistry.kt) (Device registry), [`app/src/main/java/com/rfsentinel/app/settings/SettingsActivity.kt`](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/settings/SettingsActivity.kt) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scanning and detection"]
  node_scanner["Scan service"]
  node_ble["BLE scanning<br/>[BleScanEngine.kt]"]
  node_wifi["WiFi scanning<br/>[WifiScanEngine.kt]"]
  node_signatures["Signature engine<br/>[SignatureEngine.kt]"]
  node_advert["Radio observations<br/>[Advert.kt]"]
end

subgraph group_state["Device state"]
  node_registry["Device registry<br/>[DeviceRegistry.kt]"]
  node_database[("App database<br/>[AppDatabase.kt]")]
  node_prefs[("Preferences<br/>[Prefs.kt]")]
end

subgraph group_awareness["Maps and navigation"]
  node_alpr["Camera awareness<br/>[AlprStore.kt]"]
  node_online["Online alerts<br/>[PoliceAircraft.kt]"]
  node_navigation["Navigation"]
  node_map["Map display<br/>[MapFragment.kt]"]
end

subgraph group_integrations["Hardware and sharing"]
  node_sdr["SDR radio<br/>[SdrRadio.kt]"]
  node_esp["ESP hardware<br/>[EspReader.kt]"]
  node_usb["USB adapters<br/>[UsbWifi.kt]"]
  node_link["Sentinel Link<br/>[PhoneLink.kt]"]
end

subgraph group_experience["App experience"]
  node_main["Main screen<br/>[MainActivity.kt]"]
  node_car["Android Auto"]
  node_settings["Settings"]
end

node_user(("Phone user"))

node_user -->|"uses"| node_main
node_main -->|"starts scanning"| node_scanner
node_scanner -->|"processes observations"| node_advert
node_scanner -->|"classifies"| node_signatures
node_ble -->|"normalizes"| node_advert
node_scanner -.->|"updates"| node_registry
node_registry -.->|"records history"| node_database
node_scanner -->|"checks nearby cameras"| node_alpr
node_main -->|"displays devices"| node_registry
node_main -->|"opens settings"| node_settings
node_settings -->|"configures"| node_prefs
node_main -.->|"shows map"| node_map
node_scanner -.->|"monitors threats"| node_online
node_user -.->|"requests guidance"| node_navigation
node_scanner -.->|"supports radio detection"| node_sdr
node_scanner -.->|"supports board input"| node_esp
node_scanner -.->|"supports adapters"| node_usb
node_scanner -.->|"shares observations"| node_link
node_user -.->|"uses in vehicle"| node_car

click node_main "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/MainActivity.kt"
click node_scanner "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt"
click node_ble "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/BleScanEngine.kt"
click node_wifi "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/WifiScanEngine.kt"
click node_signatures "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/detect/SignatureEngine.kt"
click node_advert "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/detect/Advert.kt"
click node_registry "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/DeviceRegistry.kt"
click node_database "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/data/AppDatabase.kt"
click node_alpr "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/alpr/AlprStore.kt"
click node_online "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/online/PoliceAircraft.kt"
click node_navigation "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/nav/NavigationService.kt"
click node_map "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/ui/MapFragment.kt"
click node_sdr "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/sdr/SdrRadio.kt"
click node_esp "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/esp/EspReader.kt"
click node_usb "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/usb/UsbWifi.kt"
click node_link "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/link/PhoneLink.kt"
click node_car "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/car/RFSentinelCarAppService.kt"
click node_settings "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/settings/SettingsActivity.kt"
click node_prefs "https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/util/Prefs.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_ble,node_wifi,node_signatures,node_advert,node_user toneBlue
class node_registry,node_database,node_prefs toneAmber
class node_alpr,node_online,node_navigation,node_map toneMint
class node_sdr,node_esp,node_usb,node_link toneRose
class node_main,node_car,node_settings toneIndigo
```

## Components

### Scanning and detection

- [Scan service](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt): `app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt`
- [BLE scanning](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/BleScanEngine.kt): `app/src/main/java/com/rfsentinel/app/service/BleScanEngine.kt`
- [WiFi scanning](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/WifiScanEngine.kt): `app/src/main/java/com/rfsentinel/app/service/WifiScanEngine.kt`
- [Signature engine](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/detect/SignatureEngine.kt): `app/src/main/java/com/rfsentinel/app/detect/SignatureEngine.kt`
- [Radio observations](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/detect/Advert.kt): `app/src/main/java/com/rfsentinel/app/detect/Advert.kt`

### Device state

- [Device registry](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/service/DeviceRegistry.kt): `app/src/main/java/com/rfsentinel/app/service/DeviceRegistry.kt`
- [App database](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/data/AppDatabase.kt): `app/src/main/java/com/rfsentinel/app/data/AppDatabase.kt`
- [Preferences](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/util/Prefs.kt): `app/src/main/java/com/rfsentinel/app/util/Prefs.kt`

### Maps and navigation

- [Camera awareness](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/alpr/AlprStore.kt): `app/src/main/java/com/rfsentinel/app/alpr/AlprStore.kt`
- [Online alerts](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/online/PoliceAircraft.kt): `app/src/main/java/com/rfsentinel/app/online/PoliceAircraft.kt`
- [Navigation](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/nav/NavigationService.kt): `app/src/main/java/com/rfsentinel/app/nav/NavigationService.kt`
- [Map display](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/ui/MapFragment.kt): `app/src/main/java/com/rfsentinel/app/ui/MapFragment.kt`

### Hardware and sharing

- [SDR radio](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/sdr/SdrRadio.kt): `app/src/main/java/com/rfsentinel/app/sdr/SdrRadio.kt`
- [ESP hardware](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/esp/EspReader.kt): `app/src/main/java/com/rfsentinel/app/esp/EspReader.kt`
- [USB adapters](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/usb/UsbWifi.kt): `app/src/main/java/com/rfsentinel/app/usb/UsbWifi.kt`
- [Sentinel Link](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/link/PhoneLink.kt): `app/src/main/java/com/rfsentinel/app/link/PhoneLink.kt`

### App experience

- [Main screen](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/MainActivity.kt): `app/src/main/java/com/rfsentinel/app/MainActivity.kt`
- [Android Auto](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/car/RFSentinelCarAppService.kt): `app/src/main/java/com/rfsentinel/app/car/RFSentinelCarAppService.kt`
- [Settings](https://github.com/cis-c0/rfsentinel/blob/main/app/src/main/java/com/rfsentinel/app/settings/SettingsActivity.kt): `app/src/main/java/com/rfsentinel/app/settings/SettingsActivity.kt`

### Other components

- **Phone user**

## Connections

- Phone user → Main screen: uses (evidence: `README.md`)
- Main screen → Scan service: starts scanning (evidence: `app/src/main/java/com/rfsentinel/app/MainActivity.kt`)
- Scan service → Radio observations: processes observations (evidence: `app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt`)
- Scan service → Signature engine: classifies (evidence: `app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt`)
- BLE scanning → Radio observations: normalizes (evidence: `app/src/main/java/com/rfsentinel/app/service/BleScanEngine.kt`)
- Scan service → Device registry: updates (evidence: `app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt`)
- Device registry → App database: records history
- Scan service → Camera awareness: checks nearby cameras (evidence: `app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt`)
- Main screen → Device registry: displays devices (evidence: `app/src/main/java/com/rfsentinel/app/MainActivity.kt`)
- Main screen → Settings: opens settings (evidence: `app/src/main/java/com/rfsentinel/app/MainActivity.kt`)
- Settings → Preferences: configures (evidence: `app/src/main/java/com/rfsentinel/app/settings/SettingsActivity.kt`)
- Main screen → Map display: shows map
- Scan service → Online alerts: monitors threats
- Phone user → Navigation: requests guidance
- Scan service → SDR radio: supports radio detection
- Scan service → ESP hardware: supports board input
- Scan service → USB adapters: supports adapters
- Scan service → Sentinel Link: shares observations (evidence: `app/src/main/java/com/rfsentinel/app/service/ScanForegroundService.kt`)
- Phone user → Android Auto: uses in vehicle
