Three protocols, one pipeline: TCP, HTTP and WebSocket in a single process

The hardware was bought before I was involved, which is the normal situation. The locks speak a proprietary binary protocol over a persistent TCP connection, and the manufacturer is overseas. 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.

The architectural question is where those three transports meet. The wrong answer is three services with a message bus between them, which is a lot of moving parts for a fleet this size and introduces delay between a lock reporting its position and an operator seeing it move.

What I shipped terminates all three in one process against one domain layer. A lock checks in over TCP, the handler updates vehicle state through the same service the HTTP API uses, and the change fans out to the dashboard over WebSocket in the same tick. One place where vehicle state changes, three ways to reach it.

The part that took longest was not the protocol work. It was accepting that a physical device is allowed to disagree with the database. A lock that fails to open after the database has already claimed the vehicle leaves a scooter marked in use with nobody on it, 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.