Skip to content
All stories

A fresh-grocery business in Pakistan

One system that runs a whole grocery business

Orders come from a website, a shop till, corporate clients and wholesale buyers. Every one has to be packed, driven and paid for without losing an item or a rupee.

Context

The business sells online, in its own store, through corporate gifting, subscriptions, wholesale and export, all served from its own warehouse with its own buyers and riders. The platform is one backend and one database behind five staff dashboards, a customer website and a rider app. Customers can even chat to an AI personal shopper in English, Urdu or Roman Urdu that builds a basket from live stock only.

How it works, step by step

Low-poly map of the grocery delivery network: one main warehouse, a van route to three neighbourhood dark stores, and riders fanning out to homes.

The delivery network

Main warehouse → van runs → dark stores → riders → homes

  • Main warehouse
  • Van run
  • Dark store
  • Rider
  • Customer homes

Now on the map: A customer places an order

  1. Step 1 of 10

    Built

    A customer places an order

    On the website, a customer checks out and chooses to pay cash on delivery.

    Next.js 16 storefront → Express 5 API: guest checkout with cash on delivery. An online-payment hook exists, but no provider is chosen yet.
  2. Step 2 of 10

    Built

    The online team confirms it

    Staff confirm the order in their dashboard, which automatically asks the warehouse to fulfil it.

    In the e-commerce dashboard (React 19 + TanStack), confirming raises a typed fulfilment handoff, one of five Zod-validated contracts between modules.
  3. Step 3 of 10

    Built

    Stock is reserved

    The warehouse holds the exact items, so the same item can never be sold twice.

    Stock is an append-only ledger in PostgreSQL. Reservations are ledger entries, and every status change runs through a state machine (57 of them across the API).
  4. Step 4 of 10

    Built

    A van carries it to a nearby dark store

    Orders travel in van runs from the main warehouse to small neighbourhood stores that sit closer to customers.

    The warehouse publishes van runs. The dispatcher uses the rider app to load the van, reach the dark store and close the run (Google Maps + Routes API).
  5. Step 5 of 10

    Built

    Counted in and packed

    At the dark store, staff count everything in against the van's list and pack the order.

    Count-in reconciles against the van manifest, and packing waves feed a delivery control tower.
  6. Step 6 of 10

    Built

    A rider sets off

    The rider checks in for a shift and gets turn-by-turn directions, in English or Urdu.

    Expo SDK 57 / React Native 0.86 app with instant right-to-left Urdu (Nastaliq), an offline outbox and in-app navigation. A rider's token can only reach their assigned jobs.
  7. Step 7 of 10

    Built

    Hand-over with proof

    At the door the rider takes a photo stamped with the time and place, and records the cash collected.

    The proof photo has time, GPS and order number burned in, and the cash amount is captured per job for reconciliation. Uploading the photo to the server is the next step.
  8. Step 8 of 10

    Built

    Delivered, paid, reconciled

    The order shows delivered and paid, and each rider's cash is checked against their deliveries at the end of the shift.

    Cash on delivery is reconciled per rider. The order reaches DELIVERED and PAID through its state machine.
  9. Step 9 of 10

    Built

    Returns are quarantined

    Anything returned goes to quarantine first, never straight back onto the shelf.

    Returns land in a quarantine stock location and need a quality decision before they become sellable again.
  10. Step 10 of 10

    Built

    Restocking follows a clear path

    Buying more stock goes request → purchase order → approval → quality check → goods received.

    Procurement: requirement → PO → approval → inbound QC → goods-received note, each one a handoff contract with its own state machine.

Decisions & tradeoffs

Chose
one modular backend and one database
over
a separate service for each team
because
five teams share the same orders, stock and cash. One source of truth avoids sync bugs and keeps a small team fast.
Chose
an append-only stock ledger
over
editing stock counts in place
because
every unit can be traced (who moved it, when and why), and that is what catches shrinkage.
Chose
neighbourhood dark stores fed by van runs
over
riders driving out from one warehouse
because
short last-mile trips mean faster delivery and fewer kilometres per order.

What's real today

The whole journey above, including returns and procurement, was run end to end on 28 Oct 2026. Card payment isn't built yet (cash on delivery only), and go-live is in progress. The client is not named.

What it achieved

API routes in one modular backend
~900
database tables in one PostgreSQL database
236
apps: five staff dashboards, a storefront and a rider app
7
automated backend tests
~2,000

Stack & role