60b450d869
- 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>
152 lines
5.4 KiB
Markdown
152 lines
5.4 KiB
Markdown
# 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*
|