Add comprehensive handoff documentation for new thread

2026-07-20 13:23:40 +00:00
parent ad2742c1cf
commit 2369c2cc8c
2 changed files with 322 additions and 0 deletions
@@ -0,0 +1,83 @@
+# 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
+
+```bash
+# 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:
+```json
+{
+  "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