Requirements

Functional Requirements:

• User can browse and search for products by name, keywords, price, and category.
• User can manage their shopping cart i.e. add, remove, update
• User can purchase items by completing a secure payment flow
• User can view their order history
• User can track their order status (Placed, shipped, Out for delivery, delivered, Cancelled)
• User can log in and manage their account

Non-Functional Requirements:

• Highly Available - 99.9% browsing products should load always
• Highly Scalable - system should be able to handle millions of searches, orders and payments
• Payments are strongly consistent
• Order status are eventual consistency
• Low latency <200ms Browse products; <200ms for payment processing

Capacity Estimation

• 100M DAU
• Avg 5 searches for each DAU
  • 500M searches daily
  • ~5K QPS
  • peak traffic 5x -> 25K QPS
• 10% of DAU places one order daily
  • 10M orders daily
  • ~100 orders/sec
  • peak traffic 5x -> 500 orders/sec

API Design

GET /products?keyword=x&category=y&price=z&limit=20&cursor=

• Fetch products with query parameter filters
• use cursor based pagination

GET /users/{userId}/cart

• returns items in user shopping cart

POST /users/{userId}/cart/items

req - {

productId,

quantity,

}

• If the product is not in the cart → create a new cart item.
• If the product already exists → update its quantity.
• If quantity = 0 → remove the item from the cart (or soft delete, depending on your design).

Placing order api

POST /order

req - {

userId,

items[] :

{ id,

quantity

},

shippingAddress,

paymentMethodId

}

GET /users/{userId}/orders?fromDate=x&toDate=X&limit=20&cursor

• Returns user order history in the date range, with limit and cursor pagination

POST /order/status

req - {

orderId,

status -> SHIPPED, OUT FOR DELIVERY, CANCELLED, DELIVERED

}

POST /users -> user creation

PUT /users/{userId} -> user updates

POST /auth -> user login

High-Level Design

API Gateway

Acts as the entry point for all client requests.

Responsibilities:

• Authentication (if required)
• Rate limiting - Applied using token bucket per IP to prevent fraudulent or bot views
• Request routing

Load Balancer

Distributes traffic across multiple instances of all services to improve scalability and availability.

Search Service

Responsbilities

• Handles product browse/serach queries
• Normalizes and parses query parameters in a queryable format
• For Hot searches, productIDs are cached in Redis -> so checks redis first
• If cache miss -> invoke Inverted Index elasticserach to fetch productIds
• fetch product details from redis if cached if cahce miss fetch details from DB

Inverted Index - ElasticSearch

Responsiblities

• Stores inverted index, i..e keywords/categoies -> ids . For prices, it uses a range structure (numeric tree structure) i.e
• eg: "apple" -> product123, product45, "cameras" -> product56,prodcut78, price 500 -> retruns all ids <500 price

Order Service

Responsibilites

• Handles order requests
• uses Idemptoteny key -> so if same request comes in again, we dont create duplicate order
• Validates the request -> checks if there's enough inventory, user validation, product validation etc
• Creates the order with default 'Payment Pending' status
• Delegates the payment request to payment service
• Receives a paymetnt confirmation back
• Returns back response

Payment Service

• handles payment, compensating request for failures
• Validates request, user paymentMethod
• Creates and stores a Payment record in DB
• Invokes Payment provider to complete payment
• Pushes PaymentCompelted event to kafka to update status and returns back status to Order service

User servuce

Responsiblities

• Handles User CRUD operations

Cart servuce

Respsonsiblies

• Hanldes cart CRUD operations

Order Status Updates Webhook

Responsibilities

• Handles order status updates
• Recieves order updates -> Shipped, Out for delivery, cancelled, Delivered, Refunded etc
• Validates request and status too
  • eg: if current order status is Out for delivery, then any order status update before this status for that order is rejected

Payment Provider

• External provider used to handle payments.
• Also used to store user paymetn method details -> gives us back a ref no, we store that

CDN

• Servers product media -> images, videos etc
• Fallbacks to object storage if cahce miss

Object storage

• Source of trught for product media -> images., videos

kafka

• used for order status updates
• Use orderId as parition key

Database Design

We will use SQL DB i.e. PostreSQL for our major tables. We need to ensure:

• ACID transactions for orders, payments
• Strong consitency for payments
• Strong relatitons between order and order items
• Easy querying

Hence, SQL fits best

Order

id

userId (partiton key)

status

totalPrice

paymentId

shippingAddressId

createdAt

UpdatedAt

OrderItem

id

orderId (partiton key)

productId

quantity

PriceAtPurchase

CartItems

id

userId (partiton key)

productId

quantity

price

User

id

name

email

country (partiton key)

primaryShippingAddressId

primaryPaymentMethodId

ShippingAddress

id

streeName

StreetAdd

City

PostalCode

Provice/State

Country

PaymentMethod

id

paymentProvider

refNo

Product

Id

Name

Title

Description

Price

ProductInventory

Id

ProductId

AvailableItems

LastUpdated

ProductMedia

Id

ProductId

Url -> CDN signed url

Also hot product details are cached in Redis for faster fetch

Detailed Component Design

Now we will deep dive into these topics

How to avoid concurrent placing order issue?

Problem: Theres 1 stock left for an item, 2 users places order for the same item simultaneously for the same item. Without proper solutioning, this could result in both orders going rhought even tho theres not enought inventory

Solution: Use Single ACID transaction with row locking

• User A's order is recieved by order service
• Order service does validation on invetory
• When we fetch product invetory, we would use:

• This will row lock that row; meaning no other transaction can access taht row
• During the same time when fetching product invetoryu, order service receives order request for same product from UserB
• Now when we try to fetch inventory -> it will have to now wait till lock is released
• USer B requyest will hence need to wait
• User A continues request -> completes payment -> updates inventory -> releases lock
• Now user B can then access the invenotry row
• Now when it checks invenotry row -> theres no more stock
• User B request is hence rejected.

Order Status Update Flow

• The order statsu update is majorly handled by Order Update service

Payment Pending

• Order service when it first creates the order, would put 'Payment_Pending' as default status

Order Confirmed/ Payment Failed/ Cancelled

• When payment is completed it would put the PaymentCompleted event to kafka
• Oreder status update service will consume it and update staus accordinly

Order Shipped

• Shipper will package the roder and when its ready they will update it in their system
• Shipper's system will then invoke our webhook with staus as Shipped
• Webhook will valdiate the request and current order staus, and will then update the status

Out for deliver/delivered

• Courier will update the relevant status on their system
• Couries's system will invoke our webhook with relevant staus
• Webhook will valdiate the request and current order staus, and will then update the status

Payment Processing Reliability

Problem -> User clicks pay and completes payment but during payment processing network timeout happens before our service gets response back, user then clicks pay again,user is charged twice without proper solutioning

Solution -> Use an idempotency key.

• Payment service will recieve an idempotency key adn will first create the Payment record,witj the idempotent key eg: {userId)-{orderid}-{guid}
• This idempotent key is also send to payment provider

• Payment Service -> Payment provider
  • Check idempotency key
    • If exists -> return previous result
    • if new -> process payment
      • Payment provider
      • Store result
• Payment service also stores the result, in case if payment service recives the request agian for same key, it can return result wihout invoking payment provider

how to avoid duplicate order creation?

-> Use idemptoent Key

• Each order request comes wiht an idempotency key
• This key is stored in roder Table
• So when order is processing and network glitch ahppen and user retries, we dont create new order just pick up the same oder from table and process it again
• Similarly, if user payment failed and suer tries again with new payment method, we use idemptoent key to determine if same order but diff payment method, so that we dont create new order but rather create have payment service to create a new Paymetn record as new Payment attempt.

Scalability

• Search service and order service: Horizontally scalable, add up new instances to hanle more traffic
• PostreSQL: Partition/Shard the data
  • User table can be Partitioned via country
  • Order related tables Partitioned via UserId
• Use Regional Read replicas for read heavy tables like product

Failure Handling

• Redis: Product data can be rebuild again from persistence store.
• Kafka: Events are durable, when kafka instance is back up it picks up events, No event is lost