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.
- The 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 One D1 database for the shop's data: one D1 database for everything the shop sells.
- 0002 Serve images through storefront-api: images were served by storefront-api (superseded).
- 0003 Money is whole cents: prices and totals are integers.
- 0004 Take stock at checkout, not when items go in the cart: carts check stock, checkout takes it.
- 0005 Charge with Stripe PaymentIntents from storefront-api: payments are Stripe PaymentIntents.
- 0006 storefront-api is the only Worker that writes to D1: other Workers change orders through OrdersService.
- 0007 At-least-once delivery, made safe with the order id: repeats are expected and harmless.
- 0008 Serve images from the bucket's custom domain: browsers load images from R2's custom domain.
- 0009 Cancel unpaid orders after 30 minutes: unpaid orders give their stock back.
Guides
- Running the shop locally: running the three Workers on your machine.
- Running and writing tests: how the tests run the real SQL without workerd.