wtf( )unctionsystem design, drawn
← all problemsArchitectureHard

One checkout, five parties, and the money has to add up

A marketplace checkout moves money between five parties at once: the buyer pays, the seller earns, the platform takes a fee, a tax authority is owed, and a promotion is funded out of the platform's own pocket. That is one commercial event and it has to be recorded as one thing.

Finance has one requirement above all others, and they have written it on the wall: the system must never create or destroy money.

  1. R1It must be impossible for a record whose amounts do not sum to zero to exist at all. Not caught, not flagged, not reported the next morning — impossible. Money that has already moved cannot be un-moved by a report about it.
  2. R2Records are legally permanent. A refund, a correction, an adjustment — every one of them is a NEW record that references the old one, and the original stays exactly as it was written, forever. Nothing in this system edits a record that has already been committed.
  3. R3A balance is read inside the checkout request, for any of a billion accounts, and the answer must be current. It also has to still be fast in five years, when the account with the most history has ten million entries behind it and the newest account has three.
Compose the money path. Tier 1 is what stops an unbalanced record existing and what the record is kept in, tier 2 is what a balance is read from.
Components — tap one, then tap a slot on the diagram
!A promotion was funded twice and charged once. Nobody noticed for nine days, because the report that would have caught it runs at 03:00 and reported a difference of £0.00 — the two halves had landed in different days.Every one of these five entries is correct on its own. The requirement is about the SET: five amounts that sum to zero, recorded together or not at all.

Boundaries, outermost first: LEDGER CORE: an empty slot for the nothing gets past it unbalanced, tier 1, an empty slot for the the five entries, kept, tier 1, an empty slot for the read while the buyer waits, tier 2 Outside every boundary: Entity changelog (every delta, in order), Auditor (asks what was decided), Checkout (a person is waiting), Five parties (one commercial event) Connections: Five parties calls Checkout (step 1) Checkout calls nothing gets past it unbalanced — five entries (step 2) nothing gets past it unbalanced calls the five entries, kept — sums to zero, or nothing (step 3) the five entries, kept publishes to read while the buyer waits (step 4) the five entries, kept publishes to Entity changelog (step 5) read while the buyer waits calls Checkout — balance, now (step 6) Entity changelog calls Auditor — what was decided (step 7)

Entity changelogevery delta, in order
Auditorasks what was decided
Checkouta person is waiting
Five partiesone commercial event