Skip to main content
IRL Scenarios · seven of them Architecture documentation explains what a system does. It is much worse at explaining why anyone bothered, because the reason is always a failure, usually one somebody else already had, expensively. These are that layer: the things that actually go wrong in payments infrastructure, written as the scenarios they are. Each one opens on a symptom, walks the diagnosis the way it would really go, and ends at the specific mechanism in Arc that prevents it. They are self-contained and readable in any order.
Two of these describe things that genuinely happened while building Arc: a mutation that passed sixteen tests, and a boundary rule that silently did not apply. Those are marked. The rest are the standard failures of this domain, written as scenarios because that is how they are actually learned.

Start here if you read one

The journal that balanced and lied

Compensation ran in the wrong order. The ledger balanced perfectly. All sixteen tests passed. The audit trail was fiction.The lesson: balance is necessary but not sufficient. This is the best argument on the site for why correctness needs more than one kind of assertion, and it is the scenario most worth retelling in an interview.

By theme

The cent that vanished

The trial balance is off by €0.03. Nobody can find it, because it was never in one place. It was 0.00995 of a cent, three hundred times, rounded away into nothing. Mechanism: residuals posted to a rounding account.

The journal that balanced and lied

A balanced ledger with a false audit trail, and a mutation test that caught what sixteen assertions did not. Mechanism: reverse-order compensation, asserted directly.

Why this format

A mechanism explained is forgettable.“Rails are idempotent on the caller’s key” is a true sentence that will not survive the week.
A mechanism that solved a specific disaster is not.“The rail timed out, we retried, and the beneficiary got paid twice” is remembered, and the mechanism comes with it.
Every scenario ends with the code that prevents it and a link to the architecture page that specifies it, so the narrative is an entry point rather than a substitute.

Prefer the specification?

The architecture tab covers the same mechanisms without the narrative framing.