Every must-never-happen is a database constraint

What could go wrong, and how we would know

Billing has a short list of failures that are worse than downtime. A customer's SDK retries a batch and the same usage is billed twice. Two schedulers fire at month end and a customer gets two invoices. An ops engineer double-clicks "issue credit". Someone who knows the webhook URL replays a recorded delivery and flips an invoice to paid. The hourly cache drifts from the raw events and nobody notices until the customer does. A new endpoint forgets to filter by tenant.

None of these fail loudly on their own. A double-billed row looks exactly like a legitimate one. So the design question was not "how do I avoid these" but "what raises if they happen anyway". DESIGN.md states the rule in three words: "Constraints over comments."

What I built

Ingest. POST /v1/events takes up to 1,000 events per call. The whole batch goes into one SQL statement: jsonb_to_recordset unpacks the payload, INSERT ... ON CONFLICT (request_id) DO NOTHING RETURNING request_id writes what is new, and the accepted count is the number of returned rows. The docstring puts it plainly: "The database, not the application, is the dedupe authority."

Aggregation. usage_event is the source of truth and is never edited. usage_window is a cache of units per customer per hour; the aggregator is its only writer, locks the concrete row with SELECT FOR UPDATE, and recomputes from raw events, so running it twice gives the same answer. Late events carry received_at, and any window whose last_aggregated_at is older than a contained event's received_at is picked up on the next pass. Before month-end issuance the scheduler drains aggregation; if it cannot drain in 10,000 passes it logs at CRITICAL and skips issuance rather than underbill.

Money. Amounts are integer cents. Per-unit rates are micro-dollars, because the volume rate is $0.0005 per unit and that is not a whole number of cents; a rate is a multiplier, not money. Rounding happens exactly once, half-up, where units times rate becomes a line item. The invoice total is then plain integer addition. The worked example in money.py and DESIGN.md: 250,000 units on the standard plan is 10,000 free, then 90,000 at 1,000 µUSD (9,000 cents), then 150,000 at 500 µUSD (7,500 cents), for 16,500 cents, or $165.00 exactly. A test asserts that number, and the invoicing service raises RuntimeError if the sum of its line items ever disagrees with the standalone helper.

Webhooks. The payment endpoint verifies HMAC-SHA256 over timestamp.body with hmac.compare_digest, rejects timestamps more than 300 seconds off, and does both before the JSON parser runs. A valid delivery is inserted into webhook_event and the invoice flipped to paid in one transaction; a replayed delivery_id hits the UNIQUE index, the transaction rolls back, and the response is 200 with {replayed: true}. A forged signature or a stale timestamp gets a 400 and the invoice stays issued.

Ops. Credits and overrides go through the ops console with HTTP Basic against Django staff users, a separate auth stack from API keys. Overrides never mutate a line item; they insert a new one with supersedes pointing at the old, and If-Match rejects stale views with 412. Every money-moving action writes an audit_log row in the same transaction, and a plpgsql trigger installed by post_migrate makes that table append-only, Django admin included.

Try it

Three panels that run entirely in the browser: the ingest replay from ingest.py, the tier ladder from money.py, and the webhook check from webhooks/services.py.

Verification

The backend has 145 test functions across 24 files, and they run against a real PostgreSQL 16 rather than SQLite, because the trigger is plpgsql and the ON CONFLICT path is Postgres-specific. The concurrency tests use OS threads with fresh connections: 10 threads replaying the same request_id, 5 racing to issue the same invoice, 8 double-clicking the same credit, 2 replaying the same override key. Each asserts exactly one row.

Tier math is tested at the boundaries 9,999 / 10,000 / 10,001 / 100,000 / 100,001, plus half-up rounding, negatives, and sub-cent rates that round to zero. Audit-log immutability is tested against the trigger. The late-event test ingests 50,000 units, issues the invoice, ingests 25,000 more into the same period, and checks that the window now reads 75,000 while the issued invoice's total and line-item ids are unchanged. Front-end tests are vitest on helpers (money formatting, override filtering, pagination URLs), and both builds run tsc --noEmit before Vite.

• 145test functions on live Postgres
• 24test files
• 10 / 5 / 8 / 2threads in the four race tests

What I found

Outcome, and what it does not prove

What it proves: under the races the tests can construct, every money-moving invariant holds, and it holds because of the schema rather than because of code discipline.

What it does not prove: throughput. DESIGN.md has a scaling section (partition usage_event by month at 10x, put a queue in front of ingest at 100x) but there is no load test behind it, so those are plans, not measurements. It also does not prove the system runs anywhere but docker compose on a laptop; there is no deployment and no CI, so the 145 tests pass when I run them, not on every push.

What I would do differently

Build the post-issuance reconciliation before anything else. The schema already supports a prior_period_adjustment line and the pre-issuance half is tested, so the missing piece is a policy decision plus one job. Add the GitHub Actions workflow, because a guardrail test that only runs when I remember to run it guards nothing. Split each App.tsx; roughly 1,500 lines in one file was fine for shipping and is wrong for maintaining. Replace HTTP Basic with session auth on the ops console. And write the load test, so the scaling section is backed by a number.