mtgonline/HANDOFF.md

MTG Online Project - Architecture Simplification Request

Context

Project: MTG Online at /home/wall-o/projects/mtgonline/ Current State: Backend API with FastAPI, SQLAlchemy, Alembic, Docker Compose, PostgreSQL, Redis Goal: Simplify the entire architecture so an LLM can better handle writing and debugging code

What We Have

Backend Structure:

backend/
├── app/
│   ├── core/          # Settings, database engines, Redis client, logging
│   ├── models/        # 10+ SQLAlchemy model files (models.py, user_data.py, user_deck.py, etc.)
│   ├── routers/       # 10+ router files (auth, users, decks, games, admin, card_router, etc.)
│   ├── schemas/       # 13+ Pydantic schema files
│   ├── services/      # 15+ service files (mtgjson_manager.py is 53KB, mtgjson_loader.py is 32KB)
│   └── 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:

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 for development
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

What We Want

Simplify the architecture to be LLM-friendly with these principles:

1. Single database - Use SQLite for development/local, PostgreSQL for production
2. Consolidated models - Merge related models into fewer files
3. Simplified services - Break large services into focused, smaller modules
4. No Docker for development - Run directly with Python/uvicorn
5. Linear structure - Reduce nesting and indirection
6. Clear separation - Each file has one clear responsibility
7. Easy startup - python run.py starts everything

Specific Simplifications

1. Database Layer

• Current: Dual PostgreSQL databases (mtgonline, mtgdata) + Redis
• Simplified: Single SQLite database for development, optional PostgreSQL for production
• Why: SQLite eliminates connection pooling, async drivers, migration complexity

2. Models Layer

• Current: 10+ model files (models.py, user_data.py, user_deck.py, mirror_models.py, etc.)
• Simplified: 2-3 consolidated model files
  • models.py - All application models
  • mtg_models.py - All MTG card data models
• Why: Reduces import complexity, makes relationships clearer

3. Services Layer

• Current: 15+ service files, some massive (mtgjson_manager.py = 53KB)
• Simplified: 5-7 focused service files
  • card_service.py - Card search and lookup
  • deck_service.py - Deck CRUD and validation
  • user_service.py - User management
  • mtgjson_service.py - MTGJSON data management (split from current 53KB file)
  • game_service.py - Game state management
• Why: Each file < 1000 lines, clear single responsibility

4. Routers Layer

• Current: 10+ router files
• Simplified: 5-6 router files
  • auth_router.py - Authentication
  • user_router.py - User data
  • deck_router.py - Deck management
  • card_router.py - Card search and import
  • game_router.py - Game management
  • admin_router.py - Admin functions
• Why: One router per domain, easier to navigate

5. Schemas Layer

• Current: 13+ schema files
• Simplified: 5-6 schema files matching routers
  • auth_schemas.py - Auth request/response
  • user_schemas.py - User data schemas
  • deck_schemas.py - Deck schemas
  • card_schemas.py - Card schemas
  • game_schemas.py - Game schemas
• Why: Schemas co-located with their router domain

6. Startup Script

• Current: Docker Compose, entrypoint scripts, migration scripts
• Simplified: Single run.py script

  # run.py
  import uvicorn
  from app.core.database import init_db
  from app.main import app
  
  if __name__ == "__main__":
      init_db()  # Create tables if needed
      uvicorn.run(app, host="0.0.0.0", port=8000)
  

• Why: One command to start everything

7. Configuration

• Current: pydantic-settings with 20+ env vars, Docker-specific defaults
• Simplified: Simple config with sensible defaults

  # config.py
  DATABASE_URL = "sqlite:///mtgonline.db"  # or postgresql://...
  DEBUG = True
  SECRET_KEY = "dev-secret-key"
  

• Why: Works out of the box, easy to override

Files to Review

Backend:

• /home/wall-o/projects/mtgonline/backend/app/main.py - Application entry
• /home/wall-o/projects/mtgonline/backend/app/core/ - Settings, database, Redis
• /home/wall-o/projects/mtgonline/backend/app/models/ - All model files
• /home/wall-o/projects/mtgonline/backend/app/routers/ - All router files
• /home/wall-o/projects/mtgonline/backend/app/schemas/ - All schema files
• /home/wall-o/projects/mtgonline/backend/app/services/ - All service files
• /home/wall-o/projects/mtgonline/backend/mtg_rules_engine/ - Game rules engine
• /home/wall-o/projects/mtgonline/backend/alembic/ - Migrations
• /home/wall-o/projects/mtgonline/backend/requirements.txt - Dependencies

Project Root:

• /home/wall-o/projects/mtgonline/README.md
• /home/wall-o/projects/mtgonline/ROADMAP.md
• /home/wall-o/projects/mtgonline/state.json
• /home/wall-o/projects/mtgonline/docker-compose.yml
• /home/wall-o/projects/mtgonline/scripts/

Important Considerations

1. Preserve functionality - All API endpoints must work
2. Keep tests passing - Don't break existing tests
3. Maintain data integrity - Database migrations must work
4. Support both SQLite and PostgreSQL - Easy switch for production
5. Document changes - Update README with new setup instructions
6. Remove Docker for dev - Keep it optional for production only
7. Reduce file count - Target 50% reduction in total files
8. Reduce code lines - Target 30% reduction through consolidation

Expected Outcome

After simplification:

• Backend structure:

  backend/
  ├── app/
  │   ├── core/
  │   │   ├── config.py        # Simple configuration
  │   │   ├── database.py      # Single database engine
  │   │   └── logging.py       # Logging setup
  │   ├── models/
  │   │   ├── models.py        # All app models
  │   │   └── mtg_models.py    # All MTG models
  │   ├── routers/
  │   │   ├── auth_router.py
  │   │   ├── user_router.py
  │   │   ├── deck_router.py
  │   │   ├── card_router.py
  │   │   ├── game_router.py
  │   │   └── admin_router.py
  │   ├── schemas/
  │   │   ├── auth_schemas.py
  │   │   ├── user_schemas.py
  │   │   ├── deck_schemas.py
  │   │   ├── card_schemas.py
  │   │   └── game_schemas.py
  │   ├── services/
  │   │   ├── card_service.py
  │   │   ├── deck_service.py
  │   │   ├── user_service.py
  │   │   ├── mtgjson_service.py
  │   │   └── game_service.py
  │   └── main.py
  ├── mtg_rules_engine/        # Keep as-is (specialized)
  ├── run.py                   # Simple startup script
  └── requirements.txt
  

• Startup: cd backend && python run.py

• Database: SQLite by default, PostgreSQL optional

• No Docker required for development

Next Steps

1. Review entire codebase - Understand all files and their relationships
2. Identify consolidation opportunities - Which files can be merged?
3. Create simplified structure - Build new architecture incrementally
4. Migrate functionality - Move code to new structure
5. Test everything - Ensure all endpoints work
6. Update documentation - README, setup instructions
7. Remove Docker complexity - Keep only for production if needed

Please start by exploring the project structure and understanding the current architecture before making changes. Focus on understanding what each file does and how they interact.