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