When building a core financial ledger, the single most dangerous line of code you can write looks completely harmless:
@Transactional public TransferResponse postTransfer ( TransferRequest request ) { // 1. Update balances & create ledger entries in Postgres updateBalances ( request ); createLedgerEntries ( request );
// 2. Publish event to Kafka kafkaTemplate . send ( "transfers.posted" , new TransferEvent ( request )); // ❌ DISASTER
return response ; }
Enter fullscreen mode
Exit fullscreen mode
It looks clean. It passes unit tests. And in production, it will inevitably corrupt your financial system.
Here is the story of how I encountered the classic Dual-Write Problem while designing LedgerX - a double-entry ledger engine - and how implementing the Transactional Outbox Pattern gave me verifiable, crash-resilient exactly-once semantics.
The Dual-Write Trap
In a distributed financial system, you need two things to happen when money moves:
Mutate state in PostgreSQL (balances, immutable journal…