60b450d869
- 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>
135 lines
4.6 KiB
Markdown
135 lines
4.6 KiB
Markdown
# 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*
|