akadmin
46abfe5fbc
- Updated root README with current architecture (dual PostgreSQL, Redis, MTGJSON pipeline) - Created backend/README.md with detailed architecture, database setup, and troubleshooting - Updated state.json to reflect completed documentation phase
105 lines
3.8 KiB
Markdown
105 lines
3.8 KiB
Markdown
# MTG Online Backend
|
|
|
|
A Python FastAPI application that processes Magic: The Gathering card data from [MTGJSON](https://mtgjson.com/) and stores it in PostgreSQL, with Redis for caching.
|
|
|
|
## Overview
|
|
|
|
This project provides a backend API for a Magic: The Gathering Online platform. It downloads and processes MTGJSON v5 dataset dumps, loads them into a PostgreSQL database, and exposes REST endpoints for card data, user authentication, deck management, and game state.
|
|
|
|
### Key Features
|
|
|
|
- **MTGJSON Data Pipeline** — Downloads `AllPrintings.psql`, `AllIdentifiers.json`, `Keywords.json`, `CardTypes.json`, and `AllDeckFiles.zip` from MTGJSON v5 on startup or via a `POST /refresh` endpoint.
|
|
- **Dual PostgreSQL** — Two databases: `mtgonline` for the application (users, decks, auth) and `mtgdata` for MTG card data.
|
|
- **Redis Caching** — Used for card lookup caching and interaction pipeline state.
|
|
- **REST API** — `/docs` (Swagger) available at runtime.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
mtgonline/
|
|
├── backend/ # FastAPI application
|
|
│ ├── app/
|
|
│ │ ├── core/ # Settings, database engines, Redis client
|
|
│ │ ├── models/ # SQLAlchemy ORM models (app + MTG)
|
|
│ │ ├── routers/ # API route modules
|
|
│ │ ├── schemas/ # Pydantic request/response schemas
|
|
│ │ ├── services/ # Business logic (MTGJSON manager, card DB, game server)
|
|
│ │ └── main.py # FastAPI app entry point
|
|
│ ├── scripts/ # Utility scripts (downloads, migrations, checks)
|
|
│ ├── Dockerfile
|
|
│ └── requirements.txt
|
|
├── docker-compose.dev.yml # Development stack (Postgres x2, Redis, Backend)
|
|
├── docker-compose.yml # Production stack
|
|
├── scripts/ # Shared utility scripts
|
|
└── README.md
|
|
```
|
|
|
|
### Data Flow
|
|
|
|
1. **On startup**, the backend connects to PostgreSQL (both instances) and Redis.
|
|
2. It checks `mtg_refresh_log` in the `mtgdata` database for existing data.
|
|
3. If no data exists, it downloads MTGJSON files from `https://mtgjson.com/api/v5/`, unzips if needed, and upserts them into `mtgdata` tables (`mtg_sets`, `mtg_cards`, etc.).
|
|
4. The data is then available via REST endpoints.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Docker and Docker Compose
|
|
|
|
### Run the Stack
|
|
|
|
```bash
|
|
cd /home/wall-o/projects/mtgonline
|
|
|
|
# Start all services (Postgres x2, Redis, Backend)
|
|
docker compose -f docker-compose.dev.yml up -d
|
|
|
|
# View logs
|
|
docker compose -f docker-compose.dev.yml logs -f backend
|
|
```
|
|
|
|
The backend will automatically download MTGJSON data on first startup (this may take several minutes).
|
|
|
|
### Access
|
|
|
|
| Service | Address |
|
|
|---------------|---------------------|
|
|
| Backend API | `http://localhost:5555` |
|
|
| Swagger Docs | `http://localhost:5555/docs` |
|
|
| Health Check | `http://localhost:5555/health` |
|
|
| PostgreSQL (app) | `localhost:5432` |
|
|
| PostgreSQL (MTG) | `localhost:5433` |
|
|
| Redis | `localhost:6379` |
|
|
|
|
### Manual Data Refresh
|
|
|
|
```bash
|
|
# Trigger a manual MTGJSON refresh
|
|
curl -X POST http://localhost:5555/refresh
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `DATABASE_URL` | `postgresql+asyncpg://mtgonline_user:mtgonline_password@postgres:5432/mtgonline` | Primary database connection |
|
|
| `MTG_DATABASE_URL` | `postgresql+asyncpg://mtgonline_user:mtgonline_password@mtgdata:5432/mtgdata` | MTG data database connection |
|
|
| `REDIS_URL` | `redis://redis:6379` | Redis connection |
|
|
| `DATA_DIR` | `/app/data` | Directory for MTGJSON files |
|
|
| `DEBUG` | `False` | Enable debug logging |
|
|
|
|
## Docker Cleanup
|
|
|
|
```bash
|
|
# Stop and remove all containers
|
|
docker compose -f docker-compose.dev.yml down
|
|
|
|
# Remove images and prune
|
|
docker system prune -a --volumes
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|