# How the collectors work

Lionschedule collects its own data. Nothing is synced from another server: the
collectors in `apps/sportsdata/collectors.py` read public sources and upsert
the site's tables directly.

| Data | Source | Schedule (Eastern) |
|------|--------|--------------------|
| Conferences, divisions, teams | nflverse `teams_colors_logos.csv`, ESPN team detail for venues | Mondays 6:00 |
| Season schedule and results | nflverse `games.csv` (ESPN per-team schedules as fallback) | 0:00 and 7:00 daily |
| Live scores, clock, linescores, leaders | ESPN `/scoreboard` | every 30 minutes, skipped when no game is within a day |
| Box scores for Lions games | ESPN `/summary` | every 30 minutes, only when a game is waiting |
| Lions roster | ESPN `/teams/8/roster` | 7:10 daily |
| Standings | ESPN v2 standings | 7:20 daily |
| Player season stats + NFL ranks | nflverse `stats_player_reg` (ESPN splits as fallback) | 7:30 daily |
| Team season stats + 1–32 ranks | nflverse `stats_team_reg` | 7:40 daily |
| News | ESPN `/news` (Lions + league), NewsAPI when `NEWSAPI_KEY` is set | every 2 hours |
| Lions Daily Report | Claude with web search + the collected headlines | 9:00 daily |

## Where to look

- **Schedules** — `/smallstack/scheduler/` lists every job with its last status,
  next run, and a *Run now* button. Pause or retune a cadence there; the change
  survives deploys.
- **Health** — `/smallstack/status/` has a *Lions data* service: schedule
  freshness (public, also on `/status/`), headlines arriving, Daily Report
  published, and whether every collector schedule exists and last succeeded.
- **The data** — staff pages under `/football/` (Games, Teams, Players,
  Standings, Player stats, News, Daily Report), with the same records on REST
  at `/api/football/…` and as MCP tools.

## Running by hand

```bash
uv run python manage.py football_sync                    # everything, in order
uv run python manage.py football_sync teams schedule     # a subset
uv run python manage.py football_sync --season 2025 schedule standings
uv run python manage.py football_sync daily_report       # write today's issue
uv run python manage.py football_sync --seasons 2010-2025 # history: see “Season history”
```

Each job prints `created / updated / skipped / failed` plus its notes — the same
summary the scheduler shows under a run.

## Settings

| Setting | Default | Purpose |
|---------|---------|---------|
| `SPORTSDATA_FOOTBALL_TEAM_IDS` | `8` | Teams whose rosters and player stats are collected |
| `SPORTSDATA_FOOTBALL_SEASON` | `0` (derive from date) | Pin the season the collectors work on |
| `CURRENT_SEASON` | `2026` | Season the public pages show by default |
| `NEWSAPI_KEY` | empty | Second headline source; ESPN only when unset |
| `ANTHROPIC_API_KEY` | empty | Required for the Daily Report; the job is skipped without it |
| `SPORTSDATA_DAILY_REPORT_MODEL` | `claude-opus-5-5` | Model that writes the Daily Report |

