strat-gameplay-webapp/.claude/implementation/NEXT_SESSION.md

Next Session - Phase 3E: X-Check Position Ratings

Current Status: Phase 3E-Main Complete ✅

Overall Phase 3E Progress: 90%

✅ Phase 3E-Main: Position Ratings Integration (COMPLETED)

Completion Date: 2025-11-03 Commit: 02e816a - CLAUDE: Phase 3E-Main - Position ratings integration for X-Check resolution

What Was Accomplished

1. PD API Client Integration

   • Created app/services/pd_api_client.py - async HTTP client using httpx
   • Endpoint: GET https://pd.manticorum.com/api/v2/cardpositions?player_id={id}
   • Supports position filtering via query parameters
   • Tested with real API data (player 8807 - 7 positions)

2. Position Rating Service with Caching

   • Created app/services/position_rating_service.py
   • In-memory caching (16,601x speedup: 0.214s API → 0.000s cache)
   • League-aware: PD fetches ratings, SBA returns empty list
   • Graceful degradation on API errors

3. GameState Integration

   • Added position_rating field to LineupPlayerState
   • Added get_defender_for_position() using StateManager lineup cache
   • Self-contained X-Check data - no lookups during resolution

4. League Config Pattern

   • Added supports_position_ratings() to both league configs
   • PD: Returns True (uses API)
   • SBA: Returns False (uses defaults)

5. PlayResolver Updates

   • Integrated StateManager for O(1) defender lookups
   • Uses actual position ratings when available
   • Falls back to defaults (range=3, error=15) for SBA or missing data

6. Game Engine Updates

   • Added _load_position_ratings_for_lineup() method
   • Loads ratings at game start for both teams (PD league only)
   • Updated PlayResolver instantiation with state_manager

7. Comprehensive Testing

   • Live API integration test (test_pd_api_live.py)
   • Mock API test for CI/CD (test_pd_api_mock.py)
   • Pytest integration suite (tests/integration/test_position_ratings_api.py)
   • Verified full flow: API → Cache → GameState → X-Check resolution

Live Test Results

Player 8807 (7 positions verified):

Position   Range    Error    Arm      Innings
CF         3        2        3        372
2B         3        8        3        212
SS         4        12       4        159
RF         2        2        2        74
LF         3        2        3        62
1B         4        0        3        46
3B         3        65       2        34

Performance Metrics:

• API call: 0.214s
• Cache hit: 0.000013s
• Speedup: 16,601x

---

🎯 Phase 3E-Final: Remaining Work (10%)

Tasks to Complete

1. WebSocket Event Handlers for X-Check UI

Priority: HIGH Estimate: 2-3 hours

• Create handle_xcheck_confirm event handler
• Emit xcheck_result events with defender ratings
• Update frontend WebSocket listeners
• Test real-time X-Check flow end-to-end

Files to Modify:

• app/websocket/game_events.py
• Frontend Socket.io listeners (both leagues)

2. Upgrade to Redis Caching

Priority: MEDIUM Estimate: 3-4 hours

• Add redis-py to requirements.txt
• Create Redis connection pool in app startup
• Migrate position_rating_service.py from in-memory to Redis
• Set TTL on cached ratings (e.g., 24 hours)
• Add Redis cache warming on game start
• Test cache invalidation and recovery

Files to Modify:

• requirements.txt
• app/main.py (startup/shutdown events)
• app/services/position_rating_service.py

Technical Notes:

# Redis key pattern: "position_ratings:{card_id}:{position}"
# TTL: 86400 seconds (24 hours)
# Store as JSON serialized PositionRating.model_dump()

3. Full Defensive Lineup in GameState

Priority: LOW Estimate: 1-2 hours

Currently only current_pitcher and current_catcher are direct fields. Consider adding full defensive positions for easier access:

• Add optional defensive_positions: Dict[str, int] to GameState
• Map position → lineup_id for all 9 fielders
• Update on lineup changes and substitutions
• Evaluate if this improves performance vs current StateManager lookup

Evaluation Needed: May not be necessary since StateManager lookup is already O(1).

4. Manual vs Auto Mode X-Check Workflows

Priority: MEDIUM Estimate: 2 hours

• Document manual mode flow (player confirms chart reads)
• Document auto mode flow (immediate resolution)
• Ensure UI shows defender ratings in both modes
• Add confirmation step in manual mode before advancing

---

📊 Phase 3 Overall Progress

Phase	Status	Progress
3A: Core Models	✅ Complete	100%
3B: Play Validation	✅ Complete	100%
3C: Result Charts	✅ Complete	100%
3D: Dice & Resolution	✅ Complete	100%
3E-Prep: Refactoring	✅ Complete	100%
3E-Main: Position Ratings	✅ Complete	100%
3E-Final: UI & Redis	⏳ In Progress	0%
Overall Phase 3	⏳ In Progress	~95%

---

🚀 Quick Start for Next Session

To continue Phase 3E-Final:

1. Start with WebSocket handlers (highest user impact):

   cd /mnt/NV2/Development/strat-gameplay-webapp/backend
   source venv/bin/activate
   

2. Test current implementation:

   export PYTHONPATH=.
   python test_pd_api_live.py  # Verify API still works
   

3. Add Redis (requires Redis server running):

   # Install Redis if needed
   sudo dnf install redis  # or brew install redis
   
   # Start Redis
   sudo systemctl start redis
   
   # Add to requirements
   echo "redis>=5.0.0" >> requirements.txt
   pip install redis
   

4. Run existing tests:

   pytest tests/integration/test_position_ratings_api.py -v
   

---

📝 Important Notes

Architecture Decisions

• In-memory cache is temporary: Intentional technical debt, Redis upgrade planned
• StateManager pattern: O(1) defender lookups, no DB queries during play resolution
• League-agnostic design: Config-driven behavior, easy to extend to new leagues
• Graceful degradation: Always works even if API/cache is down

API Details

• Base URL: https://pd.manticorum.com
• Endpoint: GET /api/v2/cardpositions?player_id={id}&position={pos}
• Rate Limiting: Unknown - caching mitigates this risk
• Error Handling: Returns empty list on API errors, uses defaults

Testing Strategy

• Live tests: Use player 8807 (7 positions) for comprehensive testing
• Mock tests: For CI/CD without API dependency
• Integration tests: Full flow from API → GameState → X-Check

Performance

• Cache is critical: 16,000x+ speedup
• Load ratings at game start (not during play resolution)
• Redis will enable cross-instance sharing and persistence

---

🔗 Related Documentation

• Full implementation details: backend/CLAUDE.md lines 2132-2264
• Phase 3E-Main commit: 02e816a
• PD API client: app/services/pd_api_client.py
• Position rating service: app/services/position_rating_service.py
• Live integration test: test_pd_api_live.py

---

Last Updated: 2025-11-03 Next Session Focus: WebSocket handlers + Redis caching (Phase 3E-Final)