[ { "id": "01-system-context", "title": "Usage Metering & Billing Pipeline — System Context", "layout": "context", "system": { "label": "Usage Metering & Billing Pipeline", "sub": "Event to invoice" }, "colWidth": 260, "groups": [ { "side": "top", "title": "Usage producers", "nodes": [ { "id": "svc", "label": "Product services", "sub": "250k events/s", "kind": "app", "rel": "events", "dir": "in", "kind2": "async" }, { "id": "edge", "label": "Edge & CDN nodes", "sub": "egress, requests", "kind": "app", "rel": "egress", "dir": "in", "kind2": "async" } ] }, { "side": "left", "title": "People", "nodes": [ { "id": "pricing", "label": "Pricing manager", "kind": "actor", "rel": "plans", "dir": "in" }, { "id": "controller", "label": "Finance controller", "kind": "actor", "rel": "issue / hold", "dir": "in" }, { "id": "custadmin", "label": "Customer admin", "sub": "1.5 M accounts", "kind": "actor", "rel": "usage", "dir": "in" } ] }, { "side": "right", "title": "Downstream systems", "nodes": [ { "id": "pay", "label": "Payment platform", "kind": "external", "rel": "invoice issued", "kind2": "async" }, { "id": "tax", "label": "Tax engine", "kind": "external", "rel": "line detail" }, { "id": "erp", "label": "ERP & revenue recognition", "kind": "external", "rel": "nightly post", "kind2": "batch" }, { "id": "whouse", "label": "Data warehouse", "kind": "external", "rel": "usage extract", "kind2": "batch" } ] }, { "side": "bottom", "title": "Feeds and platform services", "nodes": [ { "id": "iam", "label": "IAM & KMS", "sub": "workload identity", "kind": "security", "rel": "identity", "dir": "in" }, { "id": "trail", "label": "Audit log", "sub": "CloudTrail, locked", "kind": "security", "rel": "audit trail", "kind2": "async" }, { "id": "partner", "label": "Partner & batch feeds", "sub": "signed files", "kind": "external", "rel": "backfill", "dir": "in", "kind2": "batch" } ] } ], "note": "Out of scope: payment capture, dunning, tax determination and revenue recognition — all downstream consumers of an issued invoice. Internal operators appear in view 03.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "02-high-level-architecture", "title": "High-Level Architecture — Produce to Invoice", "layout": "flow", "chain": true, "canvas": { "width": 1760 }, "stages": [ { "title": "Produce", "nodes": [ { "id": "p-svc", "label": "Product services", "sub": "durable buffer", "kind": "app" }, { "id": "p-edge", "label": "Edge nodes", "kind": "app" }, { "id": "p-feed", "label": "Partner feeds", "kind": "external" } ] }, { "title": "Ingest", "nodes": [ { "id": "i-api", "label": "Ingest API", "sub": "API Gateway", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "i-dedup", "label": "Dedup index", "sub": "7-day TTL", "kind": "store" }, { "id": "i-quar", "label": "Quarantine", "sub": "with reason", "kind": "store", "icon": "fa5_ban" } ] }, { "title": "Record", "nodes": [ { "id": "r-stream", "label": "Event stream", "sub": "Kinesis", "kind": "queue" }, { "id": "r-ledger", "label": "Event ledger", "sub": "S3 Iceberg", "kind": "store" }, { "id": "r-cold", "label": "Audit tail", "sub": "Glacier, locked", "kind": "store" } ] }, { "title": "Meter", "nodes": [ { "id": "m-agg", "label": "Aggregation", "sub": "Managed Flink", "kind": "app", "icon": "mat_layers" }, { "id": "m-store", "label": "Aggregate store", "sub": "DynamoDB", "kind": "store" } ] }, { "title": "Rate", "nodes": [ { "id": "x-rate", "label": "Rating service", "kind": "app" }, { "id": "x-plan", "label": "Plan registry", "sub": "versioned", "kind": "store" }, { "id": "x-ent", "label": "Entitlement service", "sub": "p99 10 ms", "kind": "app" } ] }, { "title": "Invoice", "nodes": [ { "id": "v-run", "label": "Invoice run", "sub": "Step Functions", "kind": "app" }, { "id": "v-gate", "label": "Anomaly gate", "kind": "decision" }, { "id": "v-ledger", "label": "Invoice ledger", "sub": "Aurora", "kind": "store", "icon": "aws_amazon-aurora" } ] }, { "title": "Consume", "nodes": [ { "id": "c-api", "label": "Usage & invoice API", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "c-pay", "label": "Payment, tax, ERP", "kind": "external" }, { "id": "c-ev", "label": "Evidence query", "sub": "Athena", "kind": "app" } ] } ], "edges": [ { "from": "i-api", "to": "i-dedup", "label": "event id", "kind": "sync" }, { "from": "i-api", "to": "i-quar", "label": "rejected", "kind": "error" }, { "from": "r-ledger", "to": "r-cold", "label": "lifecycle", "kind": "batch" }, { "from": "r-ledger", "to": "c-ev", "label": "replay, evidence", "kind": "batch", "route": "gutter" }, { "from": "x-ent", "to": "p-svc", "label": "cap decision", "kind": "sync", "route": "gutter" }, { "from": "v-ledger", "to": "c-pay", "label": "outbox", "kind": "async" } ], "note": "The spine is the billing path. The serving path touches it only at the cap decision.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "03-actors-and-journeys", "title": "Actors and Their Core Journeys", "layout": "actors", "cardWidth": 300, "canvas": { "width": 1760 }, "groups": [ { "title": "Customers", "kind": "boundary", "actors": [ { "id": "a-custadmin", "label": "Customer platform admin", "sub": "1.5 M accounts", "goal": "Tell me today what this month will cost, and let me check your invoice against my own logs.", "journeys": [ { "id": "j-predict", "label": "Predict this month's bill" }, { "label": "Reconcile an issued invoice" }, { "label": "Set a spend cap" } ] }, { "id": "a-custfin", "label": "Customer finance owner", "sub": "procurement, audit", "goal": "Give me a line I can put in front of an auditor without opening a support ticket.", "journeys": [ { "label": "Export invoice evidence" }, { "label": "Dispute a line" } ] } ] }, { "title": "The business", "kind": "boundary", "actors": [ { "id": "a-pricing", "label": "Pricing manager", "sub": "2,000 plan versions", "goal": "Launch a meter and a tier without waiting for an engineering release.", "journeys": [ { "label": "Publish a plan version" }, { "label": "Preview a price change" } ] }, { "id": "a-controller", "label": "Finance controller", "sub": "monthly close", "goal": "Close the period on time, and never issue a number I cannot defend.", "journeys": [ { "label": "Review the draft run" }, { "label": "Issue or hold an invoice" }, { "label": "Authorise a credit memo" } ] } ] }, { "title": "Engineering and operations", "kind": "boundary", "actors": [ { "id": "a-engineer", "label": "Billing engineer", "sub": "on call through close", "goal": "When a figure is wrong, let me replay the evidence instead of writing correction SQL.", "journeys": [ { "id": "j-restate", "label": "Restate a wrong invoice" }, { "label": "Investigate a metering gap" } ] }, { "id": "a-prodeng", "label": "Product engineer", "sub": "ships new meters", "goal": "Instrument a meter and see within minutes whether my events are actually being billed.", "journeys": [ { "label": "Register a meter" }, { "label": "Verify acceptance" } ] } ] }, { "title": "Machines and third parties", "kind": "cloud", "actors": [ { "id": "a-producer", "label": "Product & edge services", "kind": "app", "sub": "250k events/s", "goal": "Hand off usage without ever waiting on the billing path.", "journeys": [ { "label": "Emit a usage event" } ] }, { "id": "a-down", "label": "Payment, tax and ERP", "kind": "external", "sub": "3 systems", "goal": "Receive an issued invoice once, and the identical one on replay.", "journeys": [ { "label": "Consume invoice.issued" } ] }, { "id": "a-auditor", "label": "External auditor", "kind": "external", "sub": "annual", "goal": "Verify a figure independently, from evidence I can check myself.", "journeys": [ { "label": "Sample an invoice line" } ] } ] } ], "note": "Goals are in each actor's own voice. Two journeys get their own map: predicting the bill, and putting a wrong one right.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "04-journey-predict-the-bill", "title": "Journey — Customer Admin Predicts the Bill", "layout": "journey", "actor": { "label": "Customer platform admin", "sub": "console and API", "goal": "Know before the month ends what this month will cost, and why", "trigger": "A cost spike noticed in their own dashboards, or a budget review", "success": "They can state the month's cost and name its drivers before the invoice arrives" }, "phases": [ { "title": "Notice", "sub": "outside the product" }, { "title": "Check usage" }, { "title": "Explain drivers" }, { "title": "Set a cap" }, { "title": "Receive invoice", "moment": true }, { "title": "Reconcile", "moment": true } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Spots a cost spike" } ], [ { "label": "Opens the usage view" } ], [ { "label": "Drills into a meter" } ], [ { "label": "Sets a spend alert" } ], [ { "label": "Reads the invoice" } ], [ { "label": "Checks own logs" } ] ] }, { "title": "Where it lands", "kind": "system", "cells": [ [ { "label": "Their own tooling", "kind": "external" } ], [ { "label": "Usage API", "icon": "aws_amazon-api-gateway" } ], [ { "label": "Aggregates + rating" } ], [ { "label": "Threshold service" } ], [ { "label": "Invoice ledger", "icon": "aws_amazon-aurora" } ], [ { "label": "Evidence export" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Uneasy", "Alarmed" ], "points": [ 0, 1, 1, 2, 1, 0 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Spike found elsewhere" } ], [ { "label": "Provisional read as final" } ], [ { "label": "Dimension not metered" } ], [], [ { "label": "Charge never seen accrue" } ], [ { "label": "Line hides its events" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Alerts they set" } ], [ { "label": "Freshness on every figure" } ], [ { "label": "Tier breakdown per line" } ], [ { "label": "Hard cap, if wanted" } ], [ { "label": "A provisional trail" } ], [ { "label": "Event-level evidence" } ] ] } ], "chain": true, "note": "The trough is reconciliation: a line a customer cannot expand to its events is the moment the invoice stops being defensible.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "05-journey-restate-a-wrong-invoice", "title": "Journey — Billing Engineer Puts a Wrong Invoice Right", "layout": "journey", "actor": { "label": "Billing engineer", "sub": "on call through close", "goal": "Make a wrong figure right without touching production data", "trigger": "The anomaly gate flags an account, or a customer disputes a line", "success": "A restated figure, both versions retained, and a customer who was told" }, "phases": [ { "title": "Alerted" }, { "title": "Diagnose" }, { "title": "Scope the replay" }, { "title": "Replay" }, { "title": "Choose remedy", "moment": true }, { "title": "Close out", "moment": true } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Takes the page" } ], [ { "label": "Reads the line's events" } ], [ { "label": "Names account and period" } ], [ { "label": "Runs a scoped replay" } ], [ { "label": "Memo or supersede" } ], [ { "label": "Tells the customer" } ] ] }, { "title": "Where it lands", "kind": "system", "cells": [ [ { "label": "Anomaly gate" } ], [ { "label": "Evidence query" } ], [ { "label": "Restatement API", "icon": "aws_amazon-api-gateway" } ], [ { "label": "Restatement run" } ], [ { "label": "Invoice ledger", "icon": "aws_amazon-aurora" } ], [ { "label": "Usage API + audit log" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "In control", "Uneasy", "Exposed" ], "points": [ 0, 1, 2, 2, 1, 2 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Found after issue" } ], [ { "label": "Evidence gone cold" } ], [ { "label": "Scope creeps wider" } ], [], [ { "label": "Policy unclear" } ], [ { "label": "Two figures to explain" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Gate fires pre-issue" } ], [ { "label": "400-day hot window" } ], [ { "label": "Unbounded scope refused" } ], [ { "label": "Replay never mutates" } ], [ { "label": "Remedy recorded" } ], [ { "label": "Both versions retained" } ] ] } ], "chain": true, "note": "The worst moment is the first, not the last: a wrong figure found after issue is a correction, and one found before it is a draft.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "06-layered-architecture", "title": "Layered Architecture", "layout": "bands", "layerHeaderWidth": 160, "canvas": { "width": 1700 }, "bands": [ { "name": "Experience", "nodes": [ { "id": "l-console", "label": "Customer usage console", "kind": "app" }, { "id": "l-usageapi", "label": "Usage & invoice API", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "l-close", "label": "Finance close console", "kind": "app" }, { "id": "l-pricingui", "label": "Pricing console", "kind": "app" } ] }, { "name": "Money", "nodes": [ { "id": "l-rate", "label": "Rating service", "kind": "app" }, { "id": "l-ent", "label": "Entitlement service", "kind": "app" }, { "id": "l-run", "label": "Invoice run", "kind": "app" }, { "id": "l-gate", "label": "Anomaly gate", "kind": "decision" }, { "id": "l-restate", "label": "Restatement orchestrator", "kind": "app" } ] }, { "name": "Metering", "nodes": [ { "id": "l-agg", "label": "Aggregation", "sub": "event-time windows", "kind": "app", "icon": "mat_layers" }, { "id": "l-close2", "label": "Period close & watermark", "kind": "app" }, { "id": "l-anom", "label": "Baseline detector", "kind": "app" } ] }, { "name": "Ingestion", "nodes": [ { "id": "l-ingest", "label": "Ingest API", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "l-valid", "label": "Validation & quarantine", "kind": "app" }, { "id": "l-dedup", "label": "Dedup index", "kind": "store" }, { "id": "l-sdk", "label": "Producer SDK & buffer", "kind": "app" } ] }, { "name": "Data", "nodes": [ { "id": "l-ledger", "label": "Event ledger", "sub": "system of record", "kind": "store" }, { "id": "l-aggstore", "label": "Aggregate store", "kind": "store" }, { "id": "l-invledger", "label": "Invoice ledger", "kind": "store", "icon": "aws_amazon-aurora" }, { "id": "l-plan", "label": "Plan registry", "kind": "store" }, { "id": "l-cold", "label": "Audit tail", "kind": "store" } ] }, { "name": "Platform", "nodes": [ { "id": "l-iam", "label": "Workload identity", "kind": "security" }, { "id": "l-kms", "label": "Keys & encryption", "kind": "security" }, { "id": "l-trail", "label": "Privileged-action log", "kind": "security" }, { "id": "l-obs", "label": "Observability", "kind": "platform" }, { "id": "l-orch", "label": "Orchestration", "kind": "platform", "icon": "aws_aws-step-functions" } ] } ], "edges": [ { "from": "l-ingest", "to": "l-ledger", "label": "append", "kind": "sync" }, { "from": "l-restate", "to": "l-ledger", "label": "replay", "kind": "batch" } ], "note": "Reads flow upward, writes downward, so most edges are implied by the layering. The two drawn are the ones it does not say: every accepted event lands in the ledger, and every correction comes back out of it.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "07-platform-components", "title": "Platform Components — Containers and Planes", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "AWS account — metering & billing platform", "kind": "cloud", "dir": "col", "children": [ { "title": "Ingestion plane", "kind": "boundary", "nodes": [ { "id": "n-api", "label": "Ingest API", "sub": "API Gateway", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "n-valid", "label": "Validator", "sub": "ECS Fargate", "kind": "app" }, { "id": "n-dedup", "label": "Dedup index", "sub": "DynamoDB, 7d TTL", "kind": "store" }, { "id": "n-quar", "label": "Quarantine", "sub": "S3 + reason", "kind": "store", "icon": "fa5_ban" } ] }, { "title": "Record plane", "kind": "boundary", "nodes": [ { "id": "n-stream", "label": "Event stream", "sub": "Kinesis Data Streams", "kind": "queue" }, { "id": "n-ledger", "label": "Event ledger", "sub": "S3 Iceberg", "kind": "store" }, { "id": "n-cold", "label": "Audit tail", "sub": "Glacier, Object Lock", "kind": "store" }, { "id": "n-cat", "label": "Schema catalogue", "sub": "Glue", "kind": "store" } ] }, { "title": "Metering plane", "kind": "boundary", "nodes": [ { "id": "n-agg", "label": "Aggregator", "sub": "Managed Flink", "kind": "app" }, { "id": "n-ckpt", "label": "Checkpoints", "sub": "S3", "kind": "store" }, { "id": "n-aggstore", "label": "Aggregate store", "sub": "DynamoDB", "kind": "store" } ] }, { "title": "Money plane", "kind": "boundary", "nodes": [ { "id": "n-rate", "label": "Rating service", "sub": "ECS Fargate", "kind": "app" }, { "id": "n-plan", "label": "Plan registry", "sub": "Aurora + S3 versions", "kind": "store" }, { "id": "n-ent", "label": "Entitlement service", "sub": "ECS + DAX", "kind": "app" }, { "id": "n-run", "label": "Invoice run", "sub": "Step Functions", "kind": "app" }, { "id": "n-inv", "label": "Invoice ledger", "sub": "Aurora PostgreSQL", "kind": "store", "icon": "aws_amazon-aurora" } ] }, { "title": "Surfaces and recovery", "kind": "boundary", "nodes": [ { "id": "n-usage", "label": "Usage & invoice API", "sub": "API Gateway", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "n-ev", "label": "Evidence query", "sub": "Athena", "kind": "app" }, { "id": "n-restate", "label": "Restatement run", "sub": "Step Functions", "kind": "app" }, { "id": "n-out", "label": "Outbox", "sub": "EventBridge", "kind": "queue" } ] } ] } ], "outside": [ { "id": "o-svc", "label": "Product services", "kind": "external" }, { "id": "o-pay", "label": "Payment platform", "kind": "external" }, { "id": "o-tax", "label": "Tax engine", "kind": "external" }, { "id": "o-erp", "label": "ERP & revrec", "kind": "external" }, { "id": "o-trail", "label": "Privileged-action log", "kind": "security" } ], "edges": [ { "from": "o-svc", "to": "n-api", "label": "events", "kind": "async" }, { "from": "n-stream", "to": "n-ledger", "label": "append" }, { "from": "n-agg", "to": "n-aggstore", "label": "aggregates" }, { "from": "n-out", "to": "o-pay", "label": "invoice.issued", "kind": "async" }, { "from": "n-restate", "to": "n-ledger", "label": "replay", "kind": "batch" }, { "from": "n-ent", "to": "o-svc", "label": "cap decision", "route": "gutter" } ], "note": "Omitted for clarity: VPC endpoints, NAT, the bastion path and per-plane IAM roles — all present in view 16 and view 20.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "08-integration-catalogue", "title": "Integration and Interface Catalogue", "layout": "hub", "canvas": { "width": 1700 }, "left": { "title": "Inbound", "nodes": [ { "id": "h-svc", "label": "Product services", "sub": "HTTPS batch · async", "kind": "app", "rel": "events", "kind2": "async" }, { "id": "h-edge", "label": "Edge & CDN nodes", "sub": "minute rollup · async", "kind": "app", "rel": "egress", "kind2": "async" }, { "id": "h-feed", "label": "Partner feeds", "sub": "signed objects · batch", "kind": "external", "rel": "backfill", "kind2": "batch" }, { "id": "h-ops", "label": "Internal consoles", "sub": "pricing, close, restate", "kind": "app", "rel": "control" } ] }, "centre": { "title": "Platform", "nodes": [ { "id": "h-core", "label": "Metering & Billing Pipeline", "kind": "app", "sub": "AWS · 6 public endpoints" } ] }, "right": { "title": "Outbound", "nodes": [ { "id": "h-tax", "label": "Tax engine", "sub": "REST · per line", "kind": "external", "rel": "lines", "dir": "out" }, { "id": "h-pay", "label": "Payment platform", "sub": "invoice.issued · async", "kind": "external", "rel": "issued", "dir": "out", "kind2": "async" }, { "id": "h-erp", "label": "ERP & revenue recognition", "sub": "IDoc · nightly", "kind": "external", "rel": "nightly", "dir": "out", "kind2": "batch" }, { "id": "h-cust", "label": "Customer surfaces", "sub": "REST, console, webhooks", "kind": "external", "rel": "usage", "dir": "out" } ] }, "note": "Protocol and cadence sit on each node, not on the arrows. Customer threshold webhooks ride the customer-surfaces contract; the nightly warehouse extract is omitted because it reads the same ledger as the evidence query in view 15.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "09-metering-data-flow", "title": "Metering Data Flow — Emit to Served Quantity", "layout": "flow", "chain": true, "canvas": { "width": 1760 }, "stages": [ { "title": "Emit", "nodes": [ { "id": "d-sdk", "label": "Producer SDK", "sub": "durable buffer", "kind": "app" }, { "id": "d-edge", "label": "Edge agent", "sub": "minute rollup", "kind": "app" } ] }, { "title": "Accept", "nodes": [ { "id": "d-valid", "label": "Validate", "sub": "schema + refs", "kind": "app" }, { "id": "d-dedup", "label": "Dedup index", "sub": "7-day TTL", "kind": "store" }, { "id": "d-quar", "label": "Quarantine", "sub": "reason kept", "kind": "store", "icon": "fa5_ban" } ] }, { "title": "Record", "nodes": [ { "id": "d-stream", "label": "Event stream", "sub": "Kinesis", "kind": "queue" }, { "id": "d-append", "label": "Ledger append", "sub": "Firehose", "kind": "app" }, { "id": "d-ledger", "label": "Event ledger", "sub": "S3 Iceberg", "kind": "store" } ] }, { "title": "Window", "nodes": [ { "id": "d-wm", "label": "Watermark", "sub": "72 h lateness", "kind": "app", "icon": "fa5_clock" }, { "id": "d-win", "label": "Event-time windows", "sub": "hourly, daily", "kind": "app", "icon": "fa5_hourglass" } ] }, { "title": "Aggregate", "nodes": [ { "id": "d-sum", "label": "Counter & gauge", "kind": "app" }, { "id": "d-uniq", "label": "Unique entity", "kind": "app" }, { "id": "d-aggstore", "label": "Aggregate store", "sub": "DynamoDB", "kind": "store" } ] }, { "title": "Serve", "nodes": [ { "id": "d-rate", "label": "Rating service", "kind": "app" }, { "id": "d-usage", "label": "Usage API", "sub": "freshness stamped", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "d-base", "label": "Baseline detector", "kind": "app" } ] } ], "edges": [ { "from": "d-valid", "to": "d-quar", "label": "rejected", "kind": "error" }, { "from": "d-valid", "to": "d-dedup", "label": "event id" }, { "from": "d-ledger", "to": "d-wm", "label": "late event", "kind": "async" }, { "from": "d-aggstore", "to": "d-base", "label": "baseline", "kind": "batch" } ], "note": "Quantities are provisional until the watermark clears the period. Nothing here is authoritative: every box right of the ledger is rebuildable from it.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "10-storage-zones", "title": "Storage Zones — Ownership and Rebuildability", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "Data estate", "kind": "cloud", "dir": "col", "children": [ { "title": "Immutable record — the only truth", "kind": "trust", "nodes": [ { "id": "z-ledger", "label": "Event ledger", "sub": "S3 Iceberg, 400 d hot", "kind": "store" }, { "id": "z-cold", "label": "Audit tail", "sub": "Glacier Object Lock, 7 y", "kind": "store" }, { "id": "z-trail", "label": "Privileged-action log", "sub": "CloudTrail, locked", "kind": "store" } ] }, { "title": "Financial ledger — append-only, corrections are new entries", "kind": "boundary", "nodes": [ { "id": "z-inv", "label": "Invoice ledger", "sub": "Aurora PostgreSQL", "kind": "store", "icon": "aws_amazon-aurora" }, { "id": "z-bal", "label": "Balance ledger", "sub": "grants, drawdown", "kind": "store" }, { "id": "z-memo", "label": "Credit memos", "sub": "and supersessions", "kind": "store" } ] }, { "title": "Versioned configuration — immutable per version", "kind": "boundary", "nodes": [ { "id": "z-plan", "label": "Plan registry", "sub": "Aurora + S3 versions", "kind": "store" }, { "id": "z-fx", "label": "Currency rates", "sub": "dated records", "kind": "store" }, { "id": "z-cat", "label": "Schema catalogue", "sub": "Glue, all versions", "kind": "store" } ] }, { "title": "Derived — droppable and rebuildable by replay", "kind": "boundary", "nodes": [ { "id": "z-agg", "label": "Aggregate store", "sub": "DynamoDB", "kind": "store" }, { "id": "z-ckpt", "label": "Flink checkpoints", "sub": "S3", "kind": "store" }, { "id": "z-read", "label": "Usage read model", "sub": "DynamoDB", "kind": "store" } ] }, { "title": "Transient — no recovery value", "kind": "plain", "nodes": [ { "id": "z-stream", "label": "Event stream", "sub": "Kinesis, 24 h", "kind": "queue" }, { "id": "z-outbox", "label": "Outbox", "sub": "EventBridge", "kind": "queue" }, { "id": "z-dax", "label": "Entitlement cache", "sub": "DAX", "kind": "store" } ] } ] } ], "outside": [ { "id": "z-quar", "label": "Quarantine", "sub": "S3, replayable", "kind": "store", "icon": "fa5_ban" }, { "id": "z-wh", "label": "Data warehouse", "kind": "external" } ], "edges": [ { "from": "z-ledger", "to": "z-agg", "label": "rebuild", "kind": "batch" }, { "from": "z-ledger", "to": "z-cold", "label": "lifecycle", "kind": "batch" } ], "note": "The test for a zone is one question: if this store were deleted, could the platform reconstruct it? Only the top two zones answer no. Quarantined events replay into the ledger once the defect that rejected them is fixed.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "11-data-model", "title": "Data Model — Event to Invoice Line", "layout": "er", "canvas": { "width": 1760, "cols": 4 }, "rowGap": 270, "entities": [ { "id": "e-acct", "name": "account", "kind": "store", "row": 0, "col": 0, "attrs": [ "account_id PK", "plan_version_id FK", "billing_currency", "billing_cycle", "cycle_anchor_day" ] }, { "id": "e-meter", "name": "meter", "kind": "store", "row": 0, "col": 1, "attrs": [ "meter_id PK", "name", "type counter|gauge|hwm|unique", "period_grain", "dimension_keys" ] }, { "id": "e-plan", "name": "plan_version", "kind": "store", "row": 0, "col": 2, "attrs": [ "plan_version_id PK", "plan_id", "effective_from", "effective_to", "pricing_shape", "immutable true" ] }, { "id": "e-rest", "name": "restatement", "kind": "store", "row": 0, "col": 3, "attrs": [ "restatement_id PK", "scope acct|meter|period", "reason", "authorised_by", "original_amount", "restated_amount" ] }, { "id": "e-event", "name": "usage_event", "kind": "store", "row": 1, "col": 0, "attrs": [ "event_id PK (producer)", "account_id FK", "meter_id FK", "quantity", "event_ts / ingest_ts", "dimensions map", "schema_version" ] }, { "id": "e-agg", "name": "aggregate", "kind": "store", "row": 1, "col": 1, "attrs": [ "account_id FK", "meter_id FK", "dimension_hash", "period_start / grain", "quantity", "event_range provenance", "state prov|closed" ] }, { "id": "e-line", "name": "priced_line", "kind": "store", "row": 1, "col": 2, "attrs": [ "line_id PK", "invoice_id FK", "plan_version_id FK", "quantity", "tier_breakdown", "amount", "fx_rate_date" ] }, { "id": "e-inv", "name": "invoice", "kind": "store", "row": 1, "col": 3, "attrs": [ "invoice_id PK", "account_id FK", "period", "status draft|issued", "subtotal / credits", "amount_payable", "issued_at" ] }, { "id": "e-bal", "name": "balance_entry", "kind": "store", "row": 2, "col": 2, "attrs": [ "entry_id PK", "account_id FK", "grant_id", "delta", "cause", "created_at" ] }, { "id": "e-memo", "name": "credit_memo", "kind": "store", "row": 2, "col": 3, "attrs": [ "memo_id PK", "invoice_id FK", "reason", "authorised_by", "amount" ] } ], "relations": [ { "from": "e-acct", "to": "e-event", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-meter", "to": "e-agg", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-event", "to": "e-agg", "label": "N : 1", "from_side": "e", "to_side": "w" }, { "from": "e-plan", "to": "e-line", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-agg", "to": "e-line", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "e-line", "to": "e-inv", "label": "N : 1", "from_side": "e", "to_side": "w" }, { "from": "e-inv", "to": "e-memo", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-line", "to": "e-bal", "label": "1 : N", "from_side": "s", "to_side": "n", "kind": "optional" }, { "from": "e-rest", "to": "e-inv", "label": "1 : N", "from_side": "s", "to_side": "n" } ], "note": "event_range on aggregate is the provenance that lets one invoice line be expanded back to its events. The dashed relation is the credit drawdown, which only exists where a grant applies.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "12-critical-flow-event-to-line", "title": "Critical Flow — One Event Becomes One Invoice Line", "layout": "sequence", "canvas": { "width": 1700 }, "lifelines": [ { "id": "s-prod", "label": "Producer", "kind": "app" }, { "id": "s-api", "label": "Ingest API", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "s-ledger", "label": "Event ledger", "kind": "store" }, { "id": "s-agg", "label": "Aggregator", "kind": "app" }, { "id": "s-rate", "label": "Rating service", "kind": "app" }, { "id": "s-run", "label": "Invoice run", "kind": "app" }, { "id": "s-cust", "label": "Customer", "kind": "actor" } ], "messages": [ { "from": "s-prod", "to": "s-api", "label": "POST /events — id, meter, qty, event_ts", "kind": "call" }, { "from": "s-api", "to": "s-api", "label": "validate schema, check dedup index", "kind": "self" }, { "from": "s-api", "to": "s-ledger", "label": "append, await replication", "kind": "call" }, { "from": "s-ledger", "to": "s-api", "label": "committed", "kind": "return" }, { "from": "s-api", "to": "s-prod", "label": "202 accepted — a durability promise", "kind": "return" }, { "from": "s-ledger", "to": "s-agg", "label": "stream by event time", "kind": "async" }, { "from": "s-agg", "to": "s-agg", "label": "window, watermark, provisional", "kind": "self" }, { "from": "s-agg", "to": "s-rate", "label": "aggregate + event_range", "kind": "async" }, { "from": "s-rate", "to": "s-rate", "label": "plan version in force at event_ts", "kind": "self" }, { "from": "s-rate", "to": "s-run", "label": "priced line with tier breakdown", "kind": "call" }, { "from": "s-run", "to": "s-run", "label": "anomaly gate, then issue", "kind": "self" }, { "from": "s-run", "to": "s-cust", "label": "invoice issued — immutable", "kind": "async" }, { "from": "s-cust", "to": "s-run", "label": "expand this line", "kind": "call" }, { "from": "s-run", "to": "s-ledger", "label": "evidence query over event_range", "kind": "call" }, { "from": "s-ledger", "to": "s-cust", "label": "the events behind the figure", "kind": "return" } ], "note": "Message 5 is the whole design: the acknowledgement follows replication, so an accepted event cannot be lost and messages 13 to 15 are always answerable.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "13-invoice-run", "title": "Invoice Run — Close to Hand-Off", "layout": "flow", "chain": true, "canvas": { "width": 1760 }, "stages": [ { "title": "Close", "nodes": [ { "id": "v-wm", "label": "Lateness bound elapsed?", "kind": "decision" }, { "id": "v-close", "label": "Close aggregates", "sub": "provisional cleared", "kind": "app" } ] }, { "title": "Price", "nodes": [ { "id": "v-rate", "label": "Rate per account", "sub": "parallel, idempotent", "kind": "app" }, { "id": "v-credit", "label": "Apply credits", "sub": "documented order", "kind": "app" }, { "id": "v-commit", "label": "Commitment drawdown", "kind": "app" } ] }, { "title": "Draft", "nodes": [ { "id": "v-assemble", "label": "Assemble invoice", "sub": "draft state", "kind": "app" }, { "id": "v-anom", "label": "Anomaly report", "sub": "vs own history", "kind": "app" } ] }, { "title": "Review", "nodes": [ { "id": "v-fin", "label": "Finance controller", "kind": "actor" }, { "id": "v-gate", "label": "Issue, or hold?", "kind": "decision" }, { "id": "v-hold", "label": "Held for restatement", "kind": "risk" } ] }, { "title": "Issue", "nodes": [ { "id": "v-issue", "label": "Issue invoice", "sub": "immutable from here", "kind": "app" }, { "id": "v-ledger", "label": "Invoice ledger", "kind": "store", "icon": "aws_amazon-aurora" } ] }, { "title": "Hand off", "nodes": [ { "id": "v-out", "label": "Outbox", "sub": "replayable", "kind": "queue" }, { "id": "v-pay", "label": "Payment & tax", "kind": "external" }, { "id": "v-erp", "label": "ERP & revrec", "kind": "external" } ] } ], "edges": [ { "from": "v-gate", "to": "v-hold", "label": "hold", "kind": "error" }, { "from": "v-hold", "to": "v-rate", "label": "re-rate", "kind": "batch", "route": "gutter" }, { "from": "v-out", "to": "v-erp", "label": "nightly", "kind": "batch" } ], "note": "The run is resumable and keyed on account plus period, so an interruption re-enters where it stopped and never invoices an account twice.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "14-meter-types", "title": "Meter Types — How Each Reaches the Invoice", "layout": "swimlane", "canvas": { "width": 1760 }, "laneHeaderWidth": 200, "stages": [ "Emit", "Window", "Aggregate", "Rate", "On the invoice" ], "lanes": [ { "title": "Counter — API calls", "cells": [ [ { "label": "Event per call", "kind": "app" } ], [ { "label": "Hourly, event time", "kind": "app" } ], [ { "label": "Sum", "kind": "app" } ], [ { "label": "Graduated tiers", "kind": "app" } ], [ { "label": "Qty × tier rates", "kind": "store" } ] ] }, { "title": "Gauge — active seats", "cells": [ [ { "label": "Hourly snapshot", "kind": "app" } ], [ { "label": "Daily", "kind": "app" } ], [ { "label": "Time-weighted mean", "kind": "app" } ], [ { "label": "Per unit", "kind": "app" } ], [ { "label": "Mean seats × price", "kind": "store" } ] ] }, { "title": "High-water — storage", "cells": [ [ { "label": "Hourly sample", "kind": "app" } ], [ { "label": "Daily", "kind": "app" } ], [ { "label": "Maximum", "kind": "app" } ], [ { "label": "Volume tiers", "kind": "app" } ], [ { "label": "Peak GB × tier", "kind": "store" } ] ] }, { "title": "Unique entity — MAU", "cells": [ [ { "label": "Event per actor", "kind": "app" } ], [ { "label": "Monthly", "kind": "app" } ], [ { "label": "Distinct count", "kind": "app" } ], [ { "label": "Package price", "kind": "app" } ], [ { "label": "Band reached", "kind": "store" } ] ] }, { "title": "Dimensioned — egress", "cells": [ [ { "label": "Minute rollup at edge", "kind": "app" } ], [ { "label": "Hourly", "kind": "app" } ], [ { "label": "Sum per region", "kind": "app" } ], [ { "label": "Rate card per region", "kind": "app" } ], [ { "label": "GB × region rate", "kind": "store" } ] ] } ], "note": "One pipeline, five aggregate functions. A new meter is a configuration row choosing a lane, which is why packaging changes without a deployment.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "15-restatement-and-evidence", "title": "Restatement and Evidence — Correcting Without Editing", "layout": "flow", "chain": true, "canvas": { "width": 1760 }, "stages": [ { "title": "Trigger", "nodes": [ { "id": "t-gate", "label": "Anomaly gate", "kind": "decision" }, { "id": "t-disp", "label": "Customer dispute", "kind": "actor" } ] }, { "title": "Scope", "nodes": [ { "id": "t-api", "label": "Restatement API", "sub": "account, meter, period", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "t-guard", "label": "Scope bounded?", "kind": "decision" }, { "id": "t-refuse", "label": "Unbounded refused", "kind": "risk" } ] }, { "title": "Replay", "nodes": [ { "id": "t-read", "label": "Read event range", "sub": "Athena over Iceberg", "kind": "app", "icon": "aws_amazon-athena" }, { "id": "t-meter", "label": "Re-meter", "sub": "same code path", "kind": "app" }, { "id": "t-rate", "label": "Re-rate", "sub": "plan version as-of", "kind": "app" } ] }, { "title": "Compare", "nodes": [ { "id": "t-diff", "label": "Difference report", "kind": "app" }, { "id": "t-orig", "label": "Original retained", "sub": "never overwritten", "kind": "store" } ] }, { "title": "Remedy", "nodes": [ { "id": "t-auth", "label": "Two-person authorisation", "kind": "decision" }, { "id": "t-memo", "label": "Credit memo", "kind": "app" }, { "id": "t-super", "label": "Superseding invoice", "kind": "app" } ] }, { "title": "Record", "nodes": [ { "id": "t-store", "label": "Restated figure", "sub": "both versions kept", "kind": "store" }, { "id": "t-audit", "label": "Audit record", "sub": "reason + identity", "kind": "security" }, { "id": "t-notice", "label": "Customer notice", "sub": "with evidence export", "kind": "integration" } ] } ], "edges": [ { "from": "t-guard", "to": "t-refuse", "label": "refused", "kind": "error" }, { "from": "t-read", "to": "t-orig", "label": "provenance", "kind": "batch" }, { "from": "t-notice", "to": "t-disp", "label": "answered", "route": "gutter" } ], "note": "Nothing on this path mutates an issued figure. The remedy is a new record, and the original survives so the history of a dispute is itself auditable.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "16-deployment-architecture", "title": "Deployment Architecture — Region, Zones and Data", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "AWS eu-west-1 — primary region", "kind": "cloud", "dir": "col", "children": [ { "title": "Entry", "kind": "boundary", "nodes": [ { "id": "p-cf", "label": "CloudFront + WAF", "sub": "console assets", "kind": "security" }, { "id": "p-gw", "label": "API Gateway", "sub": "regional, OIDC", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "p-r53", "label": "Route 53", "sub": "health checks", "kind": "platform" } ] }, { "title": "Compute — three availability zones", "kind": "boundary", "dir": "row", "children": [ { "title": "AZ-a", "kind": "boundary", "nodes": [ { "id": "p-a1", "label": "Ingest tasks", "sub": "ECS Fargate", "kind": "app" }, { "id": "p-a2", "label": "Rating tasks", "kind": "app" }, { "id": "p-a3", "label": "Flink task manager", "kind": "app" } ] }, { "title": "AZ-b", "kind": "boundary", "nodes": [ { "id": "p-b1", "label": "Ingest tasks", "sub": "ECS Fargate", "kind": "app" }, { "id": "p-b2", "label": "Rating tasks", "kind": "app" }, { "id": "p-b3", "label": "Flink task manager", "kind": "app" } ] }, { "title": "AZ-c", "kind": "boundary", "nodes": [ { "id": "p-c1", "label": "Ingest tasks", "sub": "ECS Fargate", "kind": "app" }, { "id": "p-c2", "label": "Rating tasks", "kind": "app" }, { "id": "p-c3", "label": "Flink task manager", "kind": "app" } ] } ] }, { "title": "Regional data — zone-redundant per service", "kind": "boundary", "nodes": [ { "id": "p-s3", "label": "Event ledger", "sub": "S3, 11 nines", "kind": "store" }, { "id": "p-ddb", "label": "Aggregates & dedup", "sub": "DynamoDB", "kind": "store" }, { "id": "p-aur", "label": "Invoice ledger", "sub": "Aurora Multi-AZ", "kind": "store", "icon": "aws_amazon-aurora" }, { "id": "p-dax", "label": "Entitlement cache", "sub": "DAX, 3 nodes", "kind": "store" }, { "id": "p-gl", "label": "Audit tail", "sub": "Glacier, locked", "kind": "store" } ] }, { "title": "Orchestration and platform", "kind": "boundary", "nodes": [ { "id": "p-sfn", "label": "Invoice & restatement runs", "sub": "Step Functions", "kind": "platform" }, { "id": "p-eb", "label": "Outbox", "sub": "EventBridge", "kind": "queue" }, { "id": "p-cw", "label": "Observability", "sub": "CloudWatch, Grafana", "kind": "platform" }, { "id": "p-sm", "label": "Secrets & keys", "sub": "Secrets Manager, KMS", "kind": "security" } ] } ] } ], "outside": [ { "id": "p-rep", "label": "Ledger replica", "sub": "us-east-1, cross-region", "kind": "store" }, { "id": "p-standby", "label": "Standby control plane", "sub": "us-east-1, RTO 15 min", "kind": "app" }, { "id": "p-prod", "label": "Product services", "kind": "external" } ], "edges": [ { "from": "p-prod", "to": "p-gw", "label": "events", "kind": "async" }, { "from": "p-s3", "to": "p-rep", "label": "replication", "kind": "batch" } ], "note": "Single-region active with a cross-region ledger replica: an accepted event survives a region loss, and the control plane is restored from the replica rather than run hot. Lifecycle to the audit tail is shown in view 10. Active-active ingestion is Phase 3.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "17-pricing-change-promotion", "title": "Pricing Change Promotion — The Most Dangerous Deployment", "layout": "flow", "chain": true, "canvas": { "width": 1760 }, "stages": [ { "title": "Author", "nodes": [ { "id": "g-ui", "label": "Pricing console", "kind": "app" }, { "id": "g-draft", "label": "Draft plan version", "sub": "not yet effective", "kind": "store" } ] }, { "title": "Validate", "nodes": [ { "id": "g-shape", "label": "Shape check", "sub": "tiers, currency, meters", "kind": "app" }, { "id": "g-conflict", "label": "Conflict check", "sub": "overlapping dates", "kind": "app" } ] }, { "title": "Preview", "nodes": [ { "id": "g-blast", "label": "Blast-radius preview", "sub": "accounts + Δ amount", "kind": "app" }, { "id": "g-dry", "label": "Dry-run re-rate", "sub": "last closed period", "kind": "app" } ] }, { "title": "Authorise", "nodes": [ { "id": "g-second", "label": "Second approver", "kind": "actor" }, { "id": "g-gate", "label": "Both approvals?", "kind": "decision" }, { "id": "g-reject", "label": "Rejected", "kind": "risk" } ] }, { "title": "Activate", "nodes": [ { "id": "g-ver", "label": "New plan version", "sub": "immutable", "kind": "store" }, { "id": "g-eff", "label": "Effective-from set", "sub": "splits the period", "kind": "app" } ] }, { "title": "Observe", "nodes": [ { "id": "g-base", "label": "Baseline re-armed", "kind": "app" }, { "id": "g-audit", "label": "Audit record", "sub": "who, what, when", "kind": "security" }, { "id": "g-roll", "label": "Rollback = new version", "kind": "app" } ] } ], "edges": [ { "from": "g-gate", "to": "g-reject", "label": "refused", "kind": "error" }, { "from": "g-reject", "to": "g-draft", "label": "back to draft", "kind": "batch", "route": "gutter" } ], "note": "There is no rollback in place: a wrong price is corrected by a further version plus a restatement of anything already rated under it.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "18-observability", "title": "Observability — Signal by Pipeline Stage", "layout": "grid", "canvas": { "width": 1760 }, "laneHeaderWidth": 180, "stages": [ "Ingest", "Meter", "Rate", "Invoice", "Evidence" ], "lanes": [ { "title": "Correctness", "cells": [ [ { "label": "Accept vs ack gap", "kind": "app" } ], [ { "label": "Dedup hit rate", "kind": "app" } ], [ { "label": "Re-rate difference", "kind": "app" } ], [ { "label": "Total vs sum of lines", "kind": "app" } ], [ { "label": "Replay determinism", "kind": "app" } ] ] }, { "title": "Latency", "cells": [ [ { "label": "p99 accept, 50 ms", "kind": "platform" } ], [ { "label": "Freshness p95, 5 min", "kind": "platform" } ], [ { "label": "Cap decision p99, 10 ms", "kind": "platform" } ], [ { "label": "Run complete, 6 h", "kind": "platform" } ], [ { "label": "Evidence query p95", "kind": "platform" } ] ] }, { "title": "Volume", "cells": [ [ { "label": "Events/s per producer", "kind": "store" } ], [ { "label": "Periods closed", "kind": "store" } ], [ { "label": "Lines priced", "kind": "store" } ], [ { "label": "Invoices issued", "kind": "store" } ], [ { "label": "Exports served", "kind": "store" } ] ] }, { "title": "Money", "cells": [ [ { "label": "Accepted, not yet billed", "kind": "risk" } ], [ { "label": "Provisional vs closed Δ", "kind": "risk" } ], [ { "label": "Revenue per meter", "kind": "app" } ], [ { "label": "Credit memo value", "kind": "risk" } ], [ { "label": "Disputed value", "kind": "risk" } ] ] }, { "title": "Cost to meter", "cells": [ [ { "label": "Cost per M events", "kind": "platform" } ], [ { "label": "Cost per meter", "kind": "platform" } ], [ { "label": "Rating compute", "kind": "platform" } ], [ { "label": "Run cost", "kind": "platform" } ], [ { "label": "Cold retrieval", "kind": "platform" } ] ] } ], "note": "The Money row is what makes this a billing platform rather than a pipeline: accepted-but-unbilled and provisional-versus-closed are the two numbers that catch lost revenue before a customer does.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "19-billing-period-lifecycle", "title": "Billing Period Lifecycle", "layout": "cycle", "centre": { "label": "Billing period", "sub": "per account" }, "rx": 440, "ry": 215, "nodes": [ { "id": "y-open", "label": "Period opens", "sub": "provisional", "kind": "app" }, { "id": "y-accrue", "label": "Usage accrues", "sub": "event-time", "kind": "app", "icon": "fa5_chart_line" }, { "id": "y-grace", "label": "Lateness bound", "sub": "72 h grace", "kind": "decision" }, { "id": "y-close", "label": "Period closes", "sub": "aggregates final", "kind": "app" }, { "id": "y-draft", "label": "Rated and drafted", "sub": "anomaly gate", "kind": "app" }, { "id": "y-issue", "label": "Invoice issued", "sub": "immutable", "kind": "store" } ], "ringLabels": [ "events land", "window fills", "grace elapses", "priced lines", "gate clears", "next period" ], "note": "An issued period re-enters this ring only by authorised restatement, which produces a second figure rather than reopening the first.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "20-security-zones", "title": "Security Zones and Privileged Paths", "layout": "zones", "canvas": { "width": 1760 }, "zones": [ { "title": "Internet", "kind": "trust", "nodes": [ { "id": "w-user", "label": "Customer admin", "kind": "actor" }, { "id": "w-prod", "label": "Product & edge services", "kind": "app" }, { "id": "w-feed", "label": "Partner feeds", "kind": "external" } ] }, { "title": "Perimeter", "kind": "trust", "nodes": [ { "id": "w-waf", "label": "WAF + CloudFront", "kind": "security" }, { "id": "w-gw", "label": "API Gateway", "sub": "OIDC, mTLS", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "w-authz", "label": "Request authorisation", "sub": "meter scope, account scope", "kind": "security" } ] }, { "title": "Application — private subnets, no inbound internet", "kind": "trust", "nodes": [ { "id": "w-valid", "label": "Ingest validator", "kind": "app" }, { "id": "w-agg", "label": "Aggregator", "kind": "app" }, { "id": "w-rate", "label": "Rating service", "kind": "app" }, { "id": "w-ent", "label": "Entitlement service", "kind": "app" }, { "id": "w-run", "label": "Invoice run", "kind": "app" } ] }, { "title": "Privileged — separate roles, second approver, no standing access", "kind": "trust", "nodes": [ { "id": "w-price", "label": "Pricing change", "kind": "security" }, { "id": "w-restate", "label": "Restatement", "kind": "security" }, { "id": "w-memo", "label": "Credit memo issue", "kind": "security" } ] }, { "title": "Data and evidence — reachable only by VPC endpoint", "kind": "trust", "nodes": [ { "id": "w-ledger", "label": "Event ledger", "kind": "store" }, { "id": "w-plan", "label": "Plan registry", "kind": "store" }, { "id": "w-audit", "label": "Privileged-action log", "sub": "write-once", "kind": "store" }, { "id": "w-inv", "label": "Invoice ledger", "kind": "store", "icon": "aws_amazon-aurora" }, { "id": "w-kms", "label": "KMS", "sub": "per-zone keys", "kind": "security" } ] } ], "edges": [ { "from": "w-user", "to": "w-waf", "label": "OIDC" }, { "from": "w-prod", "to": "w-gw", "label": "role + mTLS", "kind": "async" }, { "from": "w-gw", "to": "w-valid", "label": "scoped to its meters" }, { "from": "w-valid", "to": "w-ledger", "label": "append only" }, { "from": "w-price", "to": "w-plan", "label": "two-person" }, { "from": "w-restate", "to": "w-audit", "label": "written before execution" } ], "note": "No identity holds pricing, restatement and credit-memo rights together. The privileged zone writes its audit record before the action runs, so an action that fails is still on the record.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "21-entitlement-and-identity-flow", "title": "Identity and Entitlement Flow — Who Proves What", "layout": "sequence", "canvas": { "width": 1760 }, "lifelines": [ { "id": "q-prod", "label": "Product service", "kind": "app" }, { "id": "q-id", "label": "Workload identity", "kind": "security" }, { "id": "q-ent", "label": "Entitlement service", "kind": "app" }, { "id": "q-bal", "label": "Balance ledger", "kind": "store" }, { "id": "q-user", "label": "Customer admin", "kind": "actor" }, { "id": "q-api", "label": "Usage API", "kind": "integration", "icon": "aws_amazon-api-gateway" }, { "id": "q-agg", "label": "Aggregate store", "kind": "store" } ], "messages": [ { "from": "q-prod", "to": "q-id", "label": "assume role", "kind": "call" }, { "from": "q-id", "to": "q-prod", "label": "token scoped to its meters", "kind": "return" }, { "from": "q-prod", "to": "q-ent", "label": "may this account use this meter?", "kind": "call" }, { "from": "q-ent", "to": "q-ent", "label": "cache read, p99 10 ms", "kind": "self" }, { "from": "q-ent", "to": "q-bal", "label": "balance on cache miss", "kind": "call" }, { "from": "q-bal", "to": "q-ent", "label": "remaining grant", "kind": "return" }, { "from": "q-ent", "to": "q-prod", "label": "allow or deny, with headroom", "kind": "return" }, { "from": "q-ent", "to": "q-prod", "label": "unavailable — fail open, marked", "kind": "error" }, { "from": "q-user", "to": "q-api", "label": "GET /usage, OIDC session", "kind": "call" }, { "from": "q-api", "to": "q-api", "label": "account-scoped authorisation", "kind": "self" }, { "from": "q-api", "to": "q-agg", "label": "read this account only", "kind": "call" }, { "from": "q-agg", "to": "q-user", "label": "quantities with freshness", "kind": "return" } ], "note": "Message 8 is the decision in the ask's Question 3: the cap check fails open and records that it did, so the overshoot is known rather than invisible.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } }, { "id": "22-failure-classes", "title": "Failure Classes — Detection, Handling, Residual Risk", "layout": "grid", "canvas": { "width": 1700 }, "laneHeaderWidth": 230, "stages": [ "Detected by", "Handled by", "Residual risk" ], "lanes": [ { "title": "Duplicate delivery", "cells": [ [ { "label": "Dedup hit rate", "kind": "app" } ], [ { "label": "Idempotency on event id", "kind": "app" } ], [ { "label": "Retry past 7 days", "kind": "risk" } ] ] }, { "title": "Late arrival", "cells": [ [ { "label": "Watermark lag", "kind": "app" } ], [ { "label": "72 h lateness bound", "kind": "app" } ], [ { "label": "Beyond bound: restate", "kind": "risk" } ] ] }, { "title": "Lost before acknowledgement", "cells": [ [ { "label": "Producer gap report", "kind": "app" } ], [ { "label": "Durable local buffer", "kind": "app" } ], [ { "label": "Crash with full buffer", "kind": "risk" } ] ] }, { "title": "Malformed or drifted event", "cells": [ [ { "label": "Quarantine rate", "kind": "app" } ], [ { "label": "Quarantine then replay", "kind": "app" } ], [ { "label": "Drift nobody reads", "kind": "risk" } ] ] }, { "title": "Pricing misconfiguration", "cells": [ [ { "label": "Blast-radius preview", "kind": "app" } ], [ { "label": "Two-person gate", "kind": "security" } ], [ { "label": "Both approvers wrong", "kind": "risk" } ] ] }, { "title": "Hot account", "cells": [ [ { "label": "Partition skew", "kind": "app" } ], [ { "label": "Sub-partition and quota", "kind": "app" } ], [ { "label": "Skew past sub-partition", "kind": "risk" } ] ] }, { "title": "Ledger unavailable", "cells": [ [ { "label": "Accept error rate", "kind": "app" } ], [ { "label": "Reject; producer retains", "kind": "app" } ], [ { "label": "Outage past buffer depth", "kind": "risk" } ] ] }, { "title": "Downstream unavailable", "cells": [ [ { "label": "Outbox depth", "kind": "app" } ], [ { "label": "Durable outbox, replay", "kind": "app" } ], [ { "label": "Invoice late to payment", "kind": "risk" } ] ] } ], "note": "Every residual risk here is accepted deliberately and is either bounded by a stated number or escalates into a restatement, which is the one failure path the architecture is built to make routine.", "meta": { "v": "1.0", "owner": "Architecture Practice", "date": "2026-10" } } ]