Database Schema

Relevant source files

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

• app/src/main/kotlin/com/shadowcheck/mobile/data/ShadowCheckDatabase.kt
• app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt
• app/src/main/kotlin/com/shadowcheck/mobile/data/Daos.kt
• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt
• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/SensorCollectionService.kt
• app/src/main/kotlin/com/shadowcheck/mobile/data/EnrichmentTask.kt

The ShadowCheck Mobile database serves as the central repository for all signals intelligence (SIGINT) data collected by the application. Built on the Android Room persistence library, it provides an encrypted and structured local storage solution for WiFi networks, Bluetooth devices, cellular towers, and environmental sensor readings. The primary purpose of the schema is to facilitate real-time surveillance detection, historical network analysis, and geospatial mapping of signals.

Sources: README.md, app/src/main/kotlin/com/shadowcheck/mobile/data/ShadowCheckDatabase.kt:1-55

Core Architecture

The database architecture is implemented via the ShadowCheckDatabase abstract class, which serves as the main access point for the underlying SQLite database named shadowcheck_database. It manages 13 distinct entities through dedicated Data Access Objects (DAOs).

Database Component Diagram

The following diagram illustrates the relationship between the singleton database instance, the various DAOs, and the persistent storage.

Entity Definitions

The schema is composed of several specialized tables designed to capture technical metadata for various signal types and system state information.

Network and Signal Entities

These entities track the primary signals detected during active scanning.

Table Name	Entity Class	Primary Key	Key Fields
wifi_networks	WifiNetwork	bssid	ssid, signalLevel, frequency, latitude, longitude
bluetooth_devices	BluetoothDevice	id (Auto)	address, name, rssi, deviceClass
ble_devices	BleDevice	id (Auto)	address, txPower, serviceUuids, manufacturerData
cellular_towers	CellularTower	id (Auto)	cellId, lac, mcc, mnc, networkType

Sources: app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt:6-90, app/src/main/kotlin/com/shadowcheck/mobile/data/ShadowCheckDatabase.kt:10-14

Telemetry and Metadata Entities

These entities store environmental data, hardware identifiers, and administrative task information.

Table Name	Entity Class	Description
sensor_readings	SensorReading	Captures XYZ values from Accelerometer, Gyroscope, Magnetometer, etc.
hardware_metadata	HardwareMetadata	Device specifications including manufacturer, model, and capabilities.
geofences	Geofence	Defines geographic boundaries for monitoring and alerts.
enrichment_tasks	EnrichmentTask	Tracks background tasks for data enhancement (e.g., OUI lookups).
api_tokens	ApiToken	Stores encrypted credentials for services like WiGLE or Mapbox.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt:92-168, app/src/main/kotlin/com/shadowcheck/mobile/data/EnrichmentTask.kt:6-16

Data Relationships

The schema utilizes an Entity-Relationship model where signal sightings are linked via unique identifiers (BSSID for WiFi, MAC/Address for Bluetooth) and geographic coordinates.

A significant portion of the logic involves deduplication and "sightings" management. For instance, the WifiNetworkDao provides methods to retrieve both the latest distinct networks and a full history of sightings for a specific BSSID.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/data/Daos.kt:10-16, app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt:153-178

Data Flow: Signal Persistence

The following sequence diagram illustrates how a signal detected by the CompleteScannerService is processed and persisted into the database.

The system implements a 30-second deduplication logic to prevent database bloat from high-frequency scan results.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt:53-83

Conclusion

The ShadowCheck Mobile database schema is designed for high-throughput SIGINT collection while maintaining strict data integrity and deduplication. By separating signal metadata (WiFi, BT, Cell) from environmental telemetry (Sensors) and administrative data (API tokens, Tasks), the system ensures efficient querying for mapping and threat detection features.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/data/ShadowCheckDatabase.kt, app/src/main/kotlin/com/shadowcheck/mobile/data/Daos.kt