POS Framework

What it is

The transaction core is the framework; retail, food service, rentals, and rent-to-own are plugins on top of it. The bet is that a retail sale, a dinner tab, a rental contract, and a rent-to-own agreement are all the same thing — an order with different line types and lifecycle rules.

I ran a retail store for three years. I know what happens when the card reader hangs with a line at the counter, so the architecture is built around failure: a register never blocks a sale on a non-essential failure, and it keeps selling with the network unplugged.

“A register never blocks a sale on a non-essential failure. Printer down: complete the sale. Network down: keep selling. Every cashier-facing error states an action, never a stack trace.”POS core design spec

The parts that were hard

• Money is a type, not a number — integer minor units, and the type system refuses to mix Money with a plain number. Floating-point cents is the most common bug class in this software and it is fully preventable.
• Nothing financial is ever mutated or deleted. A void is a compensating event; a refund is a new event referencing the original. One mechanism gives you Z-reports, audits, and offline replay.
• Order lines snapshot everything at sale time — price, tax rate, discount rule and its version — so a receipt reprinted years later shows what the customer actually paid.
• IDs are generated locally and prefixed by register, so a terminal offline for hours creates orders with no coordination and no collision risk.
• Card data never touches the code. P2PE-certified readers are driven server-side, which is the difference between a short compliance questionnaire and a full audit.
• A payment is never blind-retried. The idempotency key is written before the processor is contacted, because double-charging a customer is the one failure that permanently loses an account.