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>
This commit is contained in:
Trey t
134
.planning/codebase/INTEGRATIONS.md
Normal file
134
.planning/codebase/INTEGRATIONS.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user