E-Commerce Platform

Architecture

• Microservices: Per-domain Lambda services behind the API Gateway; each owns its own data store.
• Data Stores: Per-service DynamoDB tables — database-per-service, one owner each.
• Shopper: End user browsing the storefront on web
• React Storefront: SPA storefront: product browsing, cart, checkout with Stripe Elements. Served via CloudFront/S3.
• Cognito User Pool: Shopper sign-up/sign-in. Issues JWTs consumed by the API Gateway authorizer.
• API Gateway: REST edge for all domain services. Cognito JWT authorizer on every route except /webhooks/stripe.
• Catalog Service: Product listing, detail, and admin CRUD. Read-heavy; candidate for caching.
• Cart Service: One active cart per user. Add/update/remove items, recalculates subtotal on every write.
• Orders Service: Validates cart + payment intent, reserves stock, persists the order, and publishes OrderPlaced to SQS.
• Payments Service: Creates Stripe PaymentIntents and handles Stripe webhooks (signature-verified).
• Inventory Service: Stock levels and reservations. Admin-only API surface; also called by the order processor.
• Products Table: DynamoDB: products keyed by product_id, GSI on category.
• Carts Table: DynamoDB: carts + cart_items, keyed by user_id. TTL abandons stale carts.
• Orders Table: DynamoDB: orders + order_items + payments, GSI on user_id for order history.
• Inventory Table: DynamoDB: available/reserved quantities per product, updated with conditional writes.
• Stripe: External PSP. PaymentIntents created server-side, confirmed client-side, settled via webhook.
• Order Processing Queue: SQS (FIFO by order_id) decoupling checkout from fulfilment. DLQ after 3 receives.
• Order Processor: Consumes OrderPlaced: confirms payment, decrements stock, flips order to confirmed, triggers email.
• SES: Transactional email: order confirmation and shipping updates from templated sends.

Workflow

• Checkout initiated: Shopper clicks Pay on the storefront
• Validate cart: Re-price items, drop inactive products, verify cart status=active
• Reserve inventory: Conditional write: quantity_available >= requested for every line item
• Stock available?
• Insufficient stock: Return 409 to client with the offending line items
• Create Stripe PaymentIntent: Amount = subtotal + shipping + tax; idempotency key = cartId
• Await payment confirmation: Client confirms card via Stripe Elements; webhook settles the intent
• Payment succeeded?
• Release reserved inventory: Move quantity_reserved back to quantity_available
• Payment failed: Order marked cancelled; shopper prompted to retry with another card
• Persist order (paid): Write order + order_items + payment record; mark cart checked_out
• Publish OrderPlaced to SQS: FIFO by order_id; order processor takes it from here
• Send confirmation email: SES templated send from the order processor
• Order confirmed
• Checkout failed

Event flow

• Orders Service: Publishes order.placed at the end of checkout
• Stripe Webhook Handler: Verifies Stripe signatures and republishes payment outcomes internally
• order-processing (SQS FIFO): FIFO by order_id, DLQ after 3 receives
• payment-events (SNS): Payment outcomes, fanned out to interested consumers
• Order Processor: Joins order.placed with payment outcome; decrements stock or releases reservation
• Order Processor: Emits order.confirmed once payment and stock are settled
• order-notifications (SNS): Downstream fan-out point; add fulfilment here
• Email Notifier (SES): Sends templated confirmation email
• Analytics Sink (Firehose to S3): Order events archived for BI/Athena
• order.placed: Emitted by the orders service once stock is reserved and the order row is persisted as pending/paid.
• payment.succeeded: Translated from Stripe's payment_intent.succeeded webhook after signature verification.
• payment.failed: Translated from Stripe's payment_intent.payment_failed webhook; triggers inventory release.
• order.confirmed: Emitted by the order processor after payment is verified and stock decremented. Fan-out to email and analytics.

API contract

• POST/productsCreate product (admin)
• GET/productsList products
• GET/products/{productId}Get product detail
• GET/cartGet the current user's active cart
• POST/cart/itemsAdd item to cart
• PATCH/cart/items/{productId}Change item quantity
• DELETE/cart/items/{productId}Remove item from cart
• POST/payments/intentCreate a Stripe PaymentIntent for the cart total
• POST/ordersPlace order (step 3 of checkout)
• GET/ordersList my orders
• GET/orders/{orderId}Get order detail
• POST/webhooks/stripeStripe webhook receiver

Database

About this design

What this is

A production-shaped reference architecture for a small-to-mid e-commerce platform on AWS serverless. A React storefront (Cognito-authenticated) talks to API Gateway, which fronts five Lambda-backed domain services — catalog, cart, orders, payments, and inventory — each owning its own DynamoDB table set. Checkout is decoupled from fulfilment with an SQS queue, Stripe handles card processing, and SES sends transactional email. Every view in this project describes the same system: the architecture is the component map, the database schema is the per-domain table design, the API contract is what the storefront calls, the workflow is the checkout state machine, and the event flow is the order lifecycle after checkout.

How it works

Browsing and cart are synchronous: the storefront hits /products and /cart, and each service reads/writes only its own table (prices are snapshotted onto cart items at add-to-cart time).

Checkout is a three-step handshake designed so a customer is never charged without an order existing:

POST /payments/intent — the payments service creates a Stripe PaymentIntent for the cart total and returns the client secret.

The storefront confirms the card with Stripe Elements (card data never touches our backend).

POST /orders — the orders service re-validates the cart, reserves stock with conditional writes on the inventory table, persists the order as pending, and publishes OrderPlaced to SQS.

The order processor consumes the queue asynchronously: it confirms the payment settled (Stripe webhooks land on /webhooks/stripe and update the payments table), decrements reserved stock, flips the order to confirmed, and sends the SES confirmation email. Failures release the reservation — see the workflow view for the exact branches and the event flow for who produces and consumes each event.

How to extend

Good first forks, roughly in order of effort:

Fulfilment/shipping service — add a consumer on the order-notifications topic that books shipments and emits order.shipped.

Search — stream the products table into OpenSearch and add GET /search.

Promotions — a discount engine the orders service consults during validation; add a promotions table.

Caching — put ElastiCache (or CloudFront) in front of catalog reads; it is by far the hottest path.

Hardening — add a DLQ redrive runbook, idempotency keys on POST /orders, and Stripe webhook replay protection.

When you add a service, keep the pattern: one Lambda per domain, one table set per service, cross-domain writes only via events — never let two services share a table.