Raymond Russell Dias

An order arrives as JSON. That is where the similarity between platforms ends. They disagree about how to express a modifier, whether a modifier can itself carry modifiers, where tax lives, whether a discount attaches to the order or to the line item, and what a “special instruction” is allowed to contain.

So the first job is to flatten all of them into one internal representation that is strict enough to reason about and loose enough to survive a platform shipping a schema change on a Friday. Everything downstream depends on that shape being right, which means the normalization layer is where you want your tests, and where a bug is cheapest to catch.

Now run it in reverse. The normalized order has to become a ticket that a specific POS will accept and that a specific kitchen will read correctly — with that restaurant's own item IDs, its own modifier groups, its own tax rules, its own tender types.

The mapping is per‑store, not per‑brand, because a franchise location will have quietly renamed half its menu. When the mapping is wrong the failure is not an exception in a log; it is the wrong food, in a bag, going out the door. That asymmetry drives most of the design decisions on this side of the system.

When the ordering platform hands us an order and gets a 200 back, that response is a promise. The order is in our custody now. Whatever happens between us and the point of sale after that is our problem to solve, not the platform's and not the customer's. The ticket is going to reach the kitchen, by hook or by crook.

Most of the time it goes in clean, as a fully mapped ticket. When it doesn't, there is a ladder to climb down. An item that won't map goes in as an open item the kitchen can still read. A ticket that half-maps goes in as a hybrid, the mapped items alongside the open ones. A POS that won't take the ticket at all gets an email to the store so the food gets made while the automatic retries keep working, each one carrying the same order reference so nothing is cooked twice. And behind all of it there is a person: somebody fixes the mapping, re-sends the order, and confirms the success webhook went back to the platform so the customer's app is telling the truth. We have our ways.

Accepted, in progress, ready, picked up. Each of those has to travel back out to the platform the order came from, so that the little progress bar in someone's app is not lying to them.

The states don't line up cleanly between vendors, the transitions don't always arrive in order, and some POS systems will happily tell you an order is ready before anyone has touched it. Mapping a messy real-world lifecycle onto each platform's stricter one — without inventing information you don't have — is most of the work.

Orders flow into the POS. The menu flows out of it, and has to be projected onto every platform the restaurant sells on, in each platform's own vocabulary. Modifier groups with minimum and maximum selections. Nested modifiers. Per‑platform price overrides, because delivery menus are marked up.

Then it changes. An item gets 86'd at 7pm on a Saturday and every platform needs to know now. Hours are per‑store and per‑timezone, holidays are per‑franchise, and a store that pauses for a rush has to come back on by itself. Menu drift is the quiet killer — nothing errors, the menus just gradually stop agreeing, and you find out from a customer.

A restaurant taking an order on its own website still needs a driver. So the platform dispatches a third-party courier on the merchant's behalf, and now you are tracking a person moving through a city on top of everything else.

Live order management, status updates as the courier is assigned and picks up, and geofenced notifications that fire when the driver comes within a radius of the drop‑off. It is the one part of this system with a physical object moving through the world, which makes it the one part where the failure modes are the most fun to explain and the least fun to be on call for.