Sportstime/.planning/codebase/STRUCTURE.md

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