System Design: [Ride-hailing dispatch name]

Reference design for ride-hailing dispatch: ingesting driver locations, indexing them geospatially (geohash or H3), matching riders to drivers, estimating arrival times, managing the trip lifecycle and guaranteeing that a driver is never assigned to two trips. It includes a note on dynamic (surge) pricing. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Values marked Example are assumptions; local transport regulation may constrain pricing and data use, so treat those parts as a format, not legal advice.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Matching queries a relational table of driver positions with a bounding box. At evening peak in our largest city the query takes 900 ms, two dispatchers sometimes offer the same driver to two riders, and the nearest driver by straight line is often across a river, 14 minutes away.]

1.2 Proposed solution

[Example: Driver apps send locations every 4 seconds to an ingestion gateway. A location service keeps the latest position and state of every online driver in memory, indexed by H3 cell, sharded by city. When a rider requests a trip, the dispatch service for that city finds candidate drivers in nearby cells, ranks them by road-network ETA from an ETA service, and assigns in small batches to minimise total pickup time. Assignment is a compare-and-set on the driver's state, so a driver can hold only one offer. The trip service drives a trip state machine and notifies both apps.]

1.3 Decisions requested from reviewers

2. Requirements

2.1 Functional requirements

2.2 Non-functional requirements

2.3 Out of scope

• [Example: shared rides (pooling) with multiple pickups]
• [Example: scheduled rides booked days ahead]
• [Example: payments (handled by the payments platform)]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Location ingestion

Latest-position state in memory: $10^{6} \times 100$ B (with index overhead) $= 100$ MB globally, about 8 MB for the largest city. Memory is not the constraint; update rate and fan-out to rider apps are.

3.3 Requests and ETA calls

plus pre-request ETA previews (Example: 5 per request) at about 3 500/s. In the largest city, $f \times 700 \approx 56$ requests/s.

3.4 Location history

Thirty days of raw history is at most about 32 TB, compressed several times in columnar storage.

3.5 Summary

4. API design

4.1 Endpoints and channels

4.2 Request and response examples

A ride request carries the price quote the rider saw, so the server can honour it or ask for confirmation if it expired:

POST /v1/trips HTTP/1.1
Content-Type: application/json
Idempotency-Key: 3b1f6a0e-9a52-4c1e-8f3e-6c4d2a1b7e90

{"pickup": {"lat": 52.52003, "lng": 13.40495}, "dropoff": {"lat": 52.50754, "lng": 13.37603}, "product": "standard", "quoteId": "q_77Z1"}

HTTP/1.1 202 Accepted
Content-Type: application/json

{"tripId": "t_5HX9", "state": "matching", "quoteExpiresAt": "2026-03-14T19:05:00Z"}

4.3 Errors

5. Data model

5.1 Entities

Driver supply state is hot and in memory; trips are durable records with a strict lifecycle.

5.2 Storage choices

6. High-level design

Each city (or large metro region) is served by its own dispatch shard; only ingestion, ETA and storage are shared services.

7. Detailed design

7.1 Location ingestion

Updates carry a device timestamp and a server receive timestamp; the location service applies an update only if it is newer than the stored one (last-write-wins by device time, rejected if more than 30 s in the future). Out-of-order and duplicate updates are therefore harmless. Implausible jumps (speed above 200 km/h between fixes) are flagged for anti-fraud and not used for matching.

7.2 Geospatial index

The design uses H3 resolution 9 (average cell area about 0.1 km², edge about 175 m) for driver lookup and resolution 7 (about 5 km²) for pricing. A candidate search starts with gridDisk(origin, 2) (19 cells, roughly a 0.8 km radius), widening to $k = 4$ (61 cells) and $k = 8$ (217 cells) if fewer than 10 available drivers are found. The number of cells in a disk of radius $k$ is $3k(k+1) + 1$.

7.3 Matching algorithm

Greedy "nearest available driver per request" is simple but globally wasteful when requests cluster. Instead, dispatch collects requests for a window of $w = 2$ s per shard and solves an assignment problem:

with a penalty for leaving a request unmatched. For a window with tens of requests and hundreds of candidates, the Hungarian algorithm or a min-cost flow solves this in milliseconds. Candidate edges are pruned to each request's 10 nearest drivers by straight-line distance before ETA is computed. Under overload (window larger than 200 requests) the shard falls back to greedy matching. Other factors (driver acceptance probability, vehicle class, fairness of trip distribution among drivers) enter as cost adjustments agreed with operations.

7.4 Request to assignment (critical path)

The rider gets an assigned driver after one batch window and the driver's acceptance.

7.5 Consistency of driver assignment

• Invariant: a driver is in at most one of offered or on_trip for at most one trip at any time.
• Single writer: one dispatch process owns a city shard at a time, elected through a lease with a fencing token; it is the only writer of driver status in that shard.
• Compare-and-set: status changes are conditional on the stored version, so even a stale former leader (old fencing token) cannot overwrite. Offers expire after 15 s; an expiry reverts offered to available unless an accept arrived first.
• Durable outcome: the accepted assignment is written to the trips database transactionally (trip state and driver ID together); the in-memory index is a cache of supply state that can be rebuilt from the stream and the trips database after failover.
• Cross-shard edges: a driver near a city boundary belongs to the shard of their current cell; shards hand a driver over on cell change through the location stream, never by both shards writing.

7.6 Trip state machine

Trip states are persisted; every transition is validated against this diagram, and both apps render from it.

7.7 ETA service

Travel times come from a road graph with precomputed shortcuts (for example contraction hierarchies) and live segment speeds from recent trips, updated every minute. A learned correction model adjusts the route-based estimate for pickup-specific delays such as entering a station forecourt. ETAs used for matching are cached per (driver cell, pickup cell) pair for 30 s.

7.8 Surge pricing note

Every minute, the pricing aggregator computes per resolution-7 cell the ratio of open requests to idle drivers, smooths it over neighbouring cells and time, and maps it to a multiplier through a capped, monotonic curve. Riders see the price before confirming (the quote ID in 4.2 locks it for a few minutes). Pricing rules are subject to local regulation (caps during emergencies, disclosure requirements) and must be reviewed by legal and policy teams per market.

8. Scalability and performance

Latency budget from request to offer sent (target p95 3 s):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security, privacy and abuse

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Switch city by city during off-peak hours, with the old dispatch kept warm in shadow mode. Rollback switches the city's request routing back; active trips continue in the trip service, which both dispatchers share.]

11.3 Risks

12. Appendices

12.1 Open questions

12.2 Glossary

12.3 References

Standard and licence note

Based on common industry practice for ride-hailing dispatch design and on the public references in 12.3. This is a reference design to adapt, with illustrative numbers; pricing and data-retention sections are a format, not legal advice. Original text written for this collection. Template licence: MIT.