mtgonline/ROADMAP.md

MTG Online Web — Project Roadmap

Overview

A modern web-based implementation of the MTG Online multiplayer Magic: The Gathering platform. Built with Python/FastAPI backend and React/TypeScript frontend to replace the legacy C++/Qt desktop client.

Phase 1: Backend Foundation ✅ (COMPLETED)

1.1 Project Setup

• Initialize Python project structure
• Create requirements.txt with pinned dependencies
• Set up pydantic-settings configuration
• Configure async SQLAlchemy with PostgreSQL
• Create JWT authentication system with bcrypt
• Set up FastAPI application with CORS

1.2 Data Models

• User model (accounts, profiles, VIP status)
• Deck models (decks, folders, files)
• Room model (chat rooms, game types)
• Ban model (moderation, history)
• Game Log model (audit trail)
• Decklist File/Folder models

1.3 API Endpoints

• Authentication (login, register, refresh)
• User management (CRUD, ban/unban)
• Deck management (CRUD, folder operations)
• Room management (list, create, update, delete)
• Game management (create, join, leave)
• Admin endpoints (user list, ban management, logs)

1.4 Services

• WebSocket game server
• Deck parser (plain text + native XML)
• Card database service (MTJSON integration)
• Protocol constants (MTG Online protocol compatibility)

1.5 Testing

• Pytest configuration with async support
• In-memory SQLite for testing
• Auth endpoint tests
• Deck CRUD tests
• Admin endpoint tests

1.6 Documentation

• README.md
• API documentation (FastAPI auto-generated)
• Environment configuration template
• Statement of Intent
• Project Roadmap
• State tracking

Phase 2: V1 Backend — Deck Building & Card Management (IN PROGRESS)

2.0 Project Setup

• Initialize Python project structure
• Create requirements.txt with pinned dependencies
• Set up pydantic-settings configuration
• Configure async SQLAlchemy with PostgreSQL
• Create JWT authentication system with bcrypt
• Set up FastAPI application with CORS
• Fuzzy matching library setup (python-Levenshtein / thefuzz)

2.1 Database Models

• User model (accounts, profiles, VIP status)
• Ban model (moderation, history)
• NEW: User Deck model (user_decks table)
  • deck_id (PK, auto-increment)
  • user_id (FK → users)
  • name (text)
  • status (ENUM: DRAFT, FINAL)
  • cards (JSONB or junction table with card_id, quantity)
  • created_at, updated_at (timestamps)
  • folder_id (FK → user folders, optional)
• NEW: User Card model (user_cards table)
  • user_card_id (PK, auto-increment)
  • user_id (FK → users)
  • card_id (FK → mtg_cards from mtgdata)
  • raw_name (original name from import file)
  • confidence (match score from fuzzy search)
  • imported_at (timestamp)
  • import_id (FK → import batch)
• NEW: Card Import Batch model
  • import_id (PK)
  • user_id (FK → users)
  • file_name (text)
  • status (ENUM: PENDING, PROCESSING, COMPLETED, FAILED)
  • total_cards (int)
  • matched_cards (int)
  • created_at (timestamp)

2.2 API Endpoints

User Deck CRUD

• POST /decks/ — Create new draft deck (auto status: DRAFT)
• GET /decks/ — List user's decks, filterable by status
• GET /decks/{deck_id} — Get full deck details
• PATCH /decks/{deck_id} — Update deck (name, status, card list)
• POST /decks/{deck_id}/finalize — Transition DRAFT → FINAL
• DELETE /decks/{deck_id} — Delete deck (only if FINAL, or admin override)
• GET /decks/{deck_id}/cards — Get cards in deck with quantity counts

Card Search & Suggestions

• GET /api/cards/search?q={query}&type={type}&set={set}&color={color} — Search MTG cards
• GET /api/cards/{card_id} — Get card details
• GET /api/sets/ — List available sets
• GET /api/cards/suggest?deck_id={deck_id}&limit={n} — Suggest similar cards

Card Import

• POST /cards/import — Upload file (XLSX, CSV, JSON, ODS)
• GET /cards/import/{import_id}/status — Check import progress
• GET /cards/import/{import_id}/results — Get match results with confidence
• POST /cards/import/{import_id}/confirm — Confirm import
• GET /user/cards — List user's imported cards
• DELETE /user/cards/{card_import_id} — Remove from user cards

2.3 Services

Deck Building Services

• services/deck_manager.py — Deck CRUD operations, status transitions
• services/card_search.py — Card search with filters (name, type, set, color)
• services/deck_suggestion.py — Similar card suggestions based on existing deck
  • Match by: same type, same color, same set, same mana cost
  • Match by: cards often paired in existing user decks

Card Import Services

• services/file_parser.py — Parse XLSX, CSV, JSON, ODS files
  • Each row = one card entry (duplicates allowed)
• services/fuzzy_card_matcher.py — Fuzzy string matching service
  • Handle spelling errors (e.g., "Wondrrland" → "Wonderland")
  • Handle American vs British English (e.g., "color" vs "colour")
  • Use python-Levenshtein or thefuzz for matching
  • Return confidence scores for each match
• services/import_batch_processor.py — Process import batches
  • Batch fuzzy matching for all cards in file
  • Update import batch status
  • Save matched cards to user_cards table

2.4 Fuzzy Matching Implementation

Requirements

• Must handle spelling errors in card names
• Must handle American vs British English differences
• Must return confidence scores for match quality
• Must process bulk imports efficiently

Approach

1. Use thefuzz (Python) or python-Levenshtein for string matching
2. Implement two-stage matching:
   • Stage 1: Exact match (if card name exists exactly)
   • Stage 2: Fuzzy match (if no exact match, find best match)
3. Configure similarity threshold (e.g., 85% for auto-accept, 70-84% for manual review)
4. Pre-process card names to normalize:
   • Remove extra whitespace
   • Normalize punctuation
   • Handle known spelling variants

Example Match Results

Raw: "Wondrrland Explorer"
Match: "Wonderland Explorer" (confidence: 92%)

Raw: "Armour Plated"
Match: "Armor Plated" (confidence: 88%)

Raw: "Colorful Burst"
Match: "Color Burst" (confidence: 85%)

2.5 Multiplayer Play Backend — Architecture Blueprint (Derived from Cockatrice Analysis)

A detailed architecture analysis of Cockatrice (v3.1.0 "Graduation Day") — the mature open-source MTG online client/server — has been completed at /home/wall-o/projects/mtgonline/C++/ARCHITECTURE_ANALYSIS.md.

The play backend will follow the same authoritative server model, adapted for a modern web stack:

Authority Model

┌─────────────────┐         WebSocket (JSON)             ┌─────────────────┐
│   CLIENT        │◄────────────────────────────────────►│   SERVER        │
│  (React/TS)     │                                      │  (FastAPI/Py)   │
│                 │                                      │                 │
│ • Game Scene    │   GameCommands (play, attack, etc.)  │ • PostgreSQL    │
│ • Hand View     │◄────────────────────────────────────►│ • Game State    │
│ • Chat Panel    │   GameEvents (state changes)         │ • Room/Player   │
│ • Deck Panel    │                                      │   Management    │
│ • Phase Toolbar │   Chat, Admin, Spectator             │ • Replay Log    │
└─────────────────┘                                      └─────────────────┘

Game Engine Architecture

Cockatrice Component	Modern Web Equivalent	Role
AbstractGame	Game (server-side)	Core game instance holding state, players, event handler
GameMetaInfo	GameMetadata	gameId, maxPlayers, description, started, spectators
GameState	GameBoardState	currentPhase, activePlayer, hostId, gameTimer
GameEventHandler	GameEventDispatcher	Central dispatch — processes events, prepares commands (~21KB in Cockatrice)
PlayerManager	PlayerRegistry	Coordinates all players in a game
PlayerLogic	Player	Per-player game logic (~10.7KB in Cockatrice)
PlayerActions	PlayerCommands	Concrete commands: play, attack, tap, draw (~64KB in Cockatrice)
CardZone	Zone (base class)	Abstract zone — Hand/Stack/Table/Graveyard/Exile/Library
HandZone	Hand	Player's hand (secret/hidden zone)
StackZone	Stack	Spells/abilities on the stack
TableZone	Battlefield	Permanents on the battlefield
PileZone	Pile (Graveyard, Exile, Library)	Discard/exile/draw piles
Replay	GameReplay	Serialized event stream for replay
Phase	TurnPhase	11-phase MTG turn structure

Turn Phase System (11 Phases with Sub-Phases)

Untap → Upkeep → Draw → Main 1 → Combat → Main 2 → End → Cleanup
                                        │
                                        └── Sub-phases:
                                            Beginning of Combat
                                            Declare Attackers
                                            Declare Blockers
                                            Combat Damage
                                            End of Combat

Command/Event Flow

User Action (React component)
    │
    ▼
GameCommand (JSON message)
    │
    ▼
GameEventDispatcher.process()
    │
    ▼
Player.handleCommand()
    │
    ▼
ZoneLogic (state mutation)
    │
    ▼
GameEvent (broadcast to all clients via WebSocket)
    │
    ▼
Client receives & updates UI via Zustand/XState

Network Protocol Design (Adapted from Cockatrice's protobuf)

Cockatrice uses Protocol Buffers over TCP. The modern web equivalent replaces protobuf with JSON over WebSocket:

Cockatrice Proto Message	JSON WebSocket Message
ServerInfo_Game	{ "type": "game_info", "game_id": 1, "max_players": 2, ... }
ServerInfo_Player	{ "type": "player_info", "player_id": 1, "name": "...", ... }
Command_PlayCard	{ "type": "cmd_play_card", "card_id": 42, "zone": "hand", ... }
Command_Attack	{ "type": "cmd_attack", "attacker_id": 7, "targets": [3, 5], ... }
Event_Join	{ "type": "event_join", "player_id": 2, "properties": {...} }
Event_Leave	{ "type": "event_leave", "player_id": 1, "reason": "..." }
Event_SetActivePlayer	{ "type": "event_active_player", "player_id": 1 }
Event_SetActivePhase	{ "type": "event_active_phase", "phase": 5 }
Event_GameSay	{ "type": "event_chat", "player_id": 1, "message": "..." }
GameReplay	{ "type": "replay", "events": [...] }

Architecture Patterns to Reuse

Pattern	Cockatrice Usage	Modern Equivalent
Event Bus	Qt signals/slots	WebSocket broadcast + Zustand stores
Command Pattern	Command_PlayCard, Command_Attack	JSON command messages, validated server-side
Observer	GameEventHandler emits signals	WebSocket events trigger UI updates
Strategy	CardZoneLogic subclasses	Zone classes with strategy pattern (Hand, Stack, Table, Pile, View)
Facade	AbstractGame	Single Game object wrapping all subsystems
Memento	DeckListMemento for undo	Immutable state snapshots for undo/redo
Repository	ServatriceDatabaseInterface	SQLAlchemy repositories for game state, decks, logs

Key Decisions (Informed by Cockatrice Analysis)

1. Server is authoritative — clients send commands, server validates and broadcasts events. No client-side state manipulation.
2. Deterministic replay — serialize all game events; same command sequence produces identical state.
3. Zone abstraction — each zone type (Hand, Stack, Battlefield, Pile) is independently implementable.
4. Phase system — 11-phase MTG turn with sub-phases, tracked server-side.
5. Command/Event separation — what a player wants to do vs. what happens.

What Modernizes Cockatrice

Cockatrice Limitation	Modern Web Solution
TCP only, no web protocol	WebSocket (JSON)
Qt Widgets desktop UI	React/Next.js with PixiJS for game board
C++/MySQL backend	Python/FastAPI + PostgreSQL
Single-server clustering	Stateless game servers + Redis state cache
No mobile support	Responsive design from start
No REST API	FastAPI REST + WebSocket hybrid
Protobuf serialization	JSON over WebSocket
106KB monolithic server handler	Modular service architecture

2.6 Play Backend Responsibilities

The play backend will implement:

• Real-time game state management (server-authoritative)
• Multiplayer WebSocket communication
• Game rule enforcement (combat, stack resolution, priority)
• Deck validation during gameplay
• Game history and replay (serialized event log)
• Room and game lobbies
• Spectator mode
• Admin commands (kick, ban, game control)

Note: The play backend lives in a separate codebase. Integration points with the card backend:

• Card Backend API (http://backend:8000):
  • Authentication via JWT
  • Card lookups: GET /api/cards/{card_id}
  • Card search: GET /api/cards/search?q=...
  • Set lists: GET /api/sets/
  • User decks: GET /api/users/{user_id}/decks
• Direct PSQL Access:
  • mtgdata database: Read card data, sets, etc.
  • mtgonline database: Read user decks, validate deck legality
  • Normalize punctuation
  • Handle known spelling variants

Example Match Results

Raw: "Wondrrland Explorer"
Match: "Wonderland Explorer" (confidence: 92%)

Raw: "Armour Plated"
Match: "Armor Plated" (confidence: 88%)

Raw: "Colorful Burst"
Match: "Color Burst" (confidence: 85%)

2.5 Multiplayer Play Backend (SEPARATE CODEBASE)

Architecture

The multiplayer gameplay feature will live in a separate backend codebase to ensure smooth, independent development.

Integration Points

• Card Backend API (http://backend:8000):

  • Authentication via JWT
  • Card lookups: GET /api/cards/{card_id}
  • Card search: GET /api/cards/search?q=...
  • Set lists: GET /api/sets/
  • User decks: GET /api/users/{user_id}/decks

• Direct PSQL Access:

  • mtgdata database: Read card data, sets, etc.
  • mtgonline database: Read user decks, validate deck legality

Play Backend Responsibilities

• Real-time game state management
• Multiplayer WebSocket communication
• Game rule enforcement
• Deck validation during gameplay
• Game history and replay

Note: This backend is out of scope for the current codebase. See separate repository when ready.

2.6 Testing

• Unit tests for deck CRUD operations
• Unit tests for card search functionality
• Unit tests for card suggestion algorithm
• Unit tests for file parsers (XLSX, CSV, JSON, ODS)
• Unit tests for fuzzy matching service
• Integration tests for import workflow
• Load tests for bulk import processing

2.7 Documentation

• API documentation (FastAPI auto-generated)
• Database schema documentation
• Fuzzy matching algorithm documentation
• Import workflow documentation
• Play backend integration guide

Phase 3: Frontend Development (TODO)

3.1 Project Setup

• Initialize React + TypeScript project with Vite
• Configure ESLint, Prettier, TypeScript strict mode
• Set up Zustand for state management
• Configure Tailwind CSS for styling
• Set up Vitest + React Testing Library

3.2 Authentication

• Login form with JWT token storage
• Registration form with validation
• Protected routes and auth context
• Session management and token refresh

3.3 Deck Builder

• Card search with filters (name, color, type, set)
• Deck list editor with drag-and-drop
• Import/export deck formats (plain text, native XML)
• Folder management UI
• Real-time deck statistics (card count, mana curve)
• NEW: Deck status indicator (DRAFT vs FINAL)
• NEW: Card suggestion panel (shows similar cards)

3.4 Card Import Interface

• File upload component (XLSX, CSV, JSON, ODS)
• Import progress indicator
• Match results display with confidence scores
• Manual override for low-confidence matches
• Import history and re-import capability

3.5 Game Interface (TODO - Dependent on Play Backend)

• Game board visualization (zones, cards)
• Player hand (private zone)
• Library, graveyard, exile, command zones
• Card interaction (click, drag, hover)
• Real-time WebSocket updates

3.6 Chat System

• Room chat interface
• Game chat (in-game messaging)
• Player list display
• Moderator tools (kick, ban)

3.7 Admin Dashboard

• User management interface
• Ban/unban controls
• Game logs viewer
• System statistics

Phase 4: Integration & Polish (TODO)

4.1 WebSocket Client

• WebSocket connection management
• Reconnection logic with exponential backoff
• Message serialization/deserialization
• Protocol buffer message handling

4.2 Card Database

• Import MTJSON card data
• Cache card images locally
• Search and filter functionality
• Card tooltips with oracle text

4.3 Game Logic (TODO - Dependent on Play Backend)

• Turn-based state management
• Priority system implementation
• Stack resolution
• Mana payment tracking
• Life totals and counters

4.4 Performance

• Virtual scrolling for card lists
• Memoization and React.memo
• Code splitting and lazy loading
• WebSocket message batching

Phase 5: Advanced Features (FUTURE)

5.1 Multiplayer Enhancements

• Spectator mode
• Game replay system
• Tournament support
• Custom game rules

5.2 Card Database

• Set filtering
• Card comparison
• Deck sharing and discovery
• Community decks

5.3 Mobile Support

• Responsive design
• PWA support
• Touch gestures
• Mobile-optimized controls

5.4 Integrations

• OAuth providers (Google, GitHub)
• Discord bot integration
• API webhooks
• Third-party deck sharing platforms

Timeline

Phase	Duration	Status
Phase 1: Backend Foundation	2 weeks	✅ Complete
Phase 2: Frontend Development	4 weeks	Not Started
Phase 3: Integration & Polish	2 weeks	Not Started
Phase 4: Deployment & Production	1 week	Not Started
Phase 5: Advanced Features	Ongoing	Future

Success Metrics

• Users can create accounts and log in
• Users can create and edit decks
• Users can play multiplayer games in real-time
• Game state syncs correctly across all players
• Admins can manage users and monitor games
• API response time < 100ms for 95% of requests
• WebSocket latency < 50ms
• Zero critical security vulnerabilities

Dependencies

Backend

• Python 3.12+
• PostgreSQL 14+
• Redis (optional, for caching)
• Node.js 18+ (for protocol buffer compilation)

Frontend

• Node.js 18+
• npm or pnpm
• Browser with WebSocket support

Development

• Git
• Docker (optional)
• VS Code or similar IDE
• PostgreSQL client (psql or DBeaver)

Risk Mitigation

Risk	Mitigation
WebSocket reliability	Implement reconnection with exponential backoff
Game state inconsistency	Server-authoritative state with conflict resolution
Performance at scale	Load balancing, connection pooling, caching
Security vulnerabilities	Input validation, rate limiting, HTTPS
Data loss	Database backups, transaction logs

Future Considerations

• Migration to Rust for game server performance
• Integration with Magic Online API
• Support for custom card games
• AI-powered deck suggestions
• Blockchain-based card ownership verification