Cal Corum 88a5207c2c CLAUDE: Refactor backend CLAUDE.md files for conciseness

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>

2025-11-19 16:10:08 -06:00

2.8 KiB

Raw Permalink Blame History

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:

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

@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

state_dict = state.model_dump()
await manager.broadcast_to_game(game_id, "game_state_update", state_dict)

Error Handling

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

2.8 KiB Raw Permalink Blame History