Add WebSocket game server architecture and handoff documentation

2026-10-19 12:05:13 +00:00
parent 1331885455
commit 92d3d40bc7
3 changed files with 623 additions and 12 deletions
@@ -0,0 +1,144 @@
+# MTG Online WebSocket Game Server - Handoff Document
+
+## Project Overview
+
+MTG Online is a multiplayer Magic: The Gathering platform with a FastAPI backend. Phase 5 (Game Management) is complete. Phase 6 (WebSocket Game Server) is ready for implementation.
+
+## Current Status
+
+- **Phase 1-4:** Complete (authentication, users, decks, cards, user data)
+- **Phase 5:** Complete (game management, rooms, MTGJSON integration)
+- **Phase 6:** In Progress (WebSocket game server architecture designed)
+
+## Codebase Structure
+
+```
+/home/wall-o/projects/mtgonline/backend/
+├── app/
+│   ├── core/         # Configuration, database, security, logging
+│   ├── models/       # SQLAlchemy ORM models
+│   ├── routers/      # API endpoint definitions
+│   ├── services/     # Business logic layer
+│   ├── schemas/      # Pydantic request/response schemas
+│   └── main.py       # Application entry point
+├── tests/            # Test suite (28 tests, all passing)
+├── docs/             # Documentation
+└── state.json        # Project state
+```
+
+## Recent Changes
+
+1. **Fixed critical bug** in `games_router.py`: `player_result` → `player_stmt` in `create_game` endpoint
+2. **Fixed deprecation warning** in `main.py`: Updated lifespan from generator to `@asynccontextmanager`
+3. **Designed WebSocket architecture** documented in `docs/WEB_SOCKET_ARCHITECTURE.md`
+
+## WebSocket Game Server Architecture
+
+The architecture is fully designed and documented. Key components:
+
+### Protocol
+- JSON message format with type, sequence number, timestamp, and payload
+- Message types: connection management, game lifecycle, player actions, turn management, chat
+- JWT authentication via `hello` message
+
+### Components
+1. **WebSocket Endpoint** (`/ws/game/{game_id}`) - connection management
+2. **Game Server Manager** - coordinates active game instances
+3. **Game State Manager** - authoritative state, validates actions
+4. **Persistence Layer** - PostgreSQL for state saving and recovery
+
+### Concurrency
+- asyncio-based architecture
+- Game-level locks for state mutations
+- Action queue for ordering within turns
+
+### Key Features
+- Full state snapshots on connection
+- Incremental state updates for changes
+- Priority system for turn management
+- Reconnection and recovery support
+- Error handling with specific error codes
+
+## Implementation Plan
+
+### Phase 1: Basic Infrastructure
+- WebSocket endpoint setup
+- Connection management
+- Authentication
+- Basic message routing
+
+### Phase 2: Game State Management
+- Game state model
+- State serialization
+- Full state snapshots
+- Incremental updates
+
+### Phase 3: Turn and Phase Management
+- Turn structure implementation
+- Phase transitions
+- Priority system
+- Action validation
+
+### Phase 4: Player Actions
+- Card play actions
+- Combat actions
+- Spell casting
+- Ability activation
+
+### Phase 5: Persistence and Recovery
+- Game state persistence
+- Reconnection handling
+- Game recovery
+- Chat history
+
+### Phase 6: Testing and Optimization
+- Unit tests
+- Integration tests
+- Load testing
+- Performance optimization
+
+## Technical Stack
+
+- **Language:** Python 3.12
+- **Framework:** FastAPI
+- **ORM:** SQLAlchemy 2.0
+- **Database:** SQLite (development), PostgreSQL (production)
+- **Auth:** JWT (python-jose)
+- **WebSocket:** FastAPI built-in WebSocket support
+
+## Key Files
+
+- `app/main.py` - Application entry point with WebSocket endpoint registration
+- `app/routers/games_router.py` - Game management endpoints (includes basic WebSocket endpoint)
+- `app/services/game_server.py` - Game server service (basic implementation exists)
+- `docs/WEB_SOCKET_ARCHITECTURE.md` - Complete architecture document
+- `tests/` - Test suite
+
+## Testing
+
+- 28 tests currently passing
+- Test framework: pytest with pytest-asyncio
+- Database: In-memory SQLite for tests
+- Run tests: `pytest --tb=short`
+
+## Environment
+
+- Host venv: `/home/wall-o/workspace/venv`
+- Run as user: `wall-o` (UID 1001)
+- Gitea credentials: `/home/wall-o/projects/gitea_credentials.txt`
+- Repository: `https://git.optimex.systems/admin/mtgonline.git`
+
+## Next Steps
+
+1. Implement WebSocket game server following the architecture document
+2. Add test coverage for games, cards, and user_data routers
+3. Configure linting (Ruff)
+4. Add pre-commit hooks
+5. Set up CI/CD pipeline
+
+## Notes
+
+- The codebase is well-structured with clean separation of concerns
+- Comprehensive docstrings and type hints throughout
+- Service layer abstraction is well-implemented
+- No need for code simplification - architecture is already clean