Sportstime/.planning/codebase/CONCERNS.md

Codebase Concerns

Analysis Date: 2026-01-09

Tech Debt

Foundation Models disabled:

• Issue: On-device AI route descriptions disabled due to simulator bug
• File: SportsTime/Core/Services/RouteDescriptionGenerator.swift:30
• Why: iOS 26.2 simulator crashes with Foundation Models
• Impact: Route descriptions not generated; feature incomplete
• Fix approach: Re-enable when Apple fixes the framework (tracked via TODO)

Large service files:

• Issue: Some service files exceed 500-800 lines
• Files: SportsTime/Core/Services/SuggestedTripsGenerator.swift (794 lines)
• Why: Accumulated functionality over time
• Impact: Harder to navigate and test in isolation
• Fix approach: Extract helper methods to focused utilities

Known Bugs

No known bugs documented.

The codebase has comprehensive test coverage (180+ tests) and follows a regression test protocol for bug fixes.

Security Considerations

No hardcoded secrets:

• CloudKit uses entitlements (no API keys in code)
• Sports APIs are public (no authentication required)
• No .env files or credential storage

CloudKit data access:

• Risk: Public database readable by any app user
• Current mitigation: Only non-sensitive schedule data in public DB
• Recommendations: User data correctly uses private database

Force unwrap usage:

• Risk: Potential crashes from force unwraps (!)
• Current state: Limited to test fixtures and controlled scenarios
• Recommendations: Continue avoiding force unwraps in production code

Performance Bottlenecks

No significant bottlenecks detected.

• Route planning uses efficient DAG-based algorithms with beam search
• Data loading is async and non-blocking
• PDF export uses parallel asset prefetching (PDFAssetPrefetcher.swift)

Potential areas to monitor:

• Large game datasets (1000+ games) during planning
• Map snapshot generation for long trips (10+ stops)

Fragile Areas

GameDAGRouter complexity:

• File: SportsTime/Planning/Engine/GameDAGRouter.swift
• Why fragile: Complex beam search with diversity pruning
• Common failures: Edge cases in route diversity calculations
• Safe modification: Comprehensive test coverage exists (180+ tests total)
• Test coverage: Good - multiple scenario planner test suites

Canonical data sync:

• Files: SportsTime/Core/Services/CanonicalSyncService.swift, DataProvider.swift
• Why fragile: Multiple data sources (bundled JSON, SwiftData, CloudKit)
• Common failures: Data inconsistency if sync partially completes
• Safe modification: Follow existing patterns, test offline scenarios
• Test coverage: Limited - manual testing recommended

Scaling Limits

CloudKit free tier:

• Current capacity: Standard CloudKit quotas
• Limit: 10GB public database, rate limits on queries
• Symptoms at limit: 429 errors, slow sync
• Scaling path: Monitor usage; Apple provides generous free tier

In-memory data cache:

• Current capacity: All stadiums, teams loaded into memory (~few MB)
• Limit: Not expected to hit limits with current data size
• Symptoms at limit: Memory pressure on older devices
• Scaling path: Implement lazy loading if data grows significantly

Dependencies at Risk

NBA Stats API (unofficial):

• Risk: Unofficial API that may break without notice
• File: SportsTime/Core/Services/ScoreAPIProviders/NBAStatsProvider.swift
• Impact: NBA game scores unavailable if API changes
• Migration plan: Multi-provider fallback system in FreeScoreAPI.swift

iOS 26+ requirement:

• Risk: Limits user base to newest iOS version
• Impact: Users on older devices cannot use app
• Migration plan: Monitor adoption; consider lowering deployment target later

Missing Critical Features

None blocking current functionality.

Future phases documented in docs/MARKET_RESEARCH.md:

• Phase 2: AI-powered natural language planning
• Phase 3: Stadium bucket list with achievements (partially implemented)
• Phase 4: Group trip coordination
• Phase 5: Fan community features

Test Coverage Gaps

CloudKit sync integration:

• What's not tested: Full CloudKit → SwiftData → memory refresh cycle
• Risk: Sync issues not caught before production
• Priority: Medium
• Difficulty to test: Requires CloudKit test containers or mocks

PDF generation:

• What's not tested: PDFGenerator output (visual testing)
• Risk: PDF layout issues not caught automatically
• Priority: Low (manual QA sufficient)
• Difficulty to test: Would need snapshot testing

UI tests:

• What's not tested: Limited UI test coverage
• Risk: UI regressions
• Priority: Low (app is relatively simple UI)
• Difficulty to test: Standard Xcode UI testing

---

Concerns audit: 2026-01-09 Update as issues are fixed or new ones discovered