Sportstime/README.md

# SportsTime

An iOS app for planning multi-stop sports road trips across North America. Plan your ultimate stadium-hopping adventure with intelligent route optimization, real-time game schedules, and detailed trip itineraries.

## Features

- **Multi-Sport Trip Planning** - Plan trips across 7 professional leagues
- **Three Planning Modes**
  - **By Date Range** - Find the best games within your travel window
  - **By Must-See Games** - Build a trip around specific matchups you want to attend
  - **By Cities** - Select departure/arrival cities and discover games along the route
- **Intelligent Route Optimization** - TSP solver optimizes multi-stop routes for minimum travel time
- **Driving Constraints** - Respects max daily driving hours and number of drivers
- **Offline-First** - Works without internet using locally cached schedule data
- **PDF Export** - Generate detailed trip itineraries with maps, stadium info, and nearby attractions
- **Stadium Tracking** - Track which stadiums you've visited across all leagues

## Supported Leagues

| League | Sport | Season |
|--------|-------|--------|
| MLB | Baseball | March - October |
| NBA | Basketball | October - June |
| NHL | Hockey | October - June |
| NFL | Football | September - February |
| MLS | Soccer | February - December |
| WNBA | Basketball | May - October |
| NWSL | Soccer | March - November |

## Requirements

- iOS 26.0+
- Xcode 26.0+
- Swift 6.0+

## Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/SportsTime.git
   cd SportsTime
   ```

2. Open the project in Xcode:
   ```bash
   open SportsTime.xcodeproj
   ```

3. Build and run on simulator or device.

## Project Structure

```
SportsTime/
├── SportsTime/                 # Main app target
│   ├── Core/                   # Data layer
│   │   ├── Models/
│   │   │   ├── Domain/         # Pure Swift structs (Trip, Game, Stadium, Team)
│   │   │   ├── CloudKit/       # CKRecord wrappers
│   │   │   └── Local/          # SwiftData models
│   │   └── Services/           # CloudKit, Location services
│   ├── Planning/               # Domain layer - trip planning logic
│   │   └── Engine/             # TripPlanningEngine, RouteOptimizer, etc.
│   ├── Features/               # Presentation layer - SwiftUI views
│   │   ├── Home/
│   │   ├── Trip/
│   │   ├── Schedule/
│   │   ├── Progress/
│   │   └── Settings/
│   ├── Export/                 # PDF generation
│   └── Resources/              # Bundled JSON data
├── SportsTimeTests/            # Unit tests
├── SportsTimeUITests/          # UI test suites + screen objects
├── Scripts/                    # Python data pipeline
│   └── sportstime_parser/      # Schedule scraping & CloudKit upload
├── data/                       # Local data files
└── docs/                       # Documentation
```

## Architecture

**Clean MVVM** with feature-based modules and offline-first data architecture.

### Three-Layer Architecture

1. **Presentation Layer** (`Features/`) - SwiftUI Views + `@Observable` ViewModels
2. **Domain Layer** (`Planning/`) - Trip planning algorithms
3. **Data Layer** (`Core/`) - Models and services

### Data Flow

```
AppDataProvider.shared (Single Source of Truth)
         │
         ├── Bundled JSON (bootstrap on first launch)
         ├── SwiftData (local persistence)
         └── CloudKit (background sync)
```

All schedule data flows through `AppDataProvider.shared` - never access CloudKit or SwiftData directly for canonical data.

## Development

### Build

```bash
xcodebuild -project SportsTime.xcodeproj \
  -scheme SportsTime \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' \
  build
```

### Run Tests

```bash
# All tests
xcodebuild -project SportsTime.xcodeproj \
  -scheme SportsTime \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' \
  test

# Specific test suite
xcodebuild -project SportsTime.xcodeproj \
  -scheme SportsTime \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' \
  -only-testing:SportsTimeTests/EdgeCaseTests \
  test

# UI test target only
xcodebuild test-without-building \
  -project SportsTime.xcodeproj \
  -scheme SportsTime \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' \
  -parallel-testing-enabled NO \
  -only-testing:SportsTimeUITests
```

### Data Pipeline

The Python pipeline scrapes schedules from multiple sources and uploads to CloudKit:

```bash
cd Scripts
pip install -r requirements.txt
python -m sportstime_parser scrape --sport all --season 2026
python -m sportstime_parser upload --sport all
```

## Test Suite

124 tests across 11 phases covering:

- Trip planning engine (all 3 scenarios)
- Route optimization (TSP solver)
- Travel estimation
- Game filtering and matching
- Edge cases and boundary conditions
- Concurrency behavior

## Documentation

- `CLAUDE.md` - Development guidelines and architecture details
- `AGENTS.md` - Agent-specific execution notes for this repo
- `ARCHITECTURE.md` - Detailed system architecture
- `XCUITest-Authoring.md` - How existing UI tests are structured and how to add new ones
- `XCUITestSuiteTemplate.swift` - Starter suite template for new UI test files
- `uiTestPrompt.md` - Reusable prompt template for requesting UI test work
- `docs/TEST_PLAN.md` - Test suite documentation
- `docs/MARKET_RESEARCH.md` - Competitive analysis

## License

MIT License - see LICENSE file for details.