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>
This commit is contained in:
Trey t
161
README.md
Normal file
161
README.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user