docs: simplify README with marketing, move technical details to DEVELOP.md

2026-04-30 18:05:41 +07:00 · 2026-04-30 18:05:41 +07:00 · 2f12826386
commit 2f12826386
parent 2305b92b2b
2 changed files with 107 additions and 35 deletions
--- a/DEVELOP.md
+++ b/DEVELOP.md
@ -0,0 +1,83 @@
+# TracPulse — Developer Guide
+
+## Build
+
+```bash
+# Debug APK
+flutter build apk --debug
+
+# Release APK (requires signing config)
+flutter build apk --release
+
+# Analyze
+flutter analyze
+
+# Format
+dart format .
+```
+
+## Project Structure
+
+```
+lib/
+  main.dart                 # App entry, dark theme, routing
+  main_screen.dart          # Tracking toggle + live coordinates
+  permission_screen.dart    # Pre-flight permission setup
+  settings_screen.dart      # Server URL, device ID, accuracy config
+  status_screen.dart        # Event log (LOCATION, SYNC, ERROR, etc.)
+  preferences.dart          # SharedPreferences wrapper
+  bridge/
+    location_bridge.dart    # Dart↔Native MethodChannel
+
+android/app/src/main/kotlin/dev/fiatcode/tracpulse/
+  MainActivity.kt           # Flutter activity
+  BridgeModule.kt           # Method channel handler
+  service/
+    LocationTrackingService.kt  # Foreground service
+  location/
+    HeartbeatScheduler.kt   # AlarmManager-based heartbeat
+    DistanceFilterProcessor.kt  # Haversine distance filter
+    FusedLocationProvider.kt   # FusedLocationClient wrapper
+  network/
+    TraccarHttpClient.kt    # HTTP client for Traccar protocol
+    ConnectivityReceiver.kt # Network state monitoring
+  storage/
+    AppDatabase.kt          # Room database singleton
+    LocationDao.kt          # Location entity DAO
+    EventLogDao.kt          # Event log DAO
+    LocationEntity.kt       # Location Room entity
+    EventLogEntity.kt       # Event log Room entity
+  model/
+    Location.kt             # Location data class
+    EventLogEntry.kt        # Event log entry data class
+```
+
+## Architecture
+
+- **Flutter** UI layer with dark monospace theme
+- **MethodChannel** (`com.traccar.client/tracking`) bridges Dart to Kotlin
+- **Foreground Service** (`LocationTrackingService`) handles location updates
+- **HeartbeatScheduler** uses `AlarmManager` (not WorkManager — callbacks lost in separate process)
+- **Offline buffering** via Room database when network unavailable
+
+## Configuration Flow
+
+1. `PermissionScreen` — guides through locationAlways + notification + battery optimization
+2. `SettingsScreen` — server URL, device ID, accuracy, intervals
+3. Preferences stored via `SharedPreferences` (synced to native via `updateConfig`)
+
+## Server Request Format
+
+```
+POST https://yourserver/?id=DEVICE_ID&lat=...&lon=...&timestamp=...&is_moving=0
+```
+
+- `is_moving` = `1` when `speed > 1.0 m/s`
+- Auth via Basic auth header if password configured
+
+## Key Patterns
+
+- **Permission flow**: WhenInUse → Always (required order for background location)
+- **Battery optimization**: `PowerManager.isIgnoringBatteryOptimizations` via BridgeModule
+- **Tracking config**: passed via `startTracking()` + `updateConfig()` (both required)
+- **Dark theme**: `Brightness.dark` with `#0d0d0d` background, teal `#00bcd4` accent
--- a/README.md
+++ b/README.md
@ -1,48 +1,37 @@
-# Traccar Client
+# TracPulse

-Flutter Android app for background GPS location tracking, sending data to a Traccar server.
+**Location tracking that just works.**

-## Build
+TracPulse runs silently in the background on your Android device, keeping your Traccar server updated with real-time location data. No complicated setup — configure your server once, and TracPulse handles the rest.

-```bash
-flutter build apk --debug
-```
+---

-The APK is output to `build/app/outputs/flutter-apk/app-debug.apk`.
+## Features

-## Project Structure
+- **Background tracking** — GPS updates continue even when the app is minimized
+- **Offline buffering** — Locations stored locally when offline, synced automatically when connected
+- **Configurable intervals** — Adjust how often TracPulse checks your location
+- **Heartbeat mode** — Periodic location reports keep your server alive during inactivity
+- **Battery optimized** — Designed to run efficiently without draining your battery

-```
-lib/
-  main.dart                 # App entry, dark theme, routing
-  main_screen.dart          # Tracking toggle + live coordinates
-  permission_screen.dart    # Pre-flight permission setup
-  settings_screen.dart       # Server URL, device ID, accuracy config
-  status_screen.dart        # Event log (LOCATION, SYNC, ERROR, etc.)
-  preferences.dart          # SharedPreferences wrapper
-  bridge/
-    location_bridge.dart   # Dart↔Native MethodChannel (com.traccar.client/tracking)
+---

-android/app/src/main/kotlin/com/traccar/traccar_client/
-  BridgeModule.kt           # Method channel handler
-  service/LocationTrackingService.kt
-  location/HeartbeatScheduler.kt  # AlarmManager heartbeat
-  network/TraccarHttpClient.kt    # POST to server
-  network/ConnectivityReceiver.kt
-```
+## Getting Started

-## Configuration
+1. **Install** — Grab the APK from releases and install on your Android device
+2. **Configure** — Enter your Traccar server URL and device ID
+3. **Start tracking** — Tap the toggle and TracPulse begins reporting

-On first launch, `PermissionScreen` guides through:
-1. **Location** — `locationWhenInUse` then `locationAlways` (background)
-2. **Notification** — required for tracking alerts
-3. **Battery** — disable Doze optimization so tracking works reliably
+---

-Then set server URL and device ID in Settings before starting tracking.
+## Requirements

-## Server Request Format
+- Android device with GPS
+- Traccar server (self-hosted or cloud)
+- Android 8.0 or higher

-POST to `https://yourserver/?id=DEVICE_ID&lat=...&lon=...&timestamp=...&is_moving=0`
+---

- `is_moving` = `speed > 1.0 m/s` (3.6 km/h threshold)
- Server URL and device ID come from `Preferences` (configured in Settings screen)
+## Support
+
+Need help? Open an issue on [Codeberg](https://codeberg.org/fiatcode/tracpulse).