Illini Fantasy Hoops
A private fantasy league for men's college basketball. Managers draft real
players, set a lineup that locks per game at tip-off, and play weekly head-to-head
matchups scored on the CBB Player-Score model. Waivers run as a blind FAAB
auction, trades go through a review window, and the commissioner tunes every
league setting from a screen.
There is no background worker. The draft clock, waiver runs, and trade
executions are all settled on read — the first request past a deadline does the
work that was due, at the time it was due — so the league stays correct whether
someone refreshed all night or nobody looked for a week.
For the phase-by-phase design history and the reasoning behind each decision, see
DEVLOG.md.
Stack
- Web app — Next.js 16 (App Router), React 19, in
apps/web
- Domain logic — TypeScript packages in
packages/*, imported directly by
both the web app and the CLI scripts, so a screen cannot disagree with a
settlement
- Database — Postgres (Neon in production), plain SQL migrations,
pg driver
- Data sources — Barttorvik (stat spine), CollegeBasketballData (teams,
ratings, schedule), RotoWire (injuries), NCAA CSV (recruits)
- Tooling — npm workspaces,
tsx for scripts and tests, tsc -b for
typecheck
Layout
packages/scoring the six-block Player-Score model; weights and bounds are data
packages/sources clients for Barttorvik, CBBD, RotoWire
packages/crosswalk resolves one source's player id to another's
packages/db migrations and the data layer
packages/ingest pulls a night of games into the database
packages/league draft, lineups, settlement, waivers, trades, settings
scripts/* CLI entry points for every package (see Commands)
apps/web the Next.js app
Prerequisites
- Node 20+
- Postgres — only for running the test suite and for local end-to-end work.
Production uses Neon.
- A CollegeBasketballData API key — for ingesting real data. Free tier is
1,000 calls/month; the client caches every response to
.cache/ and tracks the
remaining quota. Not needed just to run the app against an already-populated
database.
Setup
npm install
Create .env.local (gitignored) with:
DATABASE_URL=postgresql://… # pooled connection
DATABASE_URL_UNPOOLED=postgresql://… # direct connection; migrations use this
CBBD_API_KEY=… # only for ingest
AUTH_SECRET=… # any long random string
AUTH_URL=http://localhost:3000 # must match the port you run dev on
Database
Migrations run against any Postgres. A disposable local one:
docker run -d --name illini-pg -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=illini \
-p 55432:5432 postgres:18-alpine
export DATABASE_URL=postgresql://postgres:dev@localhost:55432/illini
npm run migrate # applies pending migrations; idempotent
The db test suite creates and drops its own illini_test database.
Production is a Neon project linked with neon link, which writes and keeps
.env.local current. Migrations prefer DATABASE_URL_UNPOOLED because Neon's
pooler multiplexes sessions and DDL wants a dedicated connection.
Running the app
npm run dev # http://localhost:3000
Two things that will otherwise cost you an afternoon:
AUTH_URL pins the port. next dev falls through to the next free port if
3000 is taken, but the invite link on /commissioner is built from AUTH_URL.
Free port 3000 or move AUTH_URL to match.- One
next dev per directory. A second one exits and names the PID of the
first. To run a second copy, npm run build then npx next start --port 3006.
Browsing a finished season
The sample data is February 2026, so against the real clock every game has
tipped off and every lineup is frozen. Two env vars unpin the clock:
ILLINI_TODAY=2026-02-14 # the date the app treats as today
ILLINI_NOW=2026-02-14T18:30:00Z # the instant the lineup lock measures against
ILLINI_TODAY alone keeps the real time of day. Set both to freeze a specific
moment — useful for screenshots and for seeing the lineup controls at all.
Screens
| route | |
|---|
/home | the live matchup, tonight's slate, and what needs you |
/team | tonight's startable players, per-game locks, slot validation |
/league | the week's matchup, scored live from stored player scores |
/players · /players/:id | the pool ranked by season Player-Score; per-night game log |
/standings · /playoffs | settled weeks only |
/waivers | the wire, your sealed claims, every team's budget |
/trades | propose, answer, review, history |
/draft | the draft room — clock, best available, your queue, the board |
/commissioner · /commissioner/settings | invites, seats, and every league number — commissioner only |
/signin · /join/:token | sign in; redeem an invite |
Commands
| command | |
|---|
npm run dev | web app |
npm run build | production build |
npm test | test suite (needs a local Postgres) |
npm run typecheck | tsc -b across packages and scripts |
npm run migrate | apply pending migrations |
npm run ingest -- <verb> | pull source data (setup, schedule, night, range, link, injuries) |
npm run league -- <verb> | league operations (create, draft, lineups, settle, standings, invite, waivers, trades, settings, passwd, …) |
npm run season | build and play a full 2025-26 league over ingested data |
npm run backtest | the scoring-model validation checks |
npm run budget | CBBD quota against projected usage |
npm run pool | draft-pool coverage report |
npm run crosswalk | crosswalk accuracy against live RotoWire injuries |
Passwords and usernames are managed by the commissioner from the CLI — there is
no self-serve reset and nothing emails anybody:
npm run league -- passwd <username|email> <password>
Auth
A username and a password, stored in app_user (scrypt, parameters travel with
the hash). Sessions are rows in auth_session keyed by a random httpOnly
cookie; signing out is a DELETE. The invite link hands over a team, not a
session — redeeming one is where a manager picks their username. The whole of it
is apps/web/lib/auth.ts.
