Case study: syncing POS sales from hundreds of stores
Every Mangrove Market store keeps selling when its internet drops, and head office still needs every sale, exactly once, within minutes. This case study designs that pipeline as a full review: requirements, numbers, the upload and acknowledgement protocol, the tables, what breaks, and how you know a store has gone quiet.
By the end you can
- Write requirements and numbers for a write-heavy sync from many offline devices
- Design an upload protocol that survives a lost response without duplicates or gaps
- Keep old POS app versions working with a versioned payload
- Build an ingestion endpoint, an inbox table, a worker and partitioned sales tables
- Alert on stores that stopped syncing, and tell "offline" from "stuck"
The everyday picture
Before software, a branch sent its daily sales to head office in a sealed envelope with a numbered slip: "Envelope 214, 38 receipts, from receipt 9,101 to 9,138". Head office logged each envelope in a register and sent a signed receipt back. If the signed receipt did not come back, the branch sent a copy of the same envelope, with the same number. Head office saw "214 is already in my register", filed nothing new, and signed again.
Each branch kept the carbon copies until the signed receipt arrived. And every evening, a clerk at head office looked for branches that had sent nothing. Numbered envelopes, a register that ignores repeats, carbon copies kept until signed, and a clerk who notices silence: that is the whole design.
Step 1: Requirements
Mangrove's engineers build the sales sync for the POS, the checkout tills in its 320 stores. There are about 400 tills, one or two per store, and each till is a POS terminal running a desktop app with a local database. The business asks for this.
Functional requirements.
- FR1: A cashier can complete sales with no internet, for hours if needed (Offline sync).
- FR2: Every sale reaches head office (HQ) automatically when the internet is back.
- FR3: HQ dashboards show sales by store, hour and article (product).
- FR4: Operations is alerted when a store that should be selling has sent nothing.
- FR5: Support can replay or backfill one store's sales for a date range.
Non-functional requirements.
- No sale lost, no sale counted twice. Finance reconciles to the cent.
- When online, a sale is in HQ's database within 2 minutes for p95.
- The ingestion API is 99.9% available. Short outages are fine, because the POS keeps the sales and retries.
- After a long outage, a store with a day of sales catches up within 15 minutes.
- A stolen terminal can be cut off without touching other terminals.
Non-goals. Live stock at HQ, price downloads to the POS, and editing stored sales. A correction is a new transaction, such as a return.