Unit 3 — waterfall offers, parallel batching, locks, and scoring

Dispatch & Ride Matching

Unit 2 handed you a ranked shortlist of nearby drivers. Now comes the decision that actually moves the marketplace: which driver gets this trip, right now? It sounds like "pick the top of the list," but the top driver might decline, two riders might be eyeing the same car, and the nearest driver isn't always the one who makes the whole system flow. Dispatch is where a clean ranking meets a messy, concurrent, real-time world.

This unit builds the assignment layer — offer protocols, timeouts, atomic claims, composite scoring — and you will implement three pieces (dispatch_score, waterfall_dispatch, parallel_dispatch), run python test.py locally, and answer deterministic checkpoints to unlock each step.

Preview — Sub-unit 1

The problem: matching riders to drivers

Given a rider request and a ranked candidate list from Unit 2, commit an assignment under tight latency while keeping the marketplace consistent — no trip assigned twice, no driver double-booked, no rider waiting on a stalled offer.

Functional

Offer the trip to candidate drivers and react to accept / decline / timeout.
Assign each trip to exactly one driver, and each driver to at most one trip.
Fall through to the next candidate when an offer is declined or times out.
Track offer state durably so retries and crashes don't double-assign.

Non-functional

Low time-to-match p99 even when the best candidates decline.
Race-safe across many dispatch workers and simultaneous requests.
High driver utilization and acceptance rate.
Fair — no starvation for drivers at zone edges.

Constraints

Drivers respond on human timescales (seconds) or not at all.
Two riders can be offered the same driver at the same instant.
The dispatch service is horizontally scaled and stateless.

The core tension: you want to be fast (don't stack timeouts) and safe (never double-book) and smart (pick the driver who actually makes the marketplace work, not just the nearest line on a map).

Pro content

Dispatch & Ride Matching

This unit is part of qodebase Pro. Upgrade to unlock all tracks, checkpoints, benchmarks, and progress sync.

View pricing Sign up free