id: 0006-one-writer-for-the-database
type: decision
owner: justin
status: accepted
reviewed: 2026-10-05

0006 storefront-api is the only Worker that writes to D1

Context

Payment results arrive at a separate Worker ([[payment-webhook]]) so its URL, secret and retries stay apart from the public API. That Worker has to change orders. It could bind the database and run its own SQL, or ask storefront-api to do it.

Decision

Only storefront-api has the DB binding. Other Workers change orders through its OrdersService entrypoint over a service binding (ORDERS), with calls that name the change: markPaid, cancel. The SQL for an order's states lives in one file, src/orders.ts.

Consequences

• The rules for moving an order between states, and for giving stock back, are written once and tested once.
• A schema change only has to be deployed with one Worker.
• Service binding calls stay inside Cloudflare and add no network hop worth measuring, but they couple deploys: OrdersService methods are an interface, so add new ones before callers use them and remove old ones only after.