A double-entry posting engine that cannot silently go wrong

The problem

A sale, a purchase, a return, a damaged item written off, a till that is short — every one of them moves money, and every one has to land on the right accounts. Get it wrong and the books are quietly incorrect: no error, no alert, and nobody finds out until a year-end that does not reconcile. Get it defensive and you block the sale, which stops a shop trading.

A multi-tenant ERP and POS platform running the daily operations of twenty-plus retail businesses across Kuwait and the Gulf, including a mid-size superstore. Real cash, real inventory, real tax filings — and no second engineer to catch a mistake in review.

What I built

All of it. I designed the engine, chose its four-stage shape, wrote the rules format, built it, deployed it and support it in production. There was no architect to hand me a spec and no reviewer to disagree with me.

I made the engine four stages, each replaceable. A classifier turns a business event into a transaction type. A rules provider supplies declarative posting rules for that type, with reversal symmetry built into the format rather than written twice. An account resolver maps those rules onto the chart of accounts through 67 named posting roles, so a rule says what it is posting and never which account number. A journal builder writes the balanced debit and credit lines, and each document keeps the tax rate it was posted at. The rules are data rather than code because an accountant can read data, compare two versions of it and argue with it. Seventy-four hand-written posting routines would give them nothing to read.

Proof — one real sale

The panel at the top of this page is drawn in code. This one is not. These are the six journal lines the engine wrote for one real sale, and four things are visible in them without reading a line of source.

• The cash sale goes through Accounts Receivable and is then settled, so a cash sale and an account sale share one code path.
• Cost of goods posts at moving average cost: 0.750 against a 0.875 sale, tying exactly to the 0.125 profit the sales history reports.
• The cash landed on Cash Register 1, that till's own account — the override tier of the account ladder, working.
• No service-revenue line appears, because the basket had no service item. Empty lines are dropped, so opening a till with a zero float posts nothing at all.

What it produced

• Nothing persists unbalanced — if debits and credits disagree the posting throws inside a database transaction, so a half-written journal cannot exist.
• Money is decimal(18,3) end to end, full precision in, rounded once at the edge.
• Document numbering is gap-free, which is a legal requirement in most of the jurisdictions this runs in.
• Every ledger line links back to the document that created it — you can go from a figure on a customer's screen to the journal lines behind it, and back to the invoice.

What I would do next

Automated tests on the financial code. There are none on the web platform, and for the parts I refactor slowly that means nothing tells me when I have broken something. It is the single thing I would change about this engine.