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:
locatable_typelocatable_id
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:
activityLocations()recordActivityLocation(LocationActivityDTO $data)
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:
- action
- latitude
- longitude
- accuracy
- altitude
- captured timestamp
- user
- optional community
- optional metadata
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:
- the locatable model
- the
LocationActivityDTO
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:
- A backend process saves or updates the business record.
- The code checks that the synced item contains GPS fields.
- The code creates a
LocationActivityDTO. - The code dispatches
LocatableActivitySynced. TrackActivityLocationListenerreceives the event.- The listener calls
recordActivityLocation()on the locatable model. IsLocatablecreates the polymorphicactivity_locationsrecord.
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:
- check required GPS fields exist
- build the DTO
- dispatch the event
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:
- where agents actually performed tracked activities
- which communities have reliable GPS clusters
- what radius or boundary data may be suitable later
- which submissions happened outside expected areas
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.