TrustRide gives drivers full control over every aspect of an intercity trip — from defining the route and pricing to managing live seat availability and tracking GPS location during the journey. This guide walks through the complete lifecycle of a trip, from creation through completion.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Muhammadbugaje/trustride/llms.txt
Use this file to discover all available pages before exploring further.
Trip Lifecycle
Every trip on TrustRide moves through a defined sequence of statuses. Understanding these states helps both drivers and riders know what actions are available at any point.draft
The trip has been created but is not yet visible to riders. The driver can still edit all details before publishing.
published
The trip is live and searchable. Riders can view it, book seats, and join the waitlist if it’s full.
in_progress
The driver has started the trip. No new bookings are accepted. GPS logging is active and deviation alerts may fire.
completed
The trip has ended. All confirmed bookings are marked completed. Riders can now submit ratings.
cancelled
The driver cancelled the trip before it started. All pending bookings are cancelled and seats are released.
expired
The trip’s departure date passed without the driver starting or completing it. Managed automatically by the Celery task scheduler.
update_trip_statuses) runs periodically to auto-transition trips: published trips whose departure time has arrived become in_progress, and in-progress trips that have passed their estimated_arrival_time are marked completed.
Creating a Trip
Drivers create trips by submitting aPOST request to /create/. The driver must have at least one active vehicle registered before a trip can be created. The endpoint is protected by @login_required and validates that the user has the driver role.
Required Fields
| Field | Type | Description |
|---|---|---|
vehicle | UUID | The driver’s registered vehicle (must belong to the driver) |
origin | string | Departure city or state (e.g., Kaduna) |
destination | string | Arrival city or state (e.g., Abuja) |
departure_date | date | Trip departure date (YYYY-MM-DD) |
departure_time | time | Trip departure time (HH:MM) |
price_per_seat | decimal | Fare per seat in Naira |
Optional Fields
| Field | Type | Description |
|---|---|---|
gender_restriction | string | anyone (default), ladies_only, or gentlemen_only |
driver_note | text | A note shown to riders, e.g., “Arrive 10 minutes early” |
stop_count | integer | Number of intermediate stops |
stop_N_city | string | City name of stop N (0-indexed) |
stop_N_arrival | time | Arrival time at stop N |
stop_N_departure | time | Departure time from stop N |
stop_N_price | decimal | Per-seat price from origin to stop N |
Example Form Submission
Trips are published immediately on creation (status set to
published). If you want to review the trip before it goes live, use the duplicate workflow to create a draft, edit it, and then publish manually.Vehicle Management
Every trip must be associated with a registered vehicle. TheVehicle model captures all the information riders see on the trip listing and seat map.
Vehicle Fields
| Field | Type | Description |
|---|---|---|
make | string | Manufacturer name, e.g., Toyota |
model | string | Model name, e.g., Hiace |
year | integer | Manufacturing year (1900 – current year + 1) |
color | string | Exterior colour, e.g., Silver |
plate_number | string | Nigerian-format licence plate (unique, validated) |
vehicle_type | choice | sedan, suv, minivan, bus, truck, motorcycle, or other |
seating_capacity | integer | Total number of seats in the vehicle |
passenger_capacity | integer | Seats available to passengers (≤ seating_capacity) |
seat_layout | JSON | Structured description of how seats are arranged |
car_image | image | Primary photo of the vehicle |
Seat Layout JSON
Theseat_layout field is a JSON object that describes how seats are physically grouped. This is used to render the interactive seat map on the trip detail page.
- Numeric value — the number of seats in that section (e.g.,
"front": 2means two front seats). - Array value — multiple rows of seats within a section (e.g.,
"middle": [3, 3]means two middle rows of three seats each).
total_seats property on the Vehicle model calculates the sum of all values automatically. The seat_layout drives the visual grid shown to riders during booking.
Vehicle Management Endpoints
| Method | URL | Description |
|---|---|---|
GET/POST | /driver/vehicles/add/ | Register a new vehicle |
GET/POST | /driver/vehicles/<uuid>/edit/ | Update vehicle details and photos |
POST | /driver/vehicles/<uuid>/delete/ | Remove a vehicle |
Trip Operations
Once a trip exists, drivers manage it through a set of dedicated action endpoints. All require authentication and ownership of the trip.Publish — /trip/<uuid>/publish/
Publish — /trip/<uuid>/publish/
Transitions a
draft trip to published, making it visible and bookable. Will fail if the departure date is in the past. A previously cancelled trip can also be moved back to draft via this endpoint, then re-published after editing.Edit — /trip/<uuid>/edit/
Edit — /trip/<uuid>/edit/
Opens the edit form for a trip that is in Editable fields include: vehicle, origin, destination, departure date/time, price per seat, gender restriction, stops, and driver note.
draft or published state. Completed or cancelled trips cannot be edited — use Duplicate instead.Pause — /trip/<uuid>/pause/
Pause — /trip/<uuid>/pause/
Toggles the
is_active flag without changing the trip’s status. A paused trip disappears from search results but retains all existing bookings. Calling the endpoint again resumes it.Duplicate — /trip/<uuid>/duplicate/
Duplicate — /trip/<uuid>/duplicate/
Creates a new
draft trip with all the same settings (vehicle, route, price, gender restriction) but with today’s date. The driver is redirected to the edit form to set the new departure date before publishing.Cancel — /trip/<uuid>/cancel/
Cancel — /trip/<uuid>/cancel/
Sets the trip status to
cancelled and marks it inactive. All bookings in reserved or pending_verification state are cancelled and their seats released. Confirmed bookings are not automatically refunded — drivers should process refunds separately.Start — /start-trip/<uuid>/
Start — /start-trip/<uuid>/
Moves a
published trip to in_progress. Only possible while the trip is in published state. This activates GPS logging for the trip.Complete — /complete-trip/<uuid>/
Complete — /complete-trip/<uuid>/
Marks the trip as
completed. All confirmed bookings are updated to completed. Rider and driver ride counters are incremented. The waitlist and chat messages for the trip are cleared.GPS Tracking
TrustRide logs the driver’s real-time position duringin_progress trips using the GPSLog model.
GPSLog Fields
| Field | Type | Description |
|---|---|---|
trip | FK | The associated trip |
latitude | decimal | GPS latitude (up to 6 decimal places) |
longitude | decimal | GPS longitude (up to 6 decimal places) |
timestamp | datetime | When the coordinate was recorded |
speed | float | Speed in km/h at time of logging (optional) |
is_deviation | boolean | True if this point marks a route deviation |
Deviation Alerts
When the platform detects that the driver has deviated significantly from the expected route, aDeviationAlert record is created. Alerts have three statuses: active, resolved, and ignored. An admin can review and resolve alerts from the admin panel.
| Field | Description |
|---|---|
deviation_amount | Distance off-route in metres |
status | active / resolved / ignored |
admin | The admin user who resolved the alert (nullable) |
resolved_at | Timestamp of resolution |
Waitlist
When a trip is fully booked (available_seats reaches 0), riders can add themselves to a waitlist rather than leaving empty-handed.
seating_capacity. Each WaitlistEntry stores the rider’s queue_position and expires after 30 minutes if the rider does not claim a released seat.
When any booking is cancelled or a refund is approved, the next rider in the queue (notify_next_in_waitlist) receives an in-app notification and can proceed to book the freed seat.
Waitlist functionality can be toggled platform-wide via the
waitlist_enabled key in AppSetting. When disabled, the join-waitlist endpoint returns an error message instead of adding the rider to the queue.Future Trip Interest
Riders who cannot find a trip for their route on a specific date can register interest for a future trip usingFutureTripInterest. This allows TrustRide to alert them when a matching trip is published.
FutureTripInterest Fields
| Field | Type | Options |
|---|---|---|
origin | string | Any city or state |
destination | string | Any city or state |
preferred_date | date | Must be today or later |
time_of_day | choice | morning (6AM–12PM), afternoon (12PM–6PM), evening (6PM–12AM) |
gender | choice | anyone, male, female |
(user, origin, destination, preferred_date) is unique — a rider cannot register duplicate interest for the same route and date. When a driver publishes a matching trip, the platform notifies all interested riders automatically.
Seat reservations created during booking expire after 30 minutes by default. This window is configurable via the
booking_expiry_minutes key in AppSetting. Once expired, the seat is released and the next waitlisted rider is notified. Drivers see only active (non-expired) bookings in their trip management view.