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

- [x] Fix "By Games" Mode Game Selection
- [ ] Group Schedule View Games by Sport
- [ ] Remove Buffer Days from Trip Planner

## Completed Tasks

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

**Recent Work (from git history, prior to .planning/ removal):**
- [x] GameDAGRouter edge case tests
- [x] Performance optimization for large datasets (10-17x speedup)
- [x] Scenario A timezone and conflict tests
- [x] Scenario B filler conflict tests
- [x] 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