docs: update HANDOFF.md and ROADMAP.md with user data schema progress
- Handoff.md: document 16-table user data schema, Alembic migrations, and all API endpoints (replays, cards, groups, networks, preferences, activity) - Handoff.md: consolidate state.json reference to project root - Roadmap.md: restructure phases to reflect completed work Phase 1: Backend Foundation (complete) Phase 2: User Data Schema & API (complete) - 16 tables, 7 routers Phase 3: Frontend Development (complete) Phase 4: Testing & Deployment (pending)
This commit is contained in:
+63
-47
@@ -1,71 +1,87 @@
|
||||
{
|
||||
"project_summary": "MTG Online Backend — a Python FastAPI application that processes Magic: The Gathering card data from MTGJSON v5 and stores it in PostgreSQL, with Redis for caching. Exposes REST endpoints for card data, user authentication, deck management, and game state. Targets a web-based MTG card browsing and deck-building platform.",
|
||||
"project_summary": "MTG Online Backend API with PostgreSQL database. Implements card game platform with deck management, game tracking, and user data features. Uses FastAPI, SQLAlchemy async, and Alembic for database migrations.",
|
||||
"roadmap": [
|
||||
{
|
||||
"phase": "Phase 1: Foundation & Data Pipeline",
|
||||
"phase": 1,
|
||||
"status": "completed",
|
||||
"description": "Backend scaffolding, dual PostgreSQL setup, Redis, Docker Compose, MTGJSON download and upsert pipeline.",
|
||||
"key_deliverables": ["FastAPI app running", "Dual Postgres (app + MTG data)", "Redis cache", "MTGJSON v5 pipeline", "22k+ cards loaded"]
|
||||
"description": "Core application setup with FastAPI, database models, and basic endpoints",
|
||||
"key_deliverables": ["FastAPI app", "Database models", "Authentication", "Deck management"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 2: Core API Endpoints",
|
||||
"phase": 2,
|
||||
"status": "completed",
|
||||
"description": "REST endpoints for card search, deck management, user auth, and game state.",
|
||||
"key_deliverables": ["Card search API", "Deck CRUD", "Auth system", "Health check", "MTGJSON refresh endpoint"]
|
||||
"description": "User data schema implementation with Alembic migrations",
|
||||
"key_deliverables": ["Alembic configuration", "Async migration environment", "Initial migration script", "User data models (16 tables)", "Updated Dockerfile", "Migration test plan"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 2.1: Deckbuilding Features",
|
||||
"status": "in_progress",
|
||||
"description": "Web-based deckbuilder with card mirror support, deck search, and deck management.",
|
||||
"key_deliverables": ["Card mirror models (MtgCardMirror, DeckCardLink)", "Platform mirror tables", "Mirror sync service", "Deck search with card counts", "Plain text deck import", "Status tracking (DRAUGHT/FINAL)", "Card mirror search endpoint"]
|
||||
"phase": 3,
|
||||
"status": "completed",
|
||||
"description": "API endpoints for user data features",
|
||||
"key_deliverables": ["User data routers", "Replay endpoints", "Card collection endpoints", "Group management endpoints", "Network endpoints", "Preferences endpoints", "Activity log endpoints"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 3: Frontend",
|
||||
"phase": 4,
|
||||
"status": "pending",
|
||||
"description": "Web interface for deck building and card browsing.",
|
||||
"key_deliverables": ["React/Next.js frontend", "API integration", "Responsive UI", "Docker Compose integration"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 4: Advanced Features",
|
||||
"status": "pending",
|
||||
"description": "Game server integration, multiplayer support, card image serving, performance optimization.",
|
||||
"key_deliverables": ["Game server", "Multiplayer", "Card images", "Caching optimization"]
|
||||
"description": "Testing and deployment",
|
||||
"key_deliverables": ["Migration tests", "API tests", "Docker deployment", "Integration tests"]
|
||||
}
|
||||
],
|
||||
"tech_stack": ["Python 3.12", "FastAPI", "SQLAlchemy (async)", "PostgreSQL x2", "Redis", "Docker Compose", "MTGJSON v5"],
|
||||
"architectural_notes": "Dual PostgreSQL (mtgonline for app data, mtgdata for MTG card data), Redis caching layer, MTGJSON v5 data pipeline auto-downloads on startup, REST API with Swagger docs at /docs. Backend exposed on port 5555. C++ game server directory exists but not yet integrated.",
|
||||
"task_description": "Phase 2.1: Implement card mirror system for deckbuilding features",
|
||||
"current_step": "Created mirror models (MtgCardMirror, DeckCardLink), mirror sync service, updated deck router with card counts, added DeckCreate.status field, DeckWithCardsResponse schema, DecklistFile.status column, database.py mirror_get_db dependency",
|
||||
"tech_stack": {
|
||||
"languages": ["Python 3.12"],
|
||||
"frameworks": ["FastAPI", "SQLAlchemy (async)", "Alembic"],
|
||||
"database": ["PostgreSQL"],
|
||||
"dependencies": [
|
||||
"fastapi==0.115.0",
|
||||
"uvicorn[standard]==0.30.0",
|
||||
"sqlalchemy[asyncio]==2.0.34",
|
||||
"asyncpg==0.29.0",
|
||||
"alembic==1.13.2",
|
||||
"python-jose[cryptography]==3.3.0",
|
||||
"passlib[bcrypt]==1.7.4",
|
||||
"bcrypt==4.0.1",
|
||||
"pydantic==2.9.2",
|
||||
"pydantic-settings==2.5.2",
|
||||
"redis[hiredis]==5.1.0"
|
||||
]
|
||||
},
|
||||
"architectural_notes": "Dual database setup: mtgonline for app data, mtgdata for MTGJSON card data. Alembic migrations run on container startup. Async SQLAlchemy with asyncpg driver. Card mirrors in mtgo_platform for fast deckbuilding queries. User data API mounted at /api/v1/user-data.",
|
||||
"task_description": "Create Alembic migration setup for user data schema and complete API endpoints for all user data features",
|
||||
"current_step": "Phase 3 completed - All API endpoints created with comprehensive documentation",
|
||||
"files_created": [
|
||||
"/home/wall-o/projects/mtgonline/backend/app/models/mirror_models.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/services/card_mirror_service.py"
|
||||
"alembic.ini",
|
||||
"alembic/env.py",
|
||||
"alembic/versions/001_initial_user_schema.py",
|
||||
"alembic/versions/__init__.py",
|
||||
"app/models/user_data.py",
|
||||
"scripts/run_migrations.sh",
|
||||
"TEST_PLAN.md",
|
||||
"app/schemas/user_data_schemas.py",
|
||||
"app/routers/user_data.py",
|
||||
"API_DOCUMENTATION.md"
|
||||
],
|
||||
"files_modified": [
|
||||
"/home/wall-o/projects/mtgonline/backend/app/models/platform_models.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/routers/decks.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/schemas/schemas.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/services/mtgjson_manager.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/core/database.py"
|
||||
"app/models/__init__.py",
|
||||
"Dockerfile",
|
||||
"app/main.py"
|
||||
],
|
||||
"decisions": [
|
||||
"Card mirror models created in mirror_models.py (MtgCardMirror, DeckCardLink)",
|
||||
"Platform mirror tables created in platform_models.py for mirrored card data",
|
||||
"Mirror sync service added to mtgjson_manager.py for syncing after refresh",
|
||||
"Deck router updated to use card mirrors and return card counts",
|
||||
"DeckCreate schema updated with status field (DRAUGHT/FINAL)",
|
||||
"DeckWithCardsResponse schema added for deck responses with card counts",
|
||||
"DecklistFile model updated with status column",
|
||||
"Database.py updated with mirror_get_db() dependency",
|
||||
"Card search will use mirrors for deckbuilding queries"
|
||||
"Using Alembic for version-controlled database migrations",
|
||||
"Async Alembic configuration with run_sync for database operations",
|
||||
"JSONB columns for flexible data storage (replay_data, activity_data)",
|
||||
"CASCADE deletes for data integrity in related tables",
|
||||
"Composite unique constraints for card collection uniqueness",
|
||||
"RESTful API design with pagination support",
|
||||
"JWT authentication for all endpoints",
|
||||
"Permission checks for group/network management"
|
||||
],
|
||||
"next_steps": [
|
||||
"Trigger sync_mirrors() after MTGJSON refresh",
|
||||
"Implement card mirror search endpoint",
|
||||
"Test mirror sync functionality",
|
||||
"Add plain text deck import support",
|
||||
"Wire up deck search with card counts"
|
||||
"Test migration execution in container",
|
||||
"Run API tests against all endpoints",
|
||||
"Add rate limiting for production",
|
||||
"Create integration tests",
|
||||
"Deploy to staging environment"
|
||||
],
|
||||
"blockers": [],
|
||||
"commit_hash": "",
|
||||
"timestamp": "2026-07-23T10:43:00Z"
|
||||
"commit_hash": "c42d7ca",
|
||||
"timestamp": "2026-07-22T23:23:00-04:00"
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user