1

Ride-Lifecycle

Jonathan Miller edited this page 2026-06-27 19:44:51 +00:00

Contents

Table of Contents

• Ride Lifecycle
• Status Flow
• 1. Ride Request
• 2. Dispatch
• 3. Driver Acceptance
• 4. Arriving
• 5. In Progress
• 6. Completion
• 7. Cancellation
• Retry Logic

Ride Lifecycle

Complete workflow from ride request to completion, including dispatch, tracking, and fare settlement.

Status Flow

requested --> dispatched --> accepted --> arriving --> in_progress --> completed
    |             |                                        |
    v             v                                        v
 no_driver    (timeout)                               cancelled
    |          re-dispatch
    v
  retry

1. Ride Request

A ride begins when a rider submits a request through the API.

RideHelper::requestRide() handles:

1. Validates rider identity (CRM contact or guest)
2. Generates unique ride reference (TX + hex)
3. Detects pickup and dropoff zones via ZoneHelper::detectZone()
4. Captures current surge multiplier from pickup zone
5. Creates ride record with status requested
6. Triggers dispatch process

Key design decision: the surge multiplier is captured at request time and stored on the ride record. This prevents the fare from changing between request and completion if surge conditions change during the ride.

2. Dispatch

DispatchHelper::dispatchRide() finds and offers the ride to nearby drivers.

1. Uses bounding box SQL pre-filter to find drivers within radius
2. Calculates haversine distance for precise filtering
3. Sorts by distance (nearest first)
4. Offers ride to closest available driver
5. Creates dispatch record with status offered
6. Sets ride status to dispatched

If the driver does not respond within the configured timeout, the dispatch expires and the system offers to the next nearest driver.

See Dispatch Engine for full details.

3. Driver Acceptance

When a driver accepts:

1. Dispatch record updated to accepted
2. Ride status changes to accepted
3. Driver and vehicle assigned to ride record
4. ETA calculated based on driver location

4. Arriving

Driver location updates trigger proximity checks. When the driver is near the pickup location, the status changes to arriving.

5. In Progress

The ride begins when the driver confirms pickup:

1. Status changes to in_progress
2. Route tracking begins (polyline recording)
3. Distance and duration timers start

6. Completion

RideHelper::completeRide() handles ride finalization:

1. Captures final distance and duration
2. Calls FareHelper::calculateFare() with:
   • Actual distance traveled
   • Actual duration
   • Vehicle type
   • Pickup zone ID (stored at request time)
   • Surge multiplier (stored at request time)
3. Breaks down fare into components (base, distance, time, surcharges)
4. Calculates driver payout and platform fee
5. Updates ride status to completed
6. Updates driver statistics (total rides, earnings, rating)

7. Cancellation

Rides can be cancelled at any point before completion:

• By rider: free within cancellation window, fee after
• By system: if no driver available after all dispatch attempts

Retry Logic

If all available drivers reject or time out:

1. Ride status set to no_driver
2. Rider notified
3. Rider can retry, which restarts dispatch with a fresh driver search

Pages

• API-Reference
• Configuration
• Database-Schema
• Dispatch-Engine
• Driver-Management
• Fare-System
• Fare-Zones
• Fleet-Management
• Home
• Installation
• Permissions
• Ride-Lifecycle
• Ride-Management