admin/mtgonline
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3a70feaba58bc300528ef0f1c7937d0968085e26
mtgonline/STATEMENT_OF_INTENT.md
T

8.0 KiB
Raw Blame History

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:

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 View Git Blame Copy Permalink