Ride-Hailing Service

The pings never touch the trip database. This is the decision the whole design turns on.

A quarter of a million writes a second against a relational store that also owns money is not a scaling problem, it is a category error, and no amount of read replicas fixes it. So the ping path gets its own fleet, its own load balancer, and its own contract — accept, append, return, with no read, no join, and no transaction anywhere on it. The stream is partitioned by cell and retained in hours rather than years, because a position is worthless the moment a newer one lands, and that is what licenses the cheapest durability in the system. The real cost here is not the 25 MB/s of payload, it is holding a million TLS sessions open, which is why this fleet is sized on connections and the trip fleet is sized on queries.

Nearby has to be a key lookup. The moment it becomes a distance computation over a table, this design is finished.

Every position gets a cell id — H3, S2, geohash, the family matters less than the property, which is a fixed hierarchical grid where a point maps to a key by arithmetic and neighbours are enumerable without asking anyone. The writer folds each ping into that cell's bucket, keyed by driver and last write wins, so the live map of the fleet is a few hundred megabytes of memory instead of a spatial index absorbing a quarter of a million writes a second. Resolution is the tuning decision: too coarse and one lookup returns thousands of candidates, too fine and a single request has to read a ring of dozens of cells. Distance is still computed — on the handful of candidates the lookup returned, never as the means of finding them.

The matcher never assigns a driver. It makes a short-lived offer with a lease and a countdown on it.

One driver at a time holds an exclusive lease on this trip for fifteen seconds, pushed down a socket the driver's app already holds open, because a poll cannot ring a phone and a phone that has to be rung is the whole product. If the timer expires the lease dies on its own and the next candidate is offered — expiry is the mechanism, not a cleanup job that has to run for correctness. A driver holds at most one live offer, so two matchers working two different trips do not normally ring the same phone; that is the lease doing its job, and the accept two steps from here is what makes it a guarantee rather than a habit. The search is bounded, and I will say the bound rather than wave at it: three candidates a round at a 15-second lease each, then the radius widens one ring and the price multiplier is re-read, and three rounds is all there is — a hard ceiling of 135 seconds. At the ceiling the trip moves to unmatched, the request leaves the queue instead of ageing in it, and the rider is told no with the pickup still filled in so re-requesting is one tap. Telling someone no in two minutes is a better product than a spinner that never resolves, and it is the only version of this where queue depth still means something. The queue in front of the matcher is what lets a city's demand exceed a city's matchers for a minute without dropping a request on the floor.

Everything else on this board is allowed to be eventually consistent. The accept is not.

The accept is one conditional write over two rows in a single transaction: set the driver and move offered to accepted only if the trip's state is still offered and the offer id still matches, and only if that driver's current trip is null — then stamp the trip onto the driver's row. Both directions have to be in the predicate, because they are different races. The trip clause stops two drivers taking one ride. The driver clause stops one driver taking two, which is what happens when two matchers working two different trips both reach the same phone. Exactly one attempt reports rows changed; every loser gets a screen that says taken — a real screen a person understands, not an error anyone has to debug. The lease is an optimisation over the driver clause, not a substitute for it: it keeps us from ringing two phones and it makes the race rare. With the lease store down the accept is still correct and merely louder — more phones ring, more drivers are told taken, and the decline rate on the dashboard goes up for a reason we already know. Once the write commits the lease is cleared and the transition goes on the log; the driver becomes offerable again when the trip closes, not here.

Surge is not a second system. It is the same cell index, counted a different way.

Supply is idle drivers per cell, which the geo-index already holds; demand is open requests per cell, which the match state already counts while it hands out leases. A multiplier per cell recomputed on the order of a minute, smoothed and capped, is enough — a price that moves faster than a rider can walk two blocks is a support ticket, not a market. The ETA is a road-graph question and I buy it rather than build it: a third-party routing call, cached hard by cell pair, because straight-line distance happily ranks the driver across the river as the closest one. The quote before matching is a coarse estimate; the ETA the rider watches afterwards is the matched driver's actual route, and the two are allowed to differ as long as we say which is which.

Geography is already the shard key here — I would rather choose it deliberately than discover it during an incident.

A ride does not span two cities, so every hot structure partitions cleanly by city: the cell index, the match queue, the matchers, the trip rows, the pricing loop. The gateway resolves a cell to a city stack at the edge and pins the call there, which means there is no cross-shard transaction anywhere on the critical path and a city can be failed over, drained, or upgraded on its own. Hashing on trip id would spread load more evenly and would also turn every nearby query into a scatter-gather across every shard on earth, which is the wrong trade twice over. The cost is honest: cities are wildly uneven, so the largest ones get their own capacity and their own on-call, and a rider crossing a boundary needs a rule that says the trip belongs to the city it started in.

A lost ping is a stale dot on a map. A lost trip row is a ride nobody can prove happened.

The location stream is allowed to lose messages, run thin on replicas, and expire in hours; it is downsampled into cold storage only because disputes and fraud reviews need a trace of where the car actually went. The trip log is the opposite in every respect: each state change appended in order and committed with the row it describes through an outbox, so a crash between the two is a delayed publish rather than a trip that vanished. Closed trips age out of the hot table into an archive that history reads happily and that matching never touches, which keeps the working set the size of the last few days. The rule I would write on the wall: anything that becomes money is durable, anything that becomes a dot on a map is not.

Leases outstanding, phones asleep, and a stadium emptying — this is where a matcher earns its keep.

A matcher that restarts mid-offer holds nothing anybody needs, because the leases live in shared state with TTLs: its outstanding offers expire on their own and the trips flow back onto the queue to be offered again, which is also the recovery path for a matcher that is merely slow. A driver app that goes quiet stops refreshing its cell entry and falls out of the candidate set within a couple of ping intervals — that is the correct behaviour, and it is why the entry carries a TTL rather than waiting for a delete that will never arrive. A rider cancelling mid-match races the same conditional write the driver would have taken, so first writer takes the row and a cancel that lands first simply makes the accept fail. A cell that goes hot because a venue emptied gets split at a finer resolution while the queue absorbs the burst, which turns a stampede into a wait, and a wait is a thing a screen can explain.

A cancellation fee is not a fine. It pays a driver for a drive that already happened, so it is sized to their deadhead and most of it has to reach them.

Three inputs decide whether a fee is owed and how large: who cancelled, what state the trip was in, and how much irreversible work already exists — the deadhead minutes and kilometres nobody is otherwise paying for. The schedule that falls out of those three is in the numbers above, and the property that matters is that it is total: every state a trip can be cancelled from has a row, because a gap in the table is a rider or a driver finding out at the worst possible moment which one of them we forgot. This box decides the fault and the tier; it does not price them. The fare service downstream is the only thing on this board that turns a decision into an amount, which keeps the idempotency argument in one place instead of two. Platform fault is a real value in that field, not an afterthought — a bad match, a surge glitch, a driver app that crashed, all free — and it is a field rather than a support agent's reconstruction a week later. The fee is shown before the rider confirms, because a surprise charge becomes a dispute and a dispute costs several times the fee. And a driver cancelling is not an ending: the trip goes back to matching with the search budget reset, and the rider is told the car cancelled rather than left watching an ETA that stopped falling.

Cash does not stop a driver cancelling, it changes the shape of it. So this side is priced in reputation, and that forces a detector.

A driver charged cash for cancelling stalls at the kerb, drives slowly, or rings the rider and asks them to cancel instead, which converts a driver penalty into a rider fee and makes us the party profiting from our own bad match. So driver cancellations cost dispatch priority and, past a threshold, a suspension conversation, and never money. That asymmetry is exactly what makes induced-cancellation detection load-bearing rather than a nicety: stationary far from the pickup, heading away from it, or still arriving well past a recomputed ETA waives the rider's fee and re-attributes the event to the driver. Without it the schedule is gameable by the only party who can see it coming. The inputs have to be durable, so the trip row carries a small approach record written on the same path as the state transitions — accept time, accept position, cumulative distance, last movement, geofence arrival — and that is what arrives with the cancellation. The live index is corroboration only: one point per driver, no history, and losable by design, so a decision that becomes money never rests on it. The other half of this is whose evidence it is. The accused supplies it, so the driver's fix is read against the rider's, against the geofence event, and against whether the route is physically plausible — a parked spoofed pin should not win the first argument, because the first one is the one that pays.

Every trip that closes, however it closed, becomes double-entry rows in our ledger before a cent moves anywhere.

Completion and cancellation are both state transitions, so the fare service consumes closed trips off the log keyed by trip id — a redelivered event recomputes the same number instead of billing twice — and prices whichever thing happened: a fare from base, distance and time, or a fee from the tier and fault already stamped on the cancellation record. It writes the entries before any money moves: rider debit, driver credit, processing cost, platform revenue, tax, five rows that sum to zero for that trip. The processing row is the one people leave out, and leaving it out is what turns a daily reconciliation into a daily break — the rail settles a $5 fee as $4.555 net of its $0.445, so a ledger with no line for the rail's cut disagrees with the rail on every trip it has ever booked. The ordering is the point. The ledger is ours and it is the answer to what everyone is owed; the rail's balance transactions are reconciled against it daily, and when the two disagree the rail is what is wrong until somebody proves otherwise. A break is a named trip id and an amount, found the next morning, not a quarterly surprise. Seven years of it, at 17.6 GB a day, and the retention is not our decision.

The hold goes on the card before anyone is dispatched, so a bad card is a screen rather than a debt.

The rail here is Stripe and I am going to use its nouns, because the nouns are the constraints. A manual-capture PaymentIntent for the estimate plus a buffer is created at request time, before a single phone is rung. That is the real answer to a declined card: you learn the instrument is bad while nobody has driven anywhere, which turns a debt into a screen asking for another card. The authorization is then a ceiling. As a rule a capture cannot exceed it, so a trip that outruns the hold takes an incremental authorization mid-trip or a second intent at completion. There is an escape hatch and it is narrower than people want it to be: the networks allow overcapture for a short list of merchant categories, and taxi and limousine is on it at about twenty percent on Visa, Amex and Discover — but only on interchange-plus pricing, not for Visa in the EEA, and where strong customer authentication applies you generally have to authenticate at least what you intend to capture, which takes most of it back again. Twenty percent covers a tip. It does not cover a detour, so the design still assumes the ceiling is real and asks the bank a second time. Every mutation on this path carries an idempotency key on trip plus operation, because retries here are guaranteed and the failure mode is somebody's rent.

The driver's money leaves as a second movement, after the charge — the choice that survives tips, pooled rides, and late adjustments.

The simple option is one charge that splits at the rail — a destination charge with an application fee — and it breaks the moment reality arrives: tips land after the trip closed, a pooled ride pays two drivers out of one payment, and adjustments happen post hoc, none of which survive a split decided at charge time. So we charge on the platform account and issue a Transfer to the driver's connected account afterwards, and the honest cost is that we are now holding other people's money. The cancellation fee gets its own intent instead of a partial capture of the hold, and the reason is not the split — under separate charges and transfers the split is decided at transfer time anyway — it is that a rider disputing a five-dollar fee should be disputing a charge with its own descriptor and its own evidence, not a trip that never happened. The estimate's hold is voided in the same breath, so nobody is carrying two authorizations for one ride they did not take. Payouts are gated on Connect onboarding and KYC, so trips completed before verification finishes accrue to a held balance the driver can see and cannot withdraw, which is a product problem long before it is a compliance one. Daily by default, instant on demand for a fee somebody absorbs — the driver, or us as a retention cost — and that one is a business call rather than an architectural one.