Visla GPS — Android App
What is Visla GPS?
Visla GPS is a real-time GPS tracking and device management application for Android. It connects to GPS tracking devices to provide live location monitoring, trip history, geofencing, remote commands, and device sharing — all backed by a subscription-based billing model through Google Play.
Who is it for?
- Fleet managers — monitor vehicle fleets in real time with geofence alerts and trip history
- Vehicle owners — track personal vehicles with theft alerts and location sharing
- Delivery services — coordinate drivers with live map views and command dispatch
- Families — share device locations with family members for peace of mind
Key Features
| Feature | Description |
|---|---|
| Live Map Tracking | Real-time device positions on Google Maps or Mapbox with WebSocket updates |
| Device Management | Add devices via QR code or manual entry, configure settings, view status |
| Trip History | Browse past trips with route playback and event timeline |
| Geofencing | Create, edit, and manage geofence zones with enter/exit notifications |
| Device Sharing | Share device access with other users via invite system |
| Remote Commands | Send commands to devices (engine cut, door lock, etc.) with history tracking |
| Push Notifications | Firebase FCM-powered alerts for geofence events, device status, and more |
| Home Screen Widget | Glance-based widget showing device grid with status at a glance |
| Subscription Billing | Google Play Billing integration with plan management |
| Multi-Provider Maps | Switch between Google Maps and Mapbox per user preference |
| Social Login | Google Sign-In and Facebook Login alongside email/password auth |
| Two-Factor Auth | TOTP-based 2FA with QR code setup via ML Kit and ZXing |
Tech Stack
| Category | Technology |
|---|---|
| Language | Kotlin 2.3.10 |
| UI Framework | Jetpack Compose (BOM 2026.02.00) + Material 3 |
| DI | Hilt 2.59.2 (with KSP) |
| Networking | Retrofit 3.0.0 / OkHttp 5.3.2 / WebSocket |
| Maps | Google Maps Compose 8.1.0 + Mapbox 11.18.1 |
| Push Notifications | Firebase Cloud Messaging (BOM 34.9.0) |
| Local Storage | DataStore Preferences (encrypted via Tink 1.20.0) |
| Secure Storage | EncryptedSharedPreferences (security-crypto 1.1.0) |
| Billing | Google Play Billing 8.3.0 |
| Navigation | Navigation Compose 2.9.7 |
| Widgets | Glance AppWidget 1.1.1 + WorkManager 2.11.1 |
| Camera / QR | CameraX 1.5.3 + ML Kit Barcode 17.3.0 + ZXing 3.5.4 |
| Auth Providers | Google Identity (Credential Manager 1.5.0) + Facebook Login 18.1.3 |
| Linting | ktlint 1.5.0, detekt 1.23.8, Android Lint |
| Testing | JUnit 4, Mockito 5.21.0, MockK 1.14.9, Turbine 1.2.1, Compose UI Tests |
Build Configuration
| Property | Value |
|---|---|
| Android Gradle Plugin | 9.0.1 |
| Kotlin | 2.3.10 (via kotlin-gradle-plugin, overriding AGP built-in) |
| KSP | 2.3.6 |
| Java Toolchain | 21 |
minSdk | 26 (Android 8.0 Oreo) |
targetSdk / compileSdk | 36 |
| Compose BOM | 2026.02.00 |
| Configuration Cache | Enabled |
| Core Library Desugaring | desugar_jdk_libs 2.1.5 |
AGP 9.0 uses built-in Kotlin support (android.builtInKotlin=true in gradle.properties), with an explicit higher Kotlin version applied via the buildscript classpath.
Project Structure
com.visla.vislagps/
├── MainActivity.kt # Single-activity entry point
├── VislaGPSApp.kt # Application class (Hilt entry point)
│
├── core/ # Core infrastructure
│ ├── cache/ # In-memory caching
│ ├── config/ # Deep link configuration
│ ├── data/ # Core data utilities
│ ├── geometry/ # Geo math helpers
│ ├── initialization/ # App startup logic
│ ├── network/ # Auth interceptor, token management, encrypted storage
│ ├── notification/ # Notification channel & display manager
│ ├── permissions/ # Runtime permission handling
│ ├── service/ # FCM service & token manager
│ └── utils/ # Shared utilities
│
├── data/ # Data layer
│ ├── auth/ # Google & Facebook auth managers
│ ├── billing/ # Google Play Billing manager
│ ├── mappers/ # DTO ↔ entity mappers
│ ├── models/ # Data models
│ ├── network/ # WebSocket manager
│ ├── remote/
│ │ ├── api/ # Retrofit API interfaces (Auth, Device, Geofence, etc.)
│ │ └── dto/ # Data transfer objects
│ └── repositories/ # Repository implementations
│
├── domain/ # Domain layer
│ ├── entities/ # Business entities (Device, Position, Geofence, User, etc.)
│ ├── errors/ # Domain error types
│ ├── repositories/ # Repository interfaces
│ ├── services/ # Service interfaces
│ ├── usecases/ # Use cases organized by feature
│ │ ├── auth/ # Authentication flows
│ │ ├── billing/ # Subscription management
│ │ ├── commands/ # Remote device commands
│ │ ├── deeplink/ # Deep link resolution
│ │ ├── devices/ # Device CRUD
│ │ ├── events/ # Event retrieval
│ │ ├── geofences/ # Geofence management
│ │ ├── notifications/ # Notification preferences
│ │ ├── positions/ # Position history
│ │ ├── realtime/ # WebSocket real-time updates
│ │ └── sharing/ # Device sharing & invites
│ └── ValidationConstants.kt # Shared validation rules
│
├── di/ # Hilt dependency injection modules
│ ├── AppModule.kt
│ ├── AppPreferencesModule.kt
│ ├── BaseUrlModule.kt
│ ├── BillingModule.kt
│ ├── NetworkModule.kt
│ ├── RepositoryModule.kt
│ ├── ServiceModule.kt
│ └── TokenManagerModule.kt
│
├── ui/ # Presentation layer
│ ├── base/ # Base composable patterns
│ ├── components/ # Reusable UI components
│ │ ├── common/ # Buttons, dialogs, inputs
│ │ ├── device/ # Device cards & lists
│ │ ├── geofence/ # Geofence editors
│ │ ├── map/ # Map overlays
│ │ ├── notifications/ # Notification items
│ │ ├── settings/ # Settings rows
│ │ └── subscription/ # Billing UI
│ ├── formatters/ # Display formatting utilities
│ ├── handlers/ # UI event handlers
│ ├── maps/ # Google Maps & Mapbox composables
│ ├── navigation/ # Navigation graph & bottom bar
│ ├── screens/ # Feature screens (one file per screen + ViewModel)
│ ├── state/ # UI state holders
│ ├── subscription/ # Subscription flow
│ ├── theme/ # Material 3 theme (colors, typography, dimensions)
│ ├── utils/ # UI utilities
│ └── viewmodels/ # Shared ViewModels
│
└── widget/ # Home screen widget
├── DeviceGridWidget.kt # Glance widget definition
├── WidgetDataStore.kt # Widget data persistence
├── WidgetDevice.kt # Widget device model
├── WidgetGridBuilder.kt # Grid layout builder
└── WidgetSyncWorker.kt # Background sync via WorkManager
Getting Started
Prerequisites
- Android Studio Meerkat (2024.3+) or later with AGP 9.0 support
- JDK 21 (bundled with Android Studio at
/opt/android-studio/jbr) - Android SDK with API 36 platform installed
- Mapbox account for Mapbox SDK downloads token
- Physical device or emulator (API 26+)
Setup
-
Clone the repository and navigate to the Android project:
cd android -
Create
local.propertiesfrom the example:cp local.properties.example local.properties -
Fill in required values in
local.properties:sdk.dir=/path/to/your/Android/Sdk
GOOGLE_MAPS_API_KEY=your_google_maps_api_key
MAPBOX_ACCESS_TOKEN=your_mapbox_access_token
FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_CLIENT_TOKEN=your_facebook_client_token -
Set the Mapbox downloads token (required to resolve Mapbox Maven dependencies):
export MAPBOX_DOWNLOADS_TOKEN=your_mapbox_downloads_tokenOr add to
~/.gradle/gradle.properties:MAPBOX_DOWNLOADS_TOKEN=your_mapbox_downloads_token -
Build the project:
make build
Local Development
For local backend development, uncomment and set the environment URLs in local.properties:
API_BASE_URL=http://10.0.2.2:8080
WS_BASE_URL=ws://10.0.2.2:8080
Note:
10.0.2.2is the Android emulator alias for the host machine'slocalhost.
Use make dev to build, install, set up ADB port forwarding, and launch the app in one step.
Makefile Targets
| Target | Description |
|---|---|
make help | Show all available targets with usage examples |
make build | Build debug APK (assembleDebug) |
make release | Build release AAB (bundleRelease) |
make install | Build and install debug APK to connected device |
make launch | Launch the app on a connected device |
make dev | Full dev workflow: build → install → port-forward → launch |
make uninstall | Uninstall the app from the device |
make test-unit | Run all unit tests |
make test-unit test=X | Run unit tests matching a pattern (e.g., test=DevicesViewModel) |
make test-ui | Run instrumented UI tests on a connected device/emulator |
make lint | Run all linters (ktlint + detekt + Android Lint) |
make ktlint | Run ktlint code style checks |
make ktlint-fix | Run ktlint with auto-fix |
make detekt | Run detekt static analysis |
make lint-android | Run Android Lint |
make clean | Clean build artifacts |
make clean-adb | Reset ADB server |
make clean-all | Clean build + reset ADB |
make logs | Tail app logs filtered by PID, grepping for visla, Exception, Error |
make devices | List connected ADB devices |
make connect | Connect to a device over WiFi |
make emu | Start an emulator (EMU=name) |
make emulators | List available AVD emulators |
make stop-emu | Stop the running emulator |
Device selection is controlled by the VIA variable:
make dev # WiFi (default, DEVICE=android:5555)
make dev VIA=usb # USB-connected device
make dev VIA=emu # Running emulator
make install VIA=usb # Install via USB
make logs VIA=emu # Logs from emulator
Architecture
The app follows Clean Architecture with three layers:
- UI → Domain: ViewModels invoke use cases; never touch repositories directly.
- Domain → Data: Domain defines repository interfaces; data provides implementations.
- Dependency rule: Inner layers have no knowledge of outer layers. The domain layer has zero Android framework dependencies.
Design Decisions
Jetpack Compose over XML Views
The entire UI is built with Compose. It eliminates the fragment lifecycle complexity, reduces boilerplate, and enables a declarative, state-driven UI model that pairs naturally with Kotlin coroutines and flows. The theme system uses Material 3 with custom color, typography, and dimension tokens defined in ui/theme/.
Hilt over Manual DI
Hilt provides compile-time verified dependency injection with minimal boilerplate. The di/ package contains eight focused modules (NetworkModule, RepositoryModule, BillingModule, etc.) that keep bindings organized by concern. KSP is used instead of kapt for faster annotation processing.
Clean Architecture with Use Cases
Each user-facing operation is encapsulated in a dedicated use case class under domain/usecases/, organized by feature. This keeps ViewModels thin — they orchestrate use cases rather than containing business logic — and makes the domain layer independently testable without Android dependencies.
Dual Map Provider (Google Maps + Mapbox)
The app supports both Google Maps and Mapbox through a MapProviderManager abstraction in the data layer. Map composables in ui/maps/ provide provider-specific implementations (GoogleMapContent, MapboxMapContent) behind a unified MapContent interface. This gives users a choice and reduces vendor lock-in.
Encrypted Token Storage
Authentication tokens are stored using DataStore Preferences encrypted with Google Tink (EncryptedTokenDataStore). This provides at-rest encryption without the limitations of EncryptedSharedPreferences (which is still available for legacy secure storage). Token refresh is handled transparently by TokenAuthenticator and AuthInterceptor in the OkHttp pipeline.
WebSocket for Real-Time Updates
Live device positions are delivered over a persistent WebSocket connection managed by WebSocketManager. This avoids polling overhead and provides sub-second position updates on the map. The connection lifecycle is tied to the app's foreground state via lifecycle-process.
Glance Widgets with WorkManager Sync
The home screen widget uses Jetpack Glance (Compose-based widget framework) rather than legacy RemoteViews. WidgetSyncWorker periodically refreshes device data in the background via WorkManager, keeping the widget up to date without requiring the app to be open.
AGP 9.0 with Built-In Kotlin
The project uses Android Gradle Plugin 9.0's built-in Kotlin support (android.builtInKotlin=true) with an explicit higher Kotlin version (2.3.10) applied via the buildscript classpath. This simplifies the plugin setup while allowing use of the latest Kotlin features.
Fake Billing in Debug
Debug builds set USE_FAKE_BILLING=true via BuildConfig, allowing the billing flow to be tested without a Google Play connection. Release builds always use the real billing client.