Vaultly: The Fintech Monorepo That Treats Every Transfer Like a Failure Case

Why money movement is the hardest part of a wallet

Moving money is easy to describe and hard to make safe. The second a wallet has to survive retries, concurrent requests, and delayed callbacks, it stops being a CRUD app and becomes a systems problem. Vaultly gets that right at the transfer layer, where the code is less interested in flashy UI and more interested in preventing the kinds of bugs that can quietly break trust.

That is why the interesting question here is not whether Vaultly can move balances. It is how it keeps a transfer correct when the same request appears twice, when two transfers race each other, or when an external payment step comes back late. The repo’s answer is to stack defenses: validation, idempotency, row locks, ledger writes, and explicit failure handling.

Vaultly’s real trick: it thinks like a ledger, not a balance sheet

The most important clue in the code is not a dashboard component or a route handler. It is the presence of ledger-posting functions like postP2PLedger and postOfframpLedger. That suggests the system is designed around immutable entries, not just mutable balance fields.

That distinction matters. A balance column is convenient, but it hides history. A ledger records what happened, when it happened, and why a reconciliation later has something solid to inspect. For a fintech system, that is not a nice-to-have. It is the difference between an app that looks correct and a system that can actually be audited.

How the transfer code avoids deadlocks and duplicate debits

Vaultly’s P2P path reads like defensive financial programming. Before the transaction opens, it checks the request, verifies the receiver, and runs the MPIN path. Inside the database transaction, it locks rows in a fixed order by sorting the account IDs first. That one detail prevents a classic deadlock pattern when two transfers try to touch the same accounts in opposite order.

The second guard is idempotency. Network retries happen. Mobile clients resend. Gateways time out. If a transfer can be replayed safely, the system avoids the worst failure mode in payments, a duplicate debit that looks legitimate until somebody complains later. Vaultly’s transfer flow is clearly built to survive that reality instead of hoping it never happens.

// Simplified shape of the transfer logic
const [firstId, secondId] = [senderId, receiverId].sort((a, b) => a - b);

await tx.$queryRaw`SELECT * FROM balances WHERE user_id IN (${firstId}, ${secondId}) FOR UPDATE`;

const replay = await idempotencyManager.check(key);
if (replay) return replay;

await verifyMpin(userId, mpin);
await tx.balance.update({ /* reserve or move funds */ });
await tx.ledger.create({ /* immutable transfer record */ });
await idempotencyManager.commit(key, result);

The important thing is the shape of the transaction boundary. Validation happens before the lock. Locking happens before state mutation. Ledger recording happens with the transfer. That sequencing is what makes the system feel built by people who have seen payment bugs before.

MPIN is the second lock on the vault

Vaultly does not treat transaction authorization as the same thing as login. Its MPIN flow is a separate security surface, which is the right instinct for money movement. A user might be signed in and still not be cleared to move funds without passing a fresh transaction gate.

The implementation details matter here. Failed attempts accumulate. A lockout window can kick in through lockedUntil. Security events are emitted so suspicious behavior does not vanish into the same logs as ordinary app traffic. That is not just a PIN check. It is a small security system.

• Separate transaction authorization from account login.
• Track failed attempts instead of only counting success.
• Lock the PIN after repeated failures.
• Emit security events for audit trails and review.

The mock bank is where Vaultly gets realistic

The mock payment gateway is one of the strongest parts of the repo because it refuses to flatten the outside world into a happy path. Real bank integrations are asynchronous, messy, and sometimes unreliable. Vaultly models that with BullMQ, Redis, webhook delivery, and dead-letter handling.

That choice turns the project into more than a wallet demo. It becomes a rehearsal space for partial failure. A webhook can arrive late. A confirmation can fail. A job can be retried. The system still has to behave correctly, and the queue layer gives it a place to do that work without blocking the user flow.

One Prisma client, many apps, one consistency story

The monorepo structure matters because it keeps the stack coherent. A shared packages/db layer gives every app the same Prisma-backed data model, while the Turbo layout keeps the user app, bank webhook service, mock gateway, and merchant app in one ecosystem. That is a practical way to avoid drift between services that are supposed to agree on finance-critical data.

The proxy-wrapped Prisma client is a nice detail too. Runtime validation of the database URL and lazy initialization are the kind of unglamorous safety measures that save teams later, especially in containerized or multi-app deployments. It is the infrastructure equivalent of using a seatbelt before you need it.

What Vaultly is really for

Vaultly is best understood as a reference architecture for builders who need to think about money movement the hard way. It is useful for wallet teams, internal payment rails, banking-adjacent products, and any system where the cost of a duplicate debit or a lost callback is not theoretical.

That is what separates it from a typical starter repo. A basic wallet clone stops at authentication, a balance view, and a transfer button. Vaultly keeps going. It asks how the transfer survives contention, how the PIN fails safely, how the external bank behaves when the network does not cooperate, and how the data model can support auditability after the fact.