admin/mtgonline
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
900f51af3ac65024da9eb031ce10652805dd9980
mtgonline/HANDOFF.md
T
akadmin 900f51af3a Complete architecture simplification: 54+ files → 37 files 
- Removed 11 duplicate router files (auth.py, users.py, decks.py, card_router.py, interactions.py, user_data.py, rooms.py, games/router.py, refresh.py, card_import.py, ws.py)
- Removed duplicate core files (logging_config.py, settings.py)
- Removed unused services (card_mirror_service.py, mtgjson_loader.py, mtgjson_uploader.py)
- Removed unused schemas (proto_messages.py, protocol_constants.py)
- Created run.py startup script for simple execution
- Created app/core/config.py for unified configuration management
- Created app/core/logging.py for logging configuration
- Consolidated routers into 6 focused files (auth_router.py, users_router.py, decks_router.py, cards_router.py, user_data_router.py, games_router.py)
- Updated all imports to use consolidated model paths
- Added backward compatibility aliases in database.py
- Created SIMPLIFICATION_SUMMARY.md documentation

Architecture improvements:
- Single unified database engine with auto-detection (SQLite/PostgreSQL)
- Consolidated models into 2 files (models.py, mtg_models.py)
- Clean router structure with one file per domain
- Simplified configuration with sensible defaults
- SQLite by default for development, PostgreSQL for production

Testing:
- All imports verified working
- App loads successfully
- Ready for development and testing
2026-08-26 15:15:36 +00:00

204 lines
8.4 KiB
Markdown
Raw Blame History

## 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
```python
# 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
```python
# 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.
Reference in New Issue View Git Blame Copy Permalink