docs: update README with card import API documentation and complete roadmap
This commit is contained in:
+61
-74
@@ -1,102 +1,89 @@
|
||||
# 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.
|
||||
FastAPI application for processing MTG card data and managing user decks.
|
||||
|
||||
## 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.
|
||||
Python FastAPI application that:
|
||||
- Downloads and processes MTGJSON v5 data
|
||||
- Stores card data in PostgreSQL (`mtgdata` database)
|
||||
- Manages user accounts, decks, and card imports
|
||||
- Exposes REST API for deckbuilding and card search
|
||||
|
||||
### Key Features
|
||||
## 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.
|
||||
- **MTGJSON Data Pipeline** — Downloads and upserts MTGJSON v5 dataset
|
||||
- **Card Import** — Users import card collections with fuzzy matching
|
||||
- **Deck Management** — Create, edit, and finalize decks with precedents
|
||||
- **Card Search** — Fast card lookup for deckbuilding
|
||||
- **JWT Authentication** — Secured API endpoints
|
||||
|
||||
## Architecture
|
||||
## API Endpoints
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
### Card Import (`/api/v1/card-import/`)
|
||||
|
||||
### Data Flow
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/status` | Get import status |
|
||||
| `POST` | `/` | Import/update cards |
|
||||
| `DELETE` | `/` | Delete import |
|
||||
| `GET` | `/summary` | Match results summary |
|
||||
|
||||
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.
|
||||
### User Data (`/api/v1/user-data/`)
|
||||
|
||||
## Quick Start
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET/PUT` | `/profile` | User profile |
|
||||
| `GET` | `/collection` | Card collection |
|
||||
| `GET` | `/groups` | User groups |
|
||||
| `GET` | `/preferences` | User preferences |
|
||||
| `GET` | `/replays` | User replays |
|
||||
|
||||
### Prerequisites
|
||||
### Decks (`/api/v1/decks/`)
|
||||
|
||||
- Docker and Docker Compose
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| CRUD | `/{deck_id}` | Deck management |
|
||||
| `POST` | `/{deck_id}/cards` | Add card to deck |
|
||||
| `POST` | `/{deck_id}/finalize` | Finalize deck |
|
||||
| `POST` | `/search/cards` | Search cards |
|
||||
| CRUD | `/precedents/` | Deck precedents |
|
||||
| CRUD | `/suggestions/` | Card suggestions |
|
||||
|
||||
### Run the Stack
|
||||
## Tech Stack
|
||||
|
||||
- **Language:** Python 3.12
|
||||
- **Framework:** FastAPI
|
||||
- **Database:** PostgreSQL (async via asyncpg)
|
||||
- **ORM:** SQLAlchemy 2.0
|
||||
- **Migrations:** Alembic
|
||||
- **Cache:** Redis
|
||||
- **Auth:** JWT (python-jose + bcrypt)
|
||||
|
||||
## Running Locally
|
||||
|
||||
```bash
|
||||
cd /home/wall-o/projects/mtgonline
|
||||
# Start services
|
||||
docker compose -f ../docker-compose.dev.yml up -d
|
||||
|
||||
# Start all services (Postgres x2, Redis, Backend)
|
||||
docker compose -f docker-compose.dev.yml up -d
|
||||
# Run migrations
|
||||
cd app && alembic upgrade head
|
||||
|
||||
# View logs
|
||||
docker compose -f docker-compose.dev.yml logs -f backend
|
||||
# Access API
|
||||
curl http://localhost:5555/health
|
||||
```
|
||||
|
||||
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
|
||||
## Migrations
|
||||
|
||||
```bash
|
||||
# Trigger a manual MTGJSON refresh
|
||||
curl -X POST http://localhost:5555/refresh
|
||||
```
|
||||
# Create new migration
|
||||
alembic revision --autogenerate -m "description"
|
||||
|
||||
## Environment Variables
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
| 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
|
||||
# Rollback
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Reference in New Issue
Block a user