175 lines
4.8 KiB
Markdown
175 lines
4.8 KiB
Markdown
# MTG Online Web Application
|
|
|
|
A modern web-based implementation of the MTG Online multiplayer Magic: The Gathering platform.
|
|
|
|
## Features
|
|
|
|
- **User Authentication**: Secure JWT-based authentication with bcrypt password hashing
|
|
- **Deck Building**: Full-featured deck editor with import/export in multiple formats
|
|
- **Real-Time Multiplayer**: WebSocket-based game server for live gameplay
|
|
- **Protocol Compatibility**: Compatible with MTG Online protocol buffer messages
|
|
- **Card Database**: Integration with MTJSON for comprehensive card data
|
|
- **Admin Tools**: Comprehensive moderation and administration dashboard
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Python 3.12, FastAPI, SQLAlchemy (async), PostgreSQL
|
|
- **Frontend**: React, TypeScript, Zustand (coming soon)
|
|
- **Game Server**: WebSocket with real-time state synchronization
|
|
- **Authentication**: JWT tokens with bcrypt password hashing
|
|
- **Database**: PostgreSQL with async driver (asyncpg)
|
|
- **Protocol**: Protocol buffer message compatibility
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.12+
|
|
- PostgreSQL 14+
|
|
- Redis (optional, for caching)
|
|
|
|
### Installation
|
|
|
|
1. **Clone the repository**
|
|
|
|
```bash
|
|
git clone https://github.com/yourusername/mtgonline-web.git
|
|
cd mtgonline-web
|
|
```
|
|
|
|
2. **Create a virtual environment**
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
3. **Install dependencies**
|
|
|
|
```bash
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
4. **Configure environment**
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
5. **Set up the database**
|
|
|
|
```bash
|
|
# Create PostgreSQL database
|
|
createdb mtgonline
|
|
|
|
# Run migrations (when Alembic is set up)
|
|
alembic upgrade head
|
|
```
|
|
|
|
6. **Run the application**
|
|
|
|
```bash
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
7. **Access the API documentation**
|
|
|
|
Open http://localhost:8000/docs to view the FastAPI Swagger UI.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
mtgonline-web/
|
|
├── backend/
|
|
│ ├── app/
|
|
│ │ ├── core/ # Core configuration and utilities
|
|
│ │ │ ├── settings.py # Application settings
|
|
│ │ │ ├── database.py # Database engine and sessions
|
|
│ │ │ └── security.py # Authentication and password hashing
|
|
│ │ ├── models/ # SQLAlchemy ORM models
|
|
│ │ │ └── models.py
|
|
│ │ ├── schemas/ # Pydantic schemas
|
|
│ │ │ ├── schemas.py
|
|
│ │ │ ├── proto_messages.py
|
|
│ │ │ └── protocol_constants.py
|
|
│ │ ├── routers/ # API route handlers
|
|
│ │ │ ├── auth.py
|
|
│ │ │ ├── users.py
|
|
│ │ │ ├── decks.py
|
|
│ │ │ ├── rooms.py
|
|
│ │ │ ├── games.py
|
|
│ │ │ ├── admin.py
|
|
│ │ │ └── ws.py
|
|
│ │ ├── services/ # Business logic services
|
|
│ │ │ ├── game_server.py
|
|
│ │ │ ├── card_database.py
|
|
│ │ │ └── deck_parser.py
|
|
│ │ └── main.py # FastAPI application
|
|
│ ├── tests/ # Test suite
|
|
│ ├── requirements.txt # Python dependencies
|
|
│ ├── pyproject.toml # Ruff configuration
|
|
│ └── .env.example # Environment template
|
|
├── frontend/ # React/TypeScript frontend (coming soon)
|
|
├── shared/ # Shared protocol definitions
|
|
│ └── proto/ # Protocol buffer definitions
|
|
└── README.md
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
- `POST /api/v1/auth/login` - User login
|
|
- `POST /api/v1/auth/register` - User registration
|
|
- `POST /api/v1/auth/refresh` - Refresh access token
|
|
- `GET /api/v1/auth/me` - Get current user
|
|
|
|
### Users
|
|
|
|
- `GET /api/v1/users/{user_id}` - Get user by ID
|
|
- `PATCH /api/v1/users/{user_id}` - Update user profile
|
|
- `POST /api/v1/users/{user_id}/ban` - Ban user (admin)
|
|
- `POST /api/v1/users/{user_id}/unban` - Unban user (admin)
|
|
|
|
### Decks
|
|
|
|
- `GET /api/v1/decks/` - List decks
|
|
- `POST /api/v1/decks/` - Create deck
|
|
- `GET /api/v1/decks/{deck_id}` - Get deck
|
|
- `PATCH /api/v1/decks/{deck_id}` - Update deck
|
|
- `DELETE /api/v1/decks/{deck_id}` - Delete deck
|
|
- `GET /api/v1/decks/folders` - List folders
|
|
- `POST /api/v1/decks/folders` - Create folder
|
|
- `DELETE /api/v1/decks/folders/{folder_id}` - Delete folder
|
|
|
|
### Admin
|
|
|
|
- `GET /api/v1/admin/users` - List all users (admin)
|
|
- `GET /api/v1/admin/bans` - List all bans (admin)
|
|
- `POST /api/v1/admin/bans` - Create ban (admin)
|
|
- `POST /api/v1/admin/bans/{ban_id}/unban` - Unban user (admin)
|
|
- `GET /api/v1/admin/logs` - List game logs (admin)
|
|
|
|
## Testing
|
|
|
|
Run the test suite:
|
|
|
|
```bash
|
|
cd backend
|
|
pytest
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please open an issue or submit a pull request.
|
|
|
|
## Support
|
|
|
|
For questions or issues, please open a GitHub issue.
|