Designing an E-commerce Platform

We are designing an e-commerce platform where users browse products, search by keyword, add items to cart, check out, pay, and receive confirmation, fulfillment and delivery of their orders -- with cancellation and returns as part of the lifecycle, not an afterthought.

The architectural challenge is not handling any single one of these operations -- it is recognizing that each requires a different architectural strategy, and that correctness has to be preserved across all of them even though none of them can share one database transaction. The same approach that makes product browsing fast would cause inventory oversell. The same database that stores orders cannot efficiently power full-text search.

The central lesson

An e-commerce platform contains at least six distinct workloads: (1) product catalog browsing -- read-heavy, cacheable, eventually consistent; (2) search -- text-optimized, indexed, fresh against its own SLO rather than real-time; (3) pricing -- a commercial decision that must be authoritative at checkout even though it's displayed from a cache elsewhere; (4) inventory -- correctness-critical, guarded at the reservation decision; (5) cart and checkout -- session state plus a cross-service orchestration with distributed failure handling; (6) order, payment and fulfillment -- a durable business record, an external financial workflow, and an asynchronous physical workflow, each with its own state machine.

Functional requirements define what users can do. Non-functional requirements differ dramatically per workload -- there is no single platform-wide consistency or latency rule that fits all of them.

Functional

Browse the catalog and categories. Search and filter products. View product/SKU details. Add, update and remove cart items. Validate price and availability. Initiate checkout idempotently. Reserve inventory. Create and confirm an order. Make and resolve payment. View order status. Cancel where permitted. Return and refund at least conceptually. Track fulfillment and shipping.

Non-functional, per workload

Capacity estimate (illustrative)

These are illustrative planning numbers, not measurements of any real system. Assumptions: 5 million daily active users; 20 catalog/search page requests per user per day; a CDN and cache layer that serves 95% of browse requests; a 2% order conversion per daily active user; peak-to-average factor 5; 10 million SKUs at about 5 KB of catalog data each (images excluded); about 2 KB per order; and, for the flash sale, 1,000 units of one SKU with 500,000 users attempting to buy in the first 60 seconds. Day = 86,400 s.

What this implies for the design: browse is the large number (thousands per second) but the CDN and cache turn it into a few hundred origin requests per second, so it is a caching problem. Checkout is tiny (single-digit orders per second at peak), so aggregate checkout throughput is not the constraint. The hard shape is one SKU: about 8,300 attempts/s converge on one row or partition for 1,000 units, which is why reservation uses an atomic conditional update and why a flash sale needs admission control. Assumption: one contended conditional update takes about 1 ms, so one SKU serialises at roughly 1,000 reservations/s. Admitting about 3× the unit count as candidates (3,000, to cover payment failures and expiries) then takes about 3 s; everyone else gets a fast sold-out or waiting-room response before reaching payment.

Before any implementation detail, it's worth naming the entities this whole design revolves around -- they reappear in every chapter that follows.

The product catalog is the most read-heavy component. Products are browsed far more often than they're updated -- but inventory and price live on the SKU underneath, not on the Product itself.

A Product carries ID, title, description, category and attributes; a SKU underneath it carries the variant, inventory and price. Product metadata changes rarely, which makes catalog reads ideal for caching -- images and price are a different story, covered next.

Product search benefits from full-text matching, relevance ranking, faceted filtering and autocomplete -- capabilities a dedicated search engine provides more richly than a relational database as scale grows.

A dedicated search engine handles search queries; the catalog database remains the authoritative source, and the search index is a derived, eventually consistent read model built from catalog change events.

Pricing deserves its own architectural treatment -- catalog metadata and checkout price are not one value, even though they're often taught that way.

The product page shows a display price, served from the catalog cache -- fine for browsing. Checkout resolves a separate, authoritative quote: current currency, active promotions if any, and an explicit price version, valid for a bounded window.

Inventory is correctness-critical. Unlike product names and descriptions, inventory counts change on every purchase -- and the reservation decision, not the display count, is where correctness actually lives.

A cart is a user's expressed intent to purchase. It is not a reservation. Adding to cart must not hold inventory.

Cart data is: SKU/variant identity and quantity per line, associated with a user or guest session, and commonly a displayed-price snapshot for UX continuity. It is lightweight, frequently read and written, and naturally expires -- a fast key-value store is a reasonable fit for that access pattern.

Checkout combines cart validation, inventory reservation, order creation and payment -- a multi-step sequence spanning several systems with no shared ACID transaction. This is the chapter where ambiguity is most costly, so the baseline ordering has to be explicit.

Three identities

Checkout tracks three distinct identities that may be created at different points but must stay durably linked: a checkout_id (the orchestration attempt), an order_id (the durable commercial record), and a payment_id (the financial operation, owned by the Payment System).

A clear baseline sequence

(1) the client submits checkout with an idempotency key; (2) a durable checkout/order is created or reused in a PENDING state; (3) line items and accepted commercial terms are snapshotted; (4) inventory is reserved idempotently; (5) payment is initiated and resolved; (6) the order transitions to CONFIRMED only once the required conditions are actually satisfied; (7) the reservation is committed according to the inventory model; (8) an outbox event is written atomically with the order transition; (9) fulfillment starts asynchronously. The exact ordering has trade-offs -- see Trade-offs & Decisions -> Order-Before-Payment vs. Order-After-Payment -- but this baseline resolves the ambiguity the diagram alone can't.

Naming the pattern matters: checkout is a saga, and a saga does not provide ACID rollback -- it provides compensation, which is its own fallible operation.

Each service commits locally; durable workflow state records progress; failures trigger retries or compensations; compensations can themselves fail and must be idempotent and retriable; reconciliation handles workflows that get stuck despite all of that.

Payment is kept bounded here -- the full mechanics live in the Payment System module. This module owns the e-commerce-specific responsibilities around that boundary.

After a successful checkout, fulfillment, notifications and analytics must not block the confirmation response -- and the hand-off from the order database to the event queue has its own failure window worth naming.

In the same database transaction that writes the CONFIRMED transition, the Order Service also writes a durable outbox event; a separate relay publishes it to the queue. Fulfillment, notification and analytics consume it independently, each retrying its own failures without affecting the customer's confirmation or each other.

Cancellation and returns are part of the core lifecycle, not an edge case bolted on afterward -- and refund is a separate financial operation, not the same fact as a cancelled order.

Cancelling before fulfillment starts: validate the order is still eligible, cancel the fulfillment request if it hasn't begun, release or restore inventory per the inventory model, and void or refund payment as required. After shipment, cancellation typically becomes a return workflow instead -- authorization, receipt, and often an inspection step before returned stock becomes sellable again.

During a flash sale, browse traffic spikes sharply and CDN/cache absorb most of it -- but inventory reservation for the scarce SKU stays correctness-critical regardless of traffic, and horizontal API scaling alone does not remove contention on that one SKU.

Even with idempotency, retries and compensation everywhere, a distributed checkout can still accumulate small inconsistencies -- reconciliation is the backstop that catches them.

A periodic, idempotent sweep checks for gaps retries alone don't close: payment succeeded but the order never confirmed, a confirmed order with no committed reservation behind it, an expired reservation for a checkout that's still active, a stuck unpublished outbox event, or a refund that never completed.

The complete platform -- every component earns its place by solving a specific workload requirement or a specific correctness gap.