DEV Community: Tochukwu Amaechina

Building PurpleWallet: a full-stack fintech app with a real ledger, AI, and ₦0 hosting

Tochukwu Amaechina — Thu, 05 Nov 2026 15:58:41 +0000

PurpleWallet started as a backend exercise: a Node.js wallet API with Prisma, Redis and a few queues. Over the past few months it grew into a complete product, with a React web app, Paystack payments, a double-entry ledger, an admin console, identity checks, AI spending insights and two layers of automated tests. It's live, and it costs nothing to run.

Here are the parts I found most interesting to build, and the surprises I hit putting it online.

Try it: walletpurple.netlify.app. Click "Use the demo account" on the login page, or sign up for your own. Payments run in Paystack's test mode, so no real money moves.

Code: github.com/tochi27/Wallet_System

The stack

Layer	Choice
API	Node.js, Express 5, TypeScript, Zod
Data	PostgreSQL with Prisma; Redis with BullMQ
Web app	React 19, Vite, Tailwind CSS, shadcn/ui, TanStack Query
Payments and AI	Paystack (test mode), Google Gemini
Tests	Jest and Supertest, Playwright

Both apps live in one npm workspaces monorepo, so a single pull request can change the API, the web app and the browser tests together.

1. Moving money, exactly once

The tempting shortcut is to credit the wallet when the user lands back from Paystack's checkout. That's wrong twice over: the redirect can be faked, and the same payment gets reported several times, by the redirect, by Paystack's webhook, and by retries of both.

So PurpleWallet never trusts the redirect. Whichever signal arrives first triggers a server-side check with Paystack, and the deposit is credited inside a database transaction that first claims it:

// Only one caller can move the deposit out of PENDING; everyone else gets count 0
const claimed = await tx.deposit.updateMany({
  where: { id: deposit.id, status: DepositStatus.PENDING },
  data: { status: DepositStatus.SUCCESSFUL, channel: payment.channel, paidAt: new Date() },
});
if (claimed.count === 0) return null; // already credited by the webhook, the redirect or a retry

The webhook, the redirect and a retry can all race, and the wallet is still credited once.

Withdrawals work the other way round: the wallet is debited first, so the money can't be spent twice while the bank transfer is in flight. A failed transfer is refunded exactly once with the same claim pattern, and a job every five minutes picks up anything a webhook missed. On top of that, an Idempotency-Key header and a Redis lock per wallet stop a double-tapped "Send" button from sending twice.

2. Books that always balance

A balance column works until a number looks wrong and you have nothing to check it against. So PurpleWallet also keeps a double-entry ledger. Every movement of money is a journal entry whose lines sum to zero. A ₦5,000 transfer from Ada to Bola:

Account	Amount
Wallet: Ada	+5,000.00 (debit: we owe Ada less)
Wallet: Bola	−5,000.00 (credit: we owe Bola more)
Total	0.00

The database enforces the rules, not just the code. A deferred constraint trigger rejects any transaction that leaves an entry unbalanced, and append-only triggers block edits and deletes, so mistakes are fixed with reversing entries, as an accountant would.

The admin console then runs a three-way reconciliation: for every wallet, it compares the stored balance, the sum of its transactions and the ledger. The trial balance should always read ₦0.00. It does.

3. Security that behaves like a bank's

Transaction PIN. Transfers and withdrawals need a 4-digit PIN. Five wrong attempts lock money movement for 30 minutes.
Verified email before money moves. Unverified accounts can look around but get 403 on anything that moves money.
Careful password resets. Links are single-use, expire in 30 minutes, and are stored only as a hash. Changing a password signs out every other session.
Never 401 for a wrong PIN. The web app treats 401 as "session expired", and a typo must never sign someone out.
Limits and tiers. Tier 1 allows ₦50,000 per payment, ₦200,000 a day and a ₦500,000 balance. The checks run inside the payment's own transaction and lock, so two simultaneous payments can't both slip under the limit.

4. Identity checks, handled like sensitive data

To reach Tier 2 (₦500,000 per payment, ₦2,000,000 a day, no balance cap), users upload a photo of their ID and a selfie holding it, and staff approve or reject the request with a reason.

ID photos are the most sensitive data the app holds, so they're checked by their contents, not their file names, then re-encoded to strip GPS and camera details, and stored AES-256-GCM encrypted with a key that never touches the database. Only staff with a dedicated permission can open them, every opening is audit-logged, and photos from rejected requests are deleted after 30 days.

5. An admin console with checks and balances

Staff have four roles: Viewer, Support, Finance and Owner. Balance adjustments over ₦10,000 use maker-checker: a second admin must approve, and both steps require re-entering a password. Every admin action lands in an append-only audit log.

6. AI that can't make up numbers

PurpleWallet uses Google Gemini for monthly spending insights and an assistant you can ask about your money.

The rule: the AI never does arithmetic. My code computes every figure first, and Gemini only writes the sentences. Every ₦ amount and percentage in its text is then checked against the computed figures. If the model quotes a number the code didn't produce, the text is rejected and the app falls back to template sentences. Names are swapped for aliases like "Person A" before anything leaves the server.

The assistant uses read-only tools. It can't move money: when it suggests a transfer, it pre-fills the Send dialog, and the user still confirms with their PIN.

7. Tests at two levels

The API has 562 Jest tests, including the nasty cases: two deposits racing, a refund claimed twice, a limit hit by simultaneous payments. Playwright tests then drive the real app in Chrome against a throwaway database, covering sign-up, sending money, wrong PINs, limits, ID checks and admin approvals. GitHub Actions runs both on every pull request, and again before each deploy.

CI had its own bug. Change detection worked on pull requests, but on merge commits it decided nothing had changed, so after every merge the tests and the deploy were skipped, while the run still showed a green tick. Pushes to main now always test and deploy.

8. Hosting for ₦0, and what the free tiers taught me

The web app runs on Netlify, the API on Render, Postgres on Supabase and Redis on Redis Cloud, all on free plans. Each had a surprise.

A "free" deploy that wasn't. Because my Render Blueprint didn't say plan: free, Render used its paid default, and months later suspended the account over an unpaid invoice. Render kindly waived it, and the Blueprint now states the plan explicitly.

Free plans block outgoing email. Render's free tier blocks SMTP, so verification emails silently timed out. The fix was a short Google Apps Script deployed in the sending Gmail account: the API posts each email to it over HTTPS with a shared secret, and the script sends it through Gmail.

Supabase exposes your tables by default. Supabase emailed a critical warning: every table was reachable through its auto-generated Data API, because row-level security was off. My app never uses that API, but the door was open. A migration now enables row-level security and revokes the API roles' access, and a test fails CI if a new migration forgets.

Free services sleep. A scheduled ping every 10 minutes keeps the API awake, using about 730 of Render's 750 free hours a month.

9. A demo you can share safely

The live site has a one-click demo account with three months of realistic Nigerian spending (rent, Shoprite, Bolt rides, DSTV), so the insights and assistant have something to talk about. Since everyone shares that login, visitors can't change its password or PIN, wrong PINs never lock it, and it never receives email. There's also a sample ID card to download for trying the identity check, so nobody uploads a real one.

What I'd tell myself at the start

Make the database enforce the rules that matter. Triggers caught mistakes that tests alone would have missed.
Design for duplicates. Webhooks, retries and double-clicks will deliver the same event twice; a conditional "claim" update solves most of it.
Let code do the maths and AI do the words, then check the words.
Read the free-tier small print, and remember that a green CI tick only means something if the jobs actually ran.

PurpleWallet is live at walletpurple.netlify.app, and the code is on GitHub. Try the demo, send some test money, or ask the assistant where your money went last month. I'd love to hear what you think.

Redis Caching Strategies for High-Performance APIs

Tochukwu Amaechina — Mon, 31 Aug 2026 16:12:29 +0000

When I first started thinking seriously about API performance, my instinct was simple:

If the database is slow, optimize the database.

Add indexes. Improve the query. Tune the connection pool.

And sometimes, that's exactly what you should do.

But eventually, you run into a different problem.

The database isn't necessarily slow.

You're just asking it the same question too many times.

Imagine an endpoint that returns product information.

GET /api/products/123

The product changes once every few hours, but the endpoint gets thousands of requests every minute.

Without caching, every request goes straight to PostgreSQL:

Request
   ↓
  API
   ↓
PostgreSQL
   ↓
Response

The database is doing the same work over and over again.

That's where Redis comes in.

The Simple Idea Behind Caching

Instead of asking the database every time, we store frequently requested data temporarily.

Request
   ↓
Redis
   ↓
  HIT ─────→ Response
   │
  MISS
   ↓
Database
   ↓
Redis
   ↓
Response

The first request pays the database cost.

The next requests don't.

In a Node.js API, a simple cache-aside implementation looks like this:

const key = `product:${productId}`;

const cached = await redis.get(key);

if (cached) {
  return JSON.parse(cached);
}

const product = await prisma.product.findUnique({
  where: { id: productId },
});

if (!product) {
  throw new Error("Product not found");
}

await redis.set(
  key,
  JSON.stringify(product),
  { EX: 300 }
);

return product;

That's the basic pattern:

Check Redis → cache miss → query database → store result → return.

Simple.

But this is where caching stops being just a performance optimization.

Because now we have two copies of the data.

And they can disagree.

The Stale Data Problem

Suppose Redis contains:

product:123
price: ₦45,000

Then someone updates the product:

Database
price: ₦50,000

Redis still contains:

₦45,000

If the cache has a five-minute TTL, users could receive the old price for another five minutes.

This is the real challenge with caching.

Making data fast to access is easy. Keeping it correct is harder.

That's why TTL alone isn't enough.

TTL vs Invalidation

TTL answers:

"How long should this cache entry exist?"

Invalidation answers:

"When should I remove it because the underlying data changed?"

For example:

await prisma.product.update({
  where: { id: productId },
  data: updateData,
});

await redis.del(`product:${productId}`);

Now the next request becomes a cache miss and retrieves the latest value from the database.

For many APIs, cache-aside + TTL + delete-on-write is a very practical starting point.

You don't need a complicated caching architecture on day one.

Then There's the Cache Stampede

Here's where things get interesting.

Imagine a popular cache entry expires:

product:123

At the exact same time, 1,000 requests arrive.

They all check Redis:

MISS
MISS
MISS
MISS
...

And suddenly all 1,000 requests hit PostgreSQL.

The cache that was supposed to protect the database has just created a database traffic spike.

This is commonly called a cache stampede or thundering herd.

For extremely hot keys, you can prevent this by allowing only one request to rebuild the cache while the others wait.

Redis can help here through distributed locking.

But you wouldn't want to introduce locking everywhere.

If a query takes 10ms, the complexity may not be worth it.

If rebuilding the cache takes several seconds under heavy traffic, it's a different conversation.

Optimize for the workload you actually have.

What Should You Cache?

This is probably the most important question.

I wouldn't cache something simply because Redis is available.

Good candidates usually have three characteristics:

Frequently requested
+
Expensive to retrieve
+
Safe to be slightly stale

For example:

Product details
Public profiles
Search results
Configuration
Reference data
Expensive aggregations

I'd be much more careful with:

Account balances
Payment state
Authorization decisions
Inventory
Transaction state

Especially in financial systems.

If a wallet contains ₦100,000 and Redis says ₦100,000 while the database says ₦70,000 after a transaction, using that cached value for a financial decision is dangerous.

Fast wrong data is still wrong data.

For critical state, the database should remain authoritative.

Your Cache Key Is Part of Your Architecture

A cache key isn't just a random string.

This:

is a terrible cache key.

This is better:

user:123

And in a multi-tenant system:

tenant:456:user:123

For filtered results:

products:category:phones:page:1

Every parameter that changes the response needs to be represented appropriately in the key.

Otherwise, you can end up returning the wrong cached response to the right request.

That's a correctness bug—not a performance bug.

Redis Should Accelerate Your System, Not Become Your System

One of the most important design decisions is what happens when Redis fails.

For a cache-aside architecture, I'd rather have:

Redis available
    ↓
Use cache

Redis unavailable
    ↓
Use database

The API might become slower.

But it remains functional.

That's a much better failure mode than:

Redis unavailable
    ↓
Entire API unavailable

If your application completely depends on Redis just to retrieve data that already exists in PostgreSQL, you've accidentally turned your cache into a critical dependency.

Measure the Difference

Finally, don't add Redis and declare victory.

Measure it.

Before caching:

Average latency: 400ms
P95 latency:     800ms
DB queries/sec:  2,000

After caching:

Average latency: 70ms
P95 latency:     150ms
DB queries/sec:  500
Cache hit rate:  85%

Now you have evidence.

The goal isn't to make Redis busy.

The goal is to make the entire system do less unnecessary work.

The Bigger Lesson

Redis isn't what makes an API fast.

Avoiding unnecessary work makes an API fast.

Redis is simply one of the tools that helps you do that.

The moment you introduce a cache, you're making a trade:

More memory
+
More complexity
+
Potentially stale data

in exchange for:

Lower latency
+
Less database load
+
Higher throughput
+
Better scalability

The best caching strategy isn't the one that puts the most data into Redis.

It's the one that eliminates the most unnecessary work while keeping the system correct.

That's the difference between simply using Redis and actually designing with Redis.

How I Stopped a Race Condition from Creating Free Money in My Wallet System

Tochukwu Amaechina — Wed, 03 Jun 2026 21:57:40 +0000

The Bug That Doesn't Show Up in Testing.
When I set out to build a production-grade wallet system, I expected the hard parts to be the database schema, the transaction logic, or the authentication layer.

What I didn't expect was that the most dangerous bug in the system would have nothing to do with wrong code - it would be about timing.

This is the story of a race condition that lets users spend money they don't have, why it's invisible until it hits production, and how Redis turned it into a non-issue.

What a Wallet System Actually Does
Before we get to the bug, a quick picture of the system. A wallet holds a balance. Users can:

Credit - add funds
Debit - spend funds
Transfer - move funds to another user
Reverse - undo a transaction
Every operation reads the current balance, validates it, and writes a new transaction record. Simple enough. The problem hides in that gap between reading and writing.

The Race Condition
Here's the scenario. A user has ₦5,000 in their wallet. They're on a slow connection, so they tap "Pay" twice. Two HTTP requests hit the server within milliseconds of each other. Both are trying to debit ₦3,000.

Without any concurrency protection, this is what happens:

Request A → reads balance: ₦5,000
Request B → reads balance: ₦5,000

Request A → ₦5,000 - ₦3,000 = ₦2,000 ✓ writes transaction
Request B → ₦5,000 - ₦3,000 = ₦2,000 ✓ writes transaction
Both requests read ₦5,000. Both pass the balance check. Both write a successful debit. The user just spent ₦6,000 from a ₦5,000 wallet - and the system called both transactions successful.

This isn't a theoretical edge case. Under any real concurrent load, this happens. And the worst part: it never shows up in testing, because your test runner doesn't fire two real HTTP requests at the same millisecond.

Why a Database Transaction Doesn't Save You
The instinct here is to reach for a database transaction. Wrap the whole thing in BEGIN / COMMIT and let Postgres sort it out.

The problem is that the race happens before the database transaction begins. Both requests read the balance from the database (or worse, from a cache), both pass the validation check in application code, and then both open their database transactions. The damage is already done.

You need a lock at the application layer, before the read even happens.

The Fix: Distributed Locking with Redis
The solution is to ensure that no two operations on the same wallet can run at the same time. Before any balance operation begins, it must claim exclusive access. If another operation already holds the claim, it retries until the lock is free, or gives up after a timeout.

This is a distributed lock, and Redis is the right tool for it. Here's the implementation:

// src/utils/lock.utils.ts
import { randomUUID } from "crypto";
import redisClient from "../services/redis.service";

const LOCK_TTL_MS = 10_000;
const LOCK_RETRY_COUNT = 50;
const LOCK_RETRY_DELAY_MS = 100;

const RELEASE_SCRIPT = `
  if redis.call("GET", KEYS[1]) == ARGV[1] then
    return redis.call("DEL", KEYS[1])
  else
    return 0
  end
`;

const acquireLock = async (key: string): Promise<string | null> => {
  const token = randomUUID();
  const result = await redisClient.set(key, token, "PX", LOCK_TTL_MS, "NX");
  return result === "OK" ? token : null;
};

export const withLock = async <T>(userId: string, fn: () => Promise<T>): Promise<T> => {
  const key = `wallet:lock:${userId}`;
  let token: string | null = null;

  for (let attempt = 0; attempt <= LOCK_RETRY_COUNT; attempt++) {
    token = await acquireLock(key);
    if (token) break;
    await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
  }

  if (!token) throw new Error("Could not acquire lock — resource is busy");

  try {
    return await fn();
  } finally {
    await redisClient.eval(RELEASE_SCRIPT, 1, key, token);
  }
};

Let's break down each decision.

SET key token PX 10000 NX
This is a single atomic Redis command that does three things at once:

NX — only set the key if it does not already exist
PX 10000 — expire the key after 10 seconds
The value is a unique token (UUID), not just 1 or "locked"
The atomicity of SET NX is the core guarantee. There is no gap between "check if key exists" and "set the key" — it's one operation. Two requests racing to acquire the same lock cannot both succeed.

Retry logic
Rather than immediately rejecting a request when the lock is held, the implementation retries up to 50 times with a 100ms delay between each attempt - giving it up to 5 seconds to acquire the lock before giving up. This handles brief overlaps gracefully without dropping legitimate requests.

The TTL
The 10-second expiry is a safety net. If the application crashes mid-operation and fails to release the lock, it will expire automatically. Without this, one crash would lock that user's wallet forever.

The Lua script on release
This is where most implementations get it wrong. A naive release looks like this:

await redisClient.del(key); // ❌ dangerous
Here's why that's broken: imagine a slow operation acquires the lock, but takes longer than 10 seconds. The TTL expires. A second operation acquires the lock. Now the first operation finishes and calls del - it just released the second operation's lock, not its own. The guarantee is broken.

The Lua script fixes this by checking the token before deleting:

if redis.call("GET", KEYS[1]) == ARGV[1] then
  return redis.call("DEL", KEYS[1])
else
  return 0
end

Because Lua scripts execute atomically in Redis, the check-and-delete is a single uninterruptible operation. You can only release a lock you actually own.

The withLock wrapper
Rather than exposing raw acquireLock / releaseLock functions and trusting every caller to use them correctly, the implementation wraps the entire pattern in a higher-order function:

// src/services/wallet.service.ts
export const debitWallet = async (userId: string, amount: number): Promise<Transaction> => {
  return await withLock(userId, async () => {
    const wallet = await prisma.wallet.findUnique({ where: { userId } });

    if (!wallet || wallet.balance.lessThan(amount)) {
      throw new Error("Insufficient balance");
    }

    // create transaction, update balance...
    return transaction;
  });
};

The finally block inside withLock ensures the lock is always released, even if the operation throws. A lock that leaks on error is as bad as no lock at all.

Preventing Deadlocks on Transfers
A transfer touches two wallets - sender and receiver. If two transfers run simultaneously in opposite directions (A→B and B→A), they can deadlock: each holds one lock and waits for the other indefinitely.

The fix is to always acquire locks in the same order, regardless of who is sending to whom. We sort the user IDs before acquiring:

export const withMultiLock = async <T>(userIds: string[], fn: () => Promise<T>): Promise<T> => {
  const sortedIds = [...new Set(userIds)].sort();
  const keys = sortedIds.map((id) => `wallet:lock:${id}`);
  const tokens: string[] = [];

  try {
    for (const key of keys) {
      let token: string | null = null;
      for (let attempt = 0; attempt <= LOCK_RETRY_COUNT; attempt++) {
        token = await acquireLock(key);
        if (token) break;
        await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
      }
      if (!token) throw new Error("Could not acquire lock — resource is busy");
      tokens.push(token);
    }
    return await fn();
  } finally {
    await Promise.all(keys.map((key, i) => releaseLock(key, tokens[i])));
  }
};

// In transfer service:
const result = await withMultiLock([senderId, receiver.id], async () => {
  // both wallets locked — safe to proceed
});

If A→B and B→A both arrive at the same time, both will sort to [A, B] and try to acquire A's lock first. One wins, the other waits. No deadlock.

The Full System
The distributed lock is one layer in a larger stack. The complete wallet engine includes:

Idempotency - Idempotency-Key header on credit and debit prevents duplicate transactions on network retries, backed by a 24-hour Redis TTL
Webhook delivery with retry - BullMQ queue, 4 attempts, exponential backoff (2s base), per-attempt audit trail
Balance caching - 60-second Redis TTL, invalidated on every write
Token blacklisting - SHA-256 hashed JWTs stored in Redis with matching expiry, making logout actually secure
Cursor-based pagination - transaction history that scales
Full test suite - 103 tests, all mocked, no database required to run.
Built with TypeScript, Express, Prisma, PostgreSQL, and Redis (ioredis). Deployed on Render with a GitHub Actions CI/CD pipeline.

Why This Matters
Race conditions in financial systems are not exotic. They're the default outcome when you don't explicitly prevent them. Most wallet tutorials never mention it. Most wallet implementations in production have it.

The fix isn't complicated - but you have to know to look for it.

If you're building anything that touches money, check your balance reads. If there's no lock between the read and the write, the race condition is already there.

Open for Collaboration
This project is open source and actively welcoming contributors. Whether you want to add a feature, improve test coverage, or spot something that could be done better - PRs are open.

Check out the CONTRIBUTING.md for how to get set up and where to send your changes.

GitHub: https://github.com/tochi27/Wallet_System.git

Live API + Swagger: https://wallet-system-api-16cv.onrender.com/api-docs