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

[] Interactive Region Map Picker

Outcome (User-Visible) Trip planner shows an actual North America map with clear geographic boundaries for West/Central/East regions. Users tap map regions to select them, with highlighted selection states replacing the current abstract three-square UI.

Why It Matters Now Current RegionMapSelector uses three equal-width colored rectangles with icons — users cannot visualize how regions map to actual geography. A map-based picker provides intuitive spatial understanding and makes region adjacency rules (East+West disallowed) obvious from the geography itself.

Files/Components Impacted

• SportsTime/Features/Trip/Views/RegionMapSelector.swift — complete redesign
• SportsTime/Core/Models/Domain/Region.swift — may need boundary coordinates
• Potentially new SVG/vector asset for North America outline with region paths

Dependencies

• None (standalone UI component)

Risk: Medium

• MapKit overlays add complexity but are well-documented
• Alternative: SVG asset with tap regions (simpler but less scalable)
• Need clear design spec for visual treatment of selected/unselected regions

Size: M

• Replace existing component with MapKit-based or vector-based region picker
• Define region boundary polygons/paths
• Handle tap gestures for region selection
• Maintain existing selection logic (adjacency rules)

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:

• Remove buffer days from trip planner (game-first mode now uses actual game dates)
• Monochrome theme: fix blue hue in dark mode (pure grayscale)

Prior 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

Checkpoint 2026-01-10

• What exists: Functional iOS app with trip planning (3 modes), stadium tracking, PDF export. Schedule view now groups games by sport (MLB, NBA, etc.) with date shown per game row. "By Games" mode game selection fixed. All active tasks complete.
• What is missing: Working test suite (broken), stable Python pipeline (needs rewrite), data quality validation, buffer days removal (moved to deferred)
• Known issues: Tests don't run (parallel or serial), data scraping broke local data (CloudKit still OK), 5 flaky tests, Python pipeline unwieldy
• Next step: Add new tasks to Active Tasks or pick from TO-DOS.md deferred items

---

Planning Queue (Claude-Proposed, Inactive)