Geofencing & Alerts
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/security/GeofenceScreen.kt
- app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt
- app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt
- app/src/main/AndroidManifest.xml
- app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/SettingsScreen.kt
- README.md
The Geofencing & Alerts system in ShadowCheck Mobile provides users with the ability to define specific geographic areas for monitoring and real-time notification. This feature is a core component of the application's surveillance detection and network intelligence capabilities, allowing for automated responses when a device enters or exits predefined security zones.
This system integrates directly with the background scanning infrastructure and local encrypted storage to ensure that location-based threats are identified even when the application is not in the foreground. It works in tandem with the Network Scanning and Mapping modules to provide a comprehensive security perimeter.
Sources: README.md:12, app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/SettingsScreen.kt:149-153
Data Architecture
The foundation of the geofencing system is the Geofence entity, which defines the physical and logical parameters of a monitored zone. Each geofence is persisted in the local SQLite database via Room.
Geofence Data Model
| Field | Type | Description |
|---|---|---|
id | Long | Primary key, auto-generated. |
name | String | User-defined label for the area. |
latitude | Double | The center latitude coordinate of the zone. |
longitude | Double | The center longitude coordinate of the zone. |
radius | Float | The radius of the circular zone in meters. |
isActive | Boolean | Flag indicating if monitoring is currently enabled. |
notifyOnEntry | Boolean | Whether to trigger an alert when entering the zone. |
notifyOnExit | Boolean | Whether to trigger an alert when leaving the zone. |
createdAt | Long | Unix timestamp of when the geofence was created. |
Sources: app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt:85-96
Entity Relationship Diagram
The following diagram illustrates the relationship between Geofences and the broader data ecosystem, including sighting records that may trigger alerts.
Background Monitoring & Services
Geofencing relies on continuous location updates processed by background services. The CompleteScannerService manages the lifecycle of network detection and works alongside location providers to determine proximity to geofenced areas.
Service Configuration
To support geofencing, the application requires specific foreground service types and permissions defined in the manifest.
- Service:
CompleteScannerService - Foreground Type:
location - Permissions:
ACCESS_FINE_LOCATION,ACCESS_COARSE_LOCATION,FOREGROUND_SERVICE_LOCATION
Sources: app/src/main/AndroidManifest.xml:7-8, app/src/main/AndroidManifest.xml:21, app/src/main/AndroidManifest.xml:51
Execution Flow
The CompleteScannerService maintains a LocationListener that updates internal state variables whenever a valid GPS signal is received.
User Interface & Management
The GeofenceScreen provides a Material 3 based interface for interacting with the geofencing system. It allows users to visualize, toggle, and manage their security zones.
Key Components
- GeofenceCard: A UI component that displays the name, radius, and exact coordinates of a geofence. It uses
ShadowCheckColors.Surfacewith alpha transparency to visually distinguish between active and inactive states. - Management Actions: Users can perform CRUD operations via an
IconButtonfor addition and aDropdownMenufor editing, deleting, or toggling individual zones. - Status Chips: Visual indicators for "Entry Alert" and "Exit Alert" configurations within each card.
Sources: app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/security/GeofenceScreen.kt:100-112, app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/security/GeofenceScreen.kt:140-184
Management Logic Flow
The UI interacts with the data layer through a series of callback functions that modify the state of the geofences.
Notifications & Alerts
Alerts are delivered via a dedicated notification channel managed by the system service.
- Channel ID:
scanner - Importance:
IMPORTANCE_LOW(standard for ongoing scanning) - Dynamic Content: The notification content is updated in real-time to show unique discovery counts for WiFi, Bluetooth, and Cellular towers, which are often correlated with the device's presence inside a specific geofence.
Sources: app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt:254-266
Notification Metadata Table
| Property | Value | Source |
|---|---|---|
| Channel Name | "Scanning" | CompleteScannerService.kt |
| Small Icon | ic_menu_search | CompleteScannerService.kt |
| Default Title | "ShadowCheck Scanning" | CompleteScannerService.kt |
| Status Message | "Waiting for GPS" (if accuracy is low) | CompleteScannerService.kt |
Sources: app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt:255-257
Summary
The Geofencing & Alerts module serves as the proactive layer of the ShadowCheck Mobile platform. By combining Room-based persistence for Geofence entities with high-accuracy background location monitoring in CompleteScannerService, the system ensures users are notified of boundary transitions. The integrated UI provides granular control over alert types (Entry/Exit) and monitoring states, facilitating robust situational awareness in surveillance-sensitive environments.