PlayIQ
A dark-mode sports betting intelligence dashboard with an HUD / sci-fi aesthetic.
Pick a sport → browse today's slate → drill into a game for deep analysis across
matchup, form, roster, and sport-specific modeling tabs.
MLB · NBA · WNBA · NFL · NHL · NCAAB
What it does
- Slate triage — MLB game cards carry a hot-play badge (🔥 HOT PLAY / ▲ LEAN /
• LOOK / ⚠ FADE SP) so you know which games are worth opening before you open one.
- Per-game deep dives — Overview, Head-to-Head, Last 5, Rosters, AI Plays for
every sport, plus per-sport analytical tabs.
- MLB — Edge Finder (batter-vs-pitcher + transparent Log5 prop projections),
Pitching (K/Outs/ER/HR projections with per-start charts), Low HR model,
High Contact report, a 3D CSS lineup diamond, and a player lookup that works
before the batting order posts.
- MLB Live — compact scoreboard, bases, current matchup, measured pitch locations,
play feed and player stats. Live indicators cover moneylines, run lines, totals,
and approximate hitter-hit projections. Click an indicator to follow its original
line with a changing probability and trend. No slips, paper trading or wager
submission in the live experience (workflow).
- NBA / WNBA — Edge Finder with a per-player threshold projection model,
lineups (WNBA gets a 3D court view), and defense-vs-position.
- NFL — season offense/defense matchup board, with weekly-slate handling so
Sunday's games still show up on a Wednesday.
- AI Plays — bring your own Anthropic API key; Claude generates plays from the
game context and you can discuss them in free-form.
The only machine-learned component is the MLB first-5-innings money line model
(XGBoost, trained offline in CI). Every other "model" in the app is transparent,
inspectable arithmetic — Log5 matchups, Binomial/Poisson distributions, additive
scoring — and each score carries a why string or a methodology entry naming its
source, endpoint, inputs and formula.
Stack
Frontend — no build step, by design.
React 18 + Babel Standalone from a CDN; .jsx files are transpiled in the browser.
No bundler, no TypeScript, no npm-installed React. Fonts are Orbitron (display) and
Space Mono (everything else).
Backend — zero dependencies.
Pure Node http + https on port 3001. No npm packages at all, in-memory caching
(10-second minimum for the live game feed, 2 min for other MLB data,
15 min for historical BvP). Live updates use SSE with a polling fallback.
Data sources. ESPN's public API (no key), the MLB Stats API, and Baseball Savant.
Claude (Haiku) is called directly from the browser with a user-supplied key.
Running it locally
# 1. Backend (port 3001, no install step — there are no dependencies)
./server/start.sh # daemonizes, logs to server/server.log
# or: node server/index.js # foreground
# 2. Frontend — any static server from the repo root
python3 -m http.server 8000
Open http://localhost:8000. The frontend auto-detects localhost and points at
http://localhost:3001, ignoring the production backend URL, so local dev works
without editing anything.
Check the backend is up:
curl http://localhost:3001/api/health
To use AI Plays, paste an sk-ant-… key into the input in the top nav. It is stored
in localStorage and sent only to Anthropic.
Repo layout
index.html Shell: CDN scripts, nav, API-key input, global CSS
frontend/
data/ Fetchers + models, split shared/ + per-sport
shared/ui-atoms.jsx Primitive UI components (HudCard, Sparkline, …)
shared/tabs/ Sport-agnostic tabs
shared/screens/ Home / Games / GameDetail
sports/{mlb,nba,nfl}/ Sport-specific tabs
server/
index.js Node HTTP server (port 3001)
mlb/ nba/ Per-sport services and endpoints
data/f5_model.json Committed XGBoost model (CI writes this)
ml/ Offline Python training pipeline (runs in CI, not the app)
Note: data-layer.js, tabs.jsx, screens-v2.jsx and ui-atoms.jsx in the
repo root are dead legacy files left over from a reorg. index.html does not load
them. Always edit under frontend/.
Architecture notes
Scripts communicate through window. With no bundler, each file ends with an
Object.assign(window, { … }) export and later scripts read from there. The load
order in index.html is load-bearing: data layer → atoms → tabs → screens → app.
Backend URL resolution (frontend/data/shared/core.js), in order:
window.PIQ_API_BASE → localhost shortcut → the <meta name="piq-api-base"> tag →
localhost fallback.
The F5 model's train/serve parity is a contract. Features are defined once in
ml/f5_common.py and server/data/f5_feature_spec.json, and must be computed
identically by the Python collector and the live buildF5Features(). Training
embeds parity samples so the Node scorer self-checks to ~1e-7. Change a feature on
both sides, then retrain.
Deployment
- Frontend — static hosting (Vercel), no build command.
- Backend — Render, via the committed
render.yaml blueprint. On the free tier
the service sleeps after ~15 min idle, so the first request after a nap takes
~30s. After deploying, point <meta name="piq-api-base"> in index.html at the
service URL.
- F5 model —
.github/workflows/train-f5.yml retrains weekly, commits the model
JSON, and Render auto-deploys it.
Contributing conventions
- Keep the no-build-step constraint. No bundler, no TypeScript, no npm React.
- Keep the backend dependency-free. Add new endpoints rather than mutating existing ones.
- Use CSS variables from
:root in index.html; wrap card-shaped content in HudCard.
- New components must be added to the
Object.assign(window, …) export at the bottom
of their file, or the next script won't find them.
- Verify an ESPN payload before writing against it — field placement varies by sport
and a wrong key fails silently as a blank value, not an exception.
CLAUDE.md holds the full blueprint: file-by-file responsibilities, per-sport
gotchas, and how to add a tab, data source, or sport.
Disclaimer
PlayIQ is an analysis and research tool. Nothing it outputs is betting advice, and
no model here predicts outcomes reliably. Bet responsibly, or don't.
