# sharawanan/traccar-client-android architecture

> Architecture diagram of the GitHub repository sharawanan/traccar-client-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sharawanan/traccar-client-android
- Repository: https://github.com/sharawanan/traccar-client-android

## Overview

#### Purpose and runtime

Traccar Client is a native Android GPS-tracking application that collects device positions and sends them to a Traccar server. It is a single Gradle Android module (`app`) with Android framework components, a foreground/background tracking service, local persistence, and HTTP networking.

#### App bootstrap and entry points

The base application and Android component declarations establish process-wide setup and externally triggered behavior. The main user entry is the activity/fragment UI; tracking can also start through boot/autostart, dial-launch, or shortcuts.

- `app/src/main/AndroidManifest.xml`
- `app/src/main/java/org/traccar/client/MainApplication.java`
- `app/src/main/java/org/traccar/client/MainActivity.java`
- `app/src/main/java/org/traccar/client/AutostartReceiver.java`

#### UI and user control boundary

`MainActivity` hosts the principal UI, with `MainFragment` providing tracking/configuration interaction. Status and about screens are separate activities. User actions ultimately control the tracking lifecycle rather than directly accessing location or networking.

- `app/src/main/java/org/traccar/client/MainActivity.java`
- `app/src/main/java/org/traccar/client/MainFragment.java`
- `app/src/main/java/org/traccar/client/StatusActivity.java`
- `app/src/main/res/xml/preferences.xml`

#### Tracking lifecycle orchestration

`TrackingController` is the likely lifecycle façade between UI/receivers and the long-lived `TrackingService`. The service owns active tracking behavior, including Android background-execution/notification concerns. `WakefulBroadcastReceiver` supports reliable receiver-to-service handoff.

- `app/src/main/java/org/traccar/client/TrackingController.java`
- `app/src/main/java/org/traccar/client/TrackingService.java`
- `app/src/main/java/org/traccar/client/WakefulBroadcastReceiver.java`

#### Position acquisition and product variants

`PositionProvider` abstracts location acquisition. The regular build uses Android location handling; a Google source set supplies Google-specific application/location-provider implementations. Factory classes form the compile-time/product-flavor boundary for selecting providers, while `Position` is the shared tracking payload.

- `app/src/main/java/org/traccar/client/PositionProvider.java`
- `app/src/main/java/org/traccar/client/AndroidPositionProvider.java`
- `app/src/main/java/org/traccar/client/Position.java`
- `app/src/google/java/org/traccar/client/GooglePositionProvider.java`
- `app/src/regular/java/org/traccar/client/PositionProviderFactory.java`

#### Delivery pipeline and server boundary

Collected `Position` records are serialized by `ProtocolFormatter`, queued/managed by `RequestManager`, and delivered through `NetworkManager`. This is the principal external boundary: the app communicates with a configured Traccar-compatible server over network transport, subject to Android network/security policy.

- `app/src/main/java/org/traccar/client/ProtocolFormatter.java`
- `app/src/main/java/org/traccar/client/RequestManager.java`
- `app/src/main/java/org/traccar/client/NetworkManager.java`
- `app/src/main/res/xml/network_security_config.xml`

#### Local durability and retry state

`DatabaseHelper` provides the persistence boundary for tracking/request state, allowing position delivery to be decoupled from transient network availability. The expected control flow is location provider → `Position` → formatting/request management → database-backed pending work → network submission.

- `app/src/main/java/org/traccar/client/DatabaseHelper.java`
- `app/src/main/java/org/traccar/client/RequestManager.java`
- `app/src/main/java/org/traccar/client/Position.java`

#### Build distribution variants

Gradle builds the Android artifact, while source sets separate Google-enabled and non-Google/hidden implementations. This supports distribution channels such as Google Play and F-Droid without changing the shared tracking pipeline.

- `app/build.gradle`
- `app/src/google/AndroidManifest.xml`
- `app/src/hidden/AndroidManifest.xml`
- `app/src/hidden/java/org/traccar/client/PositionProviderFactory.java`

Main entry points: [`app/src/main/java/org/traccar/client/TrackingService.java`](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/TrackingService.java) (TrackingService), [`app/src/main/java/org/traccar/client/PositionProvider.java`](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/PositionProvider.java) (PositionProvider), [`app/src/main/AndroidManifest.xml`](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/AndroidManifest.xml) (Android manifest), [`app/src/main/java/org/traccar/client/RequestManager.java`](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/RequestManager.java) (RequestManager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry points"]
  node_manifest["Android manifest<br/>Android declaration"]
  node_application["MainApplication<br/>application setup"]
  node_main_activity["MainActivity<br/>[MainActivity.java]"]
  node_main_fragment["MainFragment<br/>UI controller<br/>[MainFragment.java]"]
  node_autostart["AutostartReceiver<br/>broadcast receiver"]
  node_status["StatusActivity"]
end

subgraph group_tracking["Tracking runtime"]
  node_controller["TrackingController<br/>lifecycle facade"]
  node_wakeful_receiver["WakefulBroadcastReceiver<br/>receiver handoff"]
  node_service["TrackingService<br/>foreground service"]
  node_provider["PositionProvider<br/>location abstraction"]
  node_android_provider["AndroidPositionProvider<br/>location provider"]
end

subgraph group_delivery["Position delivery"]
  node_position["Position<br/>tracking payload<br/>[Position.java]"]
  node_formatter["ProtocolFormatter<br/>serializer"]
  node_requests["RequestManager<br/>delivery queue"]
  node_database[("DatabaseHelper<br/>local persistence")]
  node_network["NetworkManager<br/>HTTP transport"]
end

subgraph group_variants["Build variants"]
  node_provider_factory["PositionProviderFactory<br/>variant factory"]
  node_google_provider["GooglePositionProvider<br/>Google location provider"]
  node_gradle["App Gradle build<br/>build definition<br/>[build.gradle]"]
end

node_server{{"Traccar server<br/>external server"}}

node_manifest -->|"initializes"| node_application
node_manifest -->|"launches"| node_main_activity
node_manifest -->|"triggers"| node_autostart
node_main_activity -->|"hosts"| node_main_fragment
node_main_fragment -->|"controls tracking"| node_controller
node_autostart -->|"hands off"| node_wakeful_receiver
node_wakeful_receiver -->|"starts"| node_service
node_controller -->|"starts and stops"| node_service
node_service -->|"obtains provider"| node_provider_factory
node_provider_factory -->|"creates"| node_provider
node_android_provider -.->|"implements"| node_provider
node_google_provider -.->|"implements"| node_provider
node_service -->|"collects"| node_position
node_provider -->|"produces"| node_position
node_position -->|"serializes"| node_formatter
node_formatter -->|"creates request"| node_requests
node_requests -->|"persists pending work"| node_database
node_requests -->|"submits queued request"| node_network
node_network -->|"HTTP delivery"| node_server
node_gradle -.->|"selects source set"| node_provider_factory
node_gradle -.->|"includes Google variant"| node_google_provider

click node_manifest "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/AndroidManifest.xml"
click node_application "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/MainApplication.java"
click node_main_activity "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/MainActivity.java"
click node_main_fragment "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/MainFragment.java"
click node_autostart "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/AutostartReceiver.java"
click node_status "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/StatusActivity.java"
click node_controller "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/TrackingController.java"
click node_wakeful_receiver "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/WakefulBroadcastReceiver.java"
click node_service "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/TrackingService.java"
click node_provider_factory "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/regular/java/org/traccar/client/PositionProviderFactory.java"
click node_provider "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/PositionProvider.java"
click node_android_provider "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/AndroidPositionProvider.java"
click node_google_provider "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/google/java/org/traccar/client/GooglePositionProvider.java"
click node_position "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/Position.java"
click node_formatter "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/ProtocolFormatter.java"
click node_requests "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/RequestManager.java"
click node_database "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/DatabaseHelper.java"
click node_network "https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/NetworkManager.java"
click node_gradle "https://github.com/sharawanan/traccar-client-android/blob/master/app/build.gradle"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifest,node_application,node_main_activity,node_main_fragment,node_autostart,node_status toneBlue
class node_controller,node_wakeful_receiver,node_service,node_provider,node_android_provider toneAmber
class node_position,node_formatter,node_requests,node_database,node_network toneMint
class node_provider_factory,node_google_provider,node_gradle toneRose
class node_server toneNeutral
```

## Components

### App entry points

- [Android manifest](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/AndroidManifest.xml): Android declaration · Declares application components and triggers. · `app/src/main/AndroidManifest.xml`
- [MainApplication](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/MainApplication.java): application setup · `app/src/main/java/org/traccar/client/MainApplication.java`
- [MainActivity](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/MainActivity.java): activity · `app/src/main/java/org/traccar/client/MainActivity.java`
- [MainFragment](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/MainFragment.java): UI controller · Controls tracking and configuration. · `app/src/main/java/org/traccar/client/MainFragment.java`
- [AutostartReceiver](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/AutostartReceiver.java): broadcast receiver · Starts tracking after system triggers. · `app/src/main/java/org/traccar/client/AutostartReceiver.java`
- [StatusActivity](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/StatusActivity.java): activity · `app/src/main/java/org/traccar/client/StatusActivity.java`

### Tracking runtime

- [TrackingController](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/TrackingController.java): lifecycle facade · `app/src/main/java/org/traccar/client/TrackingController.java`
- [WakefulBroadcastReceiver](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/WakefulBroadcastReceiver.java): receiver handoff · Reliably hands receiver work to the service. · `app/src/main/java/org/traccar/client/WakefulBroadcastReceiver.java`
- [TrackingService](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/TrackingService.java): foreground service · Owns active background tracking and notification behavior. · `app/src/main/java/org/traccar/client/TrackingService.java`
- [PositionProvider](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/PositionProvider.java): location abstraction · `app/src/main/java/org/traccar/client/PositionProvider.java`
- [AndroidPositionProvider](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/AndroidPositionProvider.java): location provider · `app/src/main/java/org/traccar/client/AndroidPositionProvider.java`

### Position delivery

- [Position](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/Position.java): tracking payload · `app/src/main/java/org/traccar/client/Position.java`
- [ProtocolFormatter](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/ProtocolFormatter.java): serializer · `app/src/main/java/org/traccar/client/ProtocolFormatter.java`
- [RequestManager](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/RequestManager.java): delivery queue · Coordinates pending requests and retries. · `app/src/main/java/org/traccar/client/RequestManager.java`
- [DatabaseHelper](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/DatabaseHelper.java): local persistence · Stores tracking and pending-delivery state. · `app/src/main/java/org/traccar/client/DatabaseHelper.java`
- [NetworkManager](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/main/java/org/traccar/client/NetworkManager.java): HTTP transport · `app/src/main/java/org/traccar/client/NetworkManager.java`

### Build variants

- [PositionProviderFactory](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/regular/java/org/traccar/client/PositionProviderFactory.java): variant factory · Selects the location provider per distribution variant. · `app/src/regular/java/org/traccar/client/PositionProviderFactory.java`
- [GooglePositionProvider](https://github.com/sharawanan/traccar-client-android/blob/master/app/src/google/java/org/traccar/client/GooglePositionProvider.java): Google location provider · `app/src/google/java/org/traccar/client/GooglePositionProvider.java`
- [App Gradle build](https://github.com/sharawanan/traccar-client-android/blob/master/app/build.gradle): build definition · Builds artifacts and composes source sets. · `app/build.gradle`

### Other components

- **Traccar server**: external server · Configured Traccar-compatible endpoint.

## Connections

- Android manifest → MainApplication: initializes
- Android manifest → MainActivity: launches
- Android manifest → AutostartReceiver: triggers
- MainActivity → MainFragment: hosts
- MainFragment → TrackingController: controls tracking
- AutostartReceiver → WakefulBroadcastReceiver: hands off
- WakefulBroadcastReceiver → TrackingService: starts
- TrackingController → TrackingService: starts and stops
- TrackingService → PositionProviderFactory: obtains provider
- PositionProviderFactory → PositionProvider: creates
- AndroidPositionProvider → PositionProvider: implements
- GooglePositionProvider → PositionProvider: implements
- TrackingService → Position: collects
- PositionProvider → Position: produces
- Position → ProtocolFormatter: serializes
- ProtocolFormatter → RequestManager: creates request
- RequestManager → DatabaseHelper: persists pending work
- RequestManager → NetworkManager: submits queued request
- NetworkManager → Traccar server: HTTP delivery
- App Gradle build → PositionProviderFactory: selects source set
- App Gradle build → GooglePositionProvider: includes Google variant