All pages

How it works

Six pages, meant to be read in order. Each one states the mechanism first, then how it behaves in the cases that bite, then what it costs you.

They stop at how the thing works. Why it was chosen over the alternatives is in docs/adr/, and every page links the decisions it depends on by path.

Three ideas recur across all six, so they are worth having in advance.

A webhook is a trigger, not data. Every handler takes an id off the event and re-fetches the object, so replays and out-of-order delivery converge without bookkeeping.

Entitlement is derived from the price actually paid. There is no plan column and no field that says what somebody bought.

The api is what enforces an entitlement, so a client-side check is a loading state rather than a security boundary. The web app only decides whether the caller is signed in. Request policy lives in src/start.ts, and each private route calls the server-side requireAuth guard before loading.

  1. 01ArchitectureHow the packages separate the web interface from billing, database access and external integrations.
  2. 02IdentityClerk answers who the caller is, and the api resolves that answer to a database row on first use.
  3. 03The billing modelHow a one-time purchase and any number of concurrent subscriptions coexist as independent Stripe objects.
  4. 04EntitlementsEntitlement is derived from the price the customer actually paid, read through a SQL view, and returned only by the api.
  5. 05WebhooksStripe webhooks are triggers that make the api re-fetch the object, never payloads it writes to the database.
  6. 06FulfillmentWhat happens after a payment succeeds, with the GitHub collaborator invite as the reference implementation.

Updated