# 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