12
Domain models
money isolated in wallet and deposit ledgers
PRJ-003 · platform · 2025 · field tested on real hardware
Rent a scooter or e-bike from an app: scan the QR, the physical lock opens over cellular, ride, park in a permitted zone, pay by the minute from a prepaid wallet.
What can be checked, and what cannot
The client is unnamed and the code is theirs, so there is no repository to read and no instance to unlock a scooter from. What is checkable is the reasoning: the transport architecture and the claim race are written up in full, and the hardware protocol work was done in direct coordination with the manufacturer's engineers.
3
Protocols
TCP, HTTP, WebSocket in one pipeline
12
Domain models
money isolated in wallet and deposit ledgers
AR / EN / KU
Locales
trilingual rider app
Field tested
Verification
real vehicles, real locks
The problem
A fleet operator needed riders to find a vehicle on a live map, unlock it physically from their phone, and be billed per minute. The hardware had already been bought from an overseas manufacturer, so the system had to speak whatever protocol those locks spoke. Nothing off the shelf covers local payment rails, trilingual UI, or that specific hardware.
The hardware was bought before I was involved, which is the normal situation. Working out the signal set meant direct coordination with their engineers across a time zone gap, establishing what their commands and telemetry actually meant before any of it could be integrated.
Three services, one bus
A lot of moving parts for a fleet this size, and it introduces delay between a lock reporting its position and an operator seeing it move.
A transaction to claim
Two riders scanning the same QR at once is the defining race in this domain, and a transaction cannot be held across a call to a physical lock over cellular.
Assume the lock obeys
A lock that fails to open after the database has already claimed the vehicle leaves a scooter marked in use with nobody on it.
Read the tariff at billing
An operator changing the per-minute rate mid-afternoon would retroactively re-price every ride still in progress, and the rider would be right to dispute it.
The approach
Twelve collections around a User, Ride, Vehicle spine with money isolated in wallet and deposit ledgers. The interesting part is the transport layer. The locks speak a proprietary binary protocol over raw TCP, riders speak HTTP, the operator dashboard speaks WebSocket. I built one pipeline terminating all three against a single domain layer, so a lock checking in over TCP updates vehicle state that fans out to the live map in the same tick.
Geofences are GeoJSON polygons evaluated server-side on every telemetry beat, so parking enforcement happens against the fleet's own view of where the vehicle is rather than the rider's.
Architecture
Three protocols, one process. Raw TCP for IoT lock telemetry and commands, REST for the rider app, WebSocket for the operator dashboard, all sharing one domain layer. Vehicle state is the single point of truth every transport reads and writes through.
The part that took longest was not the protocol work. It was accepting that a physical device is allowed to disagree with the database, so the claim has to be reversible, and reversing it has to be a first-class path rather than something buried in an error handler.
Each with what it cost
All three sit on the same seam: the moment a database row and a physical scooter have to agree about who is riding it.
01
Why
Two riders scanning the same QR at once is the defining race in this domain. A conditional atomic update makes the guard and the lock the same operation, because the status filter is what prevents the second claim.
What it costs
No transaction means the physical unlock that follows needs an explicit compensating rollback. Without the status clause in the filter, both requests pass validation and two riders get billed for one scooter.
02
Why
The database claim happens before the physical unlock, so a lock that fails to open leaves a vehicle marked in use with nobody riding it. The failure path releases the claim so the vehicle stays rentable.
What it costs
A narrow window exists where the lock opened but the acknowledgement was lost. Handled operator-side rather than pretending it cannot happen.
03
Why
A ride copies the per-minute rate and unlock fee when it starts and never re-reads them, so changing the tariff cannot retroactively re-price a ride already in progress.
What it costs
Denormalised pricing on every ride, the right trade when the alternative is billing disputes.
Known limitations
Lost acknowledgement after a successful unlock
A narrow window exists where the lock opened but the acknowledgement was lost. Handled operator-side rather than pretending it cannot happen.
Denormalised pricing
Every ride carries its own copy of the rate and unlock fee. That is the right trade against billing disputes, and it means a tariff correction cannot be applied to rides already running.
One process, three transports
Terminating TCP, HTTP and WebSocket in a single process is right for a fleet this size and is the thing to revisit first if the fleet grows past it. The domain layer is the seam that would make splitting it tractable.