mtgonline/ROADMAP.md

Cockatrice Web — Project Roadmap

Overview

A modern web-based implementation of the Cockatrice 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 (Cockatrice 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: Frontend Development (TODO)

2.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

2.2 Authentication

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

2.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)

2.4 Game Interface

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

2.5 Chat System

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

2.6 Admin Dashboard

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

Phase 3: Integration & Polish (TODO)

3.1 WebSocket Client

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

3.2 Card Database

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

3.3 Game Logic

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

3.4 Performance

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

Phase 4: Deployment & Production (TODO)

4.1 DevOps

• Docker Compose for development
• Production Docker images
• CI/CD pipeline (GitHub Actions)
• Environment configuration management

4.2 Security

• Rate limiting
• Input validation and sanitization
• CORS configuration
• HTTPS/SSL configuration

4.3 Monitoring

• Logging with structured formats
• Error tracking (Sentry)
• Performance monitoring
• Uptime monitoring

4.4 Documentation

• User documentation
• Developer documentation
• API documentation
• Architecture documentation

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