Skip to content
KR7Tech

Learning guide preview

Amazon-scale marketplace design

Explore a marketplace architecture through its requirements, APIs, data ownership, checkout flow, and operational trade-offs.

Sign in and explore Pro Back to KR7Tech Student Plan

Enter the PIN separately for each Pro question or lesson. Opening one item does not unlock other items or topics.

Amazon-scale marketplace design

10 free of 135 questions / lessons

Functional requirements

  • Browse categories and product detail pages; search, filter, sort, and view product media.
  • Represent a marketplace offer as a seller's price, condition, and fulfillment option for a product.
  • Create and update a persistent cart across sessions and devices.
  • Validate price, promotions, address, tax, delivery promise, and stock at checkout.
  • Place an order, authorize payment, reserve inventory, and support safe retries.
  • Track order, shipment, delivery, cancellation, refund, and customer notification status.
  • Seller workflows to manage offers and inventory are in scope as a separate authenticated surface.

Out of scope for the first version

  • Detailed recommendation / ads ranking and machine-learning model training.
  • Warehouse robotics and route optimization internals.
  • Every region's tax, legal, and payment-provider integration.
  • Digital goods, subscriptions, auctions, and grocery cold-chain handling.

These can be additional domains behind stable APIs and events without entangling the core purchase flow.

Non-functional requirements (illustrative targets)

  • Availability: browse/search target 99.99%; order placement target 99.95%, measured monthly.
  • Latency: product/search p95 < 300 ms at edge/API; checkout orchestration response p95 < 2 s excluding external step-up authentication.
  • Durability: acknowledged order and payment state must survive a single node/AZ failure.
  • Correctness: no duplicate charge for one idempotency key; inventory reservation is atomic per stock owner.
  • Consistency: strong consistency for order transitions and stock reservation; bounded eventual consistency for search and read projections.
  • Security: least privilege, encryption, auditability, privacy controls, and payment-card compliance.
  • Operability: end-to-end traceability, reversible deployments, tested recovery, and controlled regional failover.

Why separate browse from buy?

Browsing is a high-volume read path where caches and slightly stale indexes are acceptable. Checkout is lower-volume but correctness-critical: price and inventory must be revalidated and recorded authoritatively. Independent paths let each scale and fail differently.

Read optimizedWrite correctnessGraceful degradation

2. Workload assumptions and rough sizing

Sizing converts vague “large scale” into engineering estimates. Revisit the estimates with real traffic, launch plans, and regional distribution.

Planning inputIllustrative assumptionArchitecture implication
Active shoppers50 million daily active users; peak 500,000 concurrent sessionsStateless web/API tiers; session/cart state externalized and partitioned.
Browse trafficPeak 100,000 product/search reads per secondCDN + cache + search index; elastic read replicas; protect origins on cache misses.
Checkout trafficPeak 5,000 checkout attempts per second during a major eventQueue/bulkhead downstream work; protect inventory/payment from bursts; idempotent checkout.
Read/write mixCatalog and product reads dominate writes; order writes are smaller but high valueSeparate read models from authoritative order and inventory stores.
Payload assumptionsProduct JSON around 10 KB; order event around 2 KB (media excluded)Store images/videos in object storage; keep messages small and versioned.
Failure modelNodes, AZs, providers, and network links can fail; regional outage is rare but planned forMulti-AZ by default; explicit recovery objectives; multi-region writes require domain-specific ownership.
Example bandwidth calculation: 100,000 reads/s × 10 KB is roughly 1 GB/s of uncached response payload before protocol overhead. CDN/cache hit rate therefore materially changes origin cost and capacity. This is a planning calculation, not a promise that all reads are identical.

Command path vs. event path

Commands ask an owner to perform a decision now (reserve inventory, authorize payment). Use synchronous calls only when the result is required to continue, with strict timeouts.

Events state a fact that already happened (order confirmed). Consumers react independently; retries and duplicate delivery are expected.

Trust boundaries

Clients enter through an edge protected by WAF and identity. Internal services use workload identity, authorization, and encrypted transport. Payment-provider and seller integrations are treated as external/untrusted dependencies.

4. How and why the system is divided

A service boundary should follow a business capability, data ownership, and a change/scaling boundary—not simply one service per database table.

Domain/serviceOwnsWhy it is separatedDoes not own
Identity / CustomerCustomer profile references, preferences, access policySecurity lifecycle and privacy rules are distinct from shopping transactions.Passwords in shopping tables; payment card data.
CatalogProduct descriptions, attributes, taxonomy, media metadataProduct authoring has a different write pattern from inventory and orders.Search ranking index as its source of truth.
Offer / PricingSeller offer, price, promotion rules, quote versionsMarketplace pricing and seller changes evolve independently; checkout needs a price snapshot.Final order total after an order is accepted.
SearchSearch index and query/ranking APIRead-heavy, denormalized, and rebuildable from Catalog/Offer events.Canonical product or price records.
CartCart lines, owner, version, expiryHigh-volume, ephemeral, customer-centric state with optimistic edits.Guaranteed stock or immutable order lines.
Checkout / OrderCheckout idempotency, order snapshots, lifecycle, saga stateOwns the purchase invariant and orchestrates distributed steps.Direct writes to inventory or payment storage.
InventorySellable quantities, allocations, reservations, stock adjustmentsConcurrency/oversell invariant belongs to one authoritative owner.Shopping-cart availability promises as final truth.
PaymentAttempts, provider references, authorization/capture/refund stateSecurity, auditing, reconciliation, provider-specific behavior.Raw card number/CVV or order ownership.
Fulfillment / DeliveryPick-pack work, package, carrier, delivery statusLong-running physical workflows and partner integrations.Authoritative payment or catalog data.
NotificationTemplates, delivery preferences, send attemptsCan retry/fail independently and should not block checkout.Order lifecycle decisions.
Do not start with dozens of services: keep a modular monolith if team boundaries, independent scaling, or deployment needs do not justify distributed operations. Split when ownership and measured bottlenecks are clear.

5. Example technology stack and why

One credible AWS-oriented stack for this scale. The service boundaries matter more than the brand names; equivalent managed services can be substituted in other clouds.

LayerExample choiceWhy / design note
Web storefrontTypeScript + React / Next.jsReusable components, SSR for product discovery/SEO, client hydration for interactive cart. Avoid placing payment secrets in the browser.
MobileNative iOS/Android or React NativeUse the same domain APIs; push notifications remain a separate asynchronous capability.
Edge/static assetsRoute 53 + CloudFront + AWS WAF + S3Global static/media delivery, cache policies, TLS, bot/rate controls. Version and invalidate content intentionally.
Ingress / APIAPI Gateway or ALB + BFFGateway handles routing/throttling; a BFF composes client-friendly responses. Avoid putting business transactions in a generic gateway.
Backend runtimeJava/Kotlin (Spring Boot) or Go; containers on ECS/EKSStrong ecosystem and operational flexibility. Choose a primary language per team; avoid a polyglot service per function.
Primary order DBAurora PostgreSQL (or compatible managed relational DB)Transactions, unique constraints, and order state consistency. Partition and scale deliberately; do not assume a single writer is infinite.
Cart / high-scale key-valueDynamoDBPredictable key-based reads/writes, TTL, and partition scaling. Use conditional writes for cart versions and idempotency records.
InventoryDynamoDB conditional updates or relational store with atomic transactionsChoose based on reservation/query model. The stock owner performs atomic conditional reservation; cache is never the final stock authority.
CacheElastiCache for Redis + CloudFront cacheRedis for hot product fragments, sessions/rate-limit counters where suitable; CDN for public static/cacheable responses. TTL + invalidation, stampede protection, and no cache-as-authority for stock/payment.
SearchOpenSearchFull-text, facets, and ranking over a denormalized index rebuilt/updated from catalog and offer events.
Events / queuesAmazon MSK (Kafka) for durable event streams; SQS for work queues; SNS/EventBridge for fan-out patternsSelect by ordering, replay, consumer model, retention, and operational skill. Use outbox, schema registry/contracts, bounded retries, and DLQs.
Media / documentsS3Object storage for images/videos; metadata in Catalog DB; CDN serves derivatives. Do not put blobs in order database rows.
Identity / secretsAmazon Cognito or enterprise IdP; IAM roles; Secrets Manager + KMSOIDC/OAuth flows, workload identity, key rotation, least privilege, and managed secret delivery.
ObservabilityOpenTelemetry + CloudWatch; managed Prometheus/Grafana or equivalentCommon trace context, RED metrics (rate/errors/duration), structured logs, dashboards, and alerts tied to SLOs.
Delivery / IaCTerraform or AWS CDK; GitHub Actions/CodePipeline; canary/blue-green deploymentsRepeatable environments, policy checks, automated tests, progressive rollout, and quick rollback.

6. Main runtime flows

Browse and search

  1. Client requests a category/search page. CDN serves static assets and only caches public responses with an explicit cache key and policy.
  2. API/BFF authenticates when necessary, validates query limits, and calls Search. Search reads its own index, not a fan-out of service databases.
  3. Search returns product and offer IDs; BFF fetches/cache-reads presentation details in bounded batches, avoiding N+1 calls.
  4. Product detail checks Catalog and current Offer. Displayed availability is an estimate; final stock is checked at checkout.
  5. Catalog/Offer changes publish events through outbox; indexer updates OpenSearch idempotently. Track indexing lag as a metric.

Checkout (orchestrated saga)

  1. Client sends POST /v1/checkouts with cart ID/version, address ID, payment token reference, and a unique Idempotency-Key.
  2. Checkout returns an existing result for the same customer/key; otherwise validates identity, cart version, seller/offer eligibility, price, tax, address, and delivery promise.
  3. Order Service writes PENDING order, immutable item/price/address snapshots, saga state, and an outbox event in one local DB transaction.
  4. Saga requests Inventory to reserve all lines atomically with a stable order/attempt key and an expiry. Inventory returns reserved or rejected; partial reservation is rolled back inside the inventory owner.
  5. Payment authorizes the amount with a stable provider idempotency key. A timeout is an unknown outcome, not proof of failure; query/retry using the same key.
  6. On success, Order transitions to CONFIRMED and publishes OrderConfirmed from the outbox. Return order ID and status to client.
  7. Fulfillment consumes the event and creates work; Notification and Analytics consume independently. Consumers store event IDs to make at-least-once delivery safe.
  8. If authorization is declined, release the reservation and mark payment/order failed. If later cancellation occurs, void authorization or refund according to whether capture already happened.
PENDINGRESERVINGPAYMENT_AUTHORIZEDCONFIRMEDFULFILLINGSHIPPED / DELIVERED
Compensation is a business operation: release reservation, void authorization, cancel fulfillment, or issue refund. It is not a database rollback across services. If compensation fails, retain a visible pending state, retry safely, and alert operations/customer support.
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only
Pro only