Files

Trey t 60b450d869 docs: add Phase 1 plans and codebase documentation

- 01-01-PLAN.md: core.py + mlb.py (executed)
- 01-02-PLAN.md: nba.py + nhl.py
- 01-03-PLAN.md: nfl.py + orchestrator refactor
- Codebase documentation for planning context

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-10 00:00:45 -06:00

4.6 KiB

Raw Blame History

External Integrations

Analysis Date: 2026-01-09

APIs & External Services

Sports Data - MLB Stats API:

Endpoint: https://statsapi.mlb.com/api/v1
Integration: Core/Services/ScoreAPIProviders/MLBStatsProvider.swift
Purpose: Official MLB schedule and game scores
Auth: None required (public API)
Reliability: Official, documented

Sports Data - NHL API:

Endpoint: https://api-web.nhle.com/v1
Integration: Core/Services/ScoreAPIProviders/NHLStatsProvider.swift
Purpose: Official NHL schedule and game scores
Auth: None required (public API)
Reliability: Official, documented

Sports Data - NBA Stats API:

Endpoint: https://stats.nba.com/stats
Integration: Core/Services/ScoreAPIProviders/NBAStatsProvider.swift
Purpose: NBA stats and schedules (unofficial)
Auth: Requires specific User-Agent headers
Reliability: Unofficial, may break without notice

Score Resolution Facade:

Integration: Core/Services/FreeScoreAPI.swift
Purpose: Multi-provider score resolution with fallback
Features: Rate limiting, caching, provider tiers
Cache: Core/Services/ScoreResolutionCache.swift

Data Storage

CloudKit (iCloud):

Container: iCloud.com.sportstime.app
Integration: Core/Services/CloudKitService.swift
Purpose: Remote sync for canonical data, photo backup
Database: Public (schedules), Private (user photos)
Records:
- CanonicalStadium, CanonicalTeam, CanonicalGame
- LeagueStructure, StadiumAlias, TeamAlias
Sync Service: Core/Services/CanonicalSyncService.swift

SwiftData (Local):

Integration: Core/Models/Local/*.swift
Purpose: Local persistence, offline-first
Models:
- Canonical: CanonicalStadium, CanonicalTeam, CanonicalGame
- User: SavedTrip, StadiumVisit, UserPreferences, Achievement

Bundled JSON:

Location: SportsTime/Resources/*.json
Purpose: Bootstrap data for offline-first experience
Files: stadiums_canonical.json, teams_canonical.json, games_canonical.json, league_structure.json

Location & Maps Services

Apple Maps (MapKit):

Geocoding: Core/Services/LocationService.swift - Address→Coordinates
Reverse Geocoding: Coordinates→Address lookup
Routing: MKDirections for travel time/distance
POI Search: Export/Services/POISearchService.swift - Restaurants, attractions
EV Charging: Core/Services/EVChargingService.swift - Charging station search
Map Snapshots: Export/Services/MapSnapshotService.swift - Static map images

CoreLocation:

Purpose: Coordinate types, user location (if permitted)
No active GPS tracking; uses user-provided locations

Photo Library Integration

PhotosPicker:

Integration: Features/Progress/ViewModels/PhotoImportViewModel.swift
Purpose: Import photos to match with stadium visits
Metadata: Core/Services/PhotoMetadataExtractor.swift - EXIF extraction

Visit Photos:

Integration: Core/Services/VisitPhotoService.swift
Storage: Thumbnails in SwiftData, full images in CloudKit private database
Backup: Automatic CloudKit sync for photo preservation

AI/ML Integration

Apple Foundation Models:

Integration: Core/Services/RouteDescriptionGenerator.swift
Purpose: On-device AI for natural language route descriptions
Status: Disabled due to iOS 26.2 simulator bug
Requirement: iOS 26+, Apple Silicon

Environment Configuration

Development:

Required env vars: None
Secrets location: CloudKit container in entitlements
Mock/stub services: Uses bundled JSON data

Production:

CloudKit: Production container (automatic via entitlements)
APIs: All public endpoints, no API keys required
Background Modes: remote-notification, fetch, processing

Data Pipeline (Scripts/)

Schedule Scraping:

Script: Scripts/scrape_schedules.py
Sources: Basketball-Reference, Baseball-Reference, Hockey-Reference
Rate Limiting: 3-second delay per domain
Output: JSON files for processing

Data Processing:

Scripts/canonicalize_stadiums.py - Normalize stadium identities
Scripts/canonicalize_teams.py - Normalize team identities
Scripts/canonicalize_games.py - Normalize game records
Scripts/generate_canonical_data.py - Generate bundled JSON

CloudKit Import:

Script: Scripts/cloudkit_import.py
Purpose: Upload canonical data to CloudKit public database
Auth: CloudKit server-to-server authentication (via cryptography)

Webhooks & Callbacks

Incoming:

None (no server-side components)

Outgoing:

None (all data fetched on-demand)

Integration audit: 2026-01-09 Update when adding/removing external services

4.6 KiB Raw Blame History