Architecture, stack, key decisions and the quality gates DEV3 Kerbora passed before release.
The engineering behind Kerbora: matching, fare, cancel and surge maths as pure code shared with the Dart apps, a fixed trip-offer-driver lock order, lazy deadlines and card money applied only on confirmation.
The problem it solves
Ride hailing is a race with a clock. A trip is offered to several drivers, but only one may accept, and an accept at the last second must be treated fairly. A driver can go offline while an offer is live. A passenger can cancel as a driver arrives, and the fee depends on exactly when. Surge changes the fare while someone is deciding. Money is in several hands: card, credit, cash collected by the driver, tips, tolls and promos. The same maths must run on the server and in two apps without drifting.
Architecture and approach
Kerbora is a Laravel 12 application with Filament 4 panels at /admin and /dispatch, a public site, signed trip-share links and a REST API used by two Flutter apps.
Pure maths, shared vectors
The match engine, fare maths, cancel maths, trip split, surge and GPS filter are pure PHP classes. Their test vectors live in JSON files that the Dart ports in the apps also run, so server and apps agree to the cent.
One lock order
Every entry point goes through one trip engine that locks the trip, then its offers, then drivers (in ascending id order), with wallets last. It applies any overdue deadline before acting, so deadlines are enforced lazily and the scheduled tick only catches idle trips. Deadlock victims are retried, and range locks on the offers table are avoided by reading ids first and locking by primary key.
Fair and exact
Offer expiry uses whole seconds, so an accept at exactly the expiry second wins. Cash-out locks the wallet row itself, because the driver earnings wallet may go negative and a hold alone would not stop a double cash-out.
Card money on confirmation
Card money is applied only when the payment-succeeded event arrives. Late or duplicate payments are refunded. There is no pre-authorisation, because the shared core has none.
Quality gates and results
Kerbora 1.0.0 passed the seven release gates on the final code: 157 Pest tests with 1,840 assertions, 121 pages and 15 happy paths in a headless browser with race checks on MySQL, the installer test from the zip and a clean secret scan. The passenger and driver apps pass analysis and 161 and 202 tests. A review of the engine fixed nine defects, including a deadlock and an acceptance statistic that always read zero.
Limits are listed on the item page: stored-card charging is simulated, the driver app has no GPS plugin and masked calling is a stub.
Tech stack
| Area |
Technologies |
| Application |
Laravel 12, Filament 4, Blade, REST API |
| Rides |
Pure match engine, Fare and cancel maths, Surge cells, Trip, offer, driver lock order |
| Apps |
Flutter passenger app, Flutter driver app, Shared test vectors, Demo trip simulator |
| Realtime |
Reverb (optional), Polling fallback, Lazy deadlines |
| Quality |
Pest, Larastan level 6, Headless browser smoke, MySQL race checks |
Inside the build
Night grid hero — A dark Solvanna at night while a passenger pin pings a radar ring across the blocks.
Match — Offer arcs reach three cars, two fade and one locks in with a light trail to the pin.