60b450d869
- 01-01-PLAN.md: core.py + mlb.py (executed) - 01-02-PLAN.md: nba.py + nhl.py - 01-03-PLAN.md: nfl.py + orchestrator refactor - Codebase documentation for planning context Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
133 lines
4.6 KiB
Markdown
133 lines
4.6 KiB
Markdown
# 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*
|