# Architecture One-Pager

*Usage Metering & Billing Pipeline · Solution Architecture v1.0 · Amazon Web Services · Billing Platform Architecture · 2026-10*

**The event ledger is the system of record; every priced figure is a recomputable projection of it, so a correction is a replay and never an edit.**

A customer calls 41.2 million times, streams 2.3 TB and holds 1,204 seat-days, and at the end of the month we send them one number. That number has to be right, has to be explainable line by line, and has to stay explainable months later when their auditor asks or their own logs disagree with ours. An analytics pipeline that loses a thousandth of its events is healthy; a billing pipeline that loses a thousandth has quietly given away revenue, and one that double-counts a thousandth has overcharged customers and will be found out. Meanwhile pricing changes faster than engineering releases, the free tier has to be enforced without putting a billing dependency in the product's request path, and the first time a figure is wrong there must be a remedy that is not correction SQL against production.

Accept usage events over one contract from product services, edge nodes and partner feeds, deduplicate on a producer-assigned identifier, and acknowledge only after the event is durably replicated into an append-only event ledger — so a 202 is a billing guarantee rather than a receipt. Aggregate from that ledger on event time, with an explicit watermark and a stated lateness bound, into per-account per-meter quantities that stay marked provisional until the period closes. Price the closed quantities against the plan version that was in force when the usage happened, apply credits and commitments in a documented order, assemble a draft invoice, pass it through an anomaly gate and a human, and issue it as an immutable record handed downstream through a replayable outbox. Everything downstream of the ledger — aggregates, priced lines, invoices — is a projection that can be deleted and rebuilt, which makes every class of error have the same remedy: a scoped, authorised replay that produces a second figure and retains the first.

## What it is, and what it is not

- **An append-only event ledger as the system of record** — not Running counters as truth, with raw events kept briefly for debugging
- **Event-time attribution with a stated lateness bound** — not Arrival-time counting, which moves revenue between months whenever a producer was offline
- **An acknowledgement that follows durable replication** — not A fast 202 that means the request was received
- **Corrections as scoped replays retaining both figures** — not Correction SQL against the invoice, or a quiet edit before anyone notices
- **Pricing as versioned, immutable, two-person-gated configuration** — not Prices in code, or a price row anyone in revenue operations can update
- **An invoice line that expands to its constituent events** — not A total the customer is asked to trust

## The decisions that are the architecture

1. **The ledger is the record; every priced figure is a projection** (ADR-01) — Aggregates, priced lines and invoices exist for performance and presentation. All of them can be deleted and rebuilt from retained events without changing a number, provided the rating configuration that applied at the time is still available — which is why plan versions are immutable and currency rates are dated. A bad transform, a wrong tier, a corrupt partition and an operator error therefore share one remedy instead of needing four.
2. **Corrections are replays; an issued invoice is superseded, never rewritten** (ADR-02) — Nothing issued is mutated. A difference found after issue becomes a credit memo or a superseding invoice, both figures survive with the reason and the authorising identity, and the history of a disputed invoice is itself auditable. This is what makes the first wrong figure an incident with a procedure rather than an incident with a lawyer.
3. **Acknowledge only after durable replication** (ADR-05) — Ingestion fails closed and serving fails open: where durability cannot be guaranteed the event is rejected so the producer keeps it, and the product keeps serving regardless of the metering path's health. If an accepted event can be lost, the ledger is not the system of record and nothing in this design can be proved.
4. **Pricing is immutable configuration behind a blast-radius gate** (ADR-08) — A new price is a new plan version with an effective-from date, never a mutation of a version already applied to issued invoices. Activation requires a preview of the accounts affected and the aggregate change in charged amount, plus two human approvals — because it is the one change in the platform applied uniformly to every affected account at once.
5. **Caps are enforced synchronously and fail open, marked** (ADR-11) — The product consults a sub-10 ms entitlement decision where a hard cap is required, and nothing else. When that decision is unavailable the call fails open and records that it did, so the overshoot is known rather than invisible. The alternative trades unbillable usage for refusing a paying customer during a billing outage.
6. **Partition by account; sub-partition the one that outgrows it** (ADR-12) — Keeping an account's events together makes per-account replay and dispute resolution a bounded scan rather than a full-period one, which is the operation the whole evidence story depends on. It also guarantees the largest customer eventually exceeds one partition, so sub-partitioning on the hot key is designed in rather than discovered.

## Why this should still be right in ten years

Managed stream processors, event buses, relational engines and object stores will all be replaced inside a decade, and the billing SaaS market will have consolidated twice. The parts of this design that should outlive them are the ones that are claims about authority, evidence and blast radius rather than claims about products.

- **The seam is not a technology.** "The ledger is the record and every priced figure is a projection" is a statement about which store is allowed to be wrong. It survives replacing Kinesis with Kafka, Flink with something newer, Aurora with anything transactional and S3 with any durable object store, because none of those changes where authority lives.
- **Provable arithmetic outlives every pricing model.** Packaging fashions turn over every few years — seats, then consumption, then outcomes, then tokens. The requirement that every number be reproducible from retained evidence is indifferent to all of them, and it is the requirement that makes a new pricing model a configuration exercise rather than a migration.
- **Event time is a property of the world.** Attributing usage to the period in which it occurred rather than the period in which it arrived is not an implementation detail that a better pipeline would remove. Producers will keep being offline, clocks will keep disagreeing, and a lateness bound will keep being the honest way to say when a period is final.
- **The three dangerous actions do not change.** Changing a price, restating a figure and issuing a credit are the three ways to lose a lot of money quickly. Separating them across identities, requiring a second human, and writing the audit record before the action runs will still be the right controls when none of the services named here exist.
- **What is deliberately left replaceable.** Rating and invoicing are the parts most likely to be bought rather than built later, so they are kept behind their own interface with the ledger upstream of them. A future decision to delegate rating to a billing platform costs a reconciliation obligation, not a rebuild — which is exactly the optionality ADR-14 is protecting.

## Non-functional targets

Every figure below is a stated assumption for this design, taken from the requirement document and intended to be argued with. The view column points at where each one is visible in the set.

| Quality | Target | How it is met | View |
|---|---|---|---|
| Billing accuracy | ≤ 1 in 10^6 accepted events lost or double-counted after reconciliation | Idempotency on the producer-assigned identifier, acknowledge-after-replication, idempotent aggregation, and a correctness signal row that compares invoice totals against the sum of their lines | 18 |
| Ingestion availability | ≥ 99.99% monthly successful acceptance | Zone-redundant stateless ingest behind a regional gateway, with a durable producer-side buffer so a rejection is recoverable rather than lost | 16 |
| Entitlement availability | ≥ 99.99% monthly | Cached decisions with a balance read only on miss; fails open and marks the overshoot when unavailable | 21 |
| Event acceptance latency | p99 ≤ 50 ms, p99.9 ≤ 200 ms in-region | Replication inside the accept path, kept affordable by batching 500 events per request from the producer SDK | 12 |
| Cap decision latency | p99 ≤ 10 ms in-region | In-region cache in front of the balance ledger; the figure that decides whether synchronous caps are viable at all | 21 |
| Usage freshness | p95 within 5 min of the event, p99 within 15 min | Continuous event-time aggregation into a read model, with freshness stamped on every figure served | 09 |
| Invoice run | All accounts closed within 6 h of period close; RTO 4 h | Idempotent run parallel across accounts, resumable and keyed on account plus period | 13 |
| Throughput | 250,000 events/s per region, 5× burst for 10 min | Partitioned ingestion and aggregation on account, with sub-partitioning available for a hot account | 07 |
| Volume and scale | 1.5 M accounts, 400 meters, 2,000 plan versions, ~20 TB/month compressed | Columnar event ledger with lifecycle tiering; meters and pricing shapes held as configuration rather than code | 10 |
| Retention | Events queryable 400 days, cold 7 years; dispute window 60 days | Hot Iceberg tables sized for an annual cycle plus the dispute window, then write-once cold storage for statutory audit | 10 |
| Recovery point | RPO 0 for acknowledged events | Acknowledgement follows durable replication, so there is no window of accepted-but-lost usage; a cross-region replica survives the loss of the region | 16 |
| Restatement | One account's 90 days replayed through metering and rating within 30 min | Bounded scan over the account's own ledger partition, through the same code path as the original | 15 |
| Pipeline cost | < 0.5% of metered revenue, reported monthly | Incremental aggregation, compressed columnar storage, cold tiering, and cost reported per meter so an unprofitable dimension can be found | 18 |

## Scope

**In scope**

- One documented inbound event contract for product services, edge nodes, batch jobs and partner feeds, with workload-identity authentication scoped to specific meters
- An append-only event ledger as the system of record, queryable for the dispute window and write-once beyond it
- Event-time aggregation with watermarks and a stated lateness bound, for counter, gauge, high-water-mark, unique-entity and dimensioned meters
- Versioned immutable plan configuration with volume and graduated tiers, commitments, discounts and dated currency rates
- Rating at period close, credit and commitment drawdown in a documented order, and an idempotent resumable invoice run with a draft state and an anomaly gate
- A low-latency entitlement decision for hard caps, and threshold events on allowances, caps and commitments
- Customer-facing usage and invoice surfaces at the same grain over API and console, with freshness labelled and event-level evidence on request
- Scoped, authorised restatement retaining both figures, and an immutable audit record of every privileged action

**Explicitly out of scope**

- Payment capture, dunning and collections — a downstream consumer of an issued invoice, with its own owner
- Tax determination and revenue recognition — the platform supplies line detail and posts, and determines neither
- Pricing strategy and packaging design — the platform makes a new shape cheap to express, and takes no view on whether it is a good idea
- The product's own instrumentation decisions: which meters exist is a product question, and a dimension never emitted cannot be backfilled
- Customer entitlement modelling beyond balances, caps and commitments — contract management lives elsewhere

## What a four-week prototype should prove

The prototype's job is to falsify the two claims the whole design rests on: that an acknowledgement can be a durability guarantee inside a 50 ms budget, and that a restatement can be a routine replay rather than an incident. Everything else is engineering.

1. One meter of each of the five types, 50,000 events/s sustained for an hour, from a producer SDK with a durable buffer
2. A ledger partition for one synthetic account large enough to exceed a single partition's capacity, so sub-partitioning is exercised rather than designed
3. Two plan versions with an effective-from date inside the period, to prove a mid-period change splits rather than reprices
4. A full close-to-issue run over 10,000 accounts, interrupted halfway and resumed
5. A scoped replay of one account's 90 days, compared byte-for-byte against the original figure

- The ingest task is killed between the ledger write and the acknowledgement: the producer retries, the duplicate is suppressed on event id, and the account's total is unchanged
- An event arrives 70 hours late and lands in the correct closed-pending period; one arriving at 74 hours is refused into the period and surfaced as needing restatement
- The aggregate store is deleted entirely and rebuilt by replay: every closed period reproduces its exact prior quantity
- A price is published with a wrong tier boundary, caught by the blast-radius preview before activation, and then — deliberately activated anyway — corrected by a further version plus a restatement of the accounts already rated
- The entitlement cache is made unavailable: the product keeps serving, the overshoot is recorded, and the recorded overshoot reconciles against the events actually metered

## Open risks, carried rather than hidden

| Risk | If it lands | Response |
|---|---|---|
| The deduplication index is the cost surprise: every event identifier held for 7 days at 250,000 events/s | A line item that can rival the cost of the ledger itself, discovered after the architecture has committed to producer-assigned identifiers | Size it explicitly in the prototype, keep the window at the shortest value the longest producer retry actually needs, and treat a shorter window plus a content fingerprint as the documented fallback rather than a redesign |
| Replay determinism is assumed, not proven | A non-deterministic aggregate — an unordered distinct count, a floating-point sum — would make every restatement arguable and quietly destroy the evidence story | Make replay determinism a watched signal with a daily scheduled replay of a known account, and keep unique-entity counting exact rather than approximate until a cost argument forces otherwise |
| The anomaly gate trains its reviewers to approve | A fast-growing account trips the baseline every month, reviewers learn to click through, and the one real error arrives looking like all the false ones | Baseline against the account's own trajectory rather than a flat threshold, re-arm on deliberate price changes, and report gate precision as a signal so a useless gate is visible |
| A single monthly run concentrates all the risk into one window | A defect found during close has hours rather than days, and the remedy competes with the run itself for the same people | Per-account cycle anchors spread the load across the month from the start; staggering is in the MVP precisely because retrofitting it means restating the accounts that moved |
| Fail-open entitlement during a long outage produces usage nobody is entitled to | Unbillable consumption that is recorded but not recoverable, concentrated in exactly the accounts with the least headroom | Bound it with a secondary local limit in the producer SDK — not in the MVP, and the first thing to add if the recorded overshoot ever exceeds the accuracy target |
| An open dimension map is an open cardinality risk | A producer that puts a request identifier in the dimension map makes the aggregate grain per-event, multiplying metering cost without changing revenue | Report storage and compute cost per meter, alert on dimension cardinality growth, and make meter registration the place where a new dimension key is reviewed rather than discovered |

The reasoning behind every component and technology choice is in the [Architecture Decision Record](decision-record): 15 records across 6 areas, each with the alternatives that lost and what the choice costs.