# 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
   ```python
   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**