A Dubai bank wants a digital channel for 520,000 users, in front of an AS/400 it cannot replace. Its core services are slow, sometimes down, and owned by another team. And the platform must never show a wrong balance, never report a failed transfer as done, and never execute a transfer twice.
This is the complete architecture, designed stage by stage in a workshop where every decision was challenged before it was accepted.
📄 Architecture document with 43 decisions
💬 Workshop record: every challenge, every reversal
📊 18-slide architecture deck (PowerPoint)
📁 13 editable Excalidraw diagrams
🤖 Constraints and decision records your AI assistant can follow
Founding price for the first buyers. It goes up as copies sell.
Not ready yet? Get 8 slides free →
Inside the blueprint
Every diagram answers a hard question. The blueprint gives you the reasoning, the options rejected, and the decision record behind each answer.
Two teams of four to six developers. The split follows the data each service owns, and one service owns the whole payment lifecycle. See why, and the split it replaced.
Saved as Pending with its outbox message in one transaction, then executed with a reference the bank's services must honour. See who owns retries, failures and reversals.
Customer data can't leave the UAE. See why recovery runs at the bank's own data center, and what that changed in every AWS choice.
The last known balance, labelled “as of”, but only within a freshness period; after that, “unavailable”. See why the platform never guesses a balance.
From the workshop record
Some proposals were wrong and got caught. Others held under pressure.
Bank team: We could drop UAE Pass, no?
Architect: Yes, verify against bank records with an SMS code.
Bank team: What does UAE Pass add? Any blind spots?
Architect: I made an error: SMS codes fall to SIM swap, and the Central Bank ended them in March 2026. UAE Pass stays.
Bank team: Core Integration is our middleware to the bank. Shouldn't the payment worker sit inside the Payment Service?
Architect: Agreed. Retries, statuses and expiry are payment decisions; one owner for the whole lifecycle.
Bank team: A distributed cache has to be justified. If it’s only for balances, use the database.
Architect: Two real uses: posted history, to spare the slow core at payday peaks, and session state shared across instances.
Bank team (at the ADR review): Both can live in the database. Nothing here needs that kind of scale. Justify it properly, or remove it.
Architect: After thinking it over, I reconsidered. A peak of a few thousand reads a second fits a sized database, which already shares session state and keeps history durably. Removed, until measured load says otherwise.
Bank team: Isn’t stdout logging, shipped by agents, tamper-proof enough? Justify a separate audit trail.
Architect: No. Collection is best effort, a setting can silence it, and the people running the logs can edit them.
Bank team: Then no audit code in our business logic.
Architect: Agreed: a shared interceptor writes it, in the same transaction.
Who it’s for
Architects preparing a design review with a CTO or a security team.
Senior developers moving into architecture who want to see a full design, not fragments.
Teams modernising around a legacy core they can't replace.
Anyone preparing for system design interviews in fintech or banking.
FAQ
Before you buy.
The bank is fictional; the situation isn’t. Banking on Change is an original JustifiedCode kata, built from years of real architecture work with clients: the legacy core nobody can replace, services that go down, a security team that challenges every choice. The pushbacks in the record happened, and you’ll recognise them from your own projects.
AWS, Middle East (UAE) region, with a pilot-light DR site at the bank's own data center.
Yes: open the .excalidraw files at excalidraw.com. They use the free Software Architect Toolbox library.
No. The blueprint works at architecture level: the language and framework are left to the delivery teams. The constraints and the hexagonal code structure apply to any stack.
Free sample
Read 8 slides from the architecture deck first: the architecture, the cost, and where the bank team changed the design.