GPS Activity Location Logging

Overview

The GPS activity location logging framework records where field activities take place. It stores location evidence against the record produced or affected by an activity through a polymorphic relationship.

The resulting data provides a consistent location history for community operations, field analysis, compliance review, and future geofencing capabilities.

Purpose

TreeSyt field activities may be collected individually and synchronized in batches. Each activity carries the GPS point and capture time recorded by the mobile device when the activity was performed.

This allows every activity in a batch to retain its own location and timestamp, providing an accurate record of field operations across communities.

Core Concepts

Activity Location

ActivityLocation is the model that stores the GPS evidence.

It is polymorphic, so one table can store location records for different activity models.

The important relationship fields are:

These point back to the model instance that the location evidence belongs to.

Locatable Model

A model that can receive GPS evidence should implement HasActivityLocation and use the IsLocatable trait.

The trait provides:

The trait is responsible for creating the activity_locations row.

Activity Action

ActivityLocationAction is a native PHP enum that defines the activity types supported by the logging framework.

The enum keeps action names controlled and consistent for analysis.

Location Activity DTO

LocationActivityDTO is the structured payload used to move GPS data through the logging flow.

It carries:

Using a DTO avoids passing loose arrays into the persistence layer.

Event and Listener

Location logging is triggered with the LocatableActivitySynced event.

The event carries:

TrackActivityLocationListener handles the event and calls the locatable model's recordActivityLocation() method.

This keeps controllers and services from directly knowing the persistence details.

Architecture

The current flow is:

  1. A backend process saves or updates the business record.
  2. The code checks that the synced item contains GPS fields.
  3. The code creates a LocationActivityDTO.
  4. The code dispatches LocatableActivitySynced.
  5. TrackActivityLocationListener receives the event.
  6. The listener calls recordActivityLocation() on the locatable model.
  7. IsLocatable creates the polymorphic activity_locations record.

Design Decisions

Coordinates Are Captured Per Item

Every activity item contains its own GPS data. A synchronization request can therefore contain multiple activities performed at different locations and times without losing the context of any individual activity.

Persistence Failure Handling

IsLocatable isolates failures that occur while writing the activity location record.

If persistence fails, the trait logs a warning containing the error, model, model ID, and action.

DTO construction and event dispatch happen before this persistence boundary. Callers must provide valid typed values and a parseable capture timestamp.

captured_at Is Different From created_at

captured_at should represent when the mobile device captured the GPS point.

created_at represents when the backend stored the activity location row.

For offline sync, these can be very different times.

Community Context Is Optional In The DTO

The DTO accepts an optional community.

When the activity belongs to a community, callers should pass the community model so the record can be grouped correctly for analysis.

If a future activity has no community context, the framework can still record the location against the affected model.

Metadata Is For Supporting Context

Metadata should be used for extra traceability that does not deserve first-class columns.

Examples include related file IDs, sync identifiers, or other small references that help analysts connect the GPS point to the submitted activity.

Metadata should not replace core fields such as user, action, coordinates, or community.

How To Add GPS Logging To A New Activity

1. Make The Model Locatable

The affected model should implement HasActivityLocation and use IsLocatable.

use App\Contracts\HasActivityLocation;
use App\Trait\IsLocatable;

class SomeActivity extends Model implements HasActivityLocation
{
    use IsLocatable;
}

2. Add Or Reuse An Action Enum Case

Add a case to ActivityLocationAction when the activity is a new tracked category.

case SOME_ACTIVITY = 'some_activity';

Use existing cases when the activity already fits a supported category.

3. Dispatch The Event After The Business Record Is Saved

The event should be dispatched only after the affected model exists.

use App\DataTransferObjects\LocationActivityDTO;
use App\Enums\ActivityLocationAction;
use App\Events\LocatableActivitySynced;
use Carbon\CarbonImmutable;

if (isset($item['latitude'], $item['longitude'], $item['accuracy'], $item['altitude'], $item['captured_at'])) {
    event(new LocatableActivitySynced(
        locatable: $activity,
        locationActivityDTO: new LocationActivityDTO(
            action: ActivityLocationAction::SOME_ACTIVITY,
            latitude: (float) $item['latitude'],
            longitude: (float) $item['longitude'],
            accuracy: (float) $item['accuracy'],
            altitude: (float) $item['altitude'],
            capturedAt: CarbonImmutable::parse($item['captured_at']),
            user: $request->user(),
            community: $community,
            metadata: [
                'sync_id' => $item['sync_id'] ?? null,
            ],
        )
    ));
}

4. Keep The Call Site Small

Prefer a private helper method in the controller or service that owns the activity workflow.

The helper should:

It should not know how the activity location row is stored.

Expected Mobile Payload

Each synced item should include the GPS values captured by the device when the action happened.

{
  "latitude": 6.5244,
  "longitude": 3.3792,
  "accuracy": 12.5,
  "altitude": 0.2,
  "captured_at": "2026-06-09T10:15:00Z"
}

Queuing

TrackActivityLocationListener can be queued by implementing Laravel's ShouldQueue contract.

Queuing is useful because location logging is evidence collection, not the main business action. Moving it to the queue reduces the chance of location logging work affecting request latency.

If the listener is queued, make sure the locatable model and DTO data can be serialized safely.

Operational Notes

Activity location records are intended for analysis and future geofencing decisions.

They should help answer questions like:

This framework collects the evidence. It does not enforce geofencing rules by itself.

Current Limitations

The framework does not define final geofence boundaries.

It does not validate whether a point is inside a community polygon or radius.

It depends on the mobile client sending accurate GPS data per item.

It does not replace normal request validation for the business activity being synced.