How this is built, and why the numbers can be checked

Reading /api/meta/…

Reading /api/meta/…

data/raw/*.json[.gz]      archived NHL play-by-play + shift charts
      │
      ▼  scripts/validate_raw_data.py   (hard gates, non-zero exit)
analytics/etl.py          pure-Pandas transform: clean, normalize,
                          distance/angle/xG/strength
      │
      ▼  manage.py ingest  (idempotent, per-game rebuild)
analytics/models.py       Game / Player / ShotEvent / PlayerGameStat
analytics/evaluator.py    + shift-accurate season & pair rows, EB
                          shrinkage, bootstrap replicates  (ALL at ingest)
      │
      ▼
analytics/api.py          read-only JSON, deterministic, 1 h cacheable
      │
      ▼  same origin in prod; Next server proxy in dev
frontend/src/lib/         framework-free chart engine + pure transforms
frontend/src/components/  thin React shells that mount them

The load-bearing choice: nothing statistical runs per request. τ estimation, shrinkage, the 500-replicate bootstrap and every pair row are computed once at ingest and persisted; the API recombines stored rows. That is what makes every endpoint deterministic, cacheable for an hour, and cheap enough to serve from a scale-to-zero container — and it is why a scenario projection returns in milliseconds rather than resampling on the hot path.

Reading /api/meta/…

• manage.py ingest is idempotent and per-game: re-running rebuilds each game's rows in place, so a partial or repeated run cannot double-count. Real files always beat synthetic ones.
• Cadence: on demand locally; on every CI run (a two-club, 160-game smoke against a throwaway database) and once in full (all 1,312 games, ~3 minutes) in the Docker boot check, so the full path is exercised before an image ships.
• Dirty rows are counted and dropped, never patched. The 55 rows the league ingest drops were verified individually: 22 goalie attempts (absent from the skaters-only roster by design) and 33 penalty shots, whose no-skaters-on-ice situation code the 5v5 parser correctly rejects.
• Live-season use would need one addition, and it is a scheduler, not a rewrite: the per-game rebuild already makes incremental ingest safe, and every estimate is derived from persisted per-game rows.

• Events, then aggregates. ShotEvent is the grain; every team, player, pair and season figure is derived from it. Nothing is stored that cannot be rebuilt by re-running ingest.
• On-ice rows are spell-scoped(PlayerSeasonOnIce, PairSeasonOnIcecarry a team). A traded player therefore appears in each club's matrix with only that club's minutes, instead of silently importing another team's context.
• Uniqueness is a database constraint, not a convention. One row per player-game, per player-team-strength season, per pair-team-strength season, per bootstrap replicate — so a double ingest fails loudly instead of inflating a rate.
• Indexes follow the access pattern: (team, strength) on every on-ice and replicate table, because every evaluator endpoint filters on exactly that pair.
• Pre-computed uncertainty is first-class. BootstrapReplicateAgg persists replicate aggregates and EvaluatorMeta persists τ, the seed, the floors and the strength-agreement rate — so the method block served with every response is a record of what actually ran, not a description of what was supposed to.
• SQLite on purpose. The dataset is a finished season, read-only in production, and fits in the image; a database server would add an operational dependency and buy nothing. The ORM layer is standard Django, so the move is a settings change.

• Every game file parses; gameIds are unique (each game is on two clubs' schedules and is stored once).
• Exactly 82 games per team, 32 teams, 1,312 unique games league-wide.
• Every non-null shot coordinate is on the rink (|x| ≤ 100, |y| ≤ 42.5); null-coordinate rows are counted, then dropped as dirty.
• Goal events reconcile with the official final score archived in the mirror — in all 1,312 games, with the shootout case handled explicitly.
• The derived 5v5 strength state is checked against the shot-level situationCode, with the agreement rate reported above and gated at 95%.
• The original 82 Utah files stay uncompressed and byte-identical, guarded by the extractor's byte-identity gate.

scripts/validate_raw_data.py exits non-zero on any hard failure; results are dated in data/PROVENANCE.md.

Reading /api/meta/…

• Every endpoint is GET-only, read-only and deterministic — the dataset is a finished season — so responses carry public, max-age=3600 and are safe for shared caches.
• Bad input returns 400 with a readable sentence, not a 500 and not a silent default: an unknown sort key names the legal ones; a sub-floor player is refused with the floor and the reason.
• Unknown teams return an empty games list rather than an error — a club with no ingested games is a data state, not a failure.
• Monitoring: /healthz is a no-DB liveness probe with no-store; Cloud Run request logs and container metrics cover the rest. This page is the deliberate extra — a contract check a reviewer can run without credentials.