TrustRide is a Django-based intercity ride-booking platform built specifically for the Nigerian market. It connects riders and drivers on long-distance routes — Lagos to Abuja, Kano to Kaduna, Port Harcourt to Enugu — with a trust-first design that mirrors how money and identity actually work in Nigeria: bank transfers over card rails, WhatsApp alongside in-app chat, and human verification before drivers go live.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.
The Problem TrustRide Solves
Intercity travel in Nigeria is dominated by informal arrangements: drivers post in WhatsApp groups, riders pay strangers cash at motor parks, and there is no shared record if something goes wrong. The “trust gap” is real — riders cannot verify a driver’s vehicle or identity before boarding, and drivers have no guarantee of payment before a long trip begins. TrustRide closes this gap with admin-verified driver profiles, manual bank-transfer receipt confirmation held in an escrow-style chat thread, real-time GPS sharing with next-of-kin contacts, and a reputation layer built on trip ratings and driver reports. The platform is mobile-first and progressive-enhancement-friendly, designed to stay functional on the 3G connections common outside major cities.User Roles
TrustRide has threerole values in the User model (apps/users/models.py): rider, driver, and admin. A fourth persona — the ambassador — is not a separate role value but a boolean sub-status (is_ambassador = True) applied to a rider account. Each role and sub-status unlocks a different surface of the application.
| Role / Status | role field value | Description |
|---|---|---|
| Rider | rider | Books seats on published trips, submits bank-transfer receipts, and rates drivers after a completed journey. |
| Driver | driver | Creates trips, manages vehicle profiles, sets seat layouts and gender restrictions, and confirms payments before departure. |
| Admin | admin | Manages driver verification, resolves disputes, reviews deviation alerts, processes driver payouts, and controls platform-wide settings via the /control/ panel. |
| Ambassador | rider + is_ambassador = True | A rider with elevated trust who can book seats on behalf of other passengers — useful for agents at bus terminals. Earns a configurable ambassador_commission_rate. Granted via the AmbassadorApplication approval pipeline. |
The Nigerian market context shapes every design decision here. Manual bank-transfer verification is intentional — card penetration is low and digital identity infrastructure is still maturing. The SMTP provider defaults to Brevo, timezone is locked to
Africa/Lagos, and the settings file pre-configures i18n entries for Hausa, Yoruba, Igbo, and Nigerian Pidgin for future localisation work.Key Platform Capabilities
TrustRide ships with the following capabilities out of the box:- Seat selection — Drivers define a
seat_layoutJSON field on their vehicle (e.g.,{"front": 2, "middle": [3, 3], "back": 3}). Riders pick a specific seat ID at booking time;unique_together = ['trip', 'seat_id']prevents double-booking at the database level. - Bank-transfer payment verification — Riders upload a receipt image inside a per-booking
ChatMessagethread. The driver marks it verified, which advances the booking fromreserved→pending_verification→confirmed. - Real-time chat — Django Channels powers three WebSocket consumer types: booking-scoped chat, pre-booking inquiry threads, and direct user-to-user messages, all routed via
apps/chat/routing.py. - GPS tracking —
GPSLogrecords latitude, longitude, speed, and a deviation flag every polling cycle.DeviationAlertnotifies admin when a driver strays from the expected route. - Waitlist — When a trip is full, riders join an ordered
WaitlistEntryqueue. Celery tasks notify the next eligible rider when a seat is released. - Gender-specific rides — Drivers can restrict trips to
ladies_onlyorgentlemen_onlyat creation time; the field is enforced at both the model and view layers. - Ambassador bookings — Ambassadors can create bookings with custom
rider_name,rider_phone, andrider_emailfields on theBookingmodel, allowing them to act on behalf of passengers who are not registered users. - Future-trip interest — Riders register interest in a route and date combination via
FutureTripInterest. When a driver publishes a matching trip, the interested riders are notified automatically.
Explore the Docs
Quickstart
Clone the repo, configure your
.env, run migrations, and have a working local server in under 10 minutes.Architecture
Understand the Django app layout, WebSocket consumer design, Celery task graph, and core data model relationships.
Rides & Bookings
Deep dive into the Trip and Booking lifecycle — statuses, seat reservation expiry, and how payment flows map to model state changes.
Users & Roles
Custom
AbstractBaseUser with email-as-username, driver verification flow, and the ambassador application process.