[ { "id": "01-system-context", "title": "Leaderboard & Counting Service — System Context", "layout": "context", "system": { "label": "Leaderboard & Counting Service", "sub": "count, rank, publish" }, "colWidth": 270, "groups": [ { "side": "left", "title": "People who generate the numbers", "nodes": [ { "id": "member", "label": "Product member", "kind": "actor", "rel": "earns, views rank", "dir": "in" }, { "id": "pe", "label": "Product engineer", "kind": "actor", "rel": "declares counters", "dir": "in" }, { "id": "ts", "label": "Trust & safety analyst", "kind": "actor", "rel": "retracts, freezes", "dir": "in" } ] }, { "side": "right", "title": "Systems it reads and writes", "nodes": [ { "id": "pb", "label": "Product backends", "kind": "external", "rel": "emit events", "dir": "in" }, { "id": "dir", "label": "Member directory", "kind": "external", "rel": "display names", "dir": "in" }, { "id": "idp", "label": "Identity provider", "kind": "external", "rel": "authN", "dir": "in", "icon": "gcp_security_identity" }, { "id": "wh", "label": "Analytics warehouse", "kind": "external", "rel": "export", "kind2": "batch", "icon": "gcp_bigquery" } ] }, { "side": "top", "title": "Accountable for the number", "nodes": [ { "id": "po", "label": "Product owner", "kind": "actor", "rel": "owns the surface", "dir": "in" }, { "id": "plat", "label": "Platform engineer", "kind": "actor", "rel": "owns capacity", "dir": "in" } ] }, { "side": "bottom", "title": "Consumers of the result", "nodes": [ { "id": "app", "label": "Product clients", "kind": "external", "rel": "render rank" }, { "id": "reward", "label": "Reward & fulfilment", "kind": "external", "rel": "standings", "kind2": "batch" }, { "id": "notif", "label": "Notification service", "kind": "external", "rel": "rank changes", "kind2": "async", "icon": "fa5_bell" } ] } ], "note": "The platform never decides what earns a point: the product does, and emits the event. Display names are resolved from the member directory at read time and are never stored in a counter.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "02-high-level-architecture", "title": "Leaderboard & Counting Service — High-Level Architecture", "layout": "flow", "chain": true, "align": "middle", "stages": [ { "title": "Admit", "nodes": [ { "id": "api", "label": "Counting API", "sub": "Cloud Run", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "adm", "label": "Admission", "sub": "idempotency, quota", "kind": "app" } ] }, { "title": "Log", "nodes": [ { "id": "log", "label": "Event log", "sub": "Pub/Sub, 31 d", "kind": "queue", "icon": "gcp_pubsub" }, { "id": "arch", "label": "Event archive", "sub": "GCS, 90 d replay", "kind": "store", "icon": "gcp_cloud_storage" } ] }, { "title": "Aggregate", "nodes": [ { "id": "agg", "label": "Aggregation job", "sub": "Dataflow, event time", "kind": "app", "icon": "gcp_dataflow" }, { "id": "buck", "label": "Bucket store", "sub": "Bigtable", "kind": "store", "icon": "gcp_bigtable" } ] }, { "title": "Project", "nodes": [ { "id": "proj", "label": "Projection builder", "sub": "versioned views", "kind": "app", "icon": "gcp_dataflow" }, { "id": "rank", "label": "Ranked store", "sub": "top-N + histogram", "kind": "store", "icon": "gcp_bigtable" } ] }, { "title": "Serve", "nodes": [ { "id": "cache", "label": "Rank cache", "sub": "Memorystore", "kind": "store", "icon": "gcp_memorystore" }, { "id": "q", "label": "Query API", "sub": "staleness tagged", "kind": "integration", "icon": "gcp_cloud_run" } ] }, { "title": "Close", "nodes": [ { "id": "season", "label": "Season closer", "sub": "Workflows", "kind": "decision", "icon": "gcp_integration_services" }, { "id": "cp", "label": "Control plane", "sub": "Spanner", "kind": "platform", "icon": "gcp_cloud_spanner" } ] } ], "edges": [ { "from": "arch", "to": "agg", "label": "replay", "kind": "batch", "route": "gutter" }, { "from": "adm", "to": "q", "label": "own-write overlay", "kind": "async", "route": "gutter" } ], "note": "Six stages, and the acknowledgement happens at the end of the second. Everything after Log is a rebuildable projection; the replay edge is the recovery path and the routine one.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "03-actors-and-journeys", "title": "Leaderboard & Counting Service — Actors and Their Core Journeys", "layout": "actors", "cardWidth": 290, "groups": [ { "title": "The people the numbers are about", "kind": "boundary", "actors": [ { "id": "member", "label": "Product member", "sub": "80M monthly", "goal": "Show me where I stand, and make my own effort count the instant I make it — if the number ignores what I just did, I stop believing all of it.", "journeys": [ { "id": "j-stand", "label": "Check where I stand" }, { "label": "Watch a live round" } ] }, { "id": "top", "label": "Top-ranked member", "sub": "the visible head", "goal": "Keep the ranking honest. If someone above me got there by exploiting a bug, I want them gone and the list corrected, not quietly patched.", "journeys": [ { "label": "Report a suspect rank" } ] } ] }, { "title": "The teams that ship the surfaces", "kind": "boundary", "actors": [ { "id": "pe", "label": "Product engineer", "sub": "25 tenant teams", "goal": "Let me launch a new leaderboard this week by declaring it, not by learning how sorted sets shard.", "journeys": [ { "id": "j-ship", "label": "Ship a new leaderboard" }, { "label": "Change a window definition" } ] }, { "id": "po", "label": "Product owner", "sub": "owns the surface", "goal": "Tell me what the number means and how stale it may be, so the screen can say \"as of\" instead of implying it is live.", "journeys": [ { "label": "Agree a freshness budget" } ] } ] }, { "title": "The people who defend it", "kind": "trust", "actors": [ { "id": "ts", "label": "Trust & safety analyst", "sub": "24/7 rota", "goal": "When an exploit is running, let me stop the visible list and take the contributions out without deleting the evidence I need to prove it.", "journeys": [ { "id": "j-cheat", "label": "Remove a cheater" } ] }, { "id": "plat", "label": "Platform engineer", "sub": "9 people", "goal": "Absorb one key taking a thousand times the median write rate without the other 3.5 billion counters paying for it.", "journeys": [ { "label": "Split a hot key" }, { "label": "Rebuild a projection" } ] } ] }, { "title": "Machines in the cast", "kind": "cloud", "actors": [ { "id": "pb", "label": "Product backend", "kind": "external", "sub": "250k events/s", "goal": "Hand off the event in under 25 ms and never be blocked by someone else's leaderboard being rebuilt.", "journeys": [ { "label": "Emit a batch of events" } ] }, { "id": "sched", "label": "Season closer", "kind": "platform", "sub": "weekly, per tenant", "goal": "Freeze last week's standings exactly once, without stopping this week's counting.", "journeys": [ { "label": "Close a season" } ], "icon": "gcp_integration_services" }, { "id": "rew", "label": "Reward service", "kind": "external", "sub": "pays on standings", "goal": "Read a standing I can rely on not to change after I have paid out against it.", "journeys": [ { "label": "Grant on a closed standing" } ] } ] } ], "note": "Three journeys get their own map: the member checking their standing, the engineer launching a leaderboard, and the analyst removing a cheater. They fail in three different places.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "04-journey-where-do-i-stand", "title": "Journey — A Member Checks Where They Stand", "layout": "journey", "actor": { "label": "Product member", "sub": "opens the app 4× a day", "goal": "See my standing, and see my own effort reflected in it", "trigger": "Finishing a lesson, a ride, a round — or a push notification about the league", "success": "A rank they believe, with their last action visibly counted" }, "phases": [ { "title": "Earn", "sub": "does the thing" }, { "title": "Open", "sub": "league screen" }, { "title": "Find me", "moment": true }, { "title": "Compare", "sub": "neighbours" }, { "title": "Return", "sub": "hours later", "moment": true } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Completes a session" } ], [ { "label": "Taps the league tab" } ], [ { "label": "Looks for their row" } ], [ { "label": "Reads who is near" } ], [ { "label": "Checks if it held" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Event accepted, logged", "sub": "p99 25 ms" } ], [ { "label": "Top-N from cache", "sub": "p99 40 ms" } ], [ { "label": "Rank + own-write overlay" } ], [ { "label": "Neighbourhood slice" } ], [ { "label": "Projection advanced" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Trusts it", "Fine", "Stops believing it" ], "points": [ 1, 1, 0, 2, 1 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [], [ { "label": "Own points not there yet" }, { "label": "Rank differs on refresh" } ], [], [ { "label": "Rank moved with no reason" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [], [], [ { "label": "Own-write overlay", "sub": "≤ 1 s" }, { "label": "Version pinned per session" } ], [], [ { "label": "\"as of\" on the screen" } ] ] } ], "chain": true, "note": "The trough is not latency. It is a member's own contribution missing from a number that is otherwise correct — which is why read-your-writes is a requirement and global freshness is only a budget.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "05-journey-ship-a-leaderboard", "title": "Journey — A Product Engineer Ships a New Leaderboard", "layout": "journey", "actor": { "label": "Product engineer", "sub": "one of 25 tenant teams", "goal": "Put a new weekly leaderboard on a screen this week", "trigger": "A product decision to add a competitive surface to an existing feature", "success": "A declared counter, a leaderboard reading it, and a cost per million events they can defend" }, "phases": [ { "title": "Declare", "sub": "counter + windows" }, { "title": "Try it", "sub": "sandbox tenant" }, { "title": "Choose cost", "moment": true }, { "title": "Promote", "sub": "to production" }, { "title": "Launch", "moment": true } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Writes the definition" } ], [ { "label": "Replays sample events" } ], [ { "label": "Picks exact or approx" } ], [ { "label": "Opens a config change" } ], [ { "label": "Turns the surface on" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Schema + bounds check" } ], [ { "label": "Disposable tenant state" } ], [ { "label": "Shows unit cost per type" } ], [ { "label": "Compatibility validation" } ], [ { "label": "Quota ceiling applied" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "In control", "Fine", "Blocked" ], "points": [ 1, 1, 0, 1, 1 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Tie-break rule not obvious" } ], [], [ { "label": "Cost of exact unknown" }, { "label": "Error bound hard to judge" } ], [ { "label": "Window change breaks history" } ], [] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Declared default tie-break" } ], [], [ { "label": "Cost shown in the diff" } ], [ { "label": "New counter version, not a mutation" } ], [ { "label": "Config live ≤ 60 s" } ] ] } ], "chain": true, "note": "The trough is a cost and accuracy decision the engineer is not equipped to make blind. Showing the unit cost of each counter type in the definition is what turns it from a guess into a choice.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "06-journey-remove-a-cheater", "title": "Journey — An Analyst Removes a Cheater From a Live Leaderboard", "layout": "journey", "actor": { "label": "Trust & safety analyst", "sub": "24/7 rota", "goal": "Take the illegitimate contributions out and leave the ranking correct", "trigger": "An automated inflation signal, or a report from a member near the top", "success": "Contiguous ranks, an auditable record, and nothing a reward was paid on changed silently" }, "phases": [ { "title": "Notice", "sub": "signal or report" }, { "title": "Contain", "sub": "freeze the scope", "moment": true }, { "title": "Prove", "sub": "read the evidence" }, { "title": "Retract", "sub": "bulk compensation", "moment": true }, { "title": "Reopen", "sub": "unfreeze" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Opens the inflation alert" } ], [ { "label": "Freezes the scope" } ], [ { "label": "Reads held contributions" } ], [ { "label": "Retracts by cause" } ], [ { "label": "Publishes again" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Quarantine already holding" } ], [ { "label": "Ranking stops publishing" } ], [ { "label": "Log slice, not a counter" } ], [ { "label": "Compensating deltas + rebuild" } ], [ { "label": "Contiguous ranks restored" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Fine", "Exposed" ], "points": [ 1, 1, 1, 0, 1 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "Ingestion must not stop" } ], [], [ { "label": "Season already closed" }, { "label": "Reward already paid" } ], [] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Reversible hold, not a drop" } ], [ { "label": "Freeze is read-side only" } ], [ { "label": "Log is the evidence" } ], [ { "label": "Correction record, not a rewrite" } ], [ { "label": "Cleared holds replay in order" } ] ] } ], "chain": true, "note": "The trough is a retraction that lands after closure, where a reward has been granted. The platform's answer is a correction record beside the original standing rather than a silent rewrite of a published result.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "07-layered-architecture", "title": "Leaderboard & Counting Service — Layered Architecture", "layout": "bands", "layerHeaderWidth": 160, "bands": [ { "name": "Experience", "nodes": [ { "id": "mobile", "label": "Mobile app", "kind": "external", "icon": "fa5_mobile_alt" }, { "id": "web", "label": "Web app", "kind": "external", "icon": "fa5_globe" }, { "id": "console", "label": "Tenant console", "kind": "app" }, { "id": "tsui", "label": "Trust & safety console", "kind": "app" } ] }, { "name": "Edge", "nodes": [ { "id": "lb", "label": "Global load balancer", "sub": "anycast", "kind": "integration", "icon": "gcp_lb" }, { "id": "armor", "label": "Edge policy", "sub": "Cloud Armor", "kind": "security" }, { "id": "authn", "label": "Token verification", "sub": "Identity Platform", "kind": "security", "icon": "gcp_security_identity" } ] }, { "name": "Service", "nodes": [ { "id": "ingest", "label": "Counting API", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "query", "label": "Query API", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "admission", "label": "Admission", "sub": "dedup, shard, hold", "kind": "app" }, { "id": "admin", "label": "Config API", "kind": "integration", "icon": "gcp_cloud_run" } ] }, { "name": "Processing", "nodes": [ { "id": "aggregate", "label": "Aggregation", "sub": "Dataflow streaming", "kind": "app", "icon": "gcp_dataflow" }, { "id": "project", "label": "Projection builder", "kind": "app", "icon": "gcp_dataflow" }, { "id": "closer", "label": "Season closer", "kind": "app", "icon": "gcp_integration_services" }, { "id": "rebuild", "label": "Rebuild runner", "sub": "replay ≥ 10×", "kind": "app", "icon": "gcp_dataflow" } ] }, { "name": "State", "nodes": [ { "id": "bus", "label": "Event log", "sub": "Pub/Sub", "kind": "queue", "icon": "gcp_pubsub" }, { "id": "bt", "label": "Bucket + ranked store", "sub": "Bigtable", "kind": "store", "icon": "gcp_bigtable" }, { "id": "redis", "label": "Rank cache", "sub": "Memorystore", "kind": "store", "icon": "gcp_memorystore" }, { "id": "spanner", "label": "Control plane store", "sub": "Spanner", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "gcs", "label": "Event archive", "sub": "Cloud Storage", "kind": "store", "icon": "gcp_cloud_storage" } ] }, { "name": "Platform", "nodes": [ { "id": "iam", "label": "Workload identity", "kind": "security", "icon": "gcp_iam" }, { "id": "kms", "label": "Key management", "sub": "event signing", "kind": "security", "icon": "gcp_security_identity" }, { "id": "obs", "label": "Observability", "sub": "lag, shards, cost", "kind": "platform", "icon": "gcp_observability" }, { "id": "bq", "label": "Warehouse export", "sub": "BigQuery", "kind": "platform", "icon": "gcp_bigquery" } ] } ], "edges": [ { "from": "ingest", "to": "bus", "label": "ack on durable", "kind": "sync" }, { "from": "query", "to": "redis", "label": "top-N, rank", "kind": "sync" }, { "from": "aggregate", "to": "bt", "label": "merge deltas", "kind": "async" }, { "from": "gcs", "to": "rebuild", "label": "replay", "kind": "batch" } ], "note": "Processing sits below Service deliberately: nothing in the request path waits on it. The only synchronous dependency of an accepted write is the event log.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "08-platform-components", "title": "Leaderboard & Counting Service — Components and Boundaries", "layout": "nested", "boxes": [ { "title": "Request plane — never waits on aggregation", "kind": "boundary", "dir": "row", "children": [ { "title": "Write path", "kind": "lane", "nodes": [ { "id": "capi", "label": "Counting API", "sub": "Cloud Run", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "valid", "label": "Validator", "sub": "schema, bounds, clock", "kind": "app" }, { "id": "dedup", "label": "Idempotency check", "sub": "24 h horizon", "kind": "app" }, { "id": "hot", "label": "Hot-key detector", "sub": "shard assignment", "kind": "app" }, { "id": "hold", "label": "Abuse quarantine", "sub": "reversible hold", "kind": "security" } ] }, { "title": "Read path", "kind": "lane", "nodes": [ { "id": "qapi", "label": "Query API", "sub": "Cloud Run", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "topn", "label": "Top-N resolver", "kind": "app" }, { "id": "rankr", "label": "Rank resolver", "sub": "histogram percentile", "kind": "app" }, { "id": "overlay", "label": "Own-write overlay", "sub": "read-your-writes", "kind": "app" }, { "id": "tagger", "label": "Staleness tagger", "sub": "version + as-of", "kind": "app" } ] } ] }, { "title": "Processing plane — rebuildable, restartable", "kind": "boundary", "dir": "row", "children": [ { "title": "Streaming", "kind": "lane", "nodes": [ { "id": "aggr", "label": "Aggregation job", "sub": "Dataflow, event time", "kind": "app", "icon": "gcp_dataflow" }, { "id": "acc", "label": "Accumulators", "sub": "exact, HLL++, min/max", "kind": "app", "icon": "gcp_dataflow" }, { "id": "fanin", "label": "Shard fan-in", "kind": "app" }, { "id": "dlq", "label": "Poison sink", "sub": "parse error kept", "kind": "risk" } ] }, { "title": "Batch and scheduled", "kind": "lane", "nodes": [ { "id": "pbuild", "label": "Projection builder", "sub": "versioned output", "kind": "app", "icon": "gcp_dataflow" }, { "id": "hist", "label": "Histogram builder", "kind": "app", "icon": "gcp_dataflow" }, { "id": "close", "label": "Season closer", "sub": "Workflows", "kind": "app", "icon": "gcp_integration_services" }, { "id": "replay", "label": "Rebuild runner", "sub": "≥ 10× real time", "kind": "app", "icon": "gcp_dataflow" } ] } ] }, { "title": "State", "kind": "boundary", "dir": "row", "children": [ { "title": "High volume, rebuildable", "kind": "lane", "nodes": [ { "id": "psub", "label": "Event log", "sub": "Pub/Sub", "kind": "queue", "icon": "gcp_pubsub" }, { "id": "arch2", "label": "Event archive", "sub": "GCS, 90 d + 13 mo", "kind": "store", "icon": "gcp_cloud_storage" }, { "id": "btb", "label": "Bucket store", "sub": "Bigtable", "kind": "store", "icon": "gcp_bigtable" }, { "id": "btr", "label": "Ranked store", "sub": "Bigtable", "kind": "store", "icon": "gcp_bigtable" }, { "id": "mem", "label": "Rank cache", "sub": "Memorystore", "kind": "store", "icon": "gcp_memorystore" } ] }, { "title": "Low volume, exact", "kind": "lane", "nodes": [ { "id": "spn", "label": "Control plane store", "sub": "Spanner", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "stand", "label": "Closed standings", "sub": "immutable, 5 y", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "audit2", "label": "Audit & retraction log", "kind": "store", "icon": "gcp_cloud_spanner" } ] } ] } ], "outside": [ { "id": "pbk", "label": "Product backends", "kind": "external" }, { "id": "cli", "label": "Product clients", "kind": "external" }, { "id": "mdir", "label": "Member directory", "kind": "external" } ], "edges": [ { "from": "cli", "to": "qapi", "label": "top-N, rank", "kind": "sync" }, { "from": "capi", "to": "psub", "label": "ack after commit", "kind": "sync" }, { "from": "psub", "to": "aggr", "label": "subscribe", "kind": "async" }, { "from": "aggr", "to": "btb", "label": "bucket deltas", "kind": "async" }, { "from": "pbuild", "to": "btr", "label": "ranked view vN", "kind": "sync" }, { "from": "qapi", "to": "mem", "label": "version-keyed read", "kind": "sync" } ], "note": "Two planes and one rule between them: the request plane may read processing-plane output but never waits on it. Product backends enter at the Counting API (view 09); the config API, the consoles, the warehouse export and every observability path are omitted for clarity.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "09-integration-surface", "title": "Leaderboard & Counting Service — Integration Surface", "layout": "hub", "left": { "title": "Who calls in", "nodes": [ { "id": "be", "label": "Product backend", "sub": "server-to-server", "rel": "events:batch", "dir": "in" }, { "id": "cl", "label": "Product client", "sub": "member token", "rel": "events (signed)", "dir": "in" }, { "id": "tcon", "label": "Tenant console", "rel": "counters", "dir": "in" }, { "id": "tscon", "label": "Trust & safety console", "rel": "retract, freeze", "dir": "in" } ] }, "centre": { "title": "Leaderboard & Counting Service", "nodes": [ { "id": "core", "label": "Counting API", "sub": "accept, dedup, log", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "read", "label": "Query API", "sub": "top-N, rank, percentile", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "cfg", "label": "Config API", "sub": "versioned definitions", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "ops", "label": "Operations API", "sub": "freeze, retract, rebuild", "kind": "security", "icon": "gcp_cloud_run" } ] }, "right": { "title": "What it depends on and feeds", "nodes": [ { "id": "ip", "label": "Identity Platform", "sub": "member tokens", "rel": "verify", "dir": "out", "icon": "gcp_security_identity" }, { "id": "dirr", "label": "Member directory", "sub": "display names", "rel": "resolve", "dir": "out" }, { "id": "nt", "label": "Notification service", "rel": "rank changes", "dir": "out", "kind2": "async", "icon": "fa5_bell" }, { "id": "rw", "label": "Reward service", "rel": "standings", "dir": "out", "kind2": "batch" }, { "id": "whh", "label": "Analytics warehouse", "rel": "export", "dir": "out", "kind2": "batch", "icon": "gcp_bigquery" } ] }, "note": "Four surfaces, deliberately separate: counting, reading, configuring and operating. The client write path is narrower than the backend path by design — it can only write counters declared client-writable. Workload identity authorises every service-to-service call and is omitted here for clarity.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "10-counting-data-flow", "title": "Leaderboard & Counting Service — Counting Data Flow", "layout": "flow", "chain": true, "align": "top", "stages": [ { "title": "Sources", "nodes": [ { "id": "s1", "label": "Session completion", "kind": "external" }, { "id": "s2", "label": "Vote or reaction", "kind": "external" }, { "id": "s3", "label": "View or play", "kind": "external" }, { "id": "s4", "label": "Round result", "kind": "external" } ] }, { "title": "Admit", "nodes": [ { "id": "a1", "label": "Validate", "sub": "schema, bounds", "kind": "app" }, { "id": "a2", "label": "Dedup", "sub": "idempotency key", "kind": "app" }, { "id": "a3", "label": "Classify key", "sub": "hot or median", "kind": "app" }, { "id": "a4", "label": "Hold if suspect", "kind": "security" } ] }, { "title": "Durable log", "nodes": [ { "id": "l1", "label": "Event log", "sub": "Pub/Sub 31 d", "kind": "queue", "icon": "gcp_pubsub" }, { "id": "l2", "label": "Archive writer", "sub": "Avro to GCS", "kind": "app", "icon": "gcp_cloud_storage" }, { "id": "l3", "label": "Event archive", "sub": "90 d hot, 13 mo cold", "kind": "store", "icon": "gcp_cloud_storage" } ] }, { "title": "Aggregate", "nodes": [ { "id": "g1", "label": "Event-time windows", "sub": "hour buckets", "kind": "app" }, { "id": "g2", "label": "Exact sums", "kind": "app" }, { "id": "g3", "label": "HLL++ uniques", "sub": "≤ 2% at p95", "kind": "app" }, { "id": "g4", "label": "Late bucket", "kind": "app" } ] }, { "title": "Project", "nodes": [ { "id": "p1", "label": "Bucket store", "sub": "Bigtable", "kind": "store", "icon": "gcp_bigtable" }, { "id": "p2", "label": "Window compose", "sub": "bucket addition", "kind": "app" }, { "id": "p3", "label": "Ranked view vN", "kind": "store", "icon": "gcp_bigtable" }, { "id": "p4", "label": "Rank histogram", "kind": "store", "icon": "gcp_bigtable" } ] }, { "title": "Serve & export", "nodes": [ { "id": "c1", "label": "Rank cache", "sub": "Memorystore", "kind": "store", "icon": "gcp_memorystore" }, { "id": "c2", "label": "Query API", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "c3", "label": "Warehouse", "sub": "BigQuery", "kind": "external", "icon": "gcp_bigquery" } ] } ], "edges": [ { "from": "l3", "to": "g1", "label": "replay", "kind": "batch", "route": "gutter" } ], "note": "One stream, two destinations: the live aggregation that feeds the screen, and the archive that makes every projection downstream of it disposable. The warehouse export runs off the archive (view 11).", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "11-storage-zones", "title": "Leaderboard & Counting Service — Storage Zones by Ownership", "layout": "nested", "boxes": [ { "title": "System of record — nothing else is", "kind": "trust", "dir": "row", "children": [ { "title": "Live log", "kind": "lane", "nodes": [ { "id": "z1", "label": "Event log", "sub": "Pub/Sub, 31 d, RPO 5 s", "kind": "queue", "icon": "gcp_pubsub" } ] }, { "title": "Replayable history", "kind": "lane", "nodes": [ { "id": "z2", "label": "Event archive, hot", "sub": "GCS standard, 90 d", "kind": "store", "icon": "gcp_cloud_storage" }, { "id": "z3", "label": "Event archive, cold", "sub": "GCS archive, 13 mo", "kind": "store", "icon": "gcp_cloud_storage" } ] } ] }, { "title": "Projections — droppable, rebuildable from the log", "kind": "boundary", "dir": "row", "children": [ { "title": "Aggregates", "kind": "lane", "nodes": [ { "id": "z4", "label": "Bucket store", "sub": "Bigtable, 400 d", "kind": "store", "icon": "gcp_bigtable" }, { "id": "z5", "label": "Shard map", "sub": "per hot key", "kind": "store", "icon": "gcp_bigtable" } ] }, { "title": "Ranked views", "kind": "lane", "nodes": [ { "id": "z6", "label": "Ranked store", "sub": "Bigtable, versioned", "kind": "store", "icon": "gcp_bigtable" }, { "id": "z7", "label": "Rank histogram", "sub": "value buckets", "kind": "store", "icon": "gcp_bigtable" } ] }, { "title": "Serving cache", "kind": "lane", "nodes": [ { "id": "z8", "label": "Rank cache", "sub": "Memorystore, no RPO", "kind": "store", "icon": "gcp_memorystore" } ] } ] }, { "title": "Exact and transactional — never shares a store with a counter", "kind": "trust", "dir": "row", "children": [ { "title": "Configuration", "kind": "lane", "nodes": [ { "id": "z9", "label": "Counter definitions", "sub": "Spanner, versioned", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "z10", "label": "Tenancy & quotas", "sub": "Spanner", "kind": "store", "icon": "gcp_cloud_spanner" } ] }, { "title": "Results and evidence", "kind": "lane", "nodes": [ { "id": "z11", "label": "Closed standings", "sub": "immutable, 5 y, RPO 0", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "z12", "label": "Retraction records", "sub": "append-only, 5 y", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "z13", "label": "Admin audit log", "sub": "5 y", "kind": "store", "icon": "gcp_cloud_spanner" } ] } ] } ], "outside": [ { "id": "z14", "label": "Analytics warehouse", "sub": "BigQuery, derived", "kind": "external", "icon": "gcp_bigquery" }, { "id": "z15", "label": "Member directory", "sub": "identity, not ours", "kind": "external" } ], "edges": [ { "from": "z1", "to": "z2", "label": "continuous", "kind": "async" }, { "from": "z2", "to": "z4", "label": "replay rebuild", "kind": "batch" }, { "from": "z4", "to": "z6", "label": "build vN", "kind": "sync" }, { "from": "z6", "to": "z8", "label": "warm on publish", "kind": "sync" }, { "from": "z11", "to": "z14", "label": "export", "kind": "batch" } ], "note": "Three zones, three different recovery stories: the log is backed up, the projections are rebuilt, and the cache is simply lost. A store that cannot be put in one of those three is in the wrong zone.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "12-data-model", "title": "Leaderboard & Counting Service — Data Model", "layout": "er", "canvas": { "width": 1680, "cols": 4 }, "rowGap": 240, "entities": [ { "id": "tenant", "name": "tenant", "row": 0, "col": 0, "kind": "store", "attrs": [ "tenant_id PK", "name", "event_quota_per_s", "member_cap", "deletion_sla_days" ] }, { "id": "counter", "name": "counter_version", "row": 0, "col": 1, "kind": "store", "attrs": [ "counter_id PK", "version PK", "tenant_id FK -> tenant", "type exact|approx|unique", "bounds_lo, bounds_hi", "lateness_horizon_s", "client_writable bool", "windows []", "unit_cost_per_m" ] }, { "id": "board", "name": "leaderboard", "row": 0, "col": 2, "kind": "store", "attrs": [ "board_id PK", "counter_id FK -> counter_version", "scope_kind global|region|cohort", "tie_break rule", "materialised_cap", "freshness_budget_s" ] }, { "id": "season", "name": "season", "row": 0, "col": 3, "kind": "store", "attrs": [ "season_id PK", "board_id FK -> leaderboard", "opens_at, closes_at", "timezone", "state open|closing|closed" ] }, { "id": "event", "name": "counting_event", "row": 1, "col": 0, "kind": "queue", "attrs": [ "event_id PK", "tenant_id FK -> tenant", "counter_id, counter_version", "member_ref pseudonymous", "delta signed", "event_time, ingest_time", "idempotency_key UQ", "origin backend|client", "signature" ] }, { "id": "bucket", "name": "bucket_aggregate", "row": 1, "col": 1, "kind": "store", "attrs": [ "counter_id PK", "member_ref PK", "window_bucket PK", "shard_no PK", "exact_sum", "sketch HLL++", "late_sum", "updated_at" ] }, { "id": "rankv", "name": "ranked_view", "row": 1, "col": 2, "kind": "store", "attrs": [ "board_id PK", "scope_key PK", "version PK", "as_of", "member_ref, value, rank", "histogram_bucket_counts" ] }, { "id": "standing", "name": "closed_standing", "row": 1, "col": 3, "kind": "store", "attrs": [ "season_id PK", "scope_key PK", "member_ref PK", "final_value, final_rank", "sealed_at", "immutable true" ] }, { "id": "hold", "name": "quarantined_contribution", "row": 2, "col": 0, "kind": "risk", "attrs": [ "hold_id PK", "event_id FK -> counting_event", "signal rate|lockstep|device", "state held|cleared|rejected", "decided_by, decided_at" ] }, { "id": "shard", "name": "shard_map", "row": 2, "col": 1, "kind": "store", "attrs": [ "counter_id PK", "key_ref PK", "shard_count", "observed_rate_per_s", "split_at, merged_at" ] }, { "id": "retract", "name": "retraction", "row": 2, "col": 2, "kind": "store", "attrs": [ "retraction_id PK", "cause deleted|banned|dq|fraud", "requested_by, authority", "scope event|member|campaign", "event_ids []", "created_at" ] }, { "id": "corr", "name": "correction_record", "row": 2, "col": 3, "kind": "store", "attrs": [ "correction_id PK", "season_id FK -> season", "retraction_id FK -> retraction", "prior_rank, revised_rank", "published_at" ] } ], "relations": [ { "from": "tenant", "to": "counter", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "counter", "to": "board", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "board", "to": "season", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "counter", "to": "event", "label": "1 : N", "from_side": "s", "to_side": "n3" }, { "from": "event", "to": "bucket", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "bucket", "to": "shard", "label": "N : 1", "from_side": "s", "to_side": "n" }, { "from": "bucket", "to": "rankv", "label": "N : 1", "from_side": "e", "to_side": "w" }, { "from": "board", "to": "rankv", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "season", "to": "standing", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "event", "to": "hold", "label": "1 : 0..1", "from_side": "s", "to_side": "n", "kind": "optional" }, { "from": "retract", "to": "corr", "label": "1 : N", "from_side": "e", "to_side": "w" } ], "note": "A counter definition is versioned and a change creates a new version; an event names the version it was counted under. Member identity is a pseudonymous reference everywhere below the control plane.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "13-count-to-rank-sequence", "title": "Critical Flow — From One Event to a Rank the Member Believes", "layout": "sequence", "lifelines": [ { "id": "cl", "label": "Product client", "kind": "actor" }, { "id": "capi", "label": "Counting API", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "log", "label": "Event log", "kind": "queue", "icon": "gcp_pubsub" }, { "id": "agg", "label": "Aggregation", "kind": "app", "icon": "gcp_dataflow" }, { "id": "bt", "label": "Bucket store", "kind": "store", "icon": "gcp_bigtable" }, { "id": "pb", "label": "Projection builder", "kind": "app", "icon": "gcp_dataflow" }, { "id": "qapi", "label": "Query API", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "cache", "label": "Rank cache", "kind": "store", "icon": "gcp_memorystore" } ], "messages": [ { "from": "cl", "to": "capi", "label": "POST /events (+ idempotency key)", "kind": "call" }, { "from": "capi", "to": "capi", "label": "verify token, signature, bounds", "kind": "self" }, { "from": "capi", "to": "capi", "label": "dedup lookup, 24 h horizon", "kind": "self" }, { "from": "capi", "to": "log", "label": "publish, wait for durable", "kind": "call" }, { "from": "log", "to": "capi", "label": "committed", "kind": "return" }, { "from": "capi", "to": "cl", "label": "202 accepted, p99 ≤ 25 ms", "kind": "return" }, { "from": "log", "to": "agg", "label": "deliver (at-least-once)", "kind": "async" }, { "from": "agg", "to": "agg", "label": "event-time window, shard merge", "kind": "self" }, { "from": "agg", "to": "bt", "label": "merge delta into bucket", "kind": "call" }, { "from": "bt", "to": "pb", "label": "changed keys", "kind": "async" }, { "from": "pb", "to": "pb", "label": "build ranked view v+1", "kind": "self" }, { "from": "pb", "to": "cache", "label": "publish version, warm top-N", "kind": "call" }, { "from": "cl", "to": "qapi", "label": "GET /rank?member=me", "kind": "call" }, { "from": "qapi", "to": "cache", "label": "read at pinned version", "kind": "call" }, { "from": "cache", "to": "qapi", "label": "top-N, histogram, as-of", "kind": "return" }, { "from": "qapi", "to": "qapi", "label": "apply own-write overlay", "kind": "self" }, { "from": "qapi", "to": "cl", "label": "rank + value + as-of + version", "kind": "return" }, { "from": "agg", "to": "qapi", "label": "if pipeline stalls: staleness widens, flagged", "kind": "error" } ], "note": "The acknowledgement at message 6 is the platform's only synchronous promise. Everything between it and message 17 is allowed to be seconds behind — except the overlay, which is what makes the member's own contribution visible.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "14-aggregation-pipeline", "title": "Leaderboard & Counting Service — Aggregation Pipeline", "layout": "flow", "chain": true, "align": "middle", "stages": [ { "title": "Read", "nodes": [ { "id": "r1", "label": "Log subscription", "sub": "per tenant", "kind": "queue", "icon": "gcp_pubsub" }, { "id": "r2", "label": "Parse & schema", "kind": "app" } ] }, { "title": "Deduplicate", "nodes": [ { "id": "d1", "label": "Keyed state", "sub": "idempotency key", "kind": "app" }, { "id": "d2", "label": "Drop counter", "sub": "dedup hit rate", "kind": "platform" } ] }, { "title": "Window", "nodes": [ { "id": "w1", "label": "Event-time assign", "sub": "hour bucket", "kind": "app" }, { "id": "w2", "label": "Lateness gate", "sub": "declared horizon", "kind": "decision" }, { "id": "w3", "label": "Late bucket", "sub": "visible, not silent", "kind": "app" } ] }, { "title": "Accumulate", "nodes": [ { "id": "c1", "label": "Exact sum", "kind": "app" }, { "id": "c2", "label": "HLL++ sketch", "sub": "uniques", "kind": "app" }, { "id": "c3", "label": "Per-shard state", "sub": "hot keys split", "kind": "app" } ] }, { "title": "Write", "nodes": [ { "id": "x1", "label": "Bucket upsert", "sub": "Bigtable", "kind": "store", "icon": "gcp_bigtable" }, { "id": "x2", "label": "Shard fan-in", "sub": "on read or flush", "kind": "app" } ] }, { "title": "Signal", "nodes": [ { "id": "y1", "label": "Changed-key stream", "kind": "queue", "icon": "gcp_pubsub" }, { "id": "y2", "label": "Lag metric", "sub": "per leaderboard", "kind": "platform" } ] } ], "edges": [ { "from": "r2", "to": "y2", "label": "parse failures", "kind": "error", "route": "gutter" }, { "from": "w2", "to": "y2", "label": "late ratio", "kind": "async", "route": "gutter" } ], "note": "Every accumulator is commutative and associative, which is what makes shard fan-in order-independent and a rebuild byte-identical to the original run.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "15-read-paths-by-query", "title": "Leaderboard & Counting Service — Read Paths by Query Type", "layout": "swimlane", "stages": [ "Authorise", "Resolve version", "Fetch", "Adjust", "Answer" ], "laneHeaderWidth": 180, "lanes": [ { "title": "Top-N (70% of reads)", "cells": [ [ { "id": "t1", "label": "Tenant + board scope", "kind": "security" } ], [ { "id": "t2", "label": "Pinned session version", "kind": "app" } ], [ { "id": "t3", "label": "Cache snapshot", "sub": "p99 ≤ 40 ms", "kind": "store" } ], [ { "id": "t4", "label": "Resolve display names", "kind": "app" } ], [ { "id": "t5", "label": "List + as-of", "kind": "integration" } ] ] }, { "title": "My rank (30% of reads)", "cells": [ [ { "id": "m1", "label": "Member token = subject", "kind": "security" } ], [ { "id": "m2", "label": "Last-write version", "kind": "app" } ], [ { "id": "m3", "label": "Histogram percentile", "sub": "p99 ≤ 120 ms", "kind": "store" } ], [ { "id": "m4", "label": "Own-write overlay", "sub": "≤ 1 s", "kind": "app" } ], [ { "id": "m5", "label": "Rank band + value", "kind": "integration" } ] ] }, { "title": "Neighbourhood", "cells": [ [ { "id": "n1", "label": "Same as my rank", "kind": "security" } ], [ { "id": "n2", "label": "Same version", "kind": "app" } ], [ { "id": "n3", "label": "Ranked-store slice", "kind": "store" } ], [ { "id": "n4", "label": "Exclude opted-out", "kind": "security" } ], [ { "id": "n5", "label": "±k members", "kind": "integration" } ] ] }, { "title": "Closed standing", "cells": [ [ { "id": "s1", "label": "Reward service identity", "kind": "security" } ], [ { "id": "s2", "label": "Season id, not version", "kind": "app" } ], [ { "id": "s3", "label": "Immutable snapshot", "sub": "Spanner", "kind": "store", "icon": "gcp_cloud_spanner" } ], [ { "id": "s4", "label": "Attach corrections", "kind": "app" } ], [ { "id": "s5", "label": "Final rank, sealed", "kind": "integration" } ] ] }, { "title": "Degraded path", "cells": [ [ { "id": "f1", "label": "Unchanged", "kind": "security" } ], [ { "id": "f2", "label": "Previous version", "kind": "risk" } ], [ { "id": "f3", "label": "Cache miss to ranked store", "sub": "p99 ≤ 150 ms", "kind": "risk" } ], [ { "id": "f4", "label": "Percentile instead of rank", "kind": "risk" } ], [ { "id": "f5", "label": "Answer says it degraded", "kind": "integration" } ] ] } ], "note": "Five paths, one authorisation model, and one difference that matters: only the member's own rank gets freshness spent on it. A closed standing is read by season, never by projection version.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "16-deployment-architecture", "title": "Leaderboard & Counting Service — Deployment Architecture", "layout": "nested", "boxes": [ { "title": "Google Cloud — europe-west1 (primary read region)", "kind": "cloud", "dir": "col", "children": [ { "title": "Edge and request services (regional, multi-zone)", "kind": "boundary", "nodes": [ { "id": "glb", "label": "Global load balancer", "sub": "anycast + Cloud Armor", "kind": "integration", "icon": "gcp_lb" }, { "id": "cr1", "label": "Counting API", "sub": "Cloud Run, 3 zones", "kind": "app", "icon": "gcp_cloud_run" }, { "id": "cr2", "label": "Query API", "sub": "Cloud Run, 3 zones", "kind": "app", "icon": "gcp_cloud_run" }, { "id": "cr3", "label": "Config + Ops API", "sub": "Cloud Run", "kind": "app", "icon": "gcp_cloud_run" } ] }, { "title": "Processing (regional)", "kind": "boundary", "nodes": [ { "id": "df1", "label": "Aggregation job", "sub": "Dataflow streaming", "kind": "app", "icon": "gcp_dataflow" }, { "id": "df2", "label": "Projection builder", "sub": "Dataflow batch", "kind": "app", "icon": "gcp_dataflow" }, { "id": "wf", "label": "Season closer", "sub": "Workflows + Scheduler", "kind": "app", "icon": "gcp_integration_services" } ] }, { "title": "Regional state", "kind": "boundary", "nodes": [ { "id": "bt1", "label": "Bigtable cluster", "sub": "buckets + ranked views", "kind": "store", "icon": "gcp_bigtable" }, { "id": "ms1", "label": "Memorystore", "sub": "rank cache, HA tier", "kind": "store", "icon": "gcp_memorystore" } ] } ] }, { "title": "Google Cloud — europe-west4 (standby read region)", "kind": "cloud", "dir": "row", "children": [ { "title": "Warm read path", "kind": "boundary", "nodes": [ { "id": "cr4", "label": "Query API", "sub": "scaled to minimum", "kind": "app", "icon": "gcp_cloud_run" }, { "id": "bt2", "label": "Bigtable replica", "sub": "async replication", "kind": "store", "icon": "gcp_bigtable" }, { "id": "ms2", "label": "Memorystore", "sub": "cold, rebuilds on cutover", "kind": "store", "icon": "gcp_memorystore" } ] } ] }, { "title": "Multi-region services", "kind": "cloud", "dir": "row", "children": [ { "title": "Log and archive", "kind": "boundary", "nodes": [ { "id": "ps", "label": "Pub/Sub", "sub": "global topic, 31 d", "kind": "queue" }, { "id": "gcs1", "label": "Cloud Storage", "sub": "dual-region archive", "kind": "store", "icon": "gcp_cloud_storage" } ] }, { "title": "Exact state", "kind": "boundary", "nodes": [ { "id": "sp", "label": "Spanner", "sub": "multi-region, RPO 0", "kind": "store" }, { "id": "bq1", "label": "BigQuery", "sub": "export target", "kind": "store", "icon": "gcp_bigquery" } ] }, { "title": "Platform services", "kind": "boundary", "nodes": [ { "id": "kms1", "label": "Cloud KMS", "sub": "signing keys", "kind": "security", "icon": "gcp_security_identity" }, { "id": "sm", "label": "Secret Manager", "kind": "security", "icon": "gcp_secretmanager" }, { "id": "mon", "label": "Cloud Monitoring", "sub": "+ Logging, Trace", "kind": "platform", "icon": "gcp_monitoring" } ] } ] } ], "outside": [ { "id": "cl2", "label": "Product clients", "kind": "external" }, { "id": "be2", "label": "Product backends", "kind": "external" } ], "edges": [ { "from": "cl2", "to": "glb", "label": "HTTPS / mTLS", "kind": "sync" }, { "from": "cr1", "to": "ps", "label": "publish", "kind": "sync" }, { "from": "ps", "to": "df1", "label": "subscribe", "kind": "async" }, { "from": "df1", "to": "bt1", "label": "write buckets", "kind": "sync" }, { "from": "bt1", "to": "bt2", "label": "replicate", "kind": "async" } ], "note": "Two regions, one write region. The standby serves reads at declared staleness; a cutover rebuilds its cache rather than replicating it, which is why RTO is 10 minutes and not seconds. Product backends reach the same edge as clients; the replay path is on view 11.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "17-observability", "title": "Leaderboard & Counting Service — Observability Matrix", "layout": "grid", "columns": [ "Admit", "Log", "Aggregate", "Project", "Serve" ], "laneHeaderWidth": 170, "rows": [ { "title": "Latency", "cells": [ [ { "label": "Accept p99", "sub": "target 25 ms", "kind": "platform" } ], [ { "label": "Publish confirm", "kind": "platform" } ], [ { "label": "Window close delay", "kind": "platform" } ], [ { "label": "Build duration", "kind": "platform" } ], [ { "label": "Top-N p99, rank p99", "kind": "platform" } ] ] }, { "title": "Freshness", "cells": [ [], [ { "label": "Log backlog seconds", "kind": "platform" } ], [ { "label": "Pipeline watermark lag", "kind": "platform" } ], [ { "label": "Projection lag per board", "sub": "the user-visible one", "kind": "risk" } ], [ { "label": "As-of age served", "kind": "platform" } ] ] }, { "title": "Correctness", "cells": [ [ { "label": "Dedup hit rate", "kind": "platform" } ], [ { "label": "Poison sink volume", "kind": "risk" } ], [ { "label": "Late-event ratio", "kind": "platform" } ], [ { "label": "Rebuild diff vs live", "kind": "platform" } ], [ { "label": "Rank monotonicity breaks", "kind": "risk" } ] ] }, { "title": "Skew & capacity", "cells": [ [ { "label": "Top-key write share", "kind": "platform" } ], [ { "label": "Partition imbalance", "kind": "platform" } ], [ { "label": "Shard count per key", "kind": "platform" } ], [ { "label": "Scopes materialised", "kind": "platform" } ], [ { "label": "Cache hit ratio", "kind": "platform" } ] ] }, { "title": "Abuse & integrity", "cells": [ [ { "label": "Quarantine volume", "kind": "risk" } ], [], [ { "label": "Lockstep clusters", "kind": "risk" } ], [ { "label": "Frozen scopes", "kind": "risk" } ], [ { "label": "Retractions served", "kind": "platform" } ] ] }, { "title": "Cost", "cells": [ [ { "label": "$ per M events", "kind": "platform" } ], [ { "label": "Archive GB by class", "kind": "platform" } ], [ { "label": "Worker hours", "kind": "platform" } ], [ { "label": "Rebuild cost per run", "kind": "platform" } ], [ { "label": "$ per M reads", "kind": "platform" } ] ] } ], "note": "Projection lag has its own alert and its own owner, because it is the only signal here that a member can see. Everything else in this matrix is a cause.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "18-projection-lifecycle", "title": "Leaderboard & Counting Service — Projection Lifecycle", "layout": "cycle", "centre": { "label": "Projections", "sub": "versioned" }, "nodes": [ { "id": "y1", "label": "Declared", "sub": "counter + board config", "kind": "app" }, { "id": "y2", "label": "Materialised", "sub": "first build from buckets", "kind": "app" }, { "id": "y3", "label": "Published", "sub": "version served, as-of set", "kind": "app" }, { "id": "y4", "label": "Advanced", "sub": "next version, cache warmed", "kind": "app", "icon": false }, { "id": "y5", "label": "Closed or rebuilt", "sub": "sealed, or replayed from log", "kind": "decision" }, { "id": "y6", "label": "Dematerialised", "sub": "idle scope released", "kind": "platform" } ], "ringLabels": [ "validated", "buckets exist", "readers pinned", "on changed keys", "or corrupt / disputed", "no reads in 30 d" ], "rx": 440, "ry": 220, "note": "The loop closes on dematerialisation, not on deletion: a released scope keeps its buckets and rematerialises on the next read. Rebuild is a step on the normal loop rather than an incident path.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "19-security-trust-zones", "title": "Leaderboard & Counting Service — Trust Zones", "layout": "zones", "zones": [ { "title": "Untrusted — the member's device", "kind": "trust", "nodes": [ { "id": "app2", "label": "Product client", "kind": "external" }, { "id": "sig", "label": "Client event signature", "sub": "app attestation key", "kind": "security" } ] }, { "title": "Perimeter", "kind": "trust", "nodes": [ { "id": "lb2", "label": "Load balancer", "sub": "TLS termination", "kind": "integration" }, { "id": "ca", "label": "Edge policy", "sub": "rate limit, bot score", "kind": "security" }, { "id": "tok", "label": "Token verification", "sub": "member = subject", "kind": "security", "icon": "gcp_security_identity" } ] }, { "title": "Semi-trusted — tenant-scoped services", "kind": "trust", "nodes": [ { "id": "capi2", "label": "Counting API", "kind": "app", "icon": "gcp_cloud_run" }, { "id": "qapi2", "label": "Query API", "kind": "app", "icon": "gcp_cloud_run" }, { "id": "quar", "label": "Quarantine", "sub": "holds, never drops", "kind": "security" } ] }, { "title": "Trusted — processing and projections", "kind": "trust", "nodes": [ { "id": "agg2", "label": "Aggregation", "kind": "app", "icon": "gcp_dataflow" }, { "id": "pb2", "label": "Projection builder", "kind": "app", "icon": "gcp_dataflow" }, { "id": "bt3", "label": "Counters & ranked views", "kind": "store", "icon": "gcp_bigtable" } ] }, { "title": "Restricted — evidence and results", "kind": "trust", "nodes": [ { "id": "sp2", "label": "Control plane store", "sub": "Spanner, CMEK", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "st2", "label": "Closed standings", "sub": "immutable", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "au2", "label": "Audit & retraction log", "sub": "append-only", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "kms2", "label": "Key management", "kind": "security", "icon": "gcp_security_identity" } ] } ], "edges": [ { "from": "app2", "to": "lb2", "label": "TLS, signed event", "kind": "sync" }, { "from": "ca", "to": "capi2", "label": "admitted request", "kind": "sync" }, { "from": "capi2", "to": "quar", "label": "suspect contribution", "kind": "error" }, { "from": "capi2", "to": "agg2", "label": "via durable log", "kind": "async" }, { "from": "pb2", "to": "bt3", "label": "write version", "kind": "sync" }, { "from": "qapi2", "to": "bt3", "label": "read only", "kind": "sync" }, { "from": "pb2", "to": "st2", "label": "seal at close", "kind": "sync" }, { "from": "quar", "to": "au2", "label": "hold decision", "kind": "sync" } ], "note": "A client may increase its own counter and nothing else. Nothing in the semi-trusted zone can write a closed standing, and nothing outside the restricted zone holds a signing key.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "20-write-authorisation-flow", "title": "Identity Flow — Who May Increase a Counter", "layout": "sequence", "lifelines": [ { "id": "mem2", "label": "Member", "kind": "actor" }, { "id": "cl3", "label": "Product client", "kind": "external" }, { "id": "idp2", "label": "Identity Platform", "kind": "security", "icon": "gcp_security_identity" }, { "id": "edge", "label": "Edge policy", "kind": "security" }, { "id": "capi3", "label": "Counting API", "kind": "integration", "icon": "gcp_cloud_run" }, { "id": "cfg2", "label": "Counter definition", "kind": "store", "icon": "gcp_cloud_spanner" }, { "id": "hold2", "label": "Quarantine", "kind": "security" }, { "id": "log2", "label": "Event log", "kind": "queue", "icon": "gcp_pubsub" } ], "messages": [ { "from": "mem2", "to": "cl3", "label": "completes an action", "kind": "call" }, { "from": "cl3", "to": "idp2", "label": "member token (cached)", "kind": "call" }, { "from": "idp2", "to": "cl3", "label": "short-lived JWT", "kind": "return" }, { "from": "cl3", "to": "cl3", "label": "sign event with attestation key", "kind": "self" }, { "from": "cl3", "to": "edge", "label": "POST /events", "kind": "call" }, { "from": "edge", "to": "edge", "label": "rate limit, bot score", "kind": "self" }, { "from": "edge", "to": "capi3", "label": "admitted", "kind": "call" }, { "from": "capi3", "to": "capi3", "label": "subject must equal member_ref", "kind": "self" }, { "from": "capi3", "to": "cfg2", "label": "is this counter client-writable?", "kind": "call" }, { "from": "cfg2", "to": "capi3", "label": "type, bounds, version", "kind": "return" }, { "from": "capi3", "to": "cl3", "label": "403 if not client-writable", "kind": "error" }, { "from": "capi3", "to": "hold2", "label": "inflation signal matched", "kind": "error" }, { "from": "hold2", "to": "capi3", "label": "held, reversible", "kind": "return" }, { "from": "capi3", "to": "log2", "label": "publish accepted event", "kind": "call" }, { "from": "log2", "to": "capi3", "label": "durable", "kind": "return" }, { "from": "capi3", "to": "cl3", "label": "202 + idempotency echo", "kind": "return" } ], "note": "Four independent refusals before anything is logged: the token's subject, the counter's client-writability, the declared bounds, and the inflation signal. Only the fourth is reversible.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "21-failure-classes", "title": "Leaderboard & Counting Service — Assumed Failure Classes", "layout": "nested", "boxes": [ { "title": "Absorbed in the write path — the member never learns", "kind": "boundary", "dir": "row", "children": [ { "title": "Delivery", "kind": "lane", "nodes": [ { "id": "e1", "label": "Duplicate delivery", "sub": "idempotency key", "kind": "app" }, { "id": "e2", "label": "Out-of-order events", "sub": "event-time windows", "kind": "app" }, { "id": "e3", "label": "Late beyond horizon", "sub": "visible late bucket", "kind": "app" } ] }, { "title": "Shape of the load", "kind": "lane", "nodes": [ { "id": "e4", "label": "Hot key, 1000× median", "sub": "adaptive sharding", "kind": "app" }, { "id": "e5", "label": "4× burst, 120 s", "sub": "log admits, typed shed", "kind": "app" }, { "id": "e6", "label": "Clock skew", "sub": "server ingest time kept", "kind": "app" } ] } ] }, { "title": "Visible as staleness, never as a wrong number", "kind": "boundary", "dir": "row", "children": [ { "title": "Serving", "kind": "lane", "nodes": [ { "id": "e7", "label": "Cache tier lost", "sub": "fall through, 150 ms", "kind": "risk" }, { "id": "e8", "label": "Aggregation stalled", "sub": "as-of ages, flagged", "kind": "risk" }, { "id": "e9", "label": "Region unavailable", "sub": "standby reads, RTO 10 m", "kind": "risk" } ] }, { "title": "Projections", "kind": "lane", "nodes": [ { "id": "e10", "label": "Bad ranking deploy", "sub": "serve previous version", "kind": "risk" }, { "id": "e11", "label": "Partition write loss", "sub": "replay that partition", "kind": "risk" }, { "id": "e12", "label": "Poison event", "sub": "sink, pipeline continues", "kind": "risk" } ] } ] }, { "title": "Requires a human decision, and leaves a record", "kind": "trust", "dir": "row", "children": [ { "title": "Integrity", "kind": "lane", "nodes": [ { "id": "e13", "label": "Inflation campaign", "sub": "quarantine + freeze", "kind": "security" }, { "id": "e14", "label": "Disqualified member", "sub": "bulk compensation", "kind": "security" }, { "id": "e15", "label": "Retraction after closure", "sub": "correction record", "kind": "security" } ] }, { "title": "Configuration", "kind": "lane", "nodes": [ { "id": "e16", "label": "Incompatible definition", "sub": "refused, new version", "kind": "decision" }, { "id": "e17", "label": "Tenant over quota", "sub": "shed, not spill", "kind": "decision" } ] } ] } ], "outside": [ { "id": "e18", "label": "Not handled: a product emitting wrong events", "sub": "the platform counts what it is told", "kind": "risk" } ], "note": "Three tiers by who notices: nobody, the reader as a widened as-of, and an analyst who must decide. The platform's job is to keep as much as possible in the first tier and nothing silently in the third.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } } ]