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