88a5207c2c
Major reduction in CLAUDE.md file sizes to follow concise documentation standard: | File | Before | After | Reduction | |------|--------|-------|-----------| | backend/CLAUDE.md | 2,467 | 123 | 95% | | models/CLAUDE.md | 1,586 | 102 | 94% | | websocket/CLAUDE.md | 2,094 | 119 | 94% | | config/CLAUDE.md | 1,017 | 126 | 88% | | database/CLAUDE.md | 946 | 130 | 86% | | api/CLAUDE.md | 906 | 140 | 85% | Total: 9,016 -> 740 lines (92% reduction) All files now under 150 lines with: - Essential patterns and usage - Cross-references to related docs - Quick-start examples - Updated timestamps 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
120 lines
2.8 KiB
Markdown
120 lines
2.8 KiB
Markdown
# WebSocket Module - Real-Time Game Communication
|
|
|
|
## Purpose
|
|
|
|
Real-time bidirectional communication using Socket.io. Primary interface between players and game engine - all game actions flow through WebSocket events.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Client (Browser)
|
|
↓ Socket.io
|
|
ConnectionManager
|
|
↓
|
|
Event Handlers
|
|
↓
|
|
Game Engine → StateManager → Database
|
|
↓
|
|
Broadcast to All Players
|
|
```
|
|
|
|
## Structure
|
|
|
|
```
|
|
app/websocket/
|
|
├── connection_manager.py # Connection lifecycle & broadcasting
|
|
└── handlers.py # Event handler registration (15 handlers)
|
|
```
|
|
|
|
## ConnectionManager
|
|
|
|
Manages connections, rooms, and broadcasting.
|
|
|
|
**State**:
|
|
- `user_sessions: Dict[str, str]` - sid → user_id
|
|
- `game_rooms: Dict[str, Set[str]]` - game_id → sids
|
|
|
|
**Key Methods**:
|
|
```python
|
|
await manager.connect(sid, user_id)
|
|
await manager.disconnect(sid)
|
|
await manager.join_game(sid, game_id, role)
|
|
await manager.broadcast_to_game(game_id, event, data)
|
|
await manager.emit_to_user(sid, event, data)
|
|
```
|
|
|
|
## Event Handlers (15 Total)
|
|
|
|
### Connection Events
|
|
- `connect` - JWT authentication
|
|
- `disconnect` - Cleanup sessions
|
|
|
|
### Game Flow
|
|
- `join_game` - Join game room
|
|
- `start_game` - Initialize game state
|
|
- `get_game_state` - Request current state
|
|
- `get_box_score` - Get statistics
|
|
|
|
### Decision Submission
|
|
- `submit_defensive_decision` - Defense strategy
|
|
- `submit_offensive_decision` - Offense strategy
|
|
|
|
### Manual Outcome Flow
|
|
- `roll_dice` - Roll dice for play
|
|
- `submit_manual_outcome` - Submit card result
|
|
|
|
### Substitutions
|
|
- `submit_pinch_hitter` - Batting substitution
|
|
- `submit_pitching_change` - Pitcher substitution
|
|
- `submit_defensive_replacement` - Field substitution
|
|
|
|
### Lineup
|
|
- `get_lineup` - Get team lineup
|
|
|
|
## Event Pattern
|
|
|
|
```python
|
|
@sio.event
|
|
async def event_name(sid, data):
|
|
try:
|
|
# 1. Validate input
|
|
# 2. Get game state
|
|
# 3. Process action
|
|
# 4. Broadcast result
|
|
except Exception as e:
|
|
await emit_error(sid, str(e))
|
|
```
|
|
|
|
## Key Events Emitted
|
|
|
|
| Event | Recipient | Purpose |
|
|
|-------|-----------|---------|
|
|
| `game_state_update` | Room | State changed |
|
|
| `play_resolved` | Room | Play completed |
|
|
| `decision_required` | User | Need input |
|
|
| `error` | User | Error occurred |
|
|
| `dice_rolled` | Room | Dice result |
|
|
|
|
## Common Tasks
|
|
|
|
### Broadcasting State Update
|
|
```python
|
|
state_dict = state.model_dump()
|
|
await manager.broadcast_to_game(game_id, "game_state_update", state_dict)
|
|
```
|
|
|
|
### Error Handling
|
|
```python
|
|
await manager.emit_to_user(sid, "error", {"message": str(e)})
|
|
```
|
|
|
|
## References
|
|
|
|
- **Protocol Spec**: `../../.claude/implementation/websocket-protocol.md`
|
|
- **Game Engine**: See `../core/CLAUDE.md`
|
|
- **Frontend Integration**: See `frontend-sba/composables/CLAUDE.md`
|
|
|
|
---
|
|
|
|
**Handlers**: 15/15 implemented | **Updated**: 2025-01-19
|