nfl-edge
One game simulator, four views: game lines, player props, DFS classic, and showdown — all derived from the same correlated draws so the outputs can never disagree with each other.
Start with docs/purpose.md. Design is in docs/architecture.md; standing constraints in AGENTS.md.
Stack
- Data: nflverse via the
jrakestr/nflreadpy fork (stats, pbp, schedules with spread/total/moneyline, ffopportunity expected stats, FantasyPros weekly consensus).
- Optimizer / GPP sim:
jrakestr/NFL-DFS-Tools (vendored under vendor/NFL-DFS-Tools, see vendor/NFL-DFS-Tools/VENDORED.md; we generate its projections.csv, player_ids.csv, and config.json).
- Storage: Supabase / Postgres (
db/migrations).
- Language: Python 3.11+, managed with
uv.
Setup
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env # fill in Supabase credentials
(cd vendor/NFL-DFS-Tools && uv sync) # NFL-DFS-Tools is vendored; this installs its own env
Weekly cadence
Ordered command list and LaunchAgent install: docs/ops.md. Snapshot job: every 30 min through Sunday 2026-09-13 night, every 2 h after.
Layout
src/nfl_edge/
ingest/ nflreadpy -> Postgres (idempotent)
priors/ team pace/strength, player usage, efficiency
sim/ drive-level Monte Carlo -> player stat lines -> fantasy points
outputs/ lines, props, dfs_export, correlations (all read from sim draws)
market/ free lines from nflverse schedules, manual prop lines, edge calc
dfs/ wrappers around NFL-DFS-Tools optimizer and GPP simulator
results/ grading, CLV, calibration
cli.py `nfl-edge ingest|sim|lines|props|dfs|grade`
config/ scoring.yaml, sim.yaml, dfs/*.json
db/migrations/
data/ dk/ fd/ salary exports, props/ manual prop lines (gitignored)
web/ Next.js app (Edge board, prop detail); reads model.* read-only
Web app
cd web && npm install && npm run dev # http://localhost:3000 -> /week/<newest week with a run>
npm run lint && npm run typecheck && npm test && npm run build
web/.env.local holds DATABASE_URL = the Supabase session pooler URI (IPv4; the direct host is IPv6-only and Vercel cannot reach it). Never committed. On Vercel the project's Root Directory is web and the same variable is set in the project's environment. Spec: docs/design-system.md.
Status
Scaffold only. Build order is in docs/architecture.md §8.
