DEV Community: EzeFrancis

Six decisions behind a cross-border transfer engine

EzeFrancis — Mon, 02 Nov 2026 19:24:47 +0000

I built a backend that moves money between currencies. The product is deliberately small: two currencies (NGN and CAD), mocked FX and webhook providers, and a handful of endpoints. The point was the layer underneath, where payment software fails: rounding errors, balances that drift from their history, retries that double-send, and customers who never know the money arrived.

This post covers six decisions I would defend in a design review, what each one costs, and what went wrong along the way. The code and the README are here.

1. Money is never a float

In JavaScript, 0.1 + 0.2 is 0.30000000000000004. In a ledger, that bug compounds. So amounts travel as strings, all arithmetic goes through one small module built on decimal.js, and the database stores them as NUMERIC. A unit test fails against a float implementation, which is how I know the rule is enforced and not just intended.

The cost is ceremony: nobody gets to write a + b on money. I think that is the right price, because funnelling every calculation through one module is the only way a rule like this survives a team.

2. An append-only, double-entry ledger

Every movement of money is a set of ledger entries that net to zero. Entries are never updated or deleted; a correction is a new, offsetting entry. That makes the system auditable by construction, and any balance can be rebuilt by replaying entries.

I also keep a cached balance on each account, updated in the same database transaction as the entries, because summing a growing table on every request is a poor trade. The cost is that it is a second copy of the truth. A scheduled job that compares the cache with the ledger is the first thing on my “next” list, and the README says so plainly.

3. Cross-currency transfers need four entries, not two

Sending 500 NGN to a CAD account is not one debit and one credit. The two sides are different currencies and different amounts. I use a pool account per currency as the counterparty:

The first two entries net to zero in NGN and the last two net to zero in CAD, so each currency balances on its own. The 0.46 is 500 multiplied by the rate locked when the transfer was created, rounded to two decimals. That rate is tied to the transfer with a unique constraint, so it can never be re-locked: the price shown is the price charged.

The simpler option was a single debit and credit with a conversion note on the side. I rejected it because then no currency’s ledger actually balances. The cost is real: a pool’s balance goes negative in one currency and positive in the other, which represents the platform’s open position, and there is no liquidity management on top of it yet.

4. Lock the rows, then prove the lock works

Two requests try to spend the same 100 at the same moment. Both read the balance, both see enough money, both proceed. The fix is pessimistic locking: inside the ledger transaction, I lock every account involved with SELECT ... FOR UPDATE before checking the balance, so the second request waits and then sees the true balance. Locks are always taken in account-id order, which prevents a deadlock when A is paying B while B is paying A.

I chose pessimistic locking over optimistic retries because correctness matters more than throughput on a hot account, and because the failure mode is simple to reason about. The cost is that a very busy account becomes a serialization point.

The part I care about most is the test. Two transfers of 60 against a balance of 100: exactly one must succeed. Five transfers of 30: exactly three. Then I deleted the lock and watched both go red. A test you have never seen fail has not proven anything.

One accident helped. My database was on Neon and my Redis on Redis Cloud, about 190 milliseconds per round trip. That made every transaction slow and every race wide, which is exactly what you want when you are trying to catch one.

5. Idempotency has two layers

Clients retry and networks time out, and a retried “send money” request must not send money twice. Each transfer request carries an Idempotency-Key. A short Redis lock ( SET NX with a 30-second expiry) ensures only one request with that key is processed at a time. A Postgres record stores the response. A concurrent duplicate waits for the first to finish and gets the identical response; a later duplicate gets the stored response straight away, and the same key with a different payload is rejected.

Two details worth pointing out. Keys are namespaced by user, so one customer cannot collide with another. And I store 4xx responses but not 5xx ones: a 5xx means “we don’t know what happened,” and the client should be able to retry. The cost is that stored keys have no expiry job yet.

6. Notifications are data, not fire-and-forget

“Money sent, no alert received” is a support ticket waiting to happen. So each notification is a row with a status, an attempt count, and the last error, created before the job is queued. A worker sends it. On failure, it retries with exponential backoff (1, 2, 4, and 8 seconds, five attempts), and after the last attempt the row becomes dead_letter, and the job stays in BullMQ’s failed set for manual follow-up. “Did they get notified?” becomes a query instead of an escalation.

Two consequences. Delivery is at least once, so receivers should deduplicate. And a notification failure never fails the transfer, because by then the money has already moved: failing the request would invite a retry of something that already happened.

Where it runs

During development, the code runs against Neon (PostgreSQL) and Redis Cloud. The target deployment is one EC2 instance in a public subnet, with RDS PostgreSQL and ElastiCache Redis in private subnets, each reachable only from the instance’s security group. BullMQ is a library: its queues live in Redis, and the worker is simply a second process next to the API.

Smaller calls that mattered

The state machine is enforced twice: a pure module in the code and a CHECK constraint in the database. Status changes are compare-and-set, and the funds_moved update happens inside the ledger transaction, so money and status cannot disagree.
Redis holds only what can be recomputed: the rate cache, short locks, and queue state. If it vanished, no financial record would be lost.
Plain SQL through pg instead of an ORM, because transactions, locks, and constraints should be visible in code review.
Tests run against real PostgreSQL and Redis, with failure injection: one test makes the ledger throw halfway and checks that nothing persisted.

What went wrong during development

I seeded demo balances straight into the cached column, so they have no ledger entries behind them and cannot reconcile. I caught it while writing the balance-reconstruction function. The lifecycle test now funds its account through the ledger, and a real deposit flow is on the list.
A timing test failed because 190-millisecond round trips swamped a 200-millisecond retry delay. I fixed it by making the delay dominate the noise instead of loosening the assertion.
A test teardown deleted rows in the wrong order, hit a foreign key, and hung the whole run because the connections never closed. Teardown now closes everything in a finally block.

What I would build next

A reconciliation job that checks every cached balance against the ledger and alerts on drift.
A transactional outbox for notifications, which closes the window where Redis is down and a delivery row exists with no queued job.
A recovery job for transfers left between states by a crash.
Quote-then-confirm FX, where the stored rate expiry finally gets enforced.
A real FX provider with a spread model.
A per-attempt notification log, signed webhooks, and real push and SMS providers.

The full README, with the diagrams and every trade-off above, is here. 73 tests pass. If you had decided any of these differently, I would like to hear why.

Building a Delivery Dispatch Backend: The Decisions That Actually Mattered

EzeFrancis — Mon, 02 Nov 2026 14:53:22 +0000

Most backend portfolio projects are CRUD with extra steps. I wanted to build something with actual teeth, a system where the interesting work isn’t the endpoints but the handful of places where a naive implementation would quietly break under real conditions.

So I built a scaled-down version of what sits behind an app like Uber Eats or Chowdeck: a backend that coordinates customers, vendors, and riders through the full order lifecycle, live rider matching, atomic assignment under concurrency, idempotent payment webhooks, and automatic reassignment when nobody’s available.

This article isn’t a tour of every endpoint. It’s a discussion of questions I had to answer with code and why I answered them the way I did.

“What happens when two orders want the same rider at the same instant?”

This is the core of the whole dispatch problem. A customer’s order gets accepted by a vendor, and the system needs to find the nearest available rider and lock them in. Still, if two vendors accept orders within milliseconds of each other, and the pool of available riders near both is the same three people, you will get a collision eventually.

The naive fix would be to “check if the rider is available, then assign them.” But that has a race condition baked directly into its two steps. Both requests can pass the check before either one writes.

I used two atomic Redis operations instead of application-level locking:

SET order:lock:{orderId} riderId NX EX 10: an atomic compare-and-set with a self-expiring TTL, so a crashed process doesn’t leave an order permanently locked.

SREM riders:available riderId: Redis’s set-remove command returns exactly how many elements it removed. Only the caller that gets 1 back actually claimed the rider. Everyone else, even if they got there “at the same time” from the application’s perspective, gets 0 and moves to the next candidate.

“What happens when a payment provider retries a webhook?”

Payment providers don’t trust a single delivery attempt. If they don’t get a fast 200 response back, they resend, sometimes more than once. Any webhook handler that isn’t explicitly idempotent will eventually double-process a payment.

I handle this by inserting the event’s event_id into a table with a UNIQUE constraint inside the same database transaction as the status update. A duplicate delivery hits that constraint; the transaction rolls back cleanly, and the response is still a 200 (so the provider stops retrying), so it just reports duplicate: true instead of reprocessing.

This is a different idempotency mechanism from the one on order creation, which uses a client-supplied Idempotency-Key cached in Redis. That’s deliberate: order creation is client-driven (the client decides what counts as “the same request,” useful when it can’t tell if a timed-out request actually succeeded), while the webhook is server-driven (the event’s own identity is authoritative, and the guarantee has to survive concurrent delivery, which a Redis cache with a TTL doesn’t guarantee as strongly as a database constraint plus a row lock). Using one pattern everywhere would have been simpler to write and wrong for at least one of the two cases.

“Why mock the payment gateway?”

I mocked the payment provider rather than integrating a real sandbox (Paystack, Flutterwave), and I want to be upfront about why, because it’s a deliberate trade-off, not a shortcut.

The engineering that actually matters here, which is the HMAC signature validation, the idempotent processing logic above, and the payment state machine, is identical regardless of which provider sits behind it. A real integration would have meant a provider account, API keys, and a public tunnel just to receive callbacks during development. None of that demonstrates additional backend design skill; it’s setup friction. Swapping in a real provider later touches exactly two functions, initiation and the webhook handler, because the transaction logic and schema were built provider-agnostic from the start.

“What happens when no rider is available at all?”

This is the failure mode that’s easy to leave as an afterthought. If dispatch can’t find anyone, the order can’t just sit in limbo forever.

When a vendor accepts an order, a delayed timeout job gets scheduled alongside the immediate dispatch attempt. If dispatch doesn’t find anyone, the timeout fires later and hands the order to a background worker that retries matching with a fixed backoff. If every retry is exhausted and still nobody’s available, the system writes a notification for both the customer and the vendor, telling them to cancel instead of leaving the order stuck with no visibility into why.

Keeping this as a separate background worker, rather than retrying inline on the request, matters for a boring but important reason: a slow reassignment retry should never block a customer’s “place order” request. The two run as entirely separate processes.

What I’d do differently with more time

Being specific about scope boundaries is part of showing the work, not hiding gaps:

A real payment gateway, once there’s an actual need to move money
Routing-API-based ETAs, since the current matching is straight-line distance, not drive time
Push notifications instead of the current DB-polled notification table
Rate limiting on auth and the webhook endpoint
Structured, correlated logging across the API and both workers

Full architecture diagrams, the AWS deployment shape, and the complete decision log are in the project’s README here.