# 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*