Second Level
Fantasy-first NFL analytics. Free advanced stats framed around fantasy value —
every metric answers a fantasy question, recomputed in your league's exact
scoring and lineup — in a clean, fast interface with light and dark themes.
Live: secondlevel.app ·
API gridiron-api-t6hz.onrender.com
See CLAUDE.md for the full product spec, schema, and scope,
ARCHITECTURE.md for where everything lives, and
docs/ROADMAP.md for the milestone plan.
Architecture
Three fully decoupled apps (frontend talks to backend over HTTP only):
| Directory | Stack | Purpose |
|---|
frontend/ | React (Vite) + Tailwind + Recharts | Public stats UI |
backend/ | FastAPI + SQLAlchemy + Alembic | JSON API over PostgreSQL |
pipeline/ | Python + nflreadpy | Ingests nflverse data into PostgreSQL |
Prerequisites
- Docker Desktop — runs the local PostgreSQL instance
- Python 3.12 — for
backend/ and pipeline/. Use 3.12 specifically:
psycopg2-binary has no wheels for 3.13+ and building it from source needs
pg_config on your PATH. The backend runs from backend/.venv/ — the one
.claude/launch.json starts, and the only one with M5's PyJWT installed;
pipeline/ uses the older shared .venv/ at the repo root.
- Node 20+ — for the Vite frontend
Running locally
Everything below is already installed and the database already holds the
2020–2025 dataset, so day-to-day you only need to start the three services.
Open three terminals:
1. Database
Make sure Docker Desktop is running, then:
cd gridiron
docker compose up -d # starts Postgres 16; no-op if already running
Credentials (local dev): user gridiron / password gridiron / db gridiron
on localhost:5432.
2. Backend
cd gridiron/backend && .venv/bin/uvicorn app.main:app --reload --port 8000
--reload auto-restarts on code edits. Docs at http://localhost:8000/docs.
3. Frontend
cd gridiron/frontend
npm run dev # http://localhost:5173
Sanity check
curl localhost:8000/api/v1/health # {"status":"ok","database":"connected"}
Then open http://localhost:5173. Edit code → both servers hot-reload → refresh.
Signed-in features not working? curl localhost:8000/api/v1/health/auth reports whether
token verification is wired correctly — a misconfigured SUPABASE_URL and a genuinely
bad token both look like the same 401 without it.
Tests
cd gridiron/backend && .venv/bin/python -m pytest
Needs only the database from step 1 — no Supabase project, no network, no .env. The
suite creates its own gridiron_test, migrates it, and drops it at the end, so it never
touches your development data.
Coverage starts at the auth boundary (M5): token verification, JIT user provisioning,
cross-user isolation on every account endpoint, and the row-level-security lockdown that
keeps the account tables off Supabase's PostgREST API. See
backend/tests/README.md.
The same command runs on every pull request via GitHub Actions
(.github/workflows/backend-tests.yml).
First-time / from-scratch setup
Only needed on a fresh machine (the steps above are enough day-to-day):
# Env files
cp .env.example backend/.env
cp .env.example frontend/.env
# One virtualenv at the repo root, shared by backend/ and pipeline/
python3.12 -m venv .venv
.venv/bin/pip install -r backend/requirements.txt -r pipeline/requirements.txt
# Database schema
cd backend && ../.venv/bin/alembic upgrade head
# Data ingestion (see pipeline/README.md for details)
# Run in this order — each step depends on the rows the previous one wrote.
cd ../pipeline
../.venv/bin/python ingest_teams.py
../.venv/bin/python ingest_players.py
../.venv/bin/python ingest_schedules.py --seasons 2020 2021 2022 2023 2024 2025
../.venv/bin/python ingest_stats.py --seasons 2020 2021 2022 2023 2024 2025
../.venv/bin/python ingest_expected.py --seasons 2020 2021 2022 2023 2024 2025
../.venv/bin/python ingest_usage.py --seasons 2020 2021 2022 2023 2024 2025
../.venv/bin/python ingest_target_depth.py --seasons 2020 2021 2022 2023 2024 2025
# Frontend deps
cd ../frontend && npm install
Don't skip the last three. ingest_expected.py (expected components +
market share), ingest_usage.py (snaps + routes), and ingest_target_depth.py
(targets by pass depth) fill the columns and table that the Expected Points
board, every Insight score, and the player-page depth chart depend on. Skip
them and those pages render empty rather than erroring — a confusing failure to
debug.
Your data persists. Postgres data lives in the gridiron_pgdata Docker
volume, so it survives reboots and docker compose down. The only command
that wipes it is docker compose down -v (with -v) — avoid that flag and
you never need to re-run the pipeline.
Status
Deployed and live — frontend on Vercel, API on Render, database on Supabase.
Both auto-deploy on push to main.
Shipped so far:
| |
|---|
| Phase 1 | Data pipeline (2020–2025), FastAPI API, player + team leaderboards, player profiles, search, the Liquid Glass theme, and the Command Center home |
| M1 | Scoring-aware fantasy engine — every fantasy number recomputes to your exact league scoring, from a single metric registry |
| M2 | Expected fantasy points (scoring-aware), market share, goal-line carries, snap + route usage |
| M3 | Fantasy intelligence — VORP, Fantasy Opportunity Rating, Buy-Low and Sell-High indices, plus league context (size + starting lineup) |
| M4 | Exploration & viz — a curated scatter builder (19 charts across six position groups, players drawn as headshots), a comparison builder (up to 5 players, showing who leads each stat and by how much), usage and target-depth charts on player pages, and CSV export everywhere |
| M5 | Accounts & saved state — sign in with an email and password, or just have a link emailed to you, to keep multiple named league profiles, a watchlist of players (star them, filter any board to them, see them on the home page), and saved views of any board or chart. Nothing is behind a login: every page and share link works signed out exactly as before |
Next up: M6 — New Data Domains (depth charts, strength of schedule, a Vegas
board, and consensus projections). See docs/ROADMAP.md for
the full plan and CLAUDE.md for detailed status.
