Multi-Branch Retail Operations Platform

The cashier taps charge, the connection drops, and nobody knows whether the sale landed. Tapping again risks charging the customer twice and deducting stock twice; not tapping risks a customer leaving unbilled.

The till generates an identifier for the checkout before sending it. Inside the sale transaction the server takes a PostgreSQL advisory lock on that identifier, so a retry arriving while the first request is still committing waits rather than races it. It then looks for sales already recorded under that identifier: the same items, salesperson and payment method mean this is a retry, and the original receipt is returned from the committed rows rather than recalculated — so it still works even if the salesperson has clocked out since. The same identifier with a different basket is a conflict, not a retry, and is refused.

Idempotency was not a header added at the end. It is a decision about what an operation is, taken by the client before the operation happens.

Selling one 30 ml bottle of oil consumes raw oil, an empty 30 ml bottle and often a carry bag, all belonging to that specific branch.

Inventory items are typed — raw material oil, packaging bottle, packaging bag, tester, finished spray. An oil variant links to both a bulk oil item and a bottle size, and a product cannot be created at all without that link, because the link is what makes volume-level deduction possible. A sale aggregates requirements per inventory item first, so two 15 ml lines become one 30 g claim rather than two competing ones, then deducts them inside the sale transaction using conditional updates so the database itself refuses to go below zero.

Sellability is therefore derived, not stored: a branch screen can honestly show 500 ml of oil in stock and still mark the product as not sellable, because the bottles have run out.

Online, a card payment can be captured successfully and the order can still fail to be created. The customer has paid and has nothing.

Before anything is created the server verifies the payment independently — not only its status, but that the captured amount matches the platform’s own authoritative total in the expected currency. Order creation and stock deduction then run in one bounded transaction. If the amount disagrees, or that transaction fails after capture, the server refunds immediately with a fresh idempotency key, records the failure with a snapshot of the checkout and cart, raises an error-monitoring event, emails an administrator and tells the customer plainly what happened.

The decision that mattered was persisting the snapshot. A refund that fails leaves a capture with no context; a stored record leaves something a person can actually resolve.

An employee’s threshold for a day is their wages for that day — hours worked times their hourly rate — multiplied again by a branch-configured factor, four on weekdays and seven at weekends. Commission is a percentage of sales above that threshold. Every input can change after the fact, and an administrator can edit the rules.

So the ledger stores one row per employee, per branch, per branch-local business date, holding not just the answer but the inputs and the rules that produced it: hours, the rate applied, the multiplier applied, the percentage applied, ex-tax sales, and the commissionable amount. Recalculation is idempotent and keyed on that identity. Only pending rows recalculate — approved, paid and rejected rows are returned untouched, because recalculating them would silently rewrite a decision. Rules resolve by date, so editing a multiplier applies from the next branch-local day and an earlier pending day still uses the rules in force then.

Commission is credited to the salesperson, not the register operator, and calculated on merchandise revenue excluding tax. The employee’s phone and the approver’s ledger read from the same calculator, so they cannot disagree.

Paying someone touches the settlement record, the wage information explaining it, the commission rows it settles and the adjustments it absorbs. If some of that lands and some does not, a person is simultaneously paid and owed.

Settlement runs as a single transaction covering all four. The client sends who is being paid, through which date, and when the money moved — never an amount, because a figure that travels through a browser is a figure that can be edited. A request key makes confirmation idempotent, so a replay returns the original settlement rather than paying twice.

Where a historic attendance session predates wage-rate snapshots its value is genuinely unknown. The system reports those hours, declines to value them, and declines to pay the employee at all until they are resolved — paying the rest would mark someone settled while hours nobody can price stay unpaid. The missing rate has to be stated by an administrator, bounded by the same limits as any forward-looking rate change, recorded against the person who stated it, and written once.