Architecture

A deep-dive into how the World Cup Pool is built, from the request path down to the database, plus the CI/CD topology and the domain model. Written for engineers extending or operating the system.

Executive summary

The World Cup Pool is a self-serve bracket competition for the 2026 FIFA World Cup. Friends create a pool, share a 6-character code, and each enters their predictions; a live leaderboard scores everyone as real results come in — no accounts, no passwords. It runs on fully managed infrastructure (Next.js on Vercel, Postgres on Neon), with privacy-friendly analytics, a daily automated database backup, and an end-to-end test suite that gates every deploy. An admin enters tournament results in a few clicks — or pulls them automatically from a live football-results API and confirms each change before it is applied.

Framework: Next.js 16 (App Router)
Runtime: React 19 · Node
Data: Prisma 6 · Neon Postgres
Host: Vercel — CI · CDN · Analytics

Operations

Visitor analytics

Vercel Web Analytics records page views via <Analytics /> in the root layout — privacy-friendly, no cookies.

Daily automatic backup

A scheduled GitHub Action runs pg_dump every day, storing each snapshot as a 90-day downloadable artifact.

End-to-end tests guard every deploy

Playwright runs the full create → pick → leaderboard flow against a real Postgres in CI on every push, and the unit suite gates the production build — a failing test blocks the deploy.

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. Each push builds on Vercel, and the build is gated by the unit-test suite before Next.js compiles.

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.

Pool

A shared bracket competition

id	cuid, PK
name	string
joinCode	string, unique (6-char)
locked	boolean — freezes picks
createdAt	datetime

↔ 1 → N Player

Player

A person in one pool (no auth)

id	cuid, PK — stored in cookie
displayName	string
poolId	FK → Pool (cascade)
joinedAt	datetime
@@unique	(poolId, displayName)

↔ N → 1 Pool↔ 1 → N Pick

Pick

Player predicts Team reaches Round

id	cuid, PK
playerId	FK → Player (cascade)
teamCode	FK → Team
round	GROUP\|FINAL4\|SEMIFINAL\|WINNER
groupId	string, nullable — only for GROUP
@@unique	(playerId, round, groupId, teamCode)

↔ N → 1 Player↔ N → 1 Team

Team

Seeded reference data (48 rows)

code	string, PK (e.g. BRA)
name	string
group	"A".."L"
reachedRound	string, nullable — set by admin
wonGroup	boolean — set by admin
isChampion	boolean — set by admin

↔ 1 → N Pick

4 · Key flows

Create / join a pool

HomeClient POSTs to /api/pools or /api/pools/[code]/join.
Route handler creates the Pool/Player and calls setPlayerIdCookie().
wcpool_pid (httpOnly, 90-day) is written; client routes to /pools/[code].

Make / edit picks

PicksClient builds the full pick set client-side with progressive reveal.
Save POSTs the entire set to /api/pools/[code]/picks.
Handler validates round counts, then $transaction([deleteMany, createMany]) — an atomic replace.
Reset = POST an empty array → deletes all picks.

Admin enters results

AdminClient submits to /api/admin/results with the ADMIN_TOKEN.
Handler verifies the token server-side, then updates Team result columns.
Locking a pool flips Pool.locked; the picks API then rejects writes.

Auto-fetch results (optional)

Admin clicks Fetch latest results; AdminClient POSTs to /api/admin/fetch-results (token-gated, needs FOOTBALL_API_KEY).
Server pulls standings + matches from football-data.org; lib/results.ts maps teams and derives flags — group winners only once a group is finished, plus Final-4, finalists, champion.
The endpoint returns PROPOSED changes and writes nothing.
Admin reviews the diff and confirms; changes save via /api/admin/results.

Leaderboard

Server component loads players + picks + teams in one pass.
scoreAllPicks() computes per-round and total points purely in memory.
Rows sort by total desc, then alphabetically by name as a tie-break.

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:

Round	Correct when…	Pts	×	Max
GROUP	team.wonGroup && team.group === pick.groupId	1	12	12
FINAL4	team reached ≥ Final 4 (cumulative)	4	4	16
SEMIFINAL	team reached ≥ Semi-Final (cumulative)	8	2	16
WINNER	team.isChampion	16	1	16
Maximum achievable				60

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.

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.
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%).
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).
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.

7 · Security & sessions

No passwords. Identity = the wcpool_pid cookie (httpOnly, SameSite=Lax).
The cookie alone grants nothing: every API route verifies the player belongs to the pool named in the URL.
Admin writes are gated by a server-checked ADMIN_TOKEN env var; the page UI never trusts the client.
Viewing another player's picks reuses PicksClient in a locked (read-only) mode.
Picks close when the admin locks the pool or the global deadline in lib/lock.ts passes (end of Jun 10, 2026) — enforced in both the picks API and UI.

8 · Connection & build notes

DATABASE_URL is the pooled (PgBouncer) Neon URL for app queries.
DATABASE_URL_UNPOOLED (directUrl) is used for migrations.
Prisma is a global singleton to survive serverless function reuse and avoid connection storms.
Pages use export const dynamic = "force-dynamic" so picks/leaderboards are never statically cached.
Build: prisma generate → vitest run → next build — a failing test blocks the deploy.
Vercel Web Analytics via <Analytics /> (@vercel/analytics) mounted in the root layout — privacy-friendly page-view metrics.

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.

On-demand (local)

npm run db:backup → timestamped, gzipped pg_dump in backups/ (git-ignored).
npm run db:restore -- <file> restores (prompts first; dumps use --clean --if-exists).
scripts/db-url.sh resolves the direct/unpooled URL — best for pg_dump.

Automated (GitHub Actions)

.github/workflows/backup.yml runs pg_dump daily + on demand.
Each dump is uploaded as a 90-day workflow artifact.
Needs a DATABASE_URL_UNPOOLED repo secret to run.
Neon point-in-time restore is a short-window safety net; these dumps are the durable copy.

10 · Repository map

app/
  layout.tsx                       root layout · mounts <Analytics/>
  page.tsx · HomeClient.tsx        create / join a pool
  pools/[code]/
    page.tsx                       pool dashboard
    picks/  page.tsx · PicksClient  progressive bracket picker
    leaderboard/page.tsx           scored standings + win % (server-computed)
  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
components/   Navigation (client · active-link) · HeroBanner · ThemeToggle
lib/          db.ts (Prisma singleton) · session.ts (cookie)
              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
.github/      workflows/backup.yml (scheduled pg_dump)
__tests__/    vitest unit + component tests
e2e/          playwright smoke tests

2026 FIFA World Cup Pool