Initial commit of mtgonline project
This commit is contained in:
@@ -0,0 +1,246 @@
|
||||
# Statement of Intent — Cockatrice Web
|
||||
|
||||
## Project Title
|
||||
**Cockatrice Web** — A modern, web-based implementation of the Cockatrice 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 Cockatrice ecosystem.
|
||||
|
||||
## Problem Statement
|
||||
The original Cockatrice 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
|
||||
- **Cockatrice Compatible**: Interoperates with existing Cockatrice 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 Cockatrice
|
||||
- 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 Cockatrice 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
|
||||
1. **Casual Players**: Users who want to play Magic online without installing software
|
||||
2. **Mobile Users**: Players who want to play on tablets or phones
|
||||
3. **New Players**: Users who find desktop setup intimidating
|
||||
|
||||
### Secondary Users
|
||||
1. **Tournament Organizers**: Need reliable, accessible platform for events
|
||||
2. **Community Builders**: Want to create and manage playgroups
|
||||
3. **Developers**: Want to integrate with or extend the Cockatrice ecosystem
|
||||
|
||||
### Existing Cockatrice Users
|
||||
- Seamless migration path
|
||||
- Protocol compatibility for cross-play
|
||||
- Familiar deck formats and card data
|
||||
|
||||
## Key Differentiators
|
||||
|
||||
| Feature | Desktop Cockatrice | Cockatrice 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 Cockatrice 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 Cockatrice 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 Cockatrice users
|
||||
- Leverage existing card database and deck formats
|
||||
- Community adoption pathway
|
||||
- Battle-tested message format
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### High Risk
|
||||
1. **WebSocket Reliability**
|
||||
- Risk: Connection drops during games
|
||||
- Mitigation: Reconnection logic, game state persistence
|
||||
|
||||
2. **Game State Consistency**
|
||||
- Risk: Players see different game states
|
||||
- Mitigation: Server-authoritative state, conflict resolution
|
||||
|
||||
3. **Performance at Scale**
|
||||
- Risk: Degraded performance with many users
|
||||
- Mitigation: Load balancing, connection pooling, caching
|
||||
|
||||
### Medium Risk
|
||||
1. **Mobile Browser Limitations**
|
||||
- Risk: Some features may not work optimally
|
||||
- Mitigation: Progressive enhancement, fallback strategies
|
||||
|
||||
2. **Browser Compatibility**
|
||||
- Risk: Older browsers may not support features
|
||||
- Mitigation: Polyfills, feature detection, graceful degradation
|
||||
|
||||
### Low Risk
|
||||
1. **Database Migration**
|
||||
- Risk: Schema changes cause issues
|
||||
- Mitigation: Alembic migrations, backward compatibility
|
||||
|
||||
2. **Protocol Changes**
|
||||
- Risk: Cockatrice 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:
|
||||
1. **Open Source**: Full transparency and community contributions
|
||||
2. **Quality**: Production-ready code with comprehensive testing
|
||||
3. **Security**: Regular security audits and updates
|
||||
4. **Performance**: Continuous optimization and monitoring
|
||||
5. **Accessibility**: Inclusive design for all users
|
||||
6. **Documentation**: Clear guides for users and developers
|
||||
|
||||
## Contact
|
||||
|
||||
For questions, contributions, or support:
|
||||
- GitHub: https://github.com/cockatrice-web
|
||||
- Documentation: https://cockatrice-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."*
|
||||
Reference in New Issue
Block a user