Grudge
Grudge is the private web companion for a long-running fantasy football league. It combines the live ESPN league, recovered history back to 2005, predictions, weekly recaps, player and trade ledgers, manager-vs-manager Grudges, and versioned draft/trade models.
Production: https://grudge.planitnow.us
What the site owns
- Current season: scoreboard, standings, rankings, playoff odds, predictions, transactions and the League Wire.
- My Grudge: signed-in manager dashboard and current matchup context.
- History: seasons, franchises, managers, Team Records, Draft History, Grudges and source coverage.
- Players: NFL production, Grudge scoring, player profiles, career records and transaction/ownership history where evidence exists.
- Trades: durable trade ledger, voting, team-fit grades and player-production grades.
- Recaps: current-week homepage story plus the historical recap archive and optional weekly email.
Evidence boundaries
Grudge distinguishes authoritative league results from recovered supporting evidence.
| Era | Authority and coverage |
|---|
| 2005–2017 | Commissioner records decide final season results. ESPN supplies recovered weekly team scoreboards and draft boards. Historical player lineups and transaction ledgers are not available. |
| 2018–2025 | ESPN archive supplies standings, weekly player lineups, transactions, matchups and recovered draft boards. |
| 2026 onward | Live ESPN pipeline captures the current league and maintains derived data. |
The league did not play in 2020. Draft performance grades cover 2005 and 2007–2025. The 2005 source preserves all 128 draft coordinates: 119 named player rows plus nine excluded D/ST slots, eight identified by ESPN's defense lineup slot and one manually reviewed as a second defense. The 2006 board remains source history only because 21 non-defense zero-ID slots are still unresolved. Never invent data to fill an evidence gap. See docs/LEAGUE-HISTORY.md, docs/HISTORICAL-TRANSACTIONS.md and docs/LEGACY-TRADE-EVIDENCE.md before changing historical behavior.
Identity rules
These are architectural contracts, not implementation details.
franchise_key is the durable fantasy-franchise identity. A team name or ESPN team ID is not a franchise identity.franchise_season_teams maps a durable franchise into a season. franchise_season_results contains settled season outcomes separately.manager_key identifies a person. Grudges are manager-vs-manager and follow a person across franchise changes.nfl_players.player_key is the canonical player identity outside raw provider ingestion.- ESPN player IDs are season-scoped evidence aliases through
nfl_player_aliases; do not assume an early ESPN ID is globally durable.
- Provider evidence may enrich a canonical record. It must not silently redefine identity.
Read docs/DATA-MODEL.md before changing any identity mapping or historical join.
Models
Draft and trade grades are published, versioned results. Web requests read the published generation; they do not rebuild models on demand.
The current draft model evaluates regular-season production above replacement against historical expected production at the actual overall pick. Kicker and D/ST selections remain in draft-board coordinates but are not individually graded. Trade pages preserve separate team-fit and player-production views because they answer different questions.
Rules for model work:
- Do not change a grading formula casually or to make one displayed result look better.
- Reproduce and validate a model change against historical evidence before adopting it.
- Bump the model version when model semantics change.
- Keep display formatting out of ordering/math. Numeric results must be sorted as numeric values, not formatted text.
- A season with incomplete board, identity or scoring evidence must be blocked rather than partially graded.
See docs/MODEL-EVIDENCE.md and docs/MODEL-AUDIT.md.
Operations
The web app is intentionally usable from a phone. Admins can use:
/admin/status — production SHA, schema contract, ESPN/current-week freshness, NFL player refresh, model publications, recap status and GitHub workflow health./admin — membership and ownership-capture overview./admin/members — league access and team assignment./admin/recaps — recap delivery history./admin/trades — trade administration.
Production releases
Normal Git pushes do not deploy directly to production. Vercel Git auto-deploy is deliberately disabled.
.github/workflows/deploy-vercel.yml is the release authority. It can run in the scheduled release window or from an explicit deploy request. A successful release must verify the production schema, serve the exact requested commit, pass /api/health, smoke-test representative public routes, and only then advance the vercel-deployed marker branch.
vercel-deployed therefore means verified live, not merely “a Vercel hook was called.” See docs/DEPLOYMENT.md before changing release behavior.
Recurring data jobs
.github/workflows/weekly.yml — live ESPN capture, derived features, predictions, history refresh, ownership capture, model refresh, raw-data commit and optional recap..github/workflows/refresh-players.yml — current/prior NFL player-ledger refresh..github/workflows/refresh-model-results.yml — rebuild/publish model evidence after model-related changes..github/workflows/ci.yml — dependency audit, TypeScript, tests, production build, RLS attack suite, player browser checks and live admin gating.
The weekly and player/model writers share deployment/database safety controls. Do not bypass those workflows with ad-hoc production writes.
Development checks
Use Node 22. Before merging application changes, the normal baseline is:
npm ci
npm audit --audit-level=moderate
npm run typecheck
npm test
npm run players:import -- --dry-run
npm run build
Useful targeted checks:
npm run schema:verify
npm run models:validate
npm run models:build-data
npm run models:refresh -- --dry-run
npm run history:refresh
Production database migrations must follow the migration/release process in docs/DEPLOYMENT.md; never grant the web app the pipeline role or BYPASSRLS.
Rules for future coding agents
Before making a broad change, identify which data source and identity layer owns the fact being changed. In particular:
- Do not infer pre-2018 trades, weekly ownership or player starts from draft and final-roster endpoints.
- Do not let recovered ESPN data overwrite commissioner-authoritative 2005–2017 champions/final finishes.
- After the Grudge regular season, only explicit winners-bracket playoff games count in Grudge competitive records. Consolation/placement games remain source evidence but not tracked games.
- Do not reintroduce franchise-vs-franchise rivalry identity; Grudges are manager-vs-manager.
- Do not use ESPN player IDs as durable application player keys.
- Do not merge a current-season identity mapping with a settled season result simply because both mention the same franchise.
- Do not expose pipeline credentials to the Next.js application. User/admin reads must remain behind the existing Clerk + PostgreSQL RLS model.
- Do not treat a merged GitHub commit as deployed. Verify the exact production SHA through the controlled release flow.
- Surface uncertainty and source gaps in the UI instead of manufacturing complete-looking data.
Documentation map
docs/DATA-MODEL.md — canonical franchise, manager and player identities.docs/LEAGUE-HISTORY.md — authority by era and historical reconstruction rules.docs/MODEL-EVIDENCE.md — draft/trade model inputs, publication and evidence policy.docs/MODEL-AUDIT.md — validation of ranking and grading choices.docs/PLAYER-LEDGER.md — NFL player data, Grudge scoring and profile coverage.docs/DEPLOYMENT.md — controlled Vercel production process.docs/WEEKLY-RECAPS.md — recap product and delivery behavior.docs/HISTORICAL-TRANSACTIONS.md — 2018–2025 ESPN transaction repair.docs/LEGACY-TRADE-EVIDENCE.md — what can and cannot be established before 2018.docs/SETUP.md — environment and setup details.
When those documents conflict with an old comment or exploration file, prefer the current canonical data-model, evidence and deployment documents and verify the live schema before changing behavior.
