Al Wholesale — B2B Multi-Vendor Marketplace Case Study

Overview

Al Wholesale is a B2B wholesale marketplace built for the UAE market. Buyers purchase in bulk, vendors manage their own catalogue and fulfilment, sales staff create negotiated orders, riders handle deliveries, and admins control commissions, payouts and platform content — all from one platform.

I designed and built it end to end: the 24-model PostgreSQL schema, 90+ REST endpoints, five role-based React portals, Noon Payments integration, the vendor payout ledger and the reporting layer. The codebase spans roughly 41,000 lines across Django and React.

The challenge

Wholesale transactions are multi-party by nature. A single order can contain products from several vendors, each with its own commission structure, fulfilment status and payout schedule. Keeping inventory, VAT, payments and vendor earnings consistent — even under concurrent checkouts — was the core engineering problem.

Overselling risk: two buyers checking out the last units of a product at the same moment.
Multi-vendor orders: one cart, many sellers, each needing independent fulfilment and payout.
Variable commercial rules: product-specific fees, vendor subscriptions and a global platform fee.
Compliance: UAE VAT must be calculated dynamically and reflected on every invoice.
Financial auditability: every sale, fee, refund and payout had to be traceable.
Role separation: buyers, vendors, sales staff, riders and admins need different views of the same order.

What I built

The result is a production marketplace with a buyer storefront, vendor portal, sales desk, rider dashboard and a master admin console — backed by a single API and an automated finance layer.

Five role-based portals: buyer, vendor, salesperson, delivery rider and admin, with JWT role claims and guarded routes.
Catalogue & pricing: categories, variants, image galleries, MOQ, bulk and tiered pricing, reviews, price history and Excel bulk upload.
Cart & checkout: guest cart with automatic login merge, coupons, MOQ and stock validation, and an atomic checkout with row-level locking.
Dynamic VAT & commission: a three-tier rule engine — product override → vendor subscription → global CMS rate — plus per-vendor flat fees.
Vendor payouts: an immutable ledger of sales, fees, refunds and payouts, with single and bulk settlement plus reconciliation history.
Orders & fulfilment: a full state machine, draft approvals, partial fulfilment, returns, disputes, delivery tasks and PDF invoices.
Payments: Noon Payments initiate/verify flows and HMAC-verified webhooks with idempotency guards.
Operations: RFQ requests, Excel bulk order import, CMS-managed banners/settings and seven exportable report modules.

“One order can span several vendors, so the data model was built around per-vendor line items from day one.”

— Architecture note, Al Wholesale

Architecture

The platform is split into a decoupled React SPA and a Django REST API, with background jobs and object storage handling the slow or heavy work.

Frontend: React 19 + Vite, React Router, Zustand stores, Tailwind CSS, Axios with silent JWT refresh and route-level code splitting.
API: Django 6 + Django REST Framework, SimpleJWT authentication and role-based permissions enforced server-side.
Data: PostgreSQL with select_for_update() row locking inside transaction.atomic() during checkout.
Async: Celery + Redis for background jobs and transactional email delivery via custom SMTP templates.
Storage & delivery: DigitalOcean Spaces for media, Gunicorn + Nginx on a DigitalOcean droplet, Vercel for the frontend.

Three decisions shaped the build: locking inventory at checkout to prevent overselling, moving VAT and commission rules into the CMS so business changes ship without a deploy, and recording every financial movement as a ledger transaction instead of mutating balances.