Unified Sighting Model

Relevant source files

The following files were used as context for generating this wiki page:

• app/src/main/kotlin/com/shadowcheck/mobile/domain/model/UnifiedSighting.kt
• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt
• app/src/main/kotlin/com/shadowcheck/mobile/UnifiedDetailScreen.kt
• app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt
• app/src/main/kotlin/com/shadowcheck/mobile/utils/ExportUtils.kt
• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/MapScreen.kt

The Unified Sighting Model is a domain-level abstraction designed to consolidate diverse signal observations—including WiFi, Bluetooth (Classic and BLE), and Cellular data—into a standardized data structure. This model enables the application to perform cross-protocol analysis, unified mapping, and consistent data visualization regardless of the underlying radio technology.

By providing a common interface for different signal types, the model facilitates high-level features such as the Temporal Heatmap and unified export capabilities. It acts as the bridge between the raw hardware-specific entities stored in the database and the UI components that display integrated signal intelligence.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/domain/model/UnifiedSighting.kt, app/src/main/kotlin/com/shadowcheck/mobile/UnifiedDetailScreen.kt:20-24

Data Structure and Schema

The core of the system is the UnifiedSighting data class. It contains mandatory fields required for location-based signal tracking and optional fields that are populated based on the specific RadioType.

Field Definitions

Field	Type	Description
id	String	Unique identifier for the sighting (e.g., BSSID or MAC address).
name	String	Human-readable name (SSID for WiFi, Device Name for BT).
type	RadioType	The protocol type: WiFi, Bluetooth, or Cellular.
signalLevel	Int	Received signal strength indicator (RSSI) in dBm.
latitude / longitude	Double	GPS coordinates where the signal was observed.
timestamp	Long	Epoch time of the observation.
capabilities	String	Security or feature flags (e.g., "WPA2", "BLE").
cellId / lac	Int?	Cellular-specific identifiers (CID and Location Area Code).

Sources: app/src/main/kotlin/com/shadowcheck/mobile/domain/model/UnifiedSighting.kt:3-28, app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt:7-60

Entity Relationship Diagram

The following diagram illustrates how the UnifiedSighting domain model abstracts the concrete database entities.

Data Flow and Ingestion

The CompleteScannerService is responsible for the lifecycle of signal detection. It monitors various Android system managers to capture raw data, which is then persisted into protocol-specific tables before being queried and mapped to the UnifiedSighting model for display.

Ingestion Logic

1. Location Validation: Signals are only recorded if hasValidLocation is true (accuracy < 50m and non-zero coordinates).
2. Deduplication: A 30-second window is enforced for each unique device (BSSID/MAC/CellID) to prevent database bloating from high-frequency scans.
3. Persistence: Data is stored in ShadowCheckDatabase using Room.

Implementation in UI

The model is utilized in the UnifiedDetailScreen to provide a consistent viewing experience for any detected signal. It uses polymorphic rendering to show technology-specific details (e.g., showing MCC/MNC for cellular but Capabilities/Standard for WiFi).

// Example of polymorphic rendering based on UnifiedSighting.type
when (sighting.type) {
    RadioType.WIFI -> {
        DetailRow("Security", sighting.capabilities)
        DetailRow("Standard", sighting.standard ?: "")
    }
    RadioType.CELLULAR -> {
        DetailRow("Cell ID", sighting.cellId.toString())
        DetailRow("MCC", sighting.mcc.toString())
    }
}

Sources: app/src/main/kotlin/com/shadowcheck/mobile/UnifiedDetailScreen.kt:80-125

Export and Interoperability

The ExportUtils object provides functions to transform the collected data into standard formats. While the database stores data in separate entities, the export logic effectively "unifies" them into single files for external analysis.

• CSV: Merges all types into a single table with a "Type" column.
• KML: Organizes sightings into folders within a single document for Google Earth visualization.
• GeoJSON: Formats all signals as distinct features in a unified FeatureCollection.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/utils/ExportUtils.kt:12-40, 52-80

Conclusion

The Unified Sighting Model serves as the architectural foundation for the ShadowCheck Mobile platform. By abstracting the complexities of WiFi, Bluetooth, and Cellular protocols into a single UnifiedSighting structure, the system ensures that complex analysis features—such as threat detection and temporal mapping—can operate seamlessly across all monitored radio spectrums.