design a double-entry ledger for a fintech app with immutability, idempotency, and balancing

Steps

1. Model every financial movement as a pair of ledger entries: one debit and one credit of equal amount, each belonging to a named account (e.g., user:123:cash, revenue:fees); every entry is append-only and references an immutable transaction record.
2. Assign each transaction a unique, client-generated idempotency key (e.g., a UUID derived from the triggering business event); before inserting, check if the key already exists and return the existing transaction rather than creating a duplicate.
3. Store each ledger entry with: transaction_id, account_id, amount (positive integer in minor units), direction (DEBIT or CREDIT), currency, created_at (server-assigned), and a reference to the source event (e.g., payment_id, transfer_id).
4. Never update or delete ledger entries; to reverse a transaction, insert an equal and opposite pair of entries referencing the original transaction, preserving the full audit trail.
5. Calculate account balances by summing credits minus debits (or the inverse depending on account type convention) over all entries for that account; for performance, maintain a running balance table updated transactionally alongside new entry inserts.
6. Enforce balancing at the application layer: before committing a transaction, assert that the sum of all debit amounts equals the sum of all credit amounts in that transaction; reject and roll back if they differ.