Design Quick Commerce Platform

┌─────────────────────────────────────────────────────────────────────────────┐
│                              CUSTOMER LAYER                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  Mobile App  │  │   Web App    │  │  API Gateway │  │     CDN      │     │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            SERVICE MESH (Istio)                              │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │  Catalog   │  │  Inventory │  │   Order    │  │  Pricing   │             │
│  │  Service   │  │  Service   │  │  Service   │  │  Service   │             │
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘             │
│                                                                              │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │ Dark Store │  │  Delivery  │  │   Search   │  │  Payment   │             │
│  │  Service   │  │  Service   │  │  Service   │  │  Service   │             │
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘             │
│                                                                              │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │ Notification│  │  Analytics │  │  Forecast  │  │   User     │             │
│  │  Service   │  │  Service   │  │  Service   │  │  Service   │             │
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘             │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              DATA LAYER                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Postgres   │  │    Redis     │  │ Elasticsearch│  │    Kafka     │     │
│  │  (Primary)   │  │   (Cache)    │  │   (Search)   │  │  (Events)    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘

-- Atomic inventory reservation using Lua script
local available = redis.call('HGET', KEYS[1], 'available')
local requested = tonumber(ARGV[1])

if tonumber(available) >= requested then
    redis.call('HINCRBY', KEYS[1], 'available', -requested)
    redis.call('HINCRBY', KEYS[1], 'reserved', requested)
    -- Set TTL for soft reservation
    redis.call('SETEX', KEYS[2], 600, ARGV[2]) -- 10 min TTL
    return 1  -- Success
else
    return 0  -- Insufficient stock
end

-- Key structure: inventory:{store_id}:{sku_id}
-- KEYS[1] = inventory:DS001:SKU123
-- KEYS[2] = reservation:ORDER123:SKU123
-- ARGV[1] = quantity
-- ARGV[2] = order_id

-- Find nearby dark stores within 3km radius
SELECT
    ds.store_id,
    ds.store_name,
    ST_Distance(
        ds.location::geography,
        ST_MakePoint(:customer_lng, :customer_lat)::geography
    ) AS distance_meters,
    ds.current_order_count,
    ds.available_riders
FROM dark_stores ds
WHERE ST_DWithin(
    ds.location::geography,
    ST_MakePoint(:customer_lng, :customer_lat)::geography,
    3000  -- 3km radius
)
AND ds.is_operational = true
ORDER BY distance_meters ASC
LIMIT 5;

-- Create spatial index for fast queries
CREATE INDEX idx_store_location
ON dark_stores USING GIST (location);

PLACED (0 min)
    │
    ▼ [Payment Confirmed]
CONFIRMED (0-1 min)
    │
    ▼ [Assigned to Picker]
PICKING (1-3 min)
    │
    ▼ [All items collected]
PACKED (3-5 min)
    │
    ▼ [Rider assigned & arrived]
DISPATCHED (5-7 min)
    │
    ▼ [Rider reaches customer]
OUT_FOR_DELIVERY (7-12 min)
    │
    ▼ [Customer confirms receipt]
DELIVERED (10-15 min)

Parallel Track:
PLACED → CANCELLED (Customer/System cancellation)
PICKING → PARTIALLY_FULFILLED (Some items out of stock)

function findOptimalRider(order, store) {
  // Get available riders within 2km of store
  const nearbyRiders = await getRidersNear(store.location, 2000);

  // Filter by availability
  const availableRiders = nearbyRiders.filter(r =>
    r.status === 'IDLE' ||
    (r.status === 'DELIVERING' && r.estimatedFreeIn < 3) // Free in 3 min
  );

  // Score each rider
  const scoredRiders = availableRiders.map(rider => ({
    rider,
    score: calculateScore(rider, order, store)
  }));

  // Sort by score (higher is better)
  scoredRiders.sort((a, b) => b.score - a.score);

  return scoredRiders[0]?.rider;
}

function calculateScore(rider, order, store) {
  let score = 0;

  // Distance to store (40% weight)
  const distToStore = getDistance(rider.location, store.location);
  score += (1 - distToStore / 2000) * 40; // Closer = higher score

  // Rider rating (20% weight)
  score += (rider.rating / 5) * 20;

  // Current battery/fuel (10% weight)
  score += (rider.batteryPercent / 100) * 10;

  // Historical performance for this route (30% weight)
  const avgDeliveryTime = getHistoricalTime(rider.id, store.id, order.deliveryArea);
  score += (1 - avgDeliveryTime / 15) * 30; // Faster = higher score

  return score;
}

-- Dark Stores
CREATE TABLE dark_stores (
    store_id        VARCHAR(20) PRIMARY KEY,
    store_name      VARCHAR(100),
    location        GEOGRAPHY(Point, 4326),
    city_id         VARCHAR(10),
    is_operational  BOOLEAN DEFAULT true,
    operating_hours JSONB,
    created_at      TIMESTAMP DEFAULT NOW()
);

-- Products (Master Catalog)
CREATE TABLE products (
    sku_id          VARCHAR(50) PRIMARY KEY,
    name            VARCHAR(200),
    category_id     VARCHAR(20),
    brand           VARCHAR(100),
    mrp             DECIMAL(10,2),
    weight_grams    INT,
    image_urls      TEXT[],
    search_vector   TSVECTOR,  -- For full-text search
    created_at      TIMESTAMP DEFAULT NOW()
);

-- Orders (Sharded by city_id)
CREATE TABLE orders (
    order_id        UUID PRIMARY KEY,
    user_id         UUID,
    store_id        VARCHAR(20),
    city_id         VARCHAR(10),  -- Sharding key
    status          VARCHAR(30),
    total_amount    DECIMAL(10,2),
    delivery_address JSONB,
    delivery_location GEOGRAPHY(Point, 4326),
    placed_at       TIMESTAMP DEFAULT NOW(),
    delivered_at    TIMESTAMP,
    CONSTRAINT fk_store FOREIGN KEY (store_id) REFERENCES dark_stores(store_id)
);

-- Order Items
CREATE TABLE order_items (
    order_id        UUID REFERENCES orders(order_id),
    sku_id          VARCHAR(50),
    quantity        INT,
    unit_price      DECIMAL(10,2),
    status          VARCHAR(20), -- FULFILLED, SUBSTITUTED, CANCELLED
    PRIMARY KEY (order_id, sku_id)
);

-- Sharding Strategy: Citus on PostgreSQL
SELECT create_distributed_table('orders', 'city_id');
SELECT create_distributed_table('order_items', 'order_id',
    colocate_with => 'orders');