SportstimeAPI/CLAUDE.md

CLAUDE.md

This file provides context for Claude Code when working on this project.

Project Overview

SportsTime is a Django-based sports data pipeline that scrapes game schedules from official sources, normalizes the data, stores it in PostgreSQL, and syncs to CloudKit for iOS app consumption.

Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────┐
│  Data Sources   │ ──▶ │   Scrapers   │ ──▶ │  PostgreSQL │ ──▶ │ CloudKit │
│ (ESPN, leagues) │     │ (sportstime_ │     │  (Django)   │     │  (iOS)   │
└─────────────────┘     │   parser)    │     └─────────────┘     └──────────┘
                        └──────────────┘

Key Directories

• core/ - Django models: Sport, Team, Stadium, Game, Conference, Division, Aliases
• scraper/ - Scraper orchestration, adapter, job management
• sportstime_parser/ - Standalone scraper library (ESPN, league APIs)
• cloudkit/ - CloudKit sync client and job management
• dashboard/ - Staff dashboard for monitoring and controls
• templates/ - Django templates for dashboard UI

Data Flow

1. Scraper runs (manual or scheduled via Celery Beat)
2. sportstime_parser fetches from ESPN/league APIs
3. Adapter normalizes data and resolves team/stadium names
4. Django models store normalized data with CloudKit sync flags
5. CloudKit sync pushes pending records to iCloud

Models Hierarchy

Sport
├── Conference
│   └── Division
│       └── Team (has TeamAliases)
├── Stadium (has StadiumAliases)
└── Game (references Team, Stadium)

Name Resolution

Team and stadium names from scraped data are resolved via:

1. Direct ID match (canonical IDs from scraper)
2. Database aliases (TeamAlias/StadiumAlias with date validity)
3. Direct name/abbreviation match

Aliases support validity dates for historical names (e.g., team relocations, stadium naming rights).

Common Tasks

Run a scraper

docker-compose exec web python manage.py shell
>>> from scraper.tasks import run_scraper_task
>>> run_scraper_task.delay(config_id)

Check scraper status

Visit /dashboard/scraper-status/ or check ScrapeJob model.

Add team/stadium alias

Use Django admin at /admin/core/teamalias/ or /admin/core/stadiumalias/.

Export/Import data

All admin models support import/export (JSON, CSV, XLSX) via django-import-export.

Sync to CloudKit

docker-compose exec web python manage.py shell
>>> from cloudkit.tasks import run_cloudkit_sync
>>> run_cloudkit_sync.delay(config_id)

Environment

• Docker Compose for local development
• PostgreSQL database
• Redis for Celery broker
• Celery for async tasks and scheduled jobs

Key Files

• sportstime/settings.py - Django settings
• scraper/engine/adapter.py - Bridges sportstime_parser to Django
• scraper/engine/db_alias_loader.py - Database alias resolution
• core/resources.py - Import/export resource definitions
• docker-compose.yml - Container orchestration

Supported Sports

Code	Sport	Season Type
nba	NBA Basketball	split (Oct-Jun)
mlb	MLB Baseball	calendar (Mar-Oct)
nfl	NFL Football	split (Sep-Feb)
nhl	NHL Hockey	split (Oct-Jun)
mls	MLS Soccer	calendar (Feb-Nov)
wnba	WNBA Basketball	calendar (May-Sep)
nwsl	NWSL Soccer	calendar (Mar-Nov)

Testing

docker-compose exec web pytest

Useful Commands

# Restart containers
docker-compose restart

# Rebuild after requirements change
docker-compose down && docker-compose up -d --build

# View logs
docker-compose logs -f web

# Django shell
docker-compose exec web python manage.py shell

# Database shell
docker-compose exec db psql -U sportstime -d sportstime