feat: complete deckbuilding feature with local card mirror

- Add MtgonlineCard model (local card data mirror in mtgonline DB)
- Create user_deck.py models (UserDeck, UserDeckCard, DeckPrecedent, CardSuggestion)
- Create user_deck_schemas.py with Pydantic schemas
- Update decks.py router to use local MtgonlineCard instead of cross-DB MtgCard
- Add migration 002 (user deck building tables)
- Add migration 003 (mtgonline_cards table)
- All card lookups now use local mirror for fast queries
- No cross-DB joins in deckbuilding endpoints

state.json

@@ -21,9 +21,33 @@
     },
     {
       "phase": 4,
+      "status": "completed",
+      "description": "Per-user deck building with card search, precedents, and suggestions",
+      "key_deliverables": [
+        "UserDeck model (DRAFT/FINAL status)",
+        "UserDeckCard junction table (card_id references mtgonline_cards.id)",
+        "DeckPrecedent and DeckPrecedentCard tables (template support)",
+        "CardSuggestion table (suggestion storage)",
+        "Alembic migration 003 (mtgonline_cards table)",
+        "Deck CRUD endpoints (list, create, get, update, delete)",
+        "Card management endpoints (add, update, remove, list cards)",
+        "Deck finalize endpoint (DRAFT → FINAL transition)",
+        "Precedent endpoints (list, create, get, use/clone)",
+        "Card search endpoint (POST /decks/search/cards)",
+        "Suggestion endpoints (list, add suggestions)",
+        "Pydantic schemas for all deckbuilding operations"
+      ]
+    },
+    {
+      "phase": 5,
       "status": "pending",
-      "description": "Testing and deployment",
-      "key_deliverables": ["Migration tests", "API tests", "Docker deployment", "Integration tests"]
+      "description": "Card import with fuzzy matching and deck builder service",
+      "key_deliverables": [
+        "Fuzzy card matching service (python-Levenshtein)",
+        "Card import router (file upload/confirm)",
+        "Deck builder service (precedents, suggestions)",
+        "Integration tests for import and builder features"
+      ]
     }
   ],
   "tech_stack": {
@@ -46,17 +70,23 @@
   },
   "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": "Update HANDOFF.md and ROADMAP.md to reflect user data schema work and consolidate state.json",
-  "current_step": "Phase 3 completed - All API endpoints created with comprehensive documentation",
+  "current_step": "Phase 4 completed - Per-user deck building with card search, precedents, and suggestions fully implemented",
   "files_created": [
     "alembic.ini",
     "alembic/env.py",
     "alembic/versions/001_initial_user_schema.py",
+    "alembic/versions/002_user_deck_building_tables.py",
+    "alembic/versions/003_mtgonline_cards_table.py",
     "alembic/versions/__init__.py",
     "app/models/user_data.py",
+    "app/models/user_deck.py",
+    "app/models/models.py (MtgonlineCard added)",
+    "app/schemas/user_data_schemas.py",
+    "app/schemas/user_deck_schemas.py",
+    "app/routers/user_data.py",
+    "app/routers/decks.py",
     "scripts/run_migrations.sh",
     "TEST_PLAN.md",
-    "app/schemas/user_data_schemas.py",
-    "app/routers/user_data.py",
     "API_DOCUMENTATION.md"
   ],
   "files_modified": [
@@ -72,16 +102,21 @@
     "Composite unique constraints for card collection uniqueness",
     "RESTful API design with pagination support",
     "JWT authentication for all endpoints",
-    "Permission checks for group/network management"
+    "Permission checks for group/network management",
+    "Option B for cross-DB FK: Local card mirror in mtgonline DB (mtgonline_cards)",
+    "Fuzzy matching reserved for card import feature only (handles typos in user input)",
+    "Local card search endpoint for fast deckbuilding queries"
   ],
   "next_steps": [
     "Test migration execution in container",
     "Run API tests against all endpoints",
     "Add rate limiting for production",
     "Create integration tests",
-    "Deploy to staging environment"
+    "Deploy to staging environment",
+    "Phase 5: Card import with fuzzy matching (python-Levenshtein)",
+    "Phase 5: Deck builder service for precedents and suggestions"
   ],
   "blockers": [],
   "commit_hash": "6b38ef0",
-  "timestamp": "2026-07-23T00:30:06-04:00"
+  "timestamp": "2026-07-24T04:12:00-04:00"
 }