Sportstime/PROJECT_STATE.md

PROJECT STATE — CANONICAL

⚠️ This file is the single source of truth. ⚠️ Sections marked LOCKED may not be modified unless the user explicitly says "unlock". ⚠️ Claude must read this file before doing any work.

---

Goal (LOCKED)

Build a functional iOS sports trip planning app that helps users plan multi-stop road trips to attend games across MLB, NBA, NHL, NFL, MLS, WNBA, and NWSL. The app creates optimized routes with 3 planning modes: by dates, by must-see games, or by start/end cities. Ongoing development with no fixed completion milestone.

Non-Negotiable Constraints (LOCKED)

• No re-evaluation of prior decisions
• No alternative architectures unless explicitly requested
• No refactors outside the active task
• No scope expansion
• iOS 26 minimum target (do not support older iOS versions)
• SwiftData + CloudKit + offline-first architecture is locked
• Three-layer architecture (Presentation/Domain/Data) is locked
• Python pipeline for data scraping remains (even though it needs rewrite)

Architecture Decisions (LOCKED)

• Data flow: Python scrape → canonicalize → CloudKit → SwiftData → AppDataProvider.shared (single source of truth)
• Trip planning: 3 scenario modes (A: by dates, B: must-see games, C: start/end cities) using GameDAGRouter with beam search
• Offline-first: Bundled JSON bootstrap → SwiftData → background CloudKit sync
• Test framework: Swift Testing (@Test/@Suite syntax, not XCTest)
• Sports supported: 7 leagues (MLB, NBA, NHL, NFL, MLS, WNBA, NWSL), 148 stadiums
• Export: PDF itinerary generation with maps, photos, POIs

Current Phase

No active phase — Previous phase-based workflow (.planning/) was removed as failed organization system. Ignore all git commit references to "Phase 8", "Phase 9", "v1.1 milestone" etc.

Active Tasks

• Fix "By Games" Mode Game Selection
• Group Schedule View Games by Sport
• Remove Buffer Days from Trip Planner

Completed Tasks

Core Features (Working):

• Trip planning engine with 3 scenario modes (A/B/C)
• GameDAGRouter with beam search optimization
• Offline-first data architecture (bundled JSON → SwiftData → CloudKit)
• AppDataProvider as single source of truth
• Stadium progress tracking with photo import
• Achievement system
• PDF trip export with maps and POIs
• UI: Home, Trip Creation/Detail, Schedule, Progress, Settings views
• Python data pipeline (scraping, canonicalization, CloudKit upload) — functional but needs rewrite
• 7 sport modules with multi-source fallback architecture

Recent Work (from git history, prior to .planning/ removal):

• GameDAGRouter edge case tests
• Performance optimization for large datasets (10-17x speedup)
• Scenario A timezone and conflict tests
• Scenario B filler conflict tests
• Scenario C corridor efficiency and anti-backtracking tests

Open Questions (User-Owned)

• Data quality: User is "unsure" if the 148 stadiums across 7 sports are accurate and complete
• CloudKit sync: "As far as I know yes" — not 100% certain sync is working correctly
• Test implementation completeness: Tests exist but are broken — unclear if implementations they test are actually complete
• When to rewrite Python pipeline: Acknowledged as needed but not scheduled

Known Issues

1. Test suite broken — Tests do not run in parallel OR serial execution. Files and tests need complete revisit. (NOT BLOCKING: app is functional)
2. Data scraping broken — Python pipeline "messed up" data, data directories (data/canonical/, data/games/) emptied. CloudKit still has data, so app functions.
3. 5 flaky tests — Fail in parallel but pass individually (Swift Testing + simulator state pollution). Ignoring for now.
4. Python pipeline out of control — Grown unwieldy, needs complete rewrite from scratch (future task).

Deferred Work

All items in TO-DOS.md (16 items) are deferred — will become tasks in future phases when prioritized. See TO-DOS.md for full list.

High-level categories:

• In-app purchases (StoreKit, receipt validation)
• UI/UX improvements (redesign, theme fixes, region picker map)
• Testing gaps (trip filtering, repeat cities, must-stops, driving limits)
• Schedule improvements (UTC→local timezone, group by sport, show all games)
• Buffer days removal

Feature flags (disabled, future work):

• EV charging (FeatureFlags.enableEVCharging = false)
• Foundation Models / AI descriptions (commented out in RouteDescriptionGenerator)

What Exists

iOS App (SportsTime/):

• Functional trip planning: 3 scenario modes, can create and save trips
• GameDAGRouter: Graph routing with beam search, directional filtering, performance-optimized
• Data layer: SwiftData models (SavedTrip, StadiumVisit, CanonicalStadium, CanonicalTeam, CanonicalGame)
• Services: CloudKitService, CanonicalSyncService, BootstrapService, LocationService, AchievementEngine
• UI: 5 main views (Home, Trip, Schedule, Progress, Settings), fully SwiftUI with @Observable ViewModels
• Export: PDF generator with map snapshots, remote image caching, POI search
• Progress tracking: Stadium visits, photos, achievements, progress map
• ~27,500 lines of Swift code

Python Pipeline (Scripts/):

• 7 sport scrapers (mlb, nba, nhl, nfl, mls, wnba, nwsl)
• Canonicalization pipeline (stadiums, teams, games with alias resolution)
• CloudKit import (full CRUD with diff reporting)
• Validation tools (health scores, completeness metrics)
• ~12,000 lines of Python code
• Status: Functional but "out of control", needs rewrite

Tests:

• 6 test files, ~7,000 lines of Swift Testing code
• Coverage: GameDAGRouter, ScenarioA/B/C planners, TravelEstimator
• Status: BROKEN (don't run in parallel or serial)

Documentation:

• CLAUDE.md: Comprehensive iOS app docs, build commands, architecture
• ARCHITECTURE.md: Original design document
• docs/: Market research, stadium progress spec, WNBA/MLS/NWSL implementation guides, data scraping architecture
• Scripts/: README, DATA_SOURCES, CLOUDKIT_SETUP

Data:

• Bundled JSON in SportsTime/Resources/ (games_canonical.json, stadiums_canonical.json, teams_canonical.json, etc.)
• CloudKit container: iCloud.com.sportstime.app (contains current schedule data)
• Local data directories (data/) emptied after pipeline issues

What Is Missing

Broken/Incomplete:

• Test suite execution (doesn't run properly)
• Python pipeline stable/maintainable implementation (current version works but needs rewrite)
• Data quality confidence (user unsure if 148 stadiums are accurate)

Future Features (from TO-DOS.md):

• In-app purchases / subscription system
• UI redesign
• Trip filtering
• Repeat cities option testing
• Must-stops (non-game POIs) testing
• Full test coverage for constraints (driving limits, etc.)
• Schedule improvements (timezone conversion, grouping by sport)
• Interactive region picker map

Future Enhancements (from docs/MARKET_RESEARCH.md):

• AI trip assistant (natural language planning)
• Group trip coordination
• Ticket integration
• Fan community features

Checkpoints (APPEND-ONLY)

Checkpoint 2026-01-10 16:30

• What exists: Functional iOS app with trip planning (3 modes), stadium tracking, PDF export. Python pipeline functional. CloudKit contains current data.
• What is missing: Working test suite (broken), stable Python pipeline (needs rewrite), data quality validation
• Known issues: Tests don't run (parallel or serial), data scraping "messed up" data (CloudKit still OK), flaky tests
• Next step: Fix broken test suite as first active task