Operations

1 · Runtime request path

Every page is a React Server Component that reads through a single Prisma client into Neon. Interactive surfaces hydrate as client components and mutate state through /api route handlers.

2 · CI/CD & deployment topology

main is branch-protected; all work lands via PRs. Every PR and push to main runs ci.yml: lint → unit tests → build (with a placeholder DATABASE_URL), and Playwright against an ephemeral Postgres service. On main, a deploy job runs only after both pass: vercel pull → build → deploy --prebuilt --prod. Vercel's own git deploys are disabled for main(vercel.json) but still build previews for pull requests. The workflow runs with a read-only GITHUB_TOKEN and pins every action to a commit SHA rather than a movable tag; Dependabot checks the pins monthly and opens one grouped PR, which lands through the same checks as any other change.

3 · Data model

Four entities. Team is reference data seeded from data/worldcup2026.ts; the admin mutates only its result columns. A Pick is the join between a player and a team for a given round.

4 · Key flows

5 · Scoring engine

lib/scoring.ts is pure and deterministic — no I/O — which makes it trivial to unit test. Knockout rounds are cumulative: a team that advances further also satisfies the earlier rounds (a finalist still earns its Final-4 points; the champion earns all three). Correctness is round-specific:

6 · Win probability (leaderboard)

The leaderboard's Win % column is each player's estimated chance of finishing 1st, from a Monte-Carlo simulation of the rest of the tournament. It appears only once a live knockout bracket is available.

1. Bracket — lib/tournament-bracket.ts pulls the knockout matches from football-data.org (FOOTBALL_API_KEY), resolves each team to our codes, and builds the current bracket: the earliest undecided round is the frontier; winners of adjacent matches meet in the next round up to the final. Finished semifinals / final lock in milestones for already-eliminated teams. The provider back-fills a round's teams only once the previous round is official, so a half-empty frontier (e.g. “ESP vs TBD”) is rebuilt from the previous round's winners; if a side is still unknown the bracket is treated as unavailable — it never simulates against a TBD opponent.
2. Match model — data/ratings.ts holds a FIFA/Elo rating per team; eloWinProb converts a rating gap into a single-match win probability (logistic on the difference — a ~100-point edge ≈ 64%).
3. Simulate — lib/win-probability.ts plays the undecided matches ~20,000 times. Each trial yields a full set of team results, fed through the same scoreAllPicks the leaderboard uses, then the players are ranked (a tie for 1st splits the credit).
4. Win % — the share of trials each player finished 1st. Computed server-side and cached (~10 min result, ~15 min bracket fetch) so a page view never re-runs the simulation or re-hits the API. An already-decided bracket skips the randomness — one deterministic pass.

Pure and unit-tested: the engine and bracket parser are covered by fixtures, including a frozen real-API snapshot. With no FOOTBALL_API_KEYor no knockout data, the column simply hides.

9 · Backups & durability

Pools, players, and picks exist only in Neon — the seed Team rows regenerate from data/worldcup2026.ts, but user data does not. After picks lock on Jun 10 that data is effectively frozen, so a snapshot at lock protects nearly everything.

10 · Repository map

app/
  layout.tsx                       root layout · <Analytics/> · canonical metadata
  page.tsx · HomeClient.tsx        create / join a pool
  pools/[code]/
    page.tsx                       pool dashboard
    picks/  page.tsx · PicksClient  progressive bracket picker
    leaderboard/ page.tsx · LeaderboardClient
                                   scored standings + win % · sortable table
  how-it-works/ · architecture/    static reference pages
  admin/  page.tsx · AdminClient    results entry (token-gated)
  api/
    pools/route.ts                 create pool
    pools/[code]/join/route.ts     join pool
    pools/[code]/picks/route.ts    atomic replace of a player's picks
    admin/results/route.ts         set team results / lock pool
    admin/fetch-results/route.ts   pull live results from football-data.org
    admin/data/route.ts            admin dashboard data (token-gated read)
    admin/players/[id]/route.ts    delete a player (picks cascade)
    health/route.ts                DB liveness check
components/   Navigation (client · active-link) · HeroBanner · ThemeToggle
lib/          db.ts (Prisma singleton) · session.ts (signed cookie) · admin-auth.ts
              site.ts (BASE_PATH · apiUrl) · rate-limit.ts (in-memory)
              scoring.ts (pure, cumulative) · lock.ts (pick deadline)
              results.ts (map providers + derive fetched results)
              win-probability.ts · tournament-bracket.ts (Elo Monte-Carlo)
data/         worldcup2026.ts (48 teams, rounds, points) · ratings.ts (Elo)
prisma/       schema.prisma · seed.ts
scripts/      backup-db.sh · restore-db.sh · db-url.sh
instrumentation*.ts · app/global-error.tsx   Sentry (inert until DSN set)
.github/      workflows/ci.yml (lint · test · build · Playwright + Postgres · deploy)
              workflows/backup.yml (scheduled, encrypted pg_dump)
__tests__/    vitest unit + component tests (Prisma mocked)
e2e/          playwright: smoke · admin (public pages) · flow (real DB)