
Mint
A digital wallet backend on a double-entry ledger, built to stay correct under concurrency, retries, and partial failures
Team
Solo project
My role
Backend Engineering
Database Design
Testing
Tools
TypeScript
Node.js
Fastify
PostgreSQL
Vitest
Duration
Personal project
Overview
Mint is a wallet API: users hold accounts in a currency, deposit money in, withdraw it out, and transfer it to each other. Every movement of money is recorded as a balanced set of ledger entries, so the system can always prove where every cent came from. The core guarantees live in PostgreSQL itself, not only in application code.
Problem
Moving money looks simple until something goes wrong. A wallet that just adds and subtracts from a balance column breaks in three common situations, and leaves no history to prove a balance is right:
Races
Two withdrawals read the same balance at once, both pass the funds check, and the account goes negative.
Partial failures
A process crashes after debiting one account but before crediting the other, and money disappears.
Retries
A client times out and retries a transfer that actually succeeded, so the user is charged twice.
Goals
The MVP proves a small ledger service can keep money conserved and balances correct under concurrency, retries, and crashes, and prove it with tests. Real payment rails, currency conversion, authentication, and a consumer app are out of scope.
Double entry
Every transaction sums to zero
tx 41 · transfer
Sum 0.00 ✓
Overdraft guard
One withdrawal at a time per account
Balance $100 · row locked
Balance $20, never below zero
Idempotency
A retry never charges twice
Idempotency-Key: 7f3a
1 transaction stored
Append-only
Fixes are new rows, never edits
tx 41 stays unchanged
Reconciliation
Balances rebuild from entries
Account A
Rebuilt $50 = cached $50 ✓
Users
The primary user is a client application, such as a wallet app or another service, that calls the Mint API. It needs one call per money movement, safe retries after timeouts, and clear errors like INSUFFICIENT_FUNDS. The secondary user is an operator who runs a reconciliation to prove cached balances match the ledger.
Requirements
The API exposes accounts, deposits, withdrawals, transfers, paged entry history, and an admin reconcile endpoint. The core requirements:
- Amounts are positive integers in minor units (cents), so there is no floating-point rounding.
- Every write requires an Idempotency-Key. A replay returns the original result; a reused key with a different body returns 409.
- A withdrawal or transfer that would overdraw a user account is rejected and writes nothing.
- Transactions can't mix currencies or transfer to the same account.
- Errors share one shape, with a machine-readable code and a message.
Architecture
A Fastify API validates each request and hands it to a ledger service, which runs every money movement as one database transaction in five steps:
- Claim the idempotency key first, so a concurrent duplicate waits on the unique index and then replays the stored result.
- Lock every touched account with SELECT … FOR UPDATE in a fixed id order, so opposite transfers can't deadlock.
- Reject the write if a user balance would go negative, then update cached balances and insert entries.
- At COMMIT, deferred triggers check that entries sum to zero and use one currency; any failure rolls back everything.
- Retry deadlock and serialization failures with jittered backoff.
Testing
The tests run against a real Postgres database, because that's where the guarantees live. They show that 100 racing withdrawals can't overdraw an account, 50 concurrent duplicate requests post exactly once, 400 random concurrent transfers conserve money and reconcile with zero drift, and raw SQL can't unbalance a transaction, edit history, or go negative.
Risks
The biggest risk is a guarantee that holds in the happy path but breaks under a race nobody tested. Open risks include the external funding account becoming a hot lock under heavy deposit traffic, idempotency keys growing forever without a retention window, and a retry loop hiding a real bug as a transient conflict.
Next steps
The ledger core, concurrency safety, and retry safety are done. Next come reversals and holds, then API keys, structured logs, and metrics, and finally a load test and deploy.