mtgonline/backend/HANDOFF_WEBSOCKET.md

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