How this site is built

This site tracks all 104 matches of the 2026 World Cup — 48 teams, 12 groups, and the knockouts through to the final at MetLife Stadium on July 19. Star any team and it lights up everywhere: its group table, its live chance of reaching the knockouts, and its projected road through the bracket. Around that sits a fully connected knockout tree, a fill-it-yourself fantasy bracket, a play-money betting pool, and a day-by-day calendar you can subscribe to as .ics. Every number is derived from the live results feed — nothing is typed in by hand. The whole thing is bilingual, with a client-side English / Brazilian-Portuguese toggle, and it re-publishes itself within about five minutes of a result landing.

The site is a static-site generator written in pure Python — standard library only. No framework, no bundler, no third-party packages at build time, and zero runtime dependencies. One render pass turns a JSON results feed (plus cached blurbs, odds and squads) into over 120 files: an HTML page for each of the 48 team hubs and 12 groups plus the home, bracket, fantasy, bets and calendar views; 49 subscribable .ics calendar feeds; one stylesheet; the client scripts; and the SVG art. The code is small, focused modules — feed fetch and cache, standings math, bracket resolution, timezone handling, shared HTML-fragment builders, and one module per page. Nothing runs on a server to render a page. The output is flat files a CDN serves directly.

The openfootball feed doesn't name knockout participants until they're known — it encodes each as a slot token. A group finish like 1C (Group C winner) or 3A/B/C/D (one third-placed team), or a match edge like W76 (winner of match 76). One resolver, resolve_slot() in wc/bracket.py, turns each token into either a decided nation or the set of teams still able to fill it. That single abstraction powers the bracket connectors, every team's road, the calendar's “3 possible” cells, the fantasy picker's options, and the betting board — all reading the same resolved slots. As results land, tokens resolve to nations automatically; nothing is ever hand-edited.

Two different questions, two different methods. For “will they reach the knockouts?” the engine runs a seeded 20,000-iteration Monte-Carlo: it simulates every remaining group match with plausible scorelines, ranks all twelve groups, then takes the eight best third-placed teams — exactly the real qualification rule, cross-group thirds and all. The seed is fixed, so identical data yields identical published percentages. For “have they clinched?” it doesn't sample — it enumerates. With n group games left it walks all 3ⁿ win/draw/loss combinations and shows a clinch-or-eliminated badge only when it holds in every single one. A badge is a proof, not a forecast.

The build is deterministic by contract: identical input data produces byte-identical output. The daily job leans on that. A GitHub Action polls the results feed every five minutes through the match window, but rewrites the cached feed and its timestamp only when something actually changed — so an unchanged poll regenerates the exact same bytes, produces no git diff, and triggers no deploy. Each real result is therefore exactly one Cloudflare Pages deploy, keeping the tournament far under the free tier's 500-a-month. Determinism is tested, too: five real tournament snapshots lifted from this repo's own git history — early groups, the thirds race, groups complete, mid-knockout with penalty shootouts, and today — get rebuilt and hash-compared, so any silent change to output is caught.

openfootball posts a result at full time, which is perfect for standings but blind during a match. So a thin Cloudflare Pages Function proxies ESPN's public scoreboard and returns a small normalized JSON the page polls for in-progress scores, edge-cached about 25 seconds so a crowd can't multiply upstream calls. The polling is kickoff-aware: each match carries its kickoff instant, and the client sleeps until just before the next one rather than hammering the endpoint all day. It's pure progressive enhancement — the static page already shows every kickoff time and every final score, so if the proxy is unreachable nothing breaks and live scores simply don't appear. Name reconciliation (USA ↔ United States) happens client-side to keep the proxy a thin pass-through.

The play-money pool is a real backend on a static site: a Cloudflare D1 (SQLite) database and a handful of Functions. Everyone starts with $100 and bets on knockout winners at odds snapshotted the moment the bet is placed. The money handling is written to survive concurrent requests. Stakes are debited with a guarded conditional write — subtracted only if the balance still covers them — so two simultaneous bets can't both overdraw. Cancellations delete-then-refund using SQL RETURNING, so a concurrent edit can't over-refund. Settlement runs on every page load and is idempotent and atomic: winners are credited exactly once inside a single transaction. Identity is deliberately passwordless — a display name plus a shared pool code is the whole credential, a stated friends-only, not-real-money tradeoff.

Each team's “road to the final” blurb is written by Claude — a short sports-desk paragraph recapping the last match and framing the next — then translated into Brazilian Portuguese by a second Claude pass. Neither runs at build time. Both are cached and keyed by a fingerprint: a SHA-256 of the exact facts that shaped the prompt (the opponent, the round, the kickoff, the candidate pool). When a result moves a team's situation its fingerprint changes and only that one blurb regenerates; everything else is untouched. The Portuguese cache is stamped with the English blurb's fingerprint, and the page serves a translation only while those fingerprints still match — so a stale translation can never publish. It silently falls back to English instead.