mtgonline/HANDOFF_PROMPT.md

MTG Online Backend - Handoff Prompt

Context

You are taking over the MTG Online Backend project. The project is a Python FastAPI application that integrates with MTGJSON API to provide Magic: The Gathering card data. The system downloads, processes, and stores MTGJSON datasets in PostgreSQL with a weekly refresh cycle.

Current Status

• ✅ All containers destroyed and Docker pruned
• ✅ Code is working - last tested successfully with 5.4M+ cards loaded
• ⏸️ Project paused - ready for handoff

Quick Start for New Thread

# 1. Read the handoff documentation
cat /home/wall-o/projects/mtgonline/HANDOFF.md

# 2. Check current state
cat /home/wall-o/projects/mtgonline/state.json

# 3. Rebuild and deploy
cd /home/wall-o/projects/mtgonline
docker build -t mtgonline_backend backend/
docker compose -p mtgonline up -d

# 4. Monitor startup
docker logs -f mtgonline_backend

Key Information

Location: /home/wall-o/projects/mtgonline
Last Commit: ad2742c - "Fix MTGJSON download: use .gz URLs and handle pre-uncompressed files"

Core Service: backend/app/services/mtgjson_manager.py

• Downloads MTGJSON data from https://mtgjson.com/api/v5
• Handles both gzip-compressed and pre-uncompressed JSON files
• Upserts to PostgreSQL with ON CONFLICT DO UPDATE
• Weekly refresh cycle (7 days)
• Container marked unhealthy if data corrupted

Known Issues Fixed:

1. MTGJSON URL scheme changed from .json to .json.gz
2. Some files are pre-uncompressed (not actually gzipped)
3. Large files need 60-minute download timeout

What to Do Next

1. Rebuild and test the deployment
2. Verify MTGJSON data loads correctly
3. Review the codebase and make any needed improvements
4. Consider:
   • Incremental updates (vs full refresh)
   • Better error handling
   • Database optimization
   • Monitoring and alerting

Important Files

• HANOFOFF.md - Complete documentation
• state.json - Project state
• backend/app/services/mtgjson_manager.py - Core MTGJSON integration
• docker-compose.yml - Container orchestration
• .env - Configuration

State Tracking

Update state.json after each significant change:

{
  "task_description": "...",
  "current_step": "...",
  "files_created": [...],
  "files_modified": [...],
  "decisions": [...],
  "next_steps": [...],
  "blockers": [...],
  "commit_hash": "...",
  "timestamp": ...
}

Git

• Credentials: /home/wall-o/projects/gitea_credentials.txt
• Commit after each milestone
• Push changes regularly