How QuickCart is built

QuickCart is a meta-marketplace: it holds a canonical product catalogue but sources live price, stock and delivery-time from five platforms — Blinkit, Zepto, BigBasket, Flipkart and Amazon — through a single aggregation service, the mcp-adaptor. The architecture below is organised around that fan-out.

System context

A thin, presentation-only mobile client talks to a single API Gateway / BFF, which composes responses from a set of focused Node.js services. Only the mcp-adaptor service ever speaks to external platform MCPs; every other service is internal and stateless where possible.

How the mobile app connects to the backend

The client is a React Native app. It never talks to a database or to a platform MCP directly — it speaks only to the gateway over three channels:

Connection & auth handshake

Key API surface

An auth-guarded route

import { Router } from "express";
import { authGuard } from "../middleware/authGuard";
import { aggregation } from "../clients/aggregation";

const router = Router();

// GET /v1/products/:id/offers  — ranked offers for one canonical product
router.get("/v1/products/:id/offers", authGuard, async (req, res, next) => {
  try {
    const { id } = req.params;
    const zone = req.user.deliveryZone;              // from JWT claims
    const offers = await aggregation.getRankedOffers(id, zone);
    res.set("Cache-Control", "private, max-age=30"); // matches Redis TTL
    res.json({ productId: id, offers });
  } catch (err) { next(err); }
});

export default router;

import jwt from "jsonwebtoken";

export function authGuard(req, res, next) {
  const header = req.headers.authorization ?? "";
  const token = header.startsWith("Bearer ") ? header.slice(7) : null;
  if (!token) return res.status(401).json({ error: "missing_token" });
  try {
    req.user = jwt.verify(token, process.env.JWT_PUBLIC_KEY, { algorithms: ["RS256"] });
    next();
  } catch {
    return res.status(401).json({ error: "invalid_token" });
  }
}

Backend services

Each service owns one responsibility and (where it is stateful) one datastore. They communicate synchronously through the gateway for reads and asynchronously over Kafka for events.

Technology stack

Data model

The catalogue is deliberately separated from the volatile per-source offer snapshots. A canonical product is stable; an offer (price/stock/ETA from one source) is short-lived and refreshed constantly.

Catalogue management

The catalogue is the backbone: every search result, comparison and order references a canonical product. Platform-specific listings are attached to it, never the other way round.

The canonical product model

Mapping platform products → canonical

Each source listing is linked through PRODUCT_SOURCE_MAP with a match confidence. Matching runs a cascade: exact GTIN/EAN → fuzzy brand + normalised title + pack-size → embedding similarity on title+image. High-confidence matches auto-link; the rest go to review.

{
  "canonical_sku": "QC-GRO-AMUL-BUTTER-500G",
  "title": "Amul Butter (Pasteurised, Salted)",
  "brand": "Amul",
  "category": "Dairy > Butter & Cheese",
  "pack_size": "500 g",
  "gtin": "8901020000123",
  "attributes": { "salted": true, "veg": true },
  "status": "active",
  "source_map": [
    { "source": "blinkit",   "source_product_id": "prod_88213", "confidence": 0.99 },
    { "source": "zepto",     "source_product_id": "z_44120",    "confidence": 0.97 },
    { "source": "bigbasket", "source_product_id": "BB_10029",   "confidence": 0.98 },
    { "source": "amazon",    "source_product_id": "B07XYZ",     "confidence": 0.91 }
  ]
}

Missing-SKU discovery

QuickCart grows its catalogue from real demand. When a shopper searches for something we can't map, that gap is a signal — the same loop shown in Document 02.

Where gaps come from

Pipeline health metrics

Analytics

Every meaningful action emits a typed event from the client SDK or a service. Events flow through Kafka into both a real-time layer (dashboards, missing-SKU signal) and the warehouse (funnels, cohorts, KPIs).

Event taxonomy

Headline KPIs

Conversion funnel

Where shoppers drop off between searching and ordering. Bars are one blue ordinal ramp; magnitude is the bar length.

Source win-rate

How often each platform provides the ranked-best offer at the moment of purchase.

GMV trend

All figures on this page are illustrative design targets, not measured production data.

Payments

QuickCart supports two fulfilment-and-money models, chosen per source based on what that platform's MCP allows (see Document 04):

Payment methods

Managed-checkout payment flow (UPI)

Refunds, reconciliation & scope

• Refunds/cancellations: if a source rejects or an item is out of stock at pick time, the order is auto-cancelled and refunded through the PSP; partial refunds for partial fulfilment.
• Reconciliation: a daily job matches PSP settlements against orders and source invoices; mismatches raise a finance alert.
• Idempotency: both order placement and webhook handling are idempotent (keyed by Idempotency-Key / PSP event id) so retries never double-charge or double-fulfil.

Scaling, reliability & security