E-commerce Architecture Deep Dive

Treating 'the product' as the single unit that inventory and price attach to is a common early modeling mistake -- it breaks the moment a product has variants.

A Product carries stable, descriptive identity: title, description, brand, category, attributes, media references. It changes rarely. A SKU (or variant) is the actual purchasable unit -- a T-shirt in black, size M is a different SKU from the same T-shirt in blue, size L. Inventory and price attach to the SKU, not to the abstract Product.

Read/write ownership

The catalog admin/CMS write path publishes Product and SKU metadata, which changes rarely. A separate pricing/merchant path commonly owns Offer data, which can change far more often. Inventory owns per-SKU (and per-location, once multi-location is in scope) stock counts. Keeping these write paths separate keeps unrelated update rates -- rare product edits vs. frequent price or inventory changes -- from contending with each other or forcing one cache-invalidation policy to fit all three.

The catalog read path is cache-aside plus a CDN -- simple, but each piece has a correctness caveat worth being precise about.

Reads go through Catalog Service -> Cache -> Catalog DB on miss. Product images and static assets are served from a CDN independent of the cache/DB path. A write to the catalog (admin edit, price change, new product) invalidates the corresponding cache entry explicitly where correctness matters, rather than relying only on TTL expiry to eventually reflect the update.

The single largest content gap in a naive e-commerce design: catalog metadata and checkout price get treated as one value, when they need to be modeled, owned, and versioned separately.

Display price is a cached read used for browsing and discovery -- fine to be a few seconds or minutes stale. A checkout quote is a separate, authoritative pricing decision, validated at the moment of checkout against current commercial terms: currency, active promotions, tax and shipping if in scope, and an explicit price version.

The checkout quote

A checkout quote can carry: quote_id/version, line prices, currency, discounts, tax/shipping if in scope, and an expiry. Promotions and coupons are optional inputs to the quote -- this module does not attempt to teach a full promotion-rule engine.

Order line price snapshot

Once an order is accepted, the accepted commercial terms -- unit price, currency, discounts applied -- are snapshotted onto the order line item. Never reconstruct historical order totals from today's catalog price; the catalog price today can legitimately differ from what the customer actually paid.

If price changes between cart and checkout, surface the change and require acceptance according to product policy -- never silently charge an arbitrary stale or new value. See Failure & Scale -> Price Changes During Checkout.

The search index is a derived read model built from catalog change events -- not a second copy of the database, and not the checkout authority.

When a product or SKU is created or updated, an event triggers the indexing pipeline, which updates the search index. The catalog database remains authoritative; the index exists for relevance, faceting, typo tolerance and independent query scaling.

A cart's data model is small, but the fields it carries -- and which of them are authoritative -- matter more than the storage technology underneath it.

A cart is keyed by user ID (or a guest/session ID for unauthenticated shoppers) and holds a list of items: sku_id, quantity, and commonly a displayed-price snapshot for UX continuity, plus timestamps for expiry. A fast key-value store is a reasonable fit given the access pattern -- frequent small reads and writes, natural expiration -- but the model matters more than the specific store.

Inventory is the correctness-critical layer of the platform -- but the model needs three states, not one counter, and it is a per-SKU record, not necessarily a single global number.

Real inventory models commonly extend this baseline with safety stock, damaged/unsellable stock, in-transit stock, and per-location allocation once multiple warehouses or stores are in scope (see Complete Design's brief mention -- this module does not attempt a full warehouse-management design).

A reservation needs a durable identity -- not just an atomic decrement -- so it can be found again, retried safely, committed, released or expired.

A reservation record carries: reservation_id, checkout/order ID, sku_id, quantity, state, expires_at, and a version/idempotency key. The reserve operation and the reservation record should be coordinated transactionally where the underlying store supports it.

There is more than one valid way to implement the same atomic check-then-reserve invariant -- the right choice depends on contention level and store.

Expiry has to be durable and recoverable -- an abandoned checkout must reliably release its reservation even if nothing else about the system reminds it to.

A stable checkout idempotency identity is what maps repeated Place Order submissions to one logical checkout/order instead of creating duplicates.

A client-generated idempotency key (or a server-issued checkout session ID handed to the client at cart-to-checkout transition) maps to a durable uniqueness constraint. Store a request fingerprint -- cart contents, quote version -- alongside the key so a conflicting reuse of the same key (different cart contents under the same key) can be detected and rejected rather than silently applied.

Checkout is a saga -- a sequence of local commits across several services, coordinated by durable workflow state rather than one shared ACID transaction.

A useful baseline state machine: CHECKOUT_CREATED -> INVENTORY_RESERVED -> PAYMENT_PENDING -> CONFIRMED, with explicit failure and unknown branches (INVENTORY_UNAVAILABLE, PAYMENT_FAILED, PAYMENT_PENDING_UNKNOWN) rather than only a happy-path chain.

Compensation is a fallible business operation performed after the fact -- not an automatic rollback the saga provides for free.

Typical compensating actions: release the inventory reservation, refund or void the payment, cancel the order. Each is a real operation against a real system, with its own possible failure.

An order is a header plus an immutable, snapshotted set of line items -- it must never need to reconstruct itself from mutable catalog or pricing data.

Order state, payment state and fulfillment state are three separate state machines -- collapsing them into one enum produces invalid combinations.

Committing the order's CONFIRMED state to the database and publishing order.confirmed to a broker are two separate operations against two separate systems -- and that gap silently drops or duplicates events if left unaddressed.

Failure window: the order DB commits CONFIRMED, the process crashes before the publish call, and no fulfillment event is ever produced. The fix: in the same database transaction that writes the order transition, also insert a durable outbox row representing the event. A separate relay reads unpublished outbox rows and publishes them to the broker, marking them published once acknowledged.

Because the relay can itself crash between publishing and marking a row published, it may republish the same event on restart -- the outbox closes the durability gap, it does not eliminate the need for idempotent consumers (see Event Consumer Idempotency below).

At-least-once delivery is the guarantee actually being provided -- every downstream consumer of order events needs to tolerate duplicates by design.

Fulfillment is a real stateful workflow with its own transitions -- not a generic async consumer that just marks the order 'shipped.'

A fulfillment request is created off the order.confirmed event, then moves through allocation (assigning a location/warehouse to fulfill from), pick, pack, shipment, and delivery-status tracking. An order can ship in more than one package -- partial shipment is a normal, not exceptional, path.

A distributed checkout can accumulate inconsistencies even when every individual service retries correctly -- reconciliation is the sweep that catches what retries alone didn't resolve.

Cancellation and return are their own distributed workflows -- not a simple state flag -- and refund is a separate financial operation owned by the Payment System.

Cancellation before fulfillment starts: validate the order is still in an eligible state, cancel the fulfillment request if it hasn't started, release or restore inventory according to the inventory model's semantics, and void or refund payment as required. After shipment, cancellation typically becomes a return/refund workflow instead.

Horizontal scaling of a stateless Inventory Service does not remove contention on one scarce SKU -- the bottleneck is a single row or partition, not compute capacity.

Browse traffic during a flash sale can scale through CDN and cache. Checkout admission for the scarce SKU cannot -- every reservation attempt for that one SKU ultimately contends on the same row or partition, regardless of how many stateless service instances are running.

Catalog, cart, inventory and orders don't need to share one partition key -- each workload's access pattern picks a different natural key.

Metrics should be separated by workload boundary the same way the architecture is -- a search indexing lag spike and an inventory reservation conflict spike are different incidents, even though both can look like 'the site is slow' to a customer.