docs(04): phase 4 drag interaction (broken)
This commit is contained in:
Trey t
189
.planning/codebase/INTEGRATIONS.md
Normal file
189
.planning/codebase/INTEGRATIONS.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# External Integrations
|
||||
|
||||
**Analysis Date:** 2026-01-18
|
||||
|
||||
## APIs & External Services
|
||||
|
||||
**Apple CloudKit (Primary Data Source):**
|
||||
- Purpose: Sync game schedules, teams, stadiums, league structure to all users
|
||||
- Container: `iCloud.com.sportstime.app`
|
||||
- Database: Public (read-only for users, admin writes via Python uploader)
|
||||
- Client: `Core/Services/CloudKitService.swift`
|
||||
- Sync: `Core/Services/CanonicalSyncService.swift`
|
||||
- Record types: `Game`, `Team`, `Stadium`, `LeagueStructure`, `TeamAlias`, `StadiumAlias`, `Sport`
|
||||
- Auth: User iCloud account (automatic), server-to-server JWT (Python uploader)
|
||||
|
||||
**Apple MapKit:**
|
||||
- Purpose: Geocoding, routing, map snapshots, EV charger search, POI search
|
||||
- Services used:
|
||||
- `MKLocalSearch` - Address and POI search (`LocationService.swift`)
|
||||
- `MKDirections` - Driving routes and ETA (`LocationService.swift`)
|
||||
- `MKMapSnapshotter` - Static map images for PDF (`Export/Services/MapSnapshotService.swift`)
|
||||
- `MKLocalPointsOfInterestRequest` - EV chargers (`EVChargingService.swift`)
|
||||
- Client: `Core/Services/LocationService.swift`, `Core/Services/EVChargingService.swift`
|
||||
- Auth: Automatic via Apple frameworks
|
||||
- Rate limits: Apple's standard MapKit limits
|
||||
|
||||
**Apple StoreKit 2:**
|
||||
- Purpose: In-app subscriptions (Pro tier)
|
||||
- Products: `com.sportstime.pro.monthly`, `com.sportstime.pro.annual`
|
||||
- Client: `Core/Store/StoreManager.swift`
|
||||
- Features gated: Trip limit (1 free, unlimited Pro)
|
||||
|
||||
**Sports League APIs (Official):**
|
||||
|
||||
| API | URL | Sport | Reliability | Client |
|
||||
|-----|-----|-------|-------------|--------|
|
||||
| MLB Stats API | `https://statsapi.mlb.com/api/v1` | MLB | Official | `ScoreAPIProviders/MLBStatsProvider.swift` |
|
||||
| NHL Stats API | `https://api-web.nhle.com/v1` | NHL | Official | `ScoreAPIProviders/NHLStatsProvider.swift` |
|
||||
| NBA Stats API | `https://stats.nba.com/stats` | NBA | Unofficial | `ScoreAPIProviders/NBAStatsProvider.swift` |
|
||||
|
||||
**NBA Stats API Notes:**
|
||||
- Requires specific headers to avoid 403 (User-Agent, Referer, x-nba-stats-origin, x-nba-stats-token)
|
||||
- May break without notice (unofficial)
|
||||
|
||||
**Sports Reference Sites (Scraping Fallback):**
|
||||
|
||||
| Site | URL Pattern | Sport | Client |
|
||||
|------|-------------|-------|--------|
|
||||
| Baseball-Reference | `baseball-reference.com/boxes/?month=M&day=D&year=Y` | MLB | `HistoricalGameScraper.swift` |
|
||||
| Basketball-Reference | `basketball-reference.com/boxscores/?month=M&day=D&year=Y` | NBA | `HistoricalGameScraper.swift` |
|
||||
| Hockey-Reference | `hockey-reference.com/boxscores/?month=M&day=D&year=Y` | NHL | `HistoricalGameScraper.swift` |
|
||||
| Pro-Football-Reference | `pro-football-reference.com/boxscores/...` | NFL | `HistoricalGameScraper.swift` |
|
||||
|
||||
- Uses SwiftSoup for HTML parsing
|
||||
- On-device scraping (no server costs, unlimited scale)
|
||||
- Cached per-session to avoid redundant requests
|
||||
|
||||
## Data Storage
|
||||
|
||||
**SwiftData (Local):**
|
||||
- Purpose: Offline-first data storage, user trips, preferences
|
||||
- Location: App sandbox (automatic)
|
||||
- CloudKit sync: Disabled (`cloudKitDatabase: .none`)
|
||||
- Schema: See `SportsTimeApp.swift` ModelContainer configuration
|
||||
|
||||
**CloudKit Public Database (Remote):**
|
||||
- Purpose: Shared schedule data for all users
|
||||
- Container: `iCloud.com.sportstime.app`
|
||||
- Access: Read (all users), Write (admin via Python uploader)
|
||||
- Sync method: Date-based delta sync (modificationDate filtering)
|
||||
|
||||
**URLCache (Images):**
|
||||
- Purpose: Cache team logos and stadium photos
|
||||
- Memory: 50 MB
|
||||
- Disk: 100 MB
|
||||
- Path: `ImageCache`
|
||||
- Client: `Export/Services/RemoteImageService.swift`
|
||||
|
||||
**File Storage:**
|
||||
- Local filesystem only for PDF export (temporary)
|
||||
- Photo library access for visit photo imports
|
||||
|
||||
**Caching:**
|
||||
- In-memory game score cache: `ScoreResolutionCache.swift`
|
||||
- In-memory scraper cache: `HistoricalGameScraper.swift`
|
||||
- URLSession cache: Team logos, stadium photos
|
||||
|
||||
## Authentication & Identity
|
||||
|
||||
**iCloud (Automatic):**
|
||||
- Users authenticate via their iCloud account
|
||||
- Required for: CloudKit sync, poll voting identity
|
||||
- Optional: App works offline without iCloud
|
||||
|
||||
**CloudKit Server-to-Server (Python Uploader):**
|
||||
- JWT authentication with ECDSA P-256 key
|
||||
- Key ID and team ID from Apple Developer portal
|
||||
- Used by `Scripts/sportstime_parser/uploaders/cloudkit.py`
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
**Error Tracking:**
|
||||
- None (no Sentry, Crashlytics, etc.)
|
||||
- Errors logged to console via `os.Logger`
|
||||
|
||||
**Logs:**
|
||||
- `os.Logger` subsystem: `com.sportstime.app`
|
||||
- Categories: `BackgroundSyncManager`, `NetworkMonitor`
|
||||
- Rich console output in Python scraper
|
||||
|
||||
## CI/CD & Deployment
|
||||
|
||||
**Hosting:**
|
||||
- iOS App Store (planned)
|
||||
- CloudKit public database (Apple infrastructure)
|
||||
|
||||
**CI Pipeline:**
|
||||
- None configured (no GitHub Actions, Xcode Cloud, etc.)
|
||||
|
||||
**Data Pipeline:**
|
||||
- Python CLI (`sportstime-parser`) scrapes schedules
|
||||
- Uploads to CloudKit via CloudKit Web Services API
|
||||
- iOS apps sync from CloudKit automatically
|
||||
|
||||
## Background Processing
|
||||
|
||||
**BGTaskScheduler:**
|
||||
- Refresh task: `com.sportstime.app.refresh` (periodic CloudKit sync)
|
||||
- Processing task: `com.sportstime.app.db-cleanup` (overnight heavy sync)
|
||||
- Manager: `Core/Services/BackgroundSyncManager.swift`
|
||||
|
||||
**Network Monitoring:**
|
||||
- `NWPathMonitor` triggers sync on connectivity restoration
|
||||
- Debounce: 2.5 seconds (handles WiFi/cellular handoffs)
|
||||
- Manager: `Core/Services/NetworkMonitor.swift`
|
||||
|
||||
**Push Notifications:**
|
||||
- CloudKit subscriptions for data changes
|
||||
- Silent notifications (`shouldSendContentAvailable`)
|
||||
- Subscription IDs: `game-updates`, `league-structure-updates`, `team-alias-updates`, `stadium-alias-updates`
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
**Required Environment Variables:**
|
||||
|
||||
*iOS App:*
|
||||
- None required (CloudKit container ID hardcoded)
|
||||
|
||||
*Python Uploader:*
|
||||
- CloudKit key ID (or in config)
|
||||
- CloudKit team ID (or in config)
|
||||
- ECDSA private key path
|
||||
|
||||
**Secrets Location:**
|
||||
- iOS: Entitlements file (`SportsTime.entitlements`)
|
||||
- Python: Environment variables or local config file
|
||||
|
||||
## Webhooks & Callbacks
|
||||
|
||||
**Incoming:**
|
||||
- CloudKit silent push notifications (background sync trigger)
|
||||
- Deep links: `sportstime://poll/{shareCode}` (poll sharing)
|
||||
|
||||
**Outgoing:**
|
||||
- None
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
**Internal Rate Limiter:**
|
||||
- `Core/Services/RateLimiter.swift`
|
||||
- Per-provider keys: `mlb_stats`, `nba_stats`, `nhl_stats`
|
||||
- Prevents API abuse when resolving historical game scores
|
||||
|
||||
**Provider Auto-Disable:**
|
||||
- Official APIs: Never auto-disabled
|
||||
- Unofficial APIs: Disabled after 3 failures (24h cooldown)
|
||||
- Scraped sources: Disabled after 2 failures (24h cooldown)
|
||||
|
||||
## Polls (Group Trip Planning)
|
||||
|
||||
**CloudKit-Based Polling:**
|
||||
- Record type: `TripPoll`, `PollVote`
|
||||
- Share codes: 6-character uppercase alphanumeric
|
||||
- Deep link: `sportstime://poll/{shareCode}`
|
||||
- Service: `Core/Services/PollService.swift`
|
||||
|
||||
---
|
||||
|
||||
*Integration audit: 2026-01-18*
|
||||
Reference in New Issue
Block a user