| Stack | Role | Year | Status |
|---|---|---|---|
| NestJS, TypeScript, PostgreSQL, Prisma, Redis, BullMQ, Flutter, Firebase Auth, M-Pesa Daraja | Full-Stack Software Engineer | 2026 | Live |
Fits by Aliv — Kenya-First E-Commerce with Payment-Safe Workflows
Production-grade e-commerce with inventory self-healing, M-Pesa verification, and hardened security
Fits by Aliv — Kenya-First E-Commerce with Payment-Safe Workflows — Production-grade e-commerce with inventory self-healing, M-Pesa verification, and hardened security is a technical case study on ancel.co.ke documenting architecture, trade-offs, and outcomes. To avoid oversell and double-spend when payments are async and callbacks unreliable, I designed Fits by Aliv so we never trust a callback until we verify with STK Query, and inventory is only reserved softly until payment is confirmed. Ancel Ajanga wrote thi…
Fits by Aliv is a Kenya-first e-commerce marketplace (thrift/sustainable fashion) with payment-safe workflows, inventory self-healing, and hardened security. Backend is NestJS with PostgreSQL (Prisma); clients are Flutter (mobile, web, desktop). Identity is Firebase Auth; payments are M-Pesa via Safaricom Daraja API.
The Problem
E-commerce systems in emerging markets fail differently. Payments are asynchronous, networks are unreliable, and inventory errors directly translate to lost revenue and customer trust. Most platforms assume synchronous payments, over-trust callbacks, allow double-spend scenarios, or leak business logic across client and backend boundaries. Inventory overselling, voucher abuse, replay attacks, and unsafe automation are common failure modes. Kenya-specific constraints compound the problem: M-Pesa STK Push is asynchronous and non-authoritative, VAT/WHT rules are strict, and mobile devices are often resource-constrained.
To avoid oversell and double-spend when payments are async and callbacks unreliable, I designed Fits by Aliv so we never trust a callback until we verify with STK Query, and inventory is only reserved softly until payment is confirmed.
The Solution
I built Fits by Aliv as a production-grade e-commerce backend around failure, abuse, and latency as first-class concerns. The system uses soft inventory reservations, idempotent order creation, verified payment reconciliation (Daraja STK Query before state changes), and AI-assisted self-healing background jobs. Payments are never trusted at face value; inventory is never hard-deducted before confirmation; automation is bounded, auditable, and reversible. All business logic lives in a single NestJS backend with PostgreSQL transactions. Clients never touch the database. Firebase is used strictly for identity; authorization, rate-limiting, replay prevention, and auditability are enforced server-side.
Key Technical Terms
- Idempotent order creation:In Fits by Aliv every order mutation accepts an idempotency key so duplicate requests (e.g. double-tap or retry) create only one order; that supports the goal of no double-charge and no duplicate reservations.
- Verified payment reconciliation:We never update order or payment state from a callback alone; we call Daraja STK Query to confirm status first, so the project goal of no blind trust in M-Pesa callbacks is met.
- Soft inventory reservations:Stock is reserved for a TTL instead of hard-deducted at checkout; if payment does not complete, the reservation expires and inventory is released, preventing oversell and supporting async payment flows.
The Impact
The system guarantees: no inventory oversell due to race conditions, no voucher double-spend, no unaudited state changes, no blind trust in payment callbacks, no unbounded automation. Security highlights: Firebase JWT verification + server-side authorization, idempotency keys on all critical mutations, replay-prevention via nonce + timestamp, IP allowlisting and optional HMAC for webhooks, immutable audit and security event logs. The system is designed so an ethical hacker can reason about what cannot happen.
~90–95%
Verify first
Pessimistic
Immutable
Outcomes
- No inventory oversell; no voucher double-spend; no unaudited state changes
- Payment-safe: Daraja verification before any order/payment state update
- Self-healing with constrained automation and audit trail
- Production mindset: assume failure, verify asynchronously, automate carefully
Architecture Deep-Dive
Request layer: Flutter clients authenticate via Firebase JWT; every mutation supports idempotency. Transactional core: Orders, vouchers, inventory reservations, and tax records are created atomically in a single Prisma transaction. Asynchronous layer: BullMQ + Redis handle reservation expiry, payment verification, retries, and dead-letters. Verification layer: M-Pesa callbacks are validated, allowlisted, and verified via STK Query before state changes. Healing layer: Background jobs classify failures and execute bounded recovery actions. Audit layer: Every sensitive action leaves a durable trail. Modules: Auth, Users, Orders, Payments, Products, Categories, Cart, Wishlist, Vouchers, Referrals, Notifications, Admin, Audit, Healing, Tax, Upload, Security, Common, Prisma, Firebase, Mpesa.
Key Engineering Decisions
I removed Supabase in favor of a single NestJS backend and Prisma because I wanted vendor decoupling and full control over migrations. I retained Firebase Auth for JWT issuance and SDK support; the backend only verifies tokens. I chose Prisma over raw SQL for type safety and migrations, and use raw SQL only for the conditional voucher UPDATE. I use Redis for BullMQ (reservation-expiry, payment-verification, dead-letter) and for replay-prevention when configured.
Failure Modes & Resilience
M-Pesa callback before verification: we do not update state until STK Query confirms; duplicate callbacks are idempotent. Reservation expiry: BullMQ jobs release expired reservations so stock is not stuck. Voucher double-spend: conditional UPDATE inside the order transaction ensures one voucher use per redemption. Database or backend crash: Prisma transactions keep order, voucher, and inventory consistent; we do not commit partial state. Replay or abuse: idempotency keys, nonce, and rate limiting limit impact. Self-healing job failure: jobs are bounded and dead-lettered so we do not retry forever or mutate data blindly.
Outcome & Future Potential
The system guarantees: no inventory oversell due to race conditions, no voucher double-spend, no unaudited state changes, no blind trust in payment callbacks, no unbounded automation. Security highlights: Firebase JWT verification + server-side authorization, idempotency keys on all critical mutations, replay-prevention via nonce + timestamp, IP allowlisting and optional HMAC for webhooks, immutable audit and security event logs. The system is designed so an ethical hacker can reason about what cannot happen.
Roadmap & Expansion
Additional payment providers (schema-compatible), multi-seller inventory, regional tax rules, event-driven analytics, fraud scoring models feeding the healing layer. The core system already assumes failure, retries, abuse, and human oversight.
~90–95%
Backend, DB, payments, healing, security complete
Verify first
STK Query before trusting callback
Pessimistic
Conditional UPDATE in transaction
Immutable
Trail for every sensitive action
Project Gallery