# 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*