mrrrme/backend/README.md

MrrrMe Backend - Refactored Structure

This is a refactored version of backend_server.py split into modular components.

📁 Directory Structure

backend/
├── __init__.py              # Main package init
├── app.py                   # FastAPI app setup
├── config.py                # Configuration & constants
├── websocket.py             # WebSocket handler (TO BE CREATED)
│
├── auth/                    # Authentication
│   ├── __init__.py
│   ├── models.py            # Pydantic models
│   ├── database.py          # Database init & helpers
│   └── routes.py            # Auth endpoints
│
├── session/                 # Session management
│   ├── __init__.py
│   ├── manager.py           # Token validation, user context
│   └── summary.py           # AI summary generation
│
├── models/                  # AI model loading
│   ├── __init__.py
│   └── loader.py            # Async model initialization
│
├── processing/              # Core processing logic
│   ├── __init__.py
│   ├── video.py             # Video frame processing
│   ├── audio.py             # Audio chunk processing
│   ├── speech.py            # Speech processing (TO BE CREATED)
│   └── fusion.py            # Emotion fusion
│
├── debug/                   # Debug endpoints
│   ├── __init__.py
│   └── routes.py            # Debug routes
│
└── utils/                   # Utilities
    ├── __init__.py
    ├── helpers.py           # Helper functions
    └── patches.py           # GPU & system patches

🚀 How to Use

Option 1: Drop-in Replacement

1. Copy the backend/ folder to mrrrme/backend/
2. Create/update mrrrme/backend_new.py:

"""New modular backend server"""
from backend import app

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

3. Run: python mrrrme/backend_new.py

Option 2: Gradual Migration

Keep your old backend_server.py and slowly migrate endpoints:

1. Import refactored modules:

from backend.auth import router as auth_router
from backend.session import validate_token

2. Replace sections incrementally

🔧 Still Need to Create

The following files need the full logic from backend_server.py:

websocket.py (~400 lines)

• Main WebSocket endpoint logic
• Message type routing
• Greeting generation
• Video/audio/speech handling orchestration

processing/speech.py (~250 lines)

• Full speech processing pipeline
• Transcription filtering
• Emotion detection coordination
• LLM context preparation
• Avatar TTS integration

📋 Migration Checklist

• Config & environment setup
• Authentication (signup/login/logout)
• Database management
• Session validation
• AI summary generation
• Model loading
• Video frame processing
• Audio chunk processing
• Emotion fusion logic
• Debug endpoints
• WebSocket handler (main logic)
• Speech processing pipeline
• Greeting generation logic
• Full integration testing

🎯 Benefits

1. Modularity: Each component has a single responsibility
2. Testability: Easy to unit test individual modules
3. Maintainability: Find and fix bugs faster
4. Scalability: Add new features without bloating
5. Collaboration: Multiple devs can work on different modules

📦 Original File Size

• backend_server.py: 47KB (1,300 lines)
• Refactored: 12 modules (~100-300 lines each)

⚠️ Important Notes

• Ensure all imports match your project structure
• Update mrrrme module imports in models/loader.py
• Test thoroughly before replacing production code
• Keep backend_server.py as backup during migration