SportstimeAPI/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2026-01-18

Languages

Primary:

• Swift 5.0 - iOS app (SportsTime/)
• Python 3.11+ - Data scraping and CloudKit uploading (Scripts/sportstime_parser/)

Secondary:

• JSON - Data interchange format, bundled bootstrap data, configuration

Runtime

iOS Environment:

• iOS 26+ (iOS 26.2 targeted per Xcode 26.2)
• Swift 6 concurrency model enabled (SWIFT_APPROACHABLE_CONCURRENCY = YES, SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor)
• Deployment targets: iPhone and iPad (TARGETED_DEVICE_FAMILY = "1,2")

Python Environment:

• Python 3.11, 3.12, or 3.13
• No lockfile (uses requirements.txt + pyproject.toml)

Frameworks

Core iOS Frameworks:

• SwiftUI - UI framework (entire app)
• SwiftData - Local persistence (Core/Models/Local/)
• CloudKit - Remote data sync (Core/Services/CloudKitService.swift)
• StoreKit 2 - In-app purchases (Core/Store/StoreManager.swift)
• MapKit - Geocoding, routing, map snapshots, EV chargers
• CoreLocation - Location services
• PDFKit - PDF generation (Export/PDFGenerator.swift)
• BackgroundTasks - Background sync scheduling
• Network - Network path monitoring (NWPathMonitor)
• Photos/PhotosUI - Photo library access for visit imports
• CryptoKit - Hash generation for canonical data

Testing:

• XCTest - Unit and UI tests (SportsTimeTests/, SportsTimeUITests/)
• pytest 8.0+ - Python tests (Scripts/sportstime_parser/tests/)

Build/Dev:

• Xcode 26.2 - Build system
• Swift Package Manager - Dependency management (single package)

Key Dependencies

iOS - Swift Package Manager:

• SwiftSoup (HTML parsing) - Used in HistoricalGameScraper.swift for Sports-Reference scraping

Python - pip:

Package	Version	Purpose
requests	2.31.0+	HTTP client for API calls
beautifulsoup4	4.12.0+	HTML parsing
lxml	5.0.0+	XML/HTML parser backend
rapidfuzz	3.5.0+	Fuzzy string matching for team names
python-dateutil	2.8.0+	Date parsing
pytz	2024.1+	Timezone handling
rich	13.7.0+	CLI output formatting
pyjwt	2.8.0+	JWT token generation for CloudKit auth
cryptography	42.0.0+	ECDSA signing for CloudKit requests

Dev Dependencies (Python):

• pytest 8.0+ - Test runner
• pytest-cov 4.1+ - Coverage reporting
• responses 0.25+ - HTTP mocking

Configuration

Environment Variables:

• CloudKit Web Services requires ECDSA private key for server-to-server auth
• iOS app uses iCloud container identifier: iCloud.com.sportstime.app

Build Settings:

Setting	Value	Purpose
SWIFT_VERSION	5.0	Swift language version
SWIFT_APPROACHABLE_CONCURRENCY	YES	Modern concurrency
SWIFT_DEFAULT_ACTOR_ISOLATION	MainActor	Default isolation
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY	YES	Swift 6 prep

Info.plist:

• Background modes: remote-notification, fetch, processing
• Background task IDs: com.sportstime.app.refresh, com.sportstime.app.db-cleanup
• Photo library usage description for visit imports

Entitlements:

• CloudKit: iCloud.com.sportstime.app
• Push notifications: aps-environment (development)

Platform Requirements

Development:

• macOS with Xcode 26.2
• Python 3.11+ for data scraping
• iCloud account for CloudKit testing

Production:

• iOS 26+ (uses iOS 26 APIs, deprecated CLGeocoder annotations)
• iCloud account for data sync (optional, works offline)
• Network for CloudKit sync (offline-first architecture)

Data Architecture

Three-Tier Storage:

1. Bundled JSON (SportsTime/Resources/) - Bootstrap data for first launch
2. SwiftData (local) - Runtime source of truth, offline-capable
3. CloudKit (remote) - Public database for schedule updates

Key Data Files:

• games_canonical.json - Pre-bundled game schedules
• teams_canonical.json - Team definitions
• stadiums_canonical.json - Stadium definitions
• league_structure.json - League/conference/division hierarchy
• team_aliases.json - Historical team name mappings
• stadium_aliases.json - Historical stadium name mappings

SwiftData Models:

• Canonical: CanonicalStadium, CanonicalTeam, CanonicalGame, CanonicalSport
• User: SavedTrip, StadiumVisit, UserPreferences, Achievement
• Sync: SyncState, LeagueStructureModel, TeamAlias, StadiumAlias

---

Stack analysis: 2026-01-18