storefront knowledge base

How the storefront works and why it is built this way. Start with the concept notes, then read the decisions for the reasoning behind them. The architecture tab has the map of Workers and storage these notes refer to.

Concepts

• [[catalog]]: products, prices and stock, and how the merchant edits them.
• [[carts]]: what a cart holds and the limits it enforces.
• [[product-images]]: how images get into R2 and back out.
• [[checkout]]: how a cart becomes an order, and how stock and payment are handled.
• [[payment-webhook]]: how Stripe's events mark orders paid or cancelled.
• [[order-events]]: the queue that announces paid and cancelled orders.
• [[fulfilment]]: how paid orders become shipments at the warehouse.

Decisions

• [[0001-d1-for-shop-data]]: one D1 database for everything the shop sells.
• [[0002-serve-images-through-the-api]]: images were served by storefront-api (superseded).
• [[0003-money-in-whole-cents]]: prices and totals are integers.
• [[0004-take-stock-at-checkout]]: carts check stock, checkout takes it.
• [[0005-stripe-payment-intents]]: payments are Stripe PaymentIntents.
• [[0006-one-writer-for-the-database]]: other Workers change orders through OrdersService.
• [[0007-at-least-once-with-idempotency-keys]]: repeats are expected and harmless.
• [[0008-images-from-the-bucket-domain]]: browsers load images from R2's custom domain.
• [[0009-cancel-unpaid-orders-after-30-minutes]]: unpaid orders give their stock back.

Guides

• [[local-dev]]: running the three Workers on your machine.
• [[testing]]: how the tests run the real SQL without workerd.