SwiftCart – Case Study

01 // The Challenge

Modern e-commerce is complex and expensive

Building a production-ready online marketplace from scratch requires juggling authentication, payments, search, real-time updates, and an admin dashboard — and most open-source solutions do not support African payment methods natively.

M-Pesa not supported

Existing platforms like Shopify, Magento, and WooCommerce do not natively support M-Pesa STK Push — Kenya’s dominant mobile money payment method.

Full-stack complexity

Building authentication, payments, search, caching, real-time updates, and an admin dashboard from scratch is time-consuming and error-prone without a solid reference architecture.

No unified foundation

Developers lack an open-source, production-ready e-commerce codebase that combines a modern React frontend with a Node.js/Express backend, Docker orchestration, and comprehensive documentation.

02 // The Solution

Full-stack monorepo with modern tooling

A comprehensive monorepo containing a React + TypeScript frontend (Vite, shadcn/ui, Tailwind CSS) and a Node.js/Express backend with MongoDB, Redis caching, optional Elasticsearch search, Socket.io real-time updates, and native M-Pesa STK Push payment integration — all orchestrated with Docker and documented across 37 markdown files.

Scroll horizontally →

User Visit

Product Discovery

Cart & Checkout

M-Pesa Payment

Order Confirmed

03 // Key Features

Production-ready e-commerce platform

Every component designed for a complete shopping experience from product discovery to payment and order management.

Product Catalog & Search

Full-text MongoDB search with optional Elasticsearch integration, category/brand/price filtering, sorting, pagination, autocomplete suggestions with debounced input, and dedicated deals, new arrivals, and best sellers pages.

→

M-Pesa STK Push Integration

Native Lipa na M-Pesa Online payment with STK Push initiation, callback processing, transaction verification, sandbox/production environment switching, and full order payment status tracking.

→

Real-Time Updates via Socket.io

Live order status updates, in-app notification center for order changes and system events, and real-time communication between frontend and backend using Socket.io with event-driven architecture.

→

Admin Dashboard

Full admin panel with order management, product CRUD, inventory tracking with low stock alerts and history audit log, analytics with Recharts data visualization, and user management.

→

JWT Auth & OAuth

Short-lived access tokens with refresh token rotation, Google and Facebook OAuth via Passport.js, email verification flow, password reset, role-based access (customer/admin), and rate limiting on auth endpoints.

→

Redis Caching & Performance

Product list and detail caching with configurable TTL (5 min for lists, 1 hour for details), code splitting with React.lazy on all pages, manual Rollup chunking, and comprehensive MongoDB indexes for query performance.

→

04 // Technical Deep-Dive

Monorepo architecture with pnpm workspaces

React 18 + TypeScriptLazy-loaded pages with React.lazy, SWC fast refresh, and full type safety

Vite 5 + SWCFast HMR, ESBuild minification, and optimized production builds with manual chunking

Redux Toolkit + React QueryRTK for client state (auth, cart), TanStack Query for server state (products, orders)

Tailwind CSS + shadcn/ui40+ Radix UI primitives, class-variance-authority, clsx, tailwind-merge

React Hook Form + ZodSchema-based form validation for checkout, registration, and admin forms

React Router v6Lazy-loaded routes for all 23 pages with protected route guards for admin

Node.js + Express 4Dynamic route loading with lazy controllers, middleware pipeline, and TypeScript runtime

MongoDB + Mongoose 87 models with indexes, unique constraints, pre-save hooks, and virtual fields

Redis CachingOptional caching with configurable TTL, cache key generation from query params, graceful fallback

Socket.io 4Real-time order updates, notification center, and event-driven client communication

JWT + Passport.jsAccess/refresh token rotation, Google & Facebook OAuth, email verification, password reset

Winston LoggingDaily rotating file logs, structured JSON format, configurable log levels per environment

M-Pesa STK PushLipa na M-Pesa Online via Axios, callback processing, transaction verification, sandbox/production

ElasticsearchOptional full-text search engine integration with indexing service and graceful fallback to MongoDB

Rate Limitingexpress-rate-limit for API-wide and auth-specific rate limits, Helmet security headers, CORS

Express Validationexpress-validator middleware for input sanitization, Zod schemas for complex validation

Payment ModelsTransaction model with mpesa/card/bank support, order payment status, M-Pesa callback handling

Security MiddlewareHelmet, CORS, compression, error handler with consistent API response format

Docker + Docker Compose4-service orchestration (MongoDB 7, Redis 7, Backend, Frontend with Nginx), multi-stage builds

pnpm WorkspacesMonorepo with shared tooling, orchestration scripts, and unified dependency management

GitHub Actions CIAutomated test pipeline running Jest + Cypress on push, linting with ESLint

Vercel + RenderFrontend deployed to Vercel, backend to Render, environment config via vercel.json and render.yaml

37 Docs FilesComprehensive documentation covering setup, deployment, M-Pesa, OAuth, project gap analysis, and more

Seed Scripts6+ data seeding scripts for products, categories, and development data population

Jest + ts-jestTypeScript-first test runner for both frontend components and backend integration tests

React Testing LibraryComponent tests for ProductCard, Header, and UI primitives with user-event simulation

Cypress 13End-to-end tests with TypeScript support, configured in cypress.config.ts

supertestHTTP assertions for backend API integration tests with mongodb-memory-server

ESLint 8/9Linting with TypeScript-ESLint for both frontend and backend codebases

mongodb-memory-serverIn-memory MongoDB for isolated backend integration tests without external dependencies

05 // The Outcome

Comprehensive e-commerce foundation

0 +

Pages including admin dashboard

0 +

API endpoints across 7 route groups

0

Database models with full CRUD

0 +

Reusable UI components

SwiftCart provides a complete, production-ready e-commerce foundation with native M-Pesa STK Push integration — something no major open-source platform offers out of the box. The monorepo architecture with pnpm workspaces, Docker orchestration, and 37 documentation files make it easy to deploy, customize, and extend. With Redis caching, Elasticsearch integration, comprehensive testing, and a full admin dashboard, SwiftCart serves as both a portfolio-grade reference architecture and a launch-ready marketplace platform.

Swift Cart