Skip to main content

Part of topic: Next.js Architecture, Backend & Modular Systems, Kotlin Multiplatform & Mobile Engineering, Zero-Trust & Auditable Infrastructure, Full-Stack Systems Design

StackRoleYearStatus
—Full-Stack Software Engineer2026In Progress
NestFi — Resilient Financial Coordination Platform Architecture Diagram - Hero Preview by Ancel Ajanga.

NestFi — Resilient Financial Coordination Platform

Correctness-first finance with hybrid storage, M-Pesa B2C and failure-aware design. Developed by Ancel Ajanga.

Written by Ancel Ajanga — Senior Software Engineer
Full-Stack Software Engineer
Ongoing (2026)
In Progress

NestFi is a financial coordination platform designed around correctness under failure. It addresses what goes wrong in mobile money integrations: delayed callbacks, duplicate events, provider outages and race conditions. A ledger-first design on PostgreSQL treats every balance change as an auditable record.

The Problem

The fundamental problem in financial engineering is not building CRUD apps; it is guaranteeing correctness under failure. In the Kenyan fintech landscape, integrating with providers like M-Pesa (Daraja) presents specific, high-stakes challenges: 1. Asynchronous callback reliability: Callbacks for deposits or B2C withdrawals can be delayed by minutes, delivered multiple times, or never delivered at all. 2. Race conditions: Concurrent withdrawal requests can lead to double-spending if not guarded by distributed locks. 3. Partial failure: A system might successfully debit a user's wallet but fail to record the audit log in MongoDB or receive a network timeout from the payment provider. NestFi was architected to solve the 'Blind Trust' problem—where systems assume success without verification—by implementing a fail-closed, multi-layered validation engine.

To eliminate financial ambiguity and double-spending across asynchronous providers, I designed a ledger-backed coordination layer where every transaction is idempotent, every external call is timeout-aware and the database acts as a singular, transactional source of truth that cannot be bypassed.

The Solution

NestFi implements a 'Ledger-First' architecture using a hybrid storage model: PostgreSQL (Authoritative Ledger), MongoDB (Event & Audit Logs) and Redis (Distributed Locking & Rate Limiting). The system treats external payment providers as untrusted, asynchronous agents. All sensitive operations follow a strict lifecycle: Request -> Idempotent Lock -> Ledger Reservation -> External Intent -> Verified Callback/Query -> Ledger Finalization. This ensures that even if a network partition occurs mid-transaction, the system can self-reconcile using background 'Watchdog' jobs that query the provider's status independently. By enforcing strict double-entry accounting at the database layer (Postgres constraints), NestFi guarantees that the total system value always nets to zero, making it impossible for funds to 'vanish' or be duplicated during a partial system failure.

Key Technical Terms

  • Double-Entry Ledger Integrity:A financial constraint where every transaction must have a corresponding debit and credit across two or more accounts. In NestFi, this is enforced via database-level triggers to prevent manual balance manipulation.
  • Idempotent Reconciliation:The ability to process the same payment callback multiple times without changing the result. NestFi uses unique Transaction IDs to ensure that a replayed M-Pesa notification never credits a wallet twice.
  • Redlock Distributed Locking:A mechanism using Redis to ensure that a single user cannot initiate two parallel withdrawals at the exact same millisecond across different backend nodes, preventing the 'race-to-zero' exploit.

The Impact

NestFi shows how I approach the most sensitive part of an application, the ledger. The design puts correctness ahead of speed: double-entry style records, idempotent handling of payment events and clear separation between the transactional core and the layers around it. It is still in development and about 87% complete. The system is a private project, and no transaction volumes or production figures are claimed.

Ledger-first

Balance changes are recorded as auditable ledger entries inside ACID transactions

Idempotent

Duplicate or replayed provider callbacks are handled safely

ACID

PostgreSQL transactions are the source of financial truth

~87% complete

Core backbone implemented; remaining work is outside the ledger core

Architecture Deep-Dive

The NestFi architecture is designed for 'Isolation of Failure' across four layers: 1. Transactional Layer (PostgreSQL): This is the bedrock of the system. We use strict relational schemas and ACID transactions to manage the ledger. Every wallet modification is atomized; a user’s balance is never a 'column' but a sum of ledger entries, preventing drift from inconsistent updates. 2. Event & Audit Layer (MongoDB): While the ledger tracks 'What,' MongoDB tracks 'How' and 'Why.' Every KYC change, dispute and callback payload is stored in an immutable event stream. This separation ensures that even if the audit log experiences latency, the core financial ledger remains high-performance and transactional. 3. Coordination Layer (NestJS/Redis): The backend is stateless, scaling horizontally to handle spikes in payment traffic. Redis coordinates shared state, such as M-Pesa STK push nonces and distributed locks for withdrawal approvals. This prevents the 'Split Brain' problem where two nodes might try to process the same callback simultaneously. 4. Worker Layer (BullMQ): Asynchronous tasks like sending push notifications, generating tax reports and running reconciliation 'Watchdogs' are offloaded to background workers. This keeps heavy work off the request path so API responses stay quick.

Key Engineering Decisions

Engineering NestFi involved deliberate choices between speed, complexity and safety: - ACID vs. Base: Many modern startups use NoSQL for everything to move fast. I chose PostgreSQL for the ledger because 'Eventual Consistency' is unacceptable in finance. We trade off easy horizontal database scaling for absolute transactional guarantees. - Direct Integration vs. Aggregators: NestFi builds directly on the Daraja API rather than using 3rd-party aggregators. This increases the development burden (handling M-Pesa's specific quirks) but gives us a 100% transparent view of the failure modes and reduces dependency risk. - Sync vs. Async Callbacks: We treat all payment results as 'tentative' until verified. While we could optimistically credit a user upon an STK Push initiation, we choose a 'Pending -> Settled' flow which increases UX complexity slightly but eliminates the risk of crediting failed transactions.

Performance & Scalability

NestFi is designed for bursty financial traffic, but it has not been load-tested, so no throughput figures are claimed. The backend services are stateless, so more instances can be added behind a load balancer. Redis coordinates shared state such as distributed locks and rate limiting, which keeps contention out of PostgreSQL. Slow work such as notifications, reports and reconciliation runs in background BullMQ workers so it does not sit on the request path. The ledger tables are structured so that partitioning can be introduced later if volume requires it.

Failure Modes & Resilience

NestFi is built to 'Fail Clean.' We have engineered for the following scenarios: 1. Payment Provider Timeout: If Safaricom's API times out during a B2C withdrawal, the transaction is marked as 'AMBIGUOUS.' A background worker then queries the provider every 60 seconds until a definitive Success/Fail is returned, ensuring the user's funds are never lost in transit. 2. Idempotency Key Collision: In the rare event of a duplicate request ID from a provider, the system's unique constraints in Postgres stop the transaction before the ledger is touched, returning the previous result instead of a new debit. 3. MongoDB Outage: If the audit log fails, the system continues to process transactions but flags them for 'Manual Review.' This keeps the money moving while alerting engineers to the loss of observability. 4. Redis Crash: We utilize a 'Persistent Redis' configuration paired with Postgres-based lock fallbacks. If the distributed lock layer disappears, the system halts critical write operations (withdrawals) for 30 seconds to prevent race conditions during the failover.

Security & Trust Boundaries

Security in NestFi focuses on 'Integrity' and 'Privacy.' - Callback Hardening: All M-Pesa callback endpoints are protected by IP-allowlisting and HMAC signature verification. We do not trust the 'Sender' header; we verify the payload against the known Daraja public key. - Sensitive Data Redaction: Our logging layer (Pino) automatically redacts PII like phone numbers and M-Pesa Receipt Numbers in production logs, ensuring compliance with local data protection laws (ODPC) while maintaining debugging capability. - Financial Isolation: Admin accounts have no path to modify user balances directly. All balance changes must originate from a signed Transaction Event, creating a 'Verifiable Audit Trail' that can be reconstructed from scratch to verify the ledger total.

Frontend Engineering & UX

The NestFi frontend (Next.js & React Native) is designed to build 'User Trust' through explicit state transparency. - Real-Time Trust Loop: We use Socket.io to provide immediate feedback on payment status. When a user completes an STK Push, the 'Processing' screen updates in real-time as the Daraja callback hits our server, eliminating the 'Did it work?' anxiety. - Pessimistic State Transitions: We never hide the 'Pending' state. By showing users exactly where their money is (e.g., 'Awaiting Provider Confirmation'), we reduce support overhead and set realistic expectations for asynchronous financial flows. - Offline Resilience: The mobile app caches the last known ledger state locally, allowing users to view their transaction history and initiate new requests even with spotty 3G connectivity.

Outcome & Future Potential

NestFi shows how I approach the most sensitive part of an application, the ledger. The design puts correctness ahead of speed: double-entry style records, idempotent handling of payment events and clear separation between the transactional core and the layers around it. It is still in development and about 87% complete. The system is a private project, and no transaction volumes or production figures are claimed.

Ledger-first

Ledger Model

Balance changes are recorded as auditable ledger entries inside ACID transactions

Idempotent

Payment Events

Duplicate or replayed provider callbacks are handled safely

ACID

Consistency

PostgreSQL transactions are the source of financial truth

~87% complete

Status

Core backbone implemented; remaining work is outside the ledger core

Key Engineering Takeaways

  • In finance, correctness is a constraint, not a feature; use ACID-compliant storage.

  • EXTERNAL APIs ARE VAPORWARE: Assume every 3rd party will fail, timeout, or lie; reconcile independently.

  • Idempotency is the only cure for 'Split-Brain' distributed systems.

  • User trust is built through technical transparency (real-time state updates).

  • Monitor for drift: Build background 'Watchdogs' that verify that Ledger Total == Bank Balance.

Project Gallery

NestFi — Resilient Financial Coordination Platform Architecture Diagram - Screenshot 1 by Ancel Ajanga.