Sportstime/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-01-09

Pattern Overview

Overall: Clean MVVM with Feature-Based Modules + Offline-First Data Architecture

Key Characteristics:

• Three-layer architecture (Presentation, Domain, Data)
• Single source of truth (AppDataProvider.shared)
• Offline-first with background CloudKit sync
• Scenario-based trip planning (A/B/C discriminated scenarios)
• Explicit failure handling (no silent errors)

Layers

Presentation Layer (Features/):

• Purpose: SwiftUI Views + @Observable ViewModels
• Contains: Feature modules (Home, Trip, Schedule, Settings, Progress)
• Depends on: Domain layer for planning, Data layer for models
• Used by: App entry point

Domain Layer (Planning/):

• Purpose: Trip planning business logic
• Contains: TripPlanningEngine, Scenario Planners, GameDAGRouter, TravelEstimator
• Depends on: Domain models only (Game, Stadium, Team)
• Used by: Presentation layer ViewModels

Data Layer (Core/):

• Purpose: Models, services, persistence
• Contains: Domain models, SwiftData models, CloudKit sync, location services
• Depends on: Foundation, SwiftData, CloudKit, MapKit
• Used by: All layers

Export Layer (Export/):

• Purpose: PDF generation with asset prefetching
• Contains: PDFGenerator, map snapshots, remote images, POI search
• Depends on: Domain models, UIKit/PDFKit
• Used by: TripDetailView

Data Flow

App Startup Sequence:

1. SportsTimeApp.swift (@main) → WindowGroup
2. BootstrappedContentView initializes data:
   • BootstrapService.bootstrapIfNeeded() - JSON → SwiftData (first launch)
   • AppDataProvider.configure(with: context) - Sets ModelContext
   • AppDataProvider.loadInitialData() - SwiftData → memory
3. App immediately usable with local data
4. Background: CanonicalSyncService.syncAll() - CloudKit → SwiftData (non-blocking)

Trip Planning Request:

1. User Input → TripCreationView
2. TripCreationViewModel builds PlanningRequest
3. TripPlanningEngine.planItineraries(request:)
   • Detects scenario (A: date range, B: selected games, C: locations)
   • Delegates to appropriate ScenarioPlanner
4. GameDAGRouter finds routes with diversity
5. Returns ItineraryResult (success with ranked options or explicit failure)
6. User selects option → SavedTrip persisted

State Management:

• ViewModels use @Observable (not ObservableObject)
• SwiftData @Query for saved trips
• In-memory cache in AppDataProvider for canonical data

Key Abstractions

AppDataProvider:

• Purpose: Single source of truth for all canonical data reads
• Location: Core/Services/DataProvider.swift
• Pattern: Singleton with in-memory cache
• Usage: AppDataProvider.shared.stadiums, .teams, .fetchGames()

ScenarioPlanner Protocol:

• Purpose: Encapsulates planning algorithm for each scenario type
• Examples: ScenarioAPlanner, ScenarioBPlanner, ScenarioCPlanner
• Pattern: Strategy pattern with factory (ScenarioPlannerFactory)

GameDAGRouter:

• Purpose: DAG-based route finding with multi-dimensional diversity
• Location: Planning/Engine/GameDAGRouter.swift
• Pattern: Beam search with diversity pruning

TripPlanningEngine:

• Purpose: Thin orchestrator delegating to scenario planners
• Location: Planning/Engine/TripPlanningEngine.swift
• Pattern: Facade wrapping scenario detection and filter application

Entry Points

App Entry:

• Location: SportsTime/SportsTimeApp.swift
• Triggers: App launch
• Responsibilities: SwiftData schema, ModelContainer, BootstrappedContentView

Main UI Entry:

• Location: Features/Home/Views/HomeView.swift
• Triggers: After bootstrap completes
• Responsibilities: TabView with 4 tabs (Home, Schedule, Trips, Progress)

Trip Creation:

• Location: Features/Trip/Views/TripCreationView.swift
• Triggers: User taps "New Trip"
• Responsibilities: Form input, calls TripCreationViewModel

Trip Display:

• Location: Features/Trip/Views/TripDetailView.swift
• Triggers: User selects trip
• Responsibilities: Itinerary display, conflict detection, PDF export

Error Handling

Strategy: Explicit failure types with reasons, no silent errors

Patterns:

• ItineraryResult enum: .success([ItineraryOption]) or .failure(PlanningFailure)
• PlanningFailure contains FailureReason and user-friendly message
• ViewModels expose .error state for UI display
• Services use throws for recoverable errors

Cross-Cutting Concerns

Logging:

• print() with emoji prefixes for debugging
• No production logging framework

Validation:

• Input validation in ViewModels before planning
• ConstraintViolation type for planning constraints

Thread Safety:

• @MainActor for UI-bound services
• actor types for planning engine components
• Explicit isolation annotations throughout

Data Consistency:

• Canonical IDs (string) + UUIDs for stable identity
• SwiftData ↔ Domain model conversion via .toDomain() methods

---

Architecture analysis: 2026-01-09 Update when major patterns change