docs: add Phase 1 plans and codebase documentation
- 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>
This commit is contained in:
Trey t
132
.planning/codebase/CONCERNS.md
Normal file
132
.planning/codebase/CONCERNS.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user