Gridiron HQ

A fantasy football decision dashboard for your ESPN league — lineup building, free-agent scouting, trade analysis, and a heuristic AI Coach. Built with Vite + React + TypeScript.

Default setup: Ten Idiots League (ESPN #973201555, 2026), managing Tush Pushers. Read-mostly companion — it does not submit lineups, waivers, or trades back to ESPN.

Running it

Requires Node.js 18+ and an OpenAI key in a local .env (see .env.example).

cp .env.example .env   # then set OPENAI_API_KEY
npm install
npm run dev            # Vite (:5173) + Roster Sensei API (:8787)

npm run dev starts both:

• Web — http://localhost:5173 (proxies /api → the API)
• API — http://localhost:8787 (OpenAI tool loop; key stays server-side)

On Vercel, the same /api/chat route is a serverless function (api/[[...route]].ts) — no second process. Set OPENAI_API_KEY in the Vercel project env (see docs/vercel-redeploy-sensei.md).

Useful scripts:

npm run dev:web   # Vite only
npm run dev:api   # API only
npm run build     # type-check + production bundle → dist/
npm run preview   # serve the production build

Features

Tab	What it does
Build roster	Fill starting slots from your team (and FAs); drag-and-drop; lineup edits persist in localStorage
Free agents	Need-aware pickup recommendations + browse/search the FA pool
Lineup	Starters + projected total; optional auto-optimize sandbox
Trade analyzer	Build give/get packages; week vs rest-of-season fairness (VOR / rank-based)
AI Coach	Position outlook vs league average + suggested trades (heuristic math, not an LLM)
League	Scout all 12 teams; jump into the trade analyzer
Chat with Roster Sensei	Agentic fantasy Q&A (OpenAI + tools); uses the header's selected team by default

Use the header team picker to manage or scout any squad in the league.

Refresh from ESPN

The Refresh from ESPN button updates, live from ESPN’s public APIs:

• Weekly projections and injury/status for rostered players and known free agents
• Current lineup slot assignments (starter / bench / IR)
• News and injury headlines

It does not rebuild who owns whom. Roster membership and the FA pool still come from the bundled snapshot under src/data/. A scheduled GitHub Action (.github/workflows/sync-snapshot.yml) runs npm run sync:snapshot every 6 hours and auto-commits + pushes to main when it changes, which triggers the normal Vercel deploy — so this should stay in sync on its own. Run npm run sync:snapshot by hand if you need it sooner than that, or if the Action's push access is disabled (see below).

Refresh calls ESPN from the browser. ESPN’s CORS headers currently allow this for the configured league; if that changes, the button surfaces an error instead of failing silently.

Project layout

src/
  data/       Bundled ESPN snapshot: your team, league rosters, free agents
  config/     Tunable knobs:
                league.ts   — league identity, ESPN URL, slots/positions, colors
                scoring.ts  — player-valuation constants
                trade.ts    — trade fairness + AI Coach suggestion counts
                pages.ts    — tab bar (add / remove / reorder pages here)
  lib/        Pure functions: scoring, roster needs, trade engine, ESPN + news clients
  hooks/      State: useFantasyApp, useProjectionRefresh, useNewsFeed, useDragAndDrop
  components/ Shared UI (header, nav, badges, news modal, …)
  pages/      One file per tab — mostly markup; state comes from the `app` prop
  App.tsx     Header + active page

Configuring it for your own league

1. Point src/config/league.ts at your ESPN league/season and rename your team.
2. Swap rosters and free agents under src/data/.
3. Tune valuation / trade aggressiveness in src/config/scoring.ts and src/config/trade.ts.
4. Add, remove, or reorder tabs in src/config/pages.ts.

Notes

• The AI Coach tab is a heuristic engine (VOR, scarcity, injury discounts, need matching) — not an LLM. Roster Sensei is the LLM agent.
• Local roster edits are stored per team in localStorage; if ESPN’s lineup snapshot changes on refresh, ESPN wins for slot sync.
• The "Refresh from ESPN" button calls ESPN from the browser; Roster Sensei keeps OPENAI_API_KEY on the server only. See docs/roster-sensei-agent-tools.md.
• Ownership tiers in the snapshot are derived from ESPN ownership % at export time and are not refreshed live.
• The sync-snapshot Action needs the repo's Actions setting Workflow permissions → Read and write permissions enabled (Settings → Actions → General) or its push step will fail with a permissions error.
• Sensei tools today: league/roster/byes, player lookup, needs, compare, trade grading (week+ROS), FA search/recommendations, news, and NFL remaining schedules. Live standings / ownership sync come next.