Download CV
← all 25 systems

PRJ-003 · platform · 2025 · field tested on real hardware

Vehicle Rental Platform

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

A micromobility fleet operator, under NDA. Verified on physical hardware, not in simulation

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.

Where the obvious architectures break

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

One place where vehicle state changes, three ways to reach it

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.

Node.jsRaw TCP socketsWebSocketMongoDBGeoJSON geofences

Three decisions

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

Compare-and-swap instead of a transaction to claim a vehicle

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

Compensating rollback when the hardware refuses

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

Price snapshotting onto the ride at unlock

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

The window that cannot be closed

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.