mtgonline/SIMPLIFICATION_PLAN.md

MTG Online Architecture Simplification Plan

Current State Analysis

Backend Structure

backend/
├── app/
│   ├── core/          # Settings, database engines, Redis client, logging
│   ├── models/        # 10+ SQLAlchemy model files
│   ├── routers/       # 10+ router files
│   ├── schemas/       # 13+ Pydantic schema files
│   ├── services/      # 15+ service files (some massive)
│   └── main.py        # FastAPI app with 10+ router mounts
├── mtg_rules_engine/  # 10+ files for game rules engine
├── alembic/           # Database migrations
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

Key Issues Identified

1. Fragmented models - 10+ separate model files that should be consolidated
2. Massive services - mtgjson_manager.py is 53KB, mtgjson_loader.py is 32KB
3. Docker complexity - Multi-database setup (PostgreSQL x2, Redis) with Docker Compose
4. Async everywhere - Async SQLAlchemy, asyncpg, async Redis - adds complexity
5. Redundant schemas - 13+ schema files with potential duplication
6. Empty frontend - Frontend directory exists but is empty
7. Multiple entry points - Scripts, migrations, Docker, direct Python execution

Router Analysis

• auth.py (162 lines) - Authentication endpoints
• users.py (168 lines) - User profile management
• decks.py (721 lines) - Deck management (largest router)
• rooms.py (158 lines) - Room CRUD
• admin.py (220 lines) - Admin operations
• card_router.py (292 lines) - MTG card search
• interactions.py (674 lines) - Card interactions
• refresh.py (101 lines) - MTGJSON refresh
• user_data.py (1714 lines) - User data (massive)
• card_import.py (368 lines) - Card import
• games/router.py (135 lines) - Game stubs
• ws.py (18 lines) - WebSocket

Model Analysis

• models.py (228 lines) - Core models (User, DecklistFile, Room, etc.)
• mtg_models.py (71 lines) - MTG card/set models
• user_data.py (325 lines) - User sessions, decks, replays, etc.
• user_deck.py (153 lines) - User deck building
• mirror_models.py (97 lines) - Card mirrors
• card_import_batch.py (74 lines) - Import tracking
• relationships.py (24 lines) - Cross-model relationships

Service Analysis

• mtgjson_manager.py (53KB) - MTGJSON data management
• mtgjson_loader.py (32KB) - Data loading
• mtgjson_uploader.py (34KB) - Data uploading
• deck_manager.py (7.8KB) - Deck management
• card_database.py (9.6KB) - Card database
• game_server.py (10KB) - Game server

Simplification Strategy

Phase 1: Core Layer Simplification

Goal: Simplify configuration and database layer

1. config.py - Replace pydantic-settings with simple config class

   • SQLite by default, PostgreSQL optional
   • Single DATABASE_URL setting
   • Sensible defaults for all settings

2. database.py - Single database engine

   • Remove dual database setup
   • Support SQLite and PostgreSQL via same interface
   • Keep async engine for compatibility

3. logging.py - Simplified logging

   • Remove Docker-specific complexity
   • Keep structured logging

4. security.py - Keep existing functionality

   • JWT token management
   • Password hashing
   • Authentication dependencies

Phase 2: Model Consolidation

Goal: Reduce 10+ model files to 2-3 consolidated files

1. models.py - All application models

   • User, DecklistFile, Room, Ban, GameLog, AuditLog
   • MtgonlineCard (local card mirror)
   • UserDeck, UserDeckCard, DeckPrecedent, CardSuggestion
   • UserSession, DeckVersion, GameReplay, etc.
   • CardImportBatch, UserCardImportRecord

2. mtg_models.py - All MTG card data models

   • MtgSet, MtgCard
   • MtgCardMirror, DeckCardLink

3. Remove: relationships.py (integrate into models)

Phase 3: Router Consolidation

Goal: Reduce 12 router files to 6 focused routers

1. auth_router.py - Authentication (from auth.py)

   • Login, register, token refresh, current user

2. users_router.py - User management + admin (merge users.py + admin.py)

   • User profile, ban management, user listing, audit logs

3. decks_router.py - Deck building (from decks.py)

   • Deck CRUD, card management, precedents, suggestions

4. cards_router.py - Card data (merge card_router.py + interactions.py)

   • Card search, sets, types, rarities, interactions

5. user_data_router.py - User data + imports (merge user_data.py + card_import.py)

   • Sessions, replays, collection, wishlist, groups, networks
   • Card imports

6. games_router.py - Games + rooms + refresh (merge rooms.py + games + refresh.py)

   • Room management, game stubs, MTGJSON refresh

Phase 4: Schema Consolidation

Goal: Reduce 13+ schema files to 6 matching routers

1. auth_schemas.py - Auth request/response
2. user_schemas.py - User data schemas
3. deck_schemas.py - Deck schemas
4. card_schemas.py - Card schemas
5. user_data_schemas.py - User data schemas
6. game_schemas.py - Game schemas

Phase 5: Service Simplification

Goal: Break large services into focused modules

1. card_service.py - Card search and lookup
2. deck_service.py - Deck CRUD and validation
3. user_service.py - User management
4. mtgjson_service.py - MTGJSON data management (split from 53KB file)
5. game_service.py - Game state management

Phase 6: Startup Script

Goal: Single entry point

1. run.py - Simple startup script

   import uvicorn
   from app.core.database import create_tables
   from app.main import app
   
   if __name__ == "__main__":
       create_tables()
       uvicorn.run(app, host="0.0.0.0", port=8000)
   

Phase 7: Documentation

Goal: Update all documentation

1. README.md - New setup instructions
2. Remove Docker files - Keep only for production if needed
3. Update state.json - Document changes

Implementation Order

1. Core Layer (config, database, logging, security)
2. Models (consolidate into 2-3 files)
3. Schemas (consolidate into 6 files)
4. Services (simplify and split)
5. Routers (consolidate into 6 files)
6. Main (update to use new structure)
7. Run script (create startup script)
8. Documentation (update README)
9. Testing (verify all endpoints work)

Success Criteria

• Single SQLite database works out of the box
• All API endpoints functional
• No Docker required for development
• File count reduced by 50%
• Code lines reduced by 30%
• All tests passing
• Documentation updated
• python run.py starts everything

Risk Mitigation

1. Data integrity - Keep all database migrations compatible
2. Backward compatibility - Maintain existing endpoint paths
3. Testing - Run comprehensive tests after each phase
4. Rollback plan - Keep original files as backup until verified

Timeline

• Phase 1-2: Core and Models (1-2 hours)
• Phase 3-4: Routers and Schemas (2-3 hours)
• Phase 5-6: Services and Startup (1-2 hours)
• Phase 7: Documentation and Testing (1-2 hours)
• Total: 5-9 hours