Cheat sheet · Business processes
Double-entry ledger
The problem
A marketplace keeps buyer wallets, pays sellers and takes a fee. A balance column updated in place loses money in races and cannot say where it went. A double-entry ledger records every movement as an entry whose postings sum to zero, derives balances from it and never rewrites history.
What you learn
- Why a balance column updated in place loses updates and leaves no trail
- Accounts, journal entries and postings that sum to zero, written in one transaction
- Derived balances with a versioned cache, idempotency keys, holds and available balance
- Refunds as reversal entries, one currency per sum, and a daily trial balance with alerts
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_app(["Buyer app"])
n_api["Wallet API"]
n_ledger[("Ledger")]
n_balances[("Balance cache")]
n_payout("Capture job")
n_support(("Support agent"))
n_rates>"FX rates"]
n_checker("Trial balance")
n_pager>"On-call alert"]
n_app --> n_api
n_api --> n_ledger
n_api --> n_balances
n_payout --> n_ledger
n_support --> n_api
n_api --> n_rates
n_checker --> n_ledger
n_checker --x n_pagerMermaid: request sequence
sequenceDiagram
participant n_api as Wallet API
participant n_wallets as Wallets table
participant n_ledger as Ledger
participant n_balances as Balance cache
participant n_app as Buyer app
participant n_checker as Trial balance
Note over n_api,n_wallets: A wallet is one number in one row
n_api->>n_wallets: SELECT balance_minor FROM wallets WHERE user_id = 'u_42'#59;
n_wallets-->>n_api: UPDATE 1
Note over n_api,n_wallets: Two payments at once, one of them vanishes
n_api->>n_wallets: 12:00:01.204 tx A read balance_minor=12000 (order 4500)
Note over n_api,n_ledger: Every movement is an entry, its postings sum to zero
n_api->>n_ledger: BEGIN#59;
n_ledger-->>n_api: COMMIT
Note over n_api,n_balances: The balance is a sum, cached with a version
n_api->>n_balances: UPDATE account_balances
n_balances-->>n_api: UPDATE 1
Note over n_app,n_api: A retry posts the same payment twice
n_app->>n_api: 14:02:10 POST /v1/orders/ord_5133/pay -#62; no answer in 5 s
Note over n_app,n_api: One key per business operation
n_app->>n_api: POST /v1/orders/ord_5133/pay HTTP/1.1
n_api-->>n_app: HTTP/1.1 200 OK
Note over n_app,n_api: Holds: ledger balance and available balance
n_app->>n_api: GET /v1/wallets/u_58/balance HTTP/1.1
n_api-->>n_app: HTTP/1.1 200 OK
Note over n_api,n_ledger: A refund is a new entry, never an edit
n_api->>n_ledger: INSERT INTO journal_entries (id, kind, ref, reverses)
n_ledger-->>n_api: INSERT 0 3
Note over n_api,n_ledger: One currency per sum, FX goes through accounts
n_api->>n_ledger: INSERT INTO postings (entry_id, account, amount_minor, currency)
n_ledger-->>n_api: COMMIT
Note over n_checker,n_ledger: Every night: does everything still sum to zero?
n_checker->>n_ledger: SELECT currency, SUM(amount_minor) AS total
n_ledger-->>n_checker: trial balance 2026-11-17D2
direction: right
n_app: "Buyer app" {
shape: rectangle
}
n_api: "Wallet API" {
shape: rectangle
}
n_ledger: "Ledger" {
shape: cylinder
}
n_balances: "Balance cache" {
shape: cylinder
}
n_payout: "Capture job" {
shape: rectangle
style.multiple: true
}
n_support: "Support agent" {
shape: person
}
n_rates: "FX rates" {
shape: cloud
}
n_checker: "Trial balance" {
shape: rectangle
style.multiple: true
}
n_pager: "On-call alert" {
shape: cloud
}
n_app -> n_api
n_api -> n_ledger
n_api -> n_balances
n_payout -> n_ledger
n_support -> n_api
n_api -> n_rates
n_checker -> n_ledger
n_checker -> n_pager {
target-arrowhead.shape: cross
}PlantUML: request sequence
@startuml
participant "Wallet API" as n_api
database "Wallets table" as n_wallets
database "Ledger" as n_ledger
database "Balance cache" as n_balances
participant "Buyer app" as n_app
participant "Trial balance" as n_checker
note over n_api, n_wallets : A wallet is one number in one row
n_api -> n_wallets : SELECT balance_minor FROM wallets WHERE user_id = 'u_42';
n_wallets --> n_api : UPDATE 1
note over n_api, n_wallets : Two payments at once, one of them vanishes
n_api -> n_wallets : [duplicate] 12:00:01.204 tx A read balance_minor=12000 (order 4500)
note over n_api, n_ledger : Every movement is an entry, its postings sum to zero
n_api -> n_ledger : BEGIN;
n_ledger --> n_api : COMMIT
note over n_api, n_balances : The balance is a sum, cached with a version
n_api -> n_balances : UPDATE account_balances
n_balances --> n_api : UPDATE 1
note over n_app, n_api : A retry posts the same payment twice
n_app -> n_api : [duplicate] 14:02:10 POST /v1/orders/ord_5133/pay -> no answer in 5 s
note over n_app, n_api : One key per business operation
n_app -> n_api : POST /v1/orders/ord_5133/pay HTTP/1.1
n_api --> n_app : HTTP/1.1 200 OK
note over n_app, n_api : Holds: ledger balance and available balance
n_app -> n_api : GET /v1/wallets/u_58/balance HTTP/1.1
n_api --> n_app : HTTP/1.1 200 OK
note over n_api, n_ledger : A refund is a new entry, never an edit
n_api -> n_ledger : INSERT INTO journal_entries (id, kind, ref, reverses)
n_ledger --> n_api : INSERT 0 3
note over n_api, n_ledger : One currency per sum, FX goes through accounts
n_api -> n_ledger : INSERT INTO postings (entry_id, account, amount_minor, currency)
n_ledger --> n_api : COMMIT
note over n_checker, n_ledger : Every night: does everything still sum to zero?
n_checker -> n_ledger : SELECT currency, SUM(amount_minor) AS total
n_ledger --> n_checker : trial balance 2026-11-17
@endumlPlantUML: components
@startuml
left to right direction
agent "Buyer app" as n_app
component "Wallet API" as n_api
database "Ledger" as n_ledger
database "Balance cache" as n_balances
collections "Capture job" as n_payout
actor "Support agent" as n_support
cloud "FX rates" as n_rates
collections "Trial balance" as n_checker
cloud "On-call alert" as n_pager
n_app --> n_api
n_api --> n_ledger
n_api --> n_balances
n_payout --> n_ledger
n_support --> n_api
n_api --> n_rates
n_checker --> n_ledger
n_checker -[#c62828]-> n_pager
@endumlRecap
Six rules for money in a product.
1) Never keep money as a number overwritten in place. 2) Every movement is a journal entry whose postings sum to zero, inserted in one transaction. 3) Balances are sums of postings; a cache is fine if it has a version and can be rebuilt. 4) One idempotency key per business operation; holds lower the available balance until capture or expiry. 5) Undo with reversal entries, never UPDATE or DELETE; one currency per sum, FX through accounts. 6) Run a trial balance every day and page a person when it is not zero.
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Unexplained money | 0 $ | 0 $ |
| Lost updates | 0/day | 0/day |
| Double charges | 0/day | 0/day |
| Balance read | 2 ms | 3 ms |
Steps
- Case A wallet is one number in one row
A buyer pays $45.00 for an order.
- Problem Two payments at once, one of them vanishes
The buyer pays one order on the phone and another in the browser in the same second.
- Fix Every movement is an entry, its postings sum to zero
The wallet becomes an account, and so do the seller and the platform's fee income.
- Fix The balance is a sum, cached with a version
The true balance is
SUM(amount_minor)of an account's postings. - Problem A retry posts the same payment twice
The pay request times out on a slow network.
- Fix One key per business operation
The app creates the key once per payment,
pay-ord_5133, and sends it on every retry. - Fix Holds: ledger balance and available balance
A buyer orders a $129.00 item that ships next week.
- Fix A refund is a new entry, never an edit
Support refunds order
ord_5120. - Fix One currency per sum, FX goes through accounts
A buyer pays 100.00 EUR into a USD wallet.
- Fix Every night: does everything still sum to zero?
A nightly job runs the trial balance: the sum of all postings per currency must be exactly zero.
- Recap Recap
Six rules for money in a product.
Terms
- Double-entry ledger
- Every money movement is one entry whose postings sum to zero: debit equals credit.
- Trial balance
- A regular check that all postings in each currency sum to exactly zero.
- Reversal entry
- A new entry with opposite postings that undoes an earlier one without editing it.