Checkout v2 — design doc

This whole page is one Markdown file. The prose is CommonMark, and every diagram in it is a plain ```mermaid code block. The comark-pele plugin turns those blocks into pele nodes while Comark parses the file, and Pele draws each one as SVG. The SVG is in the HTML the server sends, so the diagrams show up before any JavaScript runs.

No MDX and no build step: the file is read and parsed on each request, so the same code would serve Markdown from a database or a model.

The request path

A checkout starts at the edge and goes to two services. Only the payment call is on the critical path. Inventory is reserved at the same time and released if the payment fails.

Authorizing a card

The API holds the reservation until the card network answers, then confirms or releases it. A timeout counts as a decline, so a slow network never leaves stock reserved.

The order lifecycle

An order is a small state machine. Every change is an event on the order stream, so the warehouse and the receipts service never call the API.

Data model

Where it runs

What we expect

v1 spends most of its time waiting on the inventory lock. Moving the reservation off the critical path should take p95 under the 400 ms budget.

Bars are v1 in production last week, the line is v2 under replayed traffic. Card payments are most of the volume, so they are what the canary watches.

Risks

Rollout

v2 ships behind a flag, one region at a time, with v1 kept warm until the last region has run clean for a week.

Each stage merges to main behind its own flag, so a rollback is a flag flip, not a revert.

Every diagram type Pele supports is on the catalog page.

1---2title: Checkout v23summary: A design doc where every diagram is a mermaid code block, drawn by Pele.4---5 6# Checkout v2 — design doc7 8This whole page is one Markdown file. The prose is CommonMark, and every9diagram in it is a plain ` ```mermaid ` code block. The10[comark-pele](https://github.com/farnabaz/comark-pele) plugin turns those11blocks into `pele` nodes while [Comark](https://comark.dev) parses the file,12and [Pele](https://pele.run) draws each one as SVG. The SVG is in the HTML the13server sends, so the diagrams show up before any JavaScript runs.14 15No MDX and no build step: the file is read and parsed on each request, so the16same code would serve Markdown from a database or a model.17 18## The request path19 20A checkout starts at the edge and goes to two services. Only the payment call21is on the critical path. Inventory is reserved at the same time and released22if the payment fails.23 24```mermaid25flowchart LR26  client([Browser]) --> edge[Edge cache]27  edge --> api{Checkout API}28  api -->|reserve| inv[(Inventory)]29  api -->|authorize| pay[Payments]30  pay --> psp[[Card network]]31  api -->|on success| queue>Order events]32  queue --> mail[Receipts]33  queue --> wh[Warehouse]34```35 36### Authorizing a card37 38The API holds the reservation until the card network answers, then confirms39or releases it. A timeout counts as a decline, so a slow network never leaves40stock reserved.41 42```mermaid43sequenceDiagram44  autonumber45  participant B as Browser46  participant A as Checkout API47  participant I as Inventory48  participant P as Payments49  B->>A: POST /checkout50  par51    A->>I: reserve(items)52  and53    A->>P: authorize(card, total)54  end55  alt approved56    P-->>A: approved57    A->>I: confirm()58    A-->>B: 201 order59  else declined or timeout60    P-->>A: declined61    A->>I: release()62    A-->>B: 402 try another card63  end64```65 66## The order lifecycle67 68An order is a small state machine. Every change is an event on the order69stream, so the warehouse and the receipts service never call the API.70 71```mermaid72stateDiagram-v273  [*] --> Pending74  Pending --> Paid: payment approved75  Pending --> Cancelled: payment declined76  Paid --> Packed77  Packed --> Shipped78  Shipped --> Delivered79  Delivered --> [*]80  Paid --> Refunded: customer cancels81  Refunded --> [*]82  Cancelled --> [*]83```84 85### Data model86 87```mermaid88erDiagram89  CUSTOMER ||--o{ ORDER : places90  ORDER ||--|{ LINE_ITEM : contains91  PRODUCT ||--o{ LINE_ITEM : "appears in"92  ORDER ||--o| PAYMENT : "paid by"93  CUSTOMER {94    string id PK95    string email96  }97  ORDER {98    string id PK99    string customer_id FK100    string status101    int total_cents102  }103  LINE_ITEM {104    string order_id FK105    string product_id FK106    int quantity107  }108  PAYMENT {109    string id PK110    string order_id FK111    string provider112  }113```114 115## Where it runs116 117```mermaid118architecture-beta119  group edge(cloud)[Edge]120  group core(server)[Core region]121 122  service cdn(internet)[CDN] in edge123  service api(server)[Checkout API] in core124  service db(database)[Postgres] in core125  service queue(disk)[Event log] in core126 127  cdn:R --> L:api128  api:R --> L:db129  api:B --> T:queue130```131 132## What we expect133 134v1 spends most of its time waiting on the inventory lock. Moving the135reservation off the critical path should take p95 under the 400 ms budget.136 137```mermaid138xychart-beta139  title "p95 checkout latency (ms)"140  x-axis [Mon, Tue, Wed, Thu, Fri, Sat, Sun]141  y-axis "ms" 0 --> 900142  bar [720, 690, 810, 760, 840, 610, 580]143  line [380, 360, 410, 390, 420, 330, 310]144```145 146Bars are v1 in production last week, the line is v2 under replayed traffic.147Card payments are most of the volume, so they are what the canary watches.148 149```mermaid150pie showData151  title Payment methods, last 30 days152  "Card" : 61153  "Wallet" : 27154  "Bank transfer" : 9155  "Gift card" : 3156```157 158### Risks159 160```mermaid161quadrantChart162  title Risks by likelihood and impact163  x-axis Unlikely --> Likely164  y-axis Minor --> Severe165  quadrant-1 Mitigate first166  quadrant-2 Plan for it167  quadrant-3 Accept168  quadrant-4 Watch169  Double charge: [0.2, 0.92]170  Stock oversold: [0.55, 0.7]171  Slow card network: [0.8, 0.45]172  Receipt delays: [0.7, 0.15]173  Currency rounding: [0.3, 0.3]174```175 176## Rollout177 178v2 ships behind a flag, one region at a time, with v1 kept warm until the179last region has run clean for a week.180 181```mermaid182gantt183  title Checkout v2 rollout184  dateFormat YYYY-MM-DD185  axisFormat %b %d186  section Build187    Async reservations    :done, b1, 2026-09-01, 14d188    Event stream          :done, b2, after b1, 10d189  section Rollout190    Canary 1%             :active, r1, 2026-09-28, 7d191    EU                    :r2, after r1, 7d192    US                    :r3, after r2, 7d193    APAC                  :crit, r4, after r3, 7d194  section Cleanup195    Remove v1             :c1, after r4, 5d196```197 198Each stage merges to `main` behind its own flag, so a rollback is a flag199flip, not a revert.200 201```mermaid202gitGraph203  commit id: "v1.9"204  branch checkout-v2205  commit id: "async reserve"206  commit id: "event stream"207  checkout main208  commit id: "hotfix"209  checkout checkout-v2210  merge main211  commit id: "flag: canary"212  checkout main213  merge checkout-v2 tag: "v2.0"214```215 216---217 218Every diagram type Pele supports is on the [catalog](/catalog) page.