# 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
- [x] Initialize Python project structure
- [x] Create requirements.txt with pinned dependencies
- [x] Set up pydantic-settings configuration
- [x] Configure async SQLAlchemy with PostgreSQL
- [x] Create JWT authentication system with bcrypt
- [x] Set up FastAPI application with CORS

### 1.2 Data Models
- [x] User model (accounts, profiles, VIP status)
- [x] Deck models (decks, folders, files)
- [x] Room model (chat rooms, game types)
- [x] Ban model (moderation, history)
- [x] Game Log model (audit trail)
- [x] Decklist File/Folder models

### 1.3 API Endpoints
- [x] Authentication (login, register, refresh)
- [x] User management (CRUD, ban/unban)
- [x] Deck management (CRUD, folder operations)
- [x] Room management (list, create, update, delete)
- [x] Game management (create, join, leave)
- [x] Admin endpoints (user list, ban management, logs)

### 1.4 Services
- [x] WebSocket game server
- [x] Deck parser (plain text + native XML)
- [x] Card database service (MTJSON integration)
- [x] Protocol constants (MTG Online protocol compatibility)

### 1.5 Testing
- [x] Pytest configuration with async support
- [x] In-memory SQLite for testing
- [x] Auth endpoint tests
- [x] Deck CRUD tests
- [x] Admin endpoint tests

### 1.6 Documentation
- [x] README.md
- [x] API documentation (FastAPI auto-generated)
- [x] Environment configuration template
- [x] Statement of Intent
- [x] Project Roadmap
- [x] 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