145 lines
4.5 KiB
Markdown
145 lines
4.5 KiB
Markdown
# 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
|