SV Dugout Pulse
Real-time baseball player tracker for Stadium Ventures. Monitors MLB, MiLB, and NCAA players, displays stats on a live dashboard, and sends Slack alerts for notable performances.
Live Dashboard
URL: https://stadium-ventures.github.io/sv-dugout-pulse
Quick Reference
Key Files
| File | Purpose |
|---|
index.html | The dashboard UI |
data/current_pulse.json | Player stats data (auto-updated by cron) |
src/roster_manager.py | Fetches roster from Google Sheet |
src/stats_engine.py | Fetches stats from MLB API + NCAA scrapers |
src/performance_analyzer.py | Grades performances (Milestone/Standout/Good/Routine/Soft Flag) |
src/alerts.py | Slack alert logic |
src/config.py | Settings, thresholds, column mappings |
main.py | Main script that orchestrates everything |
scripts/milb_watch.py | Daily MiLB watch — form + usage vs. season baseline (lull / usage-down / no-games / trending-up) → #dugout-pulse, 8:30 AM ET |
generate_test_data.py | Creates fake data for UI testing |
.github/workflows/pulse.yml | Automated cron schedule |
Slack Alerts
Alerts are sent to #dugout-pulse when:
| Trigger | Who | Example |
|---|
| Home run | Any player, any tier | "Dax Kilby (T1) just hit a HR!" |
| Pitcher enters game | Any pitcher, any tier | "Garrett Whitlock (T1) is pitching!" |
| 5+ strikeouts | Any pitcher, any tier | "Garrett Whitlock (T1) has 6 K's!" |
| 3+ times on base | T1/T2 hitters only | "Kellon Lindsey (T1) has reached base 3+ times!" |
Adjusting Alert Rules
Edit src/alerts.py to change thresholds or add new triggers. The check_and_send_alerts() function contains all the logic.
MiLB Watch (daily, 8:30 AM ET)
The alerts above fire off a single game. scripts/milb_watch.py answers a
different question — is this guy playing differently than he has all year? —
which is what earns a front-office or farm-director call.
For every client at an affiliated level (CPX/A/A+/AA/AAA) it grades the last 14
and 30 days against that player's own season line with the compared window
removed, using the same OPS/ERA thresholds as the dashboard's window grades
(src/window_grader.py), and posts four kinds of finding to #dugout-pulse:
| Trigger | Meaning |
|---|
| 🔻 Lull | Form dropped ≥ .150 OPS (or ERA rose ≥ 1.50) off his own baseline and landed in Steady/Cold |
| ⏳ Usage down | Hitters only, two reads on the 14/30 spans: role — PA per game played ≤ 70% of his season baseline ("still playing, no longer starting"); share — games played out of his team's games, down ≥ 25 points ("no longer in the lineup") |
| 😶 No games | Played this year, nothing in 14 days, and not on the IL |
| 📈 Trending up | Form gained ≥ .150 OPS (or ERA dropped ≥ 1.50) and landed in Solid/Hot — call while it's live |
A lull isn't only a rate collapse: losing playing time is a lull too, and it
shows up first, so a thin recent sample gets read for usage rather than
dismissed. The two usage reads answer different questions on purpose: "fewer
plate appearances than before" silently adds up three causes — the team played
fewer games, he was in the lineup fewer times, and he batted fewer times per
game. Role (PA per game played) is the earliest tell and is immune to both the
schedule and an org change. Share divides the schedule out, and is voided when a
player changed orgs inside the window — his new club's earlier games were never
his to miss.
Season over (2026-09-09): a player whose club has finished playing is off
the watch. The gate is the club's schedule, not a calendar — it has played
recently and has nothing left to play over the next two weeks, playoffs
included. So Single-A and High-A players drop out the week after their leagues
close, except those on playoff clubs, who stay live until elimination; Double-
and Triple-A fall out on their own dates; Complex-league players went in late
July. A shuttered player posts no findings and owes no closeout, is named once
in the footnote of the next post that goes out, and comes back the first time
his club has a game scheduled. The verdict is sticky through the offseason,
when the schedule returns nothing either way.
Absence findings are checked against the MLB Stats API's roster
entries and dropped when the player is on the IL or rehabbing — the org already
told us why he isn't playing. A player just activated off the IL gets the same
exclusion even though his roster status already reads "Active" again: the
transactions endpoint, not the roster snapshot, is what still knows he was out,
which is the only way to tell a real no-games absence from an injury that just
ended. The same closed-out stint also voids the usage-share read, not just
idle — a few games back from injury reads as a usage crash otherwise, since his
own team-games share for the hurt stretch is genuinely near zero, which is a
rehab ramp-up, not a benching. Rate verdicts still respect sample floors (40 PA /
15 IP baseline; 25 PA / 6 IP over 14 days; 45 PA / 12 IP over 30 days).
Cadence: a player is flagged the day he first qualifies, then not again
until his re-report window is up — 7 days for hitters, 14 for pitchers. If
nobody is new and nobody is due, the post is skipped entirely. Dropping below
the bar for a day doesn't reset the clock; a status flip (lull → trending up) is
a new finding and posts at once. That update is owed even if he's resolved by
then — a ✅ Back to normal line closes him out once, rather than letting a
player who quietly returned to normal vanish with no follow-up. Every tracked
player — posted or not — lands in data/milb_watch.json with both windows'
reads, how long the finding has been standing, and when he last posted.
The Slack layout is locked and pinned byte-for-byte by
test_locked_message_format in tests/test_milb_watch.py. If that test fails,
the format changed — that's the point. Preview without sending:
python -m scripts.milb_watch --dry
Data Sources
| Level | Source | Reliability |
|---|
| MLB/MiLB | Official MLB Stats API (free, no key required) | High |
| NCAA | Sidearm Sports → StatBroadcast → D1Baseball → stats.ncaa.org | Varies by school |
NCAA Notes
NCAA data is fragmented. The system tries multiple scrapers in order:
- Sidearm Sports - Many Power 5 schools
- StatBroadcast - Live stats platform
- D1Baseball.com - Covers all D1
- stats.ncaa.org - Fallback
If a school's data isn't populating, you may need to add their specific feed URL to src/stats_engine.py.
How to Edit Code
Option 1: Edit directly on GitHub (simple changes)
- Go to https://github.com/Stadium-Ventures/sv-dugout-pulse
- Navigate to the file you want to edit
- Click the pencil icon (Edit)
- Make changes
- Click "Commit changes"
- Dashboard updates automatically within minutes
Option 2: Use Claude Code (complex changes)
- Open Terminal
- Run:
cd ~/sv-dugout-pulse && claude
- Describe what you want to change
- Claude will edit the code
- Push changes:
git add -A && git commit -m "Your message" && git push
How to Resume This Project in Claude Code
cd ~/sv-dugout-pulse
claude
Then tell Claude what you want to do. It will have access to all the code.
Secrets (stored in GitHub)
These are configured in GitHub → Settings → Secrets and variables → Actions:
| Secret | Purpose |
|---|
ROSTER_URL | Google Sheet CSV URL (master roster) — no default in code |
RECRUITS_URL | Google Sheet CSV URL (recruits) — no default in code; unset = no recruits |
SLACK_WEBHOOK_URL | Slack incoming webhook |
Do not share these publicly. If compromised, regenerate them.
Roster source (sheet → SV Registry)
Clients come from ROSTER_SOURCE (repo Actions variable):
sheet (default when unset — the master sheet's published CSV, ROSTER_URL) or
registry — the SV Registry's authenticated projection
(GET https://sv-registry.vercel.app/api/roster-projection, Bearer token from the
Actions secret SV_REGISTRY_ROSTER_TOKEN, scope read:roster-projection).
Rollback is "set ROSTER_SOURCE back to sheet". Recruits (non-clients) always
come from their own sheet (RECRUITS_URL) and are never pruned against the
projection.
- Registry rows are mapped onto the sheet's headers, so everything downstream is
unchanged. Canon position labels map to this app's routing: RHP/LHP/SP/RP/P/…
→ Pitcher, "RHP/OF"-style or Two-Way → Two-Way, everything else → Hitter.
- Joins: each player carries the registry
slug and MLB id.
- Fail closed: a missing token, 401/403, a malformed or too-small (< 40 rows)
response, or a response that does not assert
contains_no_contact_data is an
error. There is no fallback to the sheet; the run uses the last good
registry cache (< 24 h, prunes disabled) or aborts.
- Peak WAR / wRC+ / ERA are not in the registry projection. The chips and the
Peak card read them from the Scouting Hub (
/api/scouting-ref, by MLB id) for
anyone signed in with the hub password, so the flip to registry does not blank
them. Without the hub, the page falls back to the roster's peak fields, which
the registry does not carry, so those viewers see no chips. The daily
no-peaks alert was removed in #47.
- #sv-automation alerts on this path (at most once a day each, state in
data/_roster_source_alerts.json): the registry read failed and the run is on the
last saved list; the dual-run read failed; the registry roster has no peaks. A
registry failure with no saved list fails the run, and pulse.yml's "Alert on
failure" step posts.
- Dual run: with
ROSTER_SOURCE=sheet and the token set, each run logs difference
counts only (these Actions logs are public). Names: run
python -m scripts.roster_dual_run locally.
Open decision (Tom) — the token is BLOCKED until it is made. This repo and its
Pages site are public, and the registry's policy ("no public anything", enforced by
its roster-projection selftest) forbids assigning a service token to a public repo.
Either:
- make the repo private (check the plan: Pages on a private repo may still be
publicly served unless it is private Pages), or
- keep it public and never commit or publish roster-derived fields beyond what the
dashboard already shows — the cache allowlist below enforces that — with the
token held only as an Actions secret, and record that exception in sv-registry.
The code works unchanged either way; only where the token may live differs.
Privacy — this repo and its Pages site are PUBLIC
Everything committed under data/ is served by GitHub Pages and readable by anyone
(the dashboard password gate is not real auth). So:
data/roster_cache.json is written through an allowlist
(ROSTER_CACHE_FIELDS in src/config.py): name, MLB id, team/level/affiliate,
position, draft class, tier, status, client flag. Nothing else can reach it.- DOB and Age are not read from the sheet at all (they had no consumer).
- Published-sheet links live only in Actions secrets, never in source.
- Never add contact or personal data (DOB, age, phone, email, address, parents,
social handles, home state) to anything under
data/.
- Older commits still contain DOB/age in
data/roster_cache.json history; purging
that history is a separate human decision (see the cutover kit).
Heartbeat hearts need Google sign-in
The ♥ status on each client card and the ♥ filter come from Heartbeat
(sv-heartbeat.vercel.app/api/heartbeat/summary), which is closing its API to
anonymous callers. This page has no server and cannot hold a secret, so the
viewer signs in with their @stadium-ventures.com Google account (Google
Identity Services, sv-registry's OAuth client id) and js/sv-google-auth.js
sends that Google ID token as Authorization: Bearer on the Heartbeat call.
- The token is kept in memory only (never localStorage/sessionStorage/cookies);
returning users are signed in silently on load.
- Not signed in, or Heartbeat answers 401/403 → the hearts and the ♥ filter are
hidden and a "sign in" prompt with the Google button is shown. Everything else
on the dashboard works without sign-in. The page never calls Heartbeat without
a token.
- Owner step:
https://stadium-ventures.github.io must be an Authorized
JavaScript origin on OAuth client 970904391216-emekreu9hdntj6k76qhkr0fjvrvd9fcm
(Google Cloud console). Without it the sign-in button fails and the hearts stay
hidden (nothing else breaks).
- Tied to Tom's D1 decision on this being a public site: if it stays public, the
heartbeat panel is sign-in-only; if the repo/site goes private, the same code
works unchanged.
- Tests:
node --test tests/js/sv_google_auth.test.js (also run by pytest via
tests/test_js_google_auth.py).
Manual Actions
Run the pulse manually (without waiting for cron)
- Go to GitHub repo → Actions tab
- Click "SV Dugout Pulse" in the left sidebar
- Click "Run workflow" → "Run workflow"
Regenerate test data
cd ~/sv-dugout-pulse
python3 generate_test_data.py
Test locally
cd ~/sv-dugout-pulse
python3 -m http.server 8888
# Then open http://localhost:8888
Schedule Details
The cron runs every 15 minutes during these windows (UTC):
- 3:00 PM - 11:59 PM UTC
- 12:00 AM - 6:45 AM UTC
In Eastern Time: 11:00 AM - 2:45 AM (next day)
This covers:
- Early afternoon NCAA games
- Evening MLB/MiLB games
- Late West Coast games
To change the schedule, edit .github/workflows/pulse.yml.
Troubleshooting
Dashboard shows old data
- Check the "Last updated" timestamp on the dashboard
- Go to Actions tab and verify the workflow ran successfully
- Manually trigger a run if needed
Slack alerts not working
- Verify
SLACK_WEBHOOK_URL secret is set correctly
- Test the webhook:
curl -X POST -H 'Content-type: application/json' --data '{"text":"Test"}' YOUR_WEBHOOK_URL
NCAA player shows "No game data"
- The school's feed may not be configured
- Check
src/stats_engine.py for the school's scraper settings
- May need to add the school's specific feed URL
Pro player shows "No game data"
- Player may not have played that day
- Player name in roster may not match MLB database exactly
- Check MLB Stats API can find them: player lookup uses exact name matching
Roster Management
The roster is managed in Google Sheets, not in this code. To add/remove players:
- Edit the Google Sheet
- Changes are picked up automatically on the next cron run
Important columns:
Level must be "Pro" or "NCAA" (High School players are filtered out)Tier (1-4) determines roster priority and some alert rulesOrg is the team name (must match what the stats APIs expect)
Performance Grades
| Grade | Emoji | Hitter Criteria | Pitcher Criteria |
|---|
| Milestone | 💎 | Debut, 1st HR, cycle | Debut, no-hitter, 1st win/save |
| Standout | 🔥 | HR, 3+ hits, 3+ RBI | QS, 5+ Ks, save |
| Good | ✅ | 2+ hits, RBI, run | 3+ clean IP |
| Routine | 😐 | 1 hit, standard game | Average outing |
| Soft Flag | 🚩 | 0-for-4+ | 3+ ER in short outing |
Future Improvements
Built with Claude Code, February 2026
