The client's brief for the dispatch rewrite ran to four pages. The constraint that actually shaped the architecture was one sentence a driver said during discovery: "if it takes longer than counting to five, I've already picked up someone off the street."
The number nobody had written down
Five seconds, door to notification, was never in a requirements document before we asked. It had been a shared understanding among drivers and dispatchers for years, enforced by nothing. Once it was a number, it became a budget we could design against instead of a vague sense that the old system was "a bit slow sometimes".
Where the old system spent its time
The previous matcher polled for available drivers, scored them, and pushed a job to the best candidate, in that order, synchronously, on a single worker. Under normal load it hit the five-second mark. During a Friday evening spike it didn't, and nobody could say by how much because nothing measured it end to end.
What we changed
- Scoring became event-driven. Driver location updates push a re-score of nearby jobs instead of jobs polling for drivers.
- The match and the notification are separate concerns. A match decision can be correct and still arrive late if it is queued behind a push notification provider having a slow minute, so we measured and alerted on each stage independently.
- We built in headroom, not just capacity. Load testing to average Friday volume told us nothing. We tested to the worst Friday of the previous year plus fifty percent, because that is the number that would eventually happen again.
The instrumentation we insisted on
Every job now carries a timestamp at creation, at match, and at driver acknowledgement, and we watch the 95th percentile, not the average. The average looked fine on the old system right up until the night it didn't.
A performance requirement that lives only in people's heads gets rediscovered during an incident. Write the number down before you need it.
What surprised us
The bottleneck we expected — scoring a large pool of drivers — was never the real one. The real one was a third-party mapping call that occasionally took four seconds on its own, invisible until we broke down the budget stage by stage. We now cache and time-box every external call in the matching path and treat a timeout as a valid, fast answer rather than a thing to wait out.
What shipped
The rewrite holds its five-second target at the load we tested for, with margin. The more useful outcome is that the number is now on a dashboard the operations team watches, rather than a folk rule that only surfaced when someone complained.