loklflow

Taking an order and charging for it are the two operations that cannot depend on the internet provider having a good day.

A cloud API with the venue’s network as a thin client, which is the default architecture and the one I would have picked out of habit. It loses at the only moment that matters: when the link drops, a thin client has nothing to do. I also rejected a native app per device, which would solve the same thing in exchange for three codebases and an app store.

The internet stops being a dependency for operating. The cost is large and worth stating: a real deployment means putting a machine in a kitchen, so what I keep running at loklflow.juank.tech is a remote instance, an exception made to show the system. And that exception is the only deployment of this system that depends on its link for everything and not just for taking payment.

Every order carries a short readable number that the waiter calls out in the kitchen. It has to be unique and must not jump around oddly.

It was computed as MAX(order_number) + 1. Eight simultaneous creations returned 500: several read the same maximum, the first won, and the others’ retries collided with each other again. The migration’s own comment says that with two waiters taking orders at once, the order was lost.

A SELECT … FOR UPDATE over the last order, which serialises correctly and would turn every order creation into a wait behind the previous one — precisely at peak hour, which is when the problem shows up. I did not measure it: I rejected it for what I expect it to do, not for a number. And a retry with random backoff over the MAX, which lowers the probability without removing it.

Eight simultaneous creations produce eight distinct numbers, and an integration test asserts it. The sequence was declared deliberately without SET DEFAULT and without OWNED BY, so TypeORM’s automatic synchronisation in development cannot fight it. The cost is that numbers can jump if a transaction aborts: nextval is not returned. For an operational counter that is acceptable; for a tax receipt number it would not be.

If a device is going to be able to resend an order that may already have arrived, the server has to be able to recognise it as the same order and not as a new one.

A server-generated id plus a client_request_id column, which works but forces id translation at sync time. And — this is the important one — I rejected catching the unique-key violation and treating it as “already existed”. With TypeORM that does not work: save() on an entity with an existing primary key does not fail, it does an UPDATE. It would have silently overwritten the order and, through the cascade, its line items too. The exception I was waiting for never arrives.

Five concurrent replays of the same uuid leave exactly one row, and a test counts it with count(*). The cost is an extra read before every write, and accepting that the client decides the identifier — which is right here and would be unacceptable if the id had to be secret or unpredictable.

A partial payment gets recorded several times against the same tab: someone pays 40 of 100, then 60. A resend cannot turn into an extra charge.

The comment on the migration that fixed it puts it plainly. It is in Spanish because it comes from a real file, and it is quoted here untranslated for that reason:

A repeated full payment bounces off the closed tab, but a repeated partial payment goes straight through and adds up: two clicks leave 60 charged against a tab of 100. That last line is the one that matters for the section further down: with an automatic retry queue, the double charge stops being an accident and becomes the normal behaviour.

Making the column mandatory, which is the clean answer and breaks the wired point of sale, which sends no key because it does not need one. And a second idempotency-key table, which is the textbook solution and adds a write and a table for a case the index already solves.

The index is unique but allows nulls, because Postgres permits multiple nulls in a unique index. That gives an opt-in guarantee per client without a second table. And there is a test asserting that the un-keyed case does produce two distinct charges, because that is the correct behaviour and not a gap: two genuine partial payments are two payments.

A cashier opens a shift, takes payments during their run, and closes with a cash count. That entire count depends on there being exactly one open shift.

The check lived in the service: read whether there is an open shift, and if not, create one. Two tabs or a double click open two shifts. Payments split across both and neither balances.

Leaving it in the service with a transaction and a row lock on the user, which works and puts the guarantee in the code that reads it rather than in the structure that holds it. A full unique index would not do either: it would prevent the next day’s second shift.

The race stopped existing, and because the violation is translated it never surfaces as a 500 — the cashier sees the same clear message as before. The service check stays for the normal case; the index is the net underneath. The cost is that the rule now lives in two places and you have to remember that the lower one is authoritative.