Skip to main content

Overview

BrokerOS automatically monitors the real-time geographic location of field agents (Sales Executives, Sourcing Managers, and Closing Managers) during their scheduled working shifts. This tracking provides two core enterprise capabilities:
  1. Live Management Oversight: Sales managers can view their entire field team on an interactive Google Maps overlay in the web dashboard.
  2. Site Visit Validation: Real-time coordinates verify that sales executives were physically present at designated project sites during client meetings.

Tracking Pipeline Architecture


Headless Background Task Architecture

The location tracking subsystem (apps/mobile/lib/location-tracking.ts) uses expo-location and expo-task-manager to register a background task:

Why SecureStore is Required for Headless Tasks

When the mobile application is minimized or the device screen is locked, Android spawns a headless JavaScript context to execute location updates. In this headless environment:
  • React state, context hooks, and component memory do not exist
  • Active session objects and web clients are uninitialized
To ensure the backend knows which employee is broadcasting coordinates, the dashboard shell writes the authenticated userId to expo-secure-store during boot. The headless task reads USER_ID_KEY from disk on every execution tick.

Foreground Service Configuration

To prevent the Android operating system from killing the tracking process during background battery optimization, BrokerOS runs an Android Foreground Service with a persistent notification:
This persistent notification informs field employees that their location is being actively logged and ensures continuous execution across all Android OEM battery managers (Samsung, Xiaomi, OnePlus, Google Pixel).

Production Optimizations & Privacy Filters

The tracking module in apps/mobile/lib/location-tracking.ts contains configurable enterprise safeguards:

1. Off-Duty Hours Filter

Prevents tracking outside business operating hours (e.g., between 11:00 PM and 6:00 AM):

2. Distance Threshold (Haversine Delta)

Skips redundant backend API calls if the agent has moved less than 10 meters since the previous recorded ping:

Required Permissions & User Experience

If an employee revokes background location permissions, tracking terminates when the app is minimized. The management dashboard will display their last known pin with a “Location Stale” warning indicator.