Skip to content

Colota - Android GPS Location tracker

update architecture doc for pause GPS when stationary feature

Max Dietrich51c4e51d9004
diff --git a/apps/docs/docs/development/architecture.md b/apps/docs/docs/development/architecture.md
index a63686d8..3be904f6 100644
--- a/apps/docs/docs/development/architecture.md
+++ b/apps/docs/docs/development/architecture.md
@@ -79,7 +79,7 @@ Location services are abstracted behind a `LocationProvider` interface (`locatio
- **GMS** (`src/gms/`) - `GmsLocationProvider` wraps Google Play Services `FusedLocationProviderClient`
- **FOSS** (`src/foss/`) - `NativeLocationProvider` wraps Android's native `LocationManager` with `GPS_PROVIDER` and `NETWORK_PROVIDER` fallback
-Each flavor provides a `LocationProviderFactory` that returns the correct implementation. The service and bridge code in `src/main/` uses only the interface.
+Each flavor provides a `LocationProviderFactory` that instantiates and returns the correct implementation at runtime. The service and bridge code in `src/main/` depends only on the `LocationProvider` interface, never on a concrete class.
### LocationForegroundService
@@ -90,6 +90,7 @@ An Android foreground service that runs continuously for GPS tracking. Manages:
- Anchor points - synthetic locations at geofence centers on zone enter/exit for clean track endpoints
- Battery critical shutdown (below 5% while discharging)
- Location accuracy filtering
+- Stationary detection - pauses GPS after 60s without movement and arms `MotionDetector` to resume on motion
- Queuing data for server sync
### NotificationHelper
@@ -157,7 +158,8 @@ Wraps Android's `EncryptedSharedPreferences` for encrypted credential storage (A
| Module | Purpose |
| --- | --- |
-| `LocationBootReceiver` | Auto-restarts tracking after device reboot |
+| `BootReceiver` | Auto-restarts tracking after device reboot |
+| `MotionDetector` | Wraps `TYPE_SIGNIFICANT_MOTION` sensor - arms a one-shot hardware trigger that fires when the device starts moving, used to resume GPS after a stationary pause |
| `DeviceInfoHelper` | Device metadata and battery status with caching |
| `FileOperations` | File I/O, sharing via FileProvider, and clipboard access |
| `PayloadBuilder` | Builds JSON payloads with dynamic field mapping |
@@ -221,6 +223,7 @@ Supporting utilities in `mapUtils.ts`:
| Utility | Purpose |
| --- | --- |
+| `lerpColor` | Linearly interpolates between two hex colors by factor `t` - used by `getSpeedColor` |
| `getSpeedColor` | Returns a theme-aware color for a given speed (m/s) using green→yellow→red interpolation |
| `createCirclePolygon` | Generates a 64-point GeoJSON `Polygon` approximating a circle on Earth's surface (for meter-based geofence radius) |
| `buildTrackSegmentsGeoJSON` | Creates per-segment `LineString` features with pre-computed speed colors for data-driven styling |
diff --git a/apps/docs/docs/introduction.md b/apps/docs/docs/introduction.md
index bc59aa09..279c4004 100644
--- a/apps/docs/docs/introduction.md
+++ b/apps/docs/docs/introduction.md
@@ -12,7 +12,7 @@ Colota is a self-hosted GPS tracking app for Android. It sends your location to
- **Self-Hosted** - Send location data to your own server via REST API. Works with Dawarich, OwnTracks, PhoneTrack, Reitti, Traccar, or any custom backend.
- **Privacy First** - No analytics, no telemetry, no third-party SDKs, no cloud services. Open source under AGPL-3.0.
- **Works Offline** - Works without a server. Store location history locally and export as CSV, GeoJSON, GPX, or KML.
-- **Background Tracking** - Foreground service, auto-start on boot, retry with exponential backoff, battery-critical shutdown.
+- **Background Tracking** - Foreground service, auto-start on boot, retry with exponential backoff, battery-critical shutdown, automatic GPS pause when stationary.
- **Geofencing** - Create pause zones where location recording automatically stops.
- **Tracking Profiles** - Automatically switch GPS interval, distance filter, and sync settings based on conditions like charging, car mode, or speed thresholds.
- **Sync Modes** - Instant, batch, or offline. Wi-Fi only sync, configurable intervals with automatic retry.