Leaderboard & Counting Service  ·  View 12 of 21  ·  Data

Data Model

Twelve entities, and the two that are versioned because changing them in place would reinterpret history.

Editable source SVG draw.io All views
tenant tenant_id PK name event_quota_per_s member_cap deletion_sla_days counter_version 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 leaderboard board_id PK counter_id FK -> counter_version scope_kind global|region|cohort tie_break rule materialised_cap freshness_budget_s season season_id PK board_id FK -> leaderboard opens_at, closes_at timezone state open|closing|closed counting_event 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 bucket_aggregate counter_id PK member_ref PK window_bucket PK shard_no PK exact_sum sketch HLL++ late_sum updated_at ranked_view board_id PK scope_key PK version PK as_of member_ref, value, rank histogram_bucket_counts closed_standing season_id PK scope_key PK member_ref PK final_value, final_rank sealed_at immutable true quarantined_contribution hold_id PK event_id FK -> counting_event signal rate|lockstep|device state held|cleared|rejected decided_by, decided_at shard_map counter_id PK key_ref PK shard_count observed_rate_per_s split_at, merged_at retraction retraction_id PK cause deleted|banned|dq|fraud requested_by, authority scope event|member|campaign event_ids [] created_at correction_record correction_id PK season_id FK -> season retraction_id FK -> retraction prior_rank, revised_rank published_at 1 : N 1 : N 1 : N 1 : N 1 : N N : 1 N : 1 1 : N 1 : N 1 : 0..1 1 : N Leaderboard & Counting Service — Data Model 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. v 1.0 · owner Platform Architecture · date 2026-10

Decisions

  • A counter definition is versioned and an event names the version it was counted under. A change of type, bounds, tie-break or window set therefore creates a new version rather than silently reinterpreting events already in the log.
  • A ranked view is keyed by (board, scope, version), so publishing is a pointer move and rolling back a bad ranking build is pointing readers at the previous version.
  • A retraction is an entity, not a delete. It carries cause, requester and authority, and a correction record links it to the standing it changed.

Why the bucket key looks like that

  • (counter, member, window_bucket, shard_no) is what makes a hot key splittable without a schema change: the shard dimension already exists, and the shard map says how many of them are live.
  • The sketch column sits beside the exact sum rather than in a second table, so a counter that is both exact and unique-counting is one read.

Risks

  • Quarantined contributions are modelled against events, so a held event exists in the log but not in any counter. Any consistency check must know that, or it will report drift that is correct behaviour.
  • Pseudonymous member references mean a deletion request has to be executed in the directory and in the log's retraction path, and the two can diverge.
◀  Storage Zones by Ownership All views From One Event to a Rank  ▶
Solution Architecture v1.0 · Google Cloud · Platform Architecture · 2026-1012-data-model