docs: add Phase 1 plans and codebase documentation

- 01-01-PLAN.md: core.py + mlb.py (executed) - 01-02-PLAN.md: nba.py + nhl.py - 01-03-PLAN.md: nfl.py + orchestrator refactor - Codebase documentation for planning context Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-10 00:00:45 -06:00
parent 504187059f
commit 60b450d869
10 changed files with 1436 additions and 0 deletions
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,151 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-01-09
+
+## Directory Layout
+
+```
+SportsTime/
+├── SportsTimeApp.swift           # @main entry point
+├── Features/                     # Presentation layer
+│   ├── Home/                    # Dashboard, suggested trips
+│   ├── Trip/                    # Creation & detail views
+│   ├── Schedule/                # Browse games
+│   ├── Settings/                # User preferences
+│   └── Progress/                # Stadium visits, achievements
+├── Planning/                     # Domain layer
+│   ├── Engine/                  # Planning algorithms
+│   └── Models/                  # Planning-specific types
+├── Core/                         # Data layer
+│   ├── Models/                  # Domain + Local + CloudKit models
+│   ├── Services/                # Data providers, sync, APIs
+│   ├── Theme/                   # Design system
+│   ├── Extensions/              # Swift extensions
+│   └── Utilities/               # Helpers
+├── Export/                       # PDF generation
+│   ├── PDFGenerator.swift       # Main generator
+│   └── Services/                # Asset services
+├── Resources/                    # Assets, bundled JSON
+└── Info.plist                   # App configuration
+
+SportsTimeTests/                  # Unit tests
+SportsTimeUITests/                # UI tests
+Scripts/                          # Python data pipeline
+docs/                            # Documentation
+```
+
+## Directory Purposes
+
+**Features/ (Presentation):**
+- Purpose: SwiftUI Views + @Observable ViewModels
+- Contains: Feature-organized modules
+- Key files: `HomeView.swift`, `TripCreationView.swift`, `TripDetailView.swift`
+- Subdirectories: Views/, ViewModels/ per feature
+
+**Planning/ (Domain):**
+- Purpose: Trip planning business logic
+- Contains: Engine algorithms, planning models
+- Key files: `TripPlanningEngine.swift`, `GameDAGRouter.swift`, `PlanningModels.swift`
+- Subdirectories: Engine/, Models/
+
+**Core/ (Data):**
+- Purpose: Models, services, infrastructure
+- Contains: Domain structs, SwiftData models, services
+- Key files: `DataProvider.swift`, `CloudKitService.swift`, `LocationService.swift`
+- Subdirectories: Models/Domain/, Models/Local/, Models/CloudKit/, Services/
+
+**Export/ (PDF):**
+- Purpose: PDF generation with parallel asset fetching
+- Contains: PDF generator, asset services
+- Key files: `PDFGenerator.swift`, `MapSnapshotService.swift`, `PDFAssetPrefetcher.swift`
+- Subdirectories: Services/
+
+## Key File Locations
+
+**Entry Points:**
+- `SportsTime/SportsTimeApp.swift` - App entry, SwiftData schema
+- `SportsTime/Features/Home/Views/HomeView.swift` - Main TabView
+
+**Configuration:**
+- `SportsTime/Info.plist` - App configuration, background modes
+- `SportsTime.xcodeproj/project.pbxproj` - Build settings
+
+**Core Logic:**
+- `SportsTime/Core/Services/DataProvider.swift` - Single source of truth
+- `SportsTime/Planning/Engine/TripPlanningEngine.swift` - Planning orchestrator
+- `SportsTime/Planning/Engine/GameDAGRouter.swift` - Route finding
+
+**Testing:**
+- `SportsTimeTests/TravelEstimatorTests.swift` - 50+ tests
+- `SportsTimeTests/ScenarioAPlannerSwiftTests.swift` - Scenario A tests
+- `SportsTimeTests/ScenarioBPlannerTests.swift` - Scenario B tests
+- `SportsTimeTests/ScenarioCPlannerTests.swift` - Scenario C tests
+
+**Documentation:**
+- `CLAUDE.md` - Project instructions for Claude Code
+- `docs/MARKET_RESEARCH.md` - Competitive analysis
+
+## Naming Conventions
+
+**Files:**
+- PascalCase for Swift files: `TripDetailView.swift`, `DataProvider.swift`
+- Pattern: `{TypeName}.swift` matches primary type
+- Views: `*View.swift`
+- ViewModels: `*ViewModel.swift`
+- Services: `*Service.swift`
+
+**Directories:**
+- PascalCase for feature directories: `Features/Trip/`
+- Plural for collections: `Models/`, `Services/`, `Views/`
+
+**Special Patterns:**
+- `index.ts` equivalent: None (Swift doesn't use barrel files)
+- Test files: `*Tests.swift` in `SportsTimeTests/`
+
+## Where to Add New Code
+
+**New Feature:**
+- Primary code: `Features/{FeatureName}/Views/` and `ViewModels/`
+- Tests: `SportsTimeTests/{FeatureName}Tests.swift`
+- Config if needed: Update `SportsTimeApp.swift` schema if adding models
+
+**New Service:**
+- Implementation: `Core/Services/{ServiceName}.swift`
+- Tests: `SportsTimeTests/{ServiceName}Tests.swift`
+
+**New Planning Algorithm:**
+- Definition: `Planning/Engine/{PlannerName}.swift`
+- Protocol: Implement `ScenarioPlanner` protocol
+- Tests: `SportsTimeTests/{PlannerName}Tests.swift`
+
+**New Domain Model:**
+- Domain struct: `Core/Models/Domain/{Model}.swift`
+- SwiftData model (if persisted): `Core/Models/Local/{Model}.swift`
+- Add to `SportsTimeApp.swift` schema
+
+**Utilities:**
+- Shared helpers: `Core/Utilities/`
+- Extensions: `Core/Extensions/`
+
+## Special Directories
+
+**Resources/ (Bundled Data):**
+- Purpose: Bootstrap data for offline-first
+- Source: Generated by `Scripts/generate_canonical_data.py`
+- Contents: `stadiums_canonical.json`, `teams_canonical.json`, `games_canonical.json`
+- Committed: Yes
+
+**Scripts/ (Python Pipeline):**
+- Purpose: Data scraping, canonicalization, CloudKit import
+- Contents: `scrape_schedules.py`, `cloudkit_import.py`, `canonicalize_*.py`
+- Committed: Yes
+
+**.planning/ (Project Planning):**
+- Purpose: GSD workflow documents
+- Contents: STATE.md, PLAN.md, codebase/
+- Committed: Yes
+
+---
+
+*Structure analysis: 2026-01-09*
+*Update when directory structure changes*