8.0 KiB
8.0 KiB
Statement of Intent — MTG Online Web
Project Title
MTG Online Web — A modern, web-based implementation of the MTG Online multiplayer Magic: The Gathering platform.
Vision Statement
To build a fully-featured, open-source multiplayer Magic: The Gathering platform that runs entirely in modern web browsers, eliminating the need for desktop software installations while maintaining compatibility with the existing MTG Online ecosystem.
Problem Statement
The original MTG Online application requires:
- Desktop software installation (Windows, macOS, Linux)
- Manual updates and dependency management
- Complex setup for new users
- Limited accessibility across devices
- No seamless integration with modern web workflows
Solution
A Progressive Web Application (PWA) that provides:
- Zero Installation: Runs directly in any modern web browser
- Cross-Platform: Works on desktop, tablet, and mobile devices
- Instant Updates: Users always have the latest version
- MTG Online Compatible: Interoperates with existing MTG Online users and protocol
- Modern UX: Contemporary interface design with modern web technologies
Core Objectives
1. User Experience
- Intuitive, modern interface that rivals native desktop applications
- Real-time multiplayer gameplay with minimal latency
- Seamless deck building with import/export from MTG Online
- Responsive design that works across all screen sizes
2. Technical Excellence
- Backend: Python 3.12 + FastAPI with async architecture
- Frontend: React + TypeScript with Zustand state management
- Database: PostgreSQL with async SQLAlchemy ORM
- Real-time: WebSocket-based game server for live multiplayer
- Protocol: Full compatibility with MTG Online protocol buffer messages
3. Feature Parity with Desktop
- User authentication and account management
- Deck creation, editing, and storage
- Multiplayer game rooms with real-time state sync
- Card game mechanics (mana, phases, priority, stack)
- Admin/moderation tools (ban, warn, log viewing)
- Card database integration with comprehensive card data
4. Performance
- API response times < 100ms for 95% of requests
- WebSocket latency < 50ms for game state updates
- Support for 1000+ concurrent users
- Sub-second page loads with proper caching
5. Security
- JWT-based authentication with secure token storage
- bcrypt password hashing with configurable rounds
- Rate limiting to prevent abuse
- Input validation and sanitization
- HTTPS-only production deployment
Target Users
Primary Users
- Casual Players: Users who want to play Magic online without installing software
- Mobile Users: Players who want to play on tablets or phones
- New Players: Users who find desktop setup intimidating
Secondary Users
- Tournament Organizers: Need reliable, accessible platform for events
- Community Builders: Want to create and manage playgroups
- Developers: Want to integrate with or extend the MTG Online ecosystem
Existing MTG Online Users
- Seamless migration path
- Protocol compatibility for cross-play
- Familiar deck formats and card data
Key Differentiators
| Feature | Desktop MTG Online | MTG Online Web |
|---|---|---|
| Installation | Required | None (browser-based) |
| Platform | Desktop only | Any device with browser |
| Updates | Manual | Automatic |
| Setup Complexity | High | Low |
| Accessibility | Limited | High |
| Mobile Support | Poor | Excellent |
| Protocol Support | Native | Compatible |
Success Criteria
Functional Requirements
- Users can create accounts and authenticate securely
- Users can create, edit, and manage decks
- Users can join and play multiplayer games in real-time
- Game state syncs correctly across all connected players
- Admin users can manage accounts and moderate games
- Deck formats are compatible with MTG Online desktop client
Performance Requirements
- 95% of API responses < 100ms
- WebSocket message latency < 50ms
- Support 1000+ concurrent users
- Page load time < 2 seconds on 4G connection
- Zero data loss during connection interruptions
Quality Requirements
- 80%+ test coverage for critical paths
- No critical security vulnerabilities
- WCAG 2.1 AA accessibility compliance
- Cross-browser compatibility (Chrome, Firefox, Safari, Edge)
- Mobile-responsive design
Business Requirements
- Open-source with community contributions
- Documentation for users and developers
- Deployment guides for self-hosting
- Integration with existing MTG Online ecosystem
Technology Choices
Backend
Why Python/FastAPI?
- Rapid development with excellent async support
- Type safety with Pydantic models
- Auto-generated API documentation
- Production-tested async framework
- Ecosystem for ML/AI features in future
Why PostgreSQL?
- Robust transaction support
- Excellent JSONB support for flexible data
- Strong concurrency handling
- Mature ecosystem with async drivers
Why async SQLAlchemy?
- Type-safe database operations
- Async support for high concurrency
- Migrations with Alembic
- Large community and ecosystem
Frontend
Why React?
- Component-based architecture
- Large ecosystem and community
- Excellent tooling and debugging
- Reusable component library
Why TypeScript?
- Type safety catches bugs early
- Excellent IDE support
- Modern language features
- Growing adoption in enterprise
Why Zustand?
- Simple, uncluttered state management
- No boilerplate
- Excellent performance
- Small bundle size
Protocol
Why Protocol Buffer Compatibility?
- Interoperability with existing MTG Online users
- Leverage existing card database and deck formats
- Community adoption pathway
- Battle-tested message format
Risk Assessment
High Risk
-
WebSocket Reliability
- Risk: Connection drops during games
- Mitigation: Reconnection logic, game state persistence
-
Game State Consistency
- Risk: Players see different game states
- Mitigation: Server-authoritative state, conflict resolution
-
Performance at Scale
- Risk: Degraded performance with many users
- Mitigation: Load balancing, connection pooling, caching
Medium Risk
-
Mobile Browser Limitations
- Risk: Some features may not work optimally
- Mitigation: Progressive enhancement, fallback strategies
-
Browser Compatibility
- Risk: Older browsers may not support features
- Mitigation: Polyfills, feature detection, graceful degradation
Low Risk
-
Database Migration
- Risk: Schema changes cause issues
- Mitigation: Alembic migrations, backward compatibility
-
Protocol Changes
- Risk: MTG Online protocol evolves
- Mitigation: Version support, backward compatibility
Future Enhancements
Short Term (3-6 months)
- Mobile app (React Native)
- Tournament management system
- Card image CDN optimization
- Performance monitoring and alerting
Medium Term (6-12 months)
- AI-powered deck suggestions
- Social features (friends, clans, notifications)
- Custom game modes and rules
- Integration with Magic Online
Long Term (12+ months)
- Multi-game support (other card games)
- Blockchain-based card ownership
- Advanced analytics and statistics
- Official tournament support
Commitment
We commit to:
- Open Source: Full transparency and community contributions
- Quality: Production-ready code with comprehensive testing
- Security: Regular security audits and updates
- Performance: Continuous optimization and monitoring
- Accessibility: Inclusive design for all users
- Documentation: Clear guides for users and developers
Contact
For questions, contributions, or support:
- GitHub: https://github.com/mtgonline-web
- Documentation: https://mtgonline-web.github.io/docs
- Discord: [Community server link]
Version
Version: 0.1.0 Status: Backend Foundation Complete Last Updated: July 17, 2026
"Building the future of online Magic: The Gathering, one web request at a time."