From 171221af0efe7fa00471da6723fe366a4949bfce Mon Sep 17 00:00:00 2001
From: Trey t <treytartt@fastmail.com>
Date: Sun, 11 Jan 2026 01:22:03 -0600
Subject: [PATCH] docs: add project README

- Project overview and features
- Supported leagues (8 sports)
- Installation and setup instructions
- Project structure and architecture
- Development commands
- Test suite summary

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..14d3ba6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,161 @@
+# 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 8 professional and college 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 |
+| CBB | College Basketball | November - April |
+
+## 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
+├── 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
+```
+
+### 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
+- `ARCHITECTURE.md` - Detailed system architecture
+- `docs/TEST_PLAN.md` - Test suite documentation
+- `docs/MARKET_RESEARCH.md` - Competitive analysis
+
+## License
+
+MIT License - see LICENSE file for details.