# app.py Refactoring - Directory Structure

## Before Refactoring
```
ws/
├── app.py                    # 1,291 lines - MONOLITHIC
│   ├── Event Registration    # 230 lines
│   ├── Helper Classes        # 78 lines
│   ├── WebSocket Utilities   # 40 lines
│   ├── Game Loop             # 190 lines
│   ├── Producer/Consumer     # 68 lines
│   ├── Consumer/Commands     # 476 lines
│   └── WebSocket Handlers    # 170 lines
```

## After Refactoring
```
ws/
├── app.py                               # ~350-450 lines - CLEAN ENTRY POINT
│   ├── Imports                          # 40 lines
│   ├── Initialization                   # 10 lines
│   ├── Game Loop (performance critical) # 150 lines
│   ├── Consumer (simplified)            # 60 lines
│   └── Main Entry Point                 # 50 lines
│
├── server/                              # NEW - Server infrastructure
│   ├── __init__.py
│   ├── event_registration.py           # ~250 lines
│   │   ├── register_all_event_handlers()
│   │   ├── register_all_events()
│   │   └── initialize_all_events()
│   │
│   ├── websocket_registry.py           # ~120 lines
│   │   ├── UserRegistry (O(1) lookups)
│   │   ├── BatchedUpdate (performance)
│   │   ├── ServerState
│   │   └── Module-level instances
│   │
│   ├── websocket_messaging.py          # ~100 lines
│   │   ├── sendToUser()
│   │   ├── sendEventMessage()
│   │   ├── sendUserInfo()
│   │   ├── sendDict()
│   │   ├── ComplexHandler()
│   │   ├── get_websocket_for_player()
│   │   └── iterateGames()
│   │
│   ├── command_dispatcher.py           # ~500 lines
│   │   ├── CommandHandler (base class)
│   │   ├── 40+ specific command handlers
│   │   ├── CommandDispatcher (router)
│   │   └── dispatch_command()
│   │
│   └── websocket_handlers.py           # ~200 lines
│       ├── start()
│       ├── shutdown()
│       ├── error()
│       ├── every_minute()
│       ├── handler()
│       └── initialize_dummy_user()
│
├── game_loop/                           # NEW - Game loop infrastructure
│   ├── __init__.py
│   ├── loop_manager.py                 # ~250 lines
│   │   ├── create_hourly_batch_update()
│   │   ├── process_daily_tick()
│   │   └── process_weekly_tick()
│   │
│   └── producer_consumer.py            # ~80 lines
│       ├── producer()
│       ├── producer_handler()
│       └── consumer_handler()
│
└── [existing modules remain unchanged]
    ├── functions.py
    ├── events.py
    ├── dayEvents.py
    ├── conversationEvents.py
    ├── intradayActivity.py
    ├── player_cache.py
    ├── config.py
    ├── database/
    ├── core/
    ├── character/
    ├── relationships/
    ├── education/
    ├── jobs/
    ├── health/
    ├── stats/
    ├── shop/
    └── utils/
```

## Module Dependency Graph

```
┌─────────────────────────────────────────────────────────────┐
│                          app.py                             │
│                    (Main Entry Point)                       │
│                      ~350-450 lines                         │
└────────────┬────────────────────────────────────────────────┘
             │
             ├─────────────────────────┬──────────────────────┐
             ▼                         ▼                      ▼
     ┌───────────────┐       ┌─────────────────┐    ┌────────────────┐
     │    server/    │       │   game_loop/    │    │   functions.py │
     │               │       │                 │    │   (existing)   │
     │ - events      │       │ - loop_manager  │    └────────────────┘
     │ - registry    │       │ - producer      │
     │ - messaging   │       └─────────────────┘
     │ - dispatcher  │
     │ - handlers    │
     └───────────────┘
             │
             └──────────────────────────────────────────────────┐
                                                                ▼
                                                    ┌──────────────────────┐
                                                    │  Existing Modules    │
                                                    │  (database, core,    │
                                                    │   character, etc.)   │
                                                    └──────────────────────┘
```

## Import Flow

### Before (app.py imports everything)
```python
# app.py - 1,291 lines
import websockets
from events import *
from functions import *
from intradayActivity import *
# ... massive inline code ...
```

### After (clean separation)
```python
# app.py - ~400 lines
import websockets

# Server infrastructure
from server.event_registration import initialize_all_events
from server.websocket_registry import get_user_registry, BatchedUpdate
from server.websocket_messaging import sendToUser, sendEventMessage
from server.command_dispatcher import dispatch_command
from server.websocket_handlers import handler, every_minute

# Game loop
from game_loop.producer_consumer import producer_handler, consumer_handler

# Existing modules
from functions import *
from player_cache import PlayerCache
from config import config

# Clean, focused code
```

## File Size Comparison

| File | Before | After | Change |
|------|--------|-------|--------|
| app.py | 1,291 lines | ~400 lines | -69% |
| server/event_registration.py | - | 250 lines | NEW |
| server/websocket_registry.py | - | 120 lines | NEW |
| server/websocket_messaging.py | - | 100 lines | NEW |
| server/command_dispatcher.py | - | 500 lines | NEW |
| server/websocket_handlers.py | - | 200 lines | NEW |
| game_loop/loop_manager.py | - | 250 lines | NEW |
| game_loop/producer_consumer.py | - | 80 lines | NEW |
| **TOTAL** | **1,291 lines** | **1,900 lines** | +47% |

**Note:** Total lines increase because:
- Better organization with docstrings
- Proper class structure for command handlers
- Clear separation of concerns
- Improved maintainability (worth the extra lines)

## Performance-Critical Sections

### ⚡ HOT PATH (Keep in app.py)
```python
async def initLifeSim(websocket, oneTimePlayer=False):
    """
    PERFORMANCE CRITICAL - runs 5000 times/sec per player
    Keep in app.py to minimize call overhead
    """
    # Tight loop logic stays here
    pass
```

### 🌡️ WARM PATH (Can extract)
```python
# server/command_dispatcher.py
async def dispatch_command(event, player, websocket):
    """
    Runs on each user command (not every tick)
    Safe to extract - not in critical path
    """
    pass
```

### ❄️ COLD PATH (Should extract)
```python
# server/event_registration.py
def register_all_events():
    """
    Runs once at server startup
    Definitely extract - zero performance impact
    """
    pass
```

## Command Dispatcher Architecture

### Before: Linear if/elif Chain (476 lines)
```python
async def consumer(message, websocket):
    # ... setup ...

    if event.get('message') == "stop":
        # 5 lines
        pass
    elif event.get('message') == "start":
        # 3 lines
        pass
    elif event.get('message') == "restart":
        # 8 lines
        pass
    elif event['type'] == 'characterSetup':
        # 5 lines
        pass
    elif event['type'] == 'deviceToken':
        # 4 lines
        pass
    # ... 35 more elif statements ...
    elif event['type'] == 'speed':
        # 60 lines!
        pass
    # ... even more ...
    else:
        # 40 lines of fallback logic
        pass
```

### After: Table-Driven Dispatch (60 lines in app.py + 500 in dispatcher)
```python
# app.py (simplified consumer)
async def consumer(message, websocket):
    # ... setup (20 lines) ...

    # Single dispatch call
    await dispatch_command(event, player, websocket)

    # ... cleanup (20 lines) ...
```

```python
# server/command_dispatcher.py
class CommandDispatcher:
    def __init__(self):
        self._handlers = {
            'stop': StopCommandHandler(),
            'start': StartCommandHandler(),
            'restart': RestartCommandHandler(),
            'characterSetup': CharacterSetupCommandHandler(),
            'speed': SpeedCommandHandler(),
            # ... 35+ more handlers ...
        }

    async def dispatch(self, event, player, websocket):
        handler = self._handlers.get(event.get('type'))
        if handler:
            await handler.handle(player, event, websocket)
```

**Benefits:**
- O(1) lookup instead of O(n) linear search
- Each handler is testable in isolation
- Easy to add new commands
- Clear separation of concerns
- Better error handling

## Testing Structure

```
tests/
├── unit/
│   ├── server/
│   │   ├── test_event_registration.py
│   │   ├── test_websocket_registry.py
│   │   ├── test_websocket_messaging.py
│   │   ├── test_command_dispatcher.py
│   │   └── test_websocket_handlers.py
│   │
│   └── game_loop/
│       ├── test_loop_manager.py
│       └── test_producer_consumer.py
│
├── integration/
│   ├── test_full_game_loop.py
│   ├── test_command_routing.py
│   └── test_websocket_lifecycle.py
│
└── load/
    ├── websocket_load.py
    └── performance_baseline.py
```

## Migration Strategy

### Step-by-Step Process

```
Current State: app.py (1,291 lines)
                    ↓
Phase 1: Extract Cold Path
├── Create server/event_registration.py (250 lines)
├── Create server/websocket_registry.py (120 lines)
└── Create server/websocket_messaging.py (100 lines)
                    ↓
Checkpoint 1: app.py (~940 lines) ✅ Test & Benchmark
                    ↓
Phase 2: Extract Warm Path
├── Create game_loop/producer_consumer.py (80 lines)
├── Create server/websocket_handlers.py (200 lines)
└── Optimize game_loop/loop_manager.py (40 lines saved)
                    ↓
Checkpoint 2: app.py (~665 lines) ✅ Test & Benchmark
                    ↓
Phase 3: Extract Command Dispatcher
└── Create server/command_dispatcher.py (416 lines)
                    ↓
Checkpoint 3: app.py (~350-450 lines) ✅ Test & Benchmark
                    ↓
Final State: Refactoring Complete! 🎉
```

## Rollback Strategy

Each phase is independently committable:

```bash
# If Phase 3 has issues, rollback to Phase 2
git revert HEAD

# Phase 2 still works independently
# app.py is still functional at ~665 lines
```

## Documentation Updates Required

After refactoring, update:

1. **CLAUDE.md** - Add new server/ and game_loop/ sections
2. **FRONTEND.md** - Update WebSocket message flow diagrams
3. **PROJECT_STATUS.md** - Mark refactoring as complete
4. **README.md** - Update architecture diagram
5. **API_DOCUMENTATION.md** - Update command reference

## Success Criteria

✅ **Code Quality**
- app.py < 500 lines
- All modules < 600 lines
- Cyclomatic complexity reduced 60%+
- 100% backward compatibility

✅ **Performance**
- No FPS regression
- Memory usage increase < 5%
- Message latency unchanged
- Startup time increase < 100ms

✅ **Testing**
- 80%+ test coverage on new modules
- All integration tests pass
- Load tests pass (100 concurrent players)
- Performance benchmarks pass

✅ **Documentation**
- All modules have docstrings
- Architecture diagrams updated
- Migration guide created
- Developer onboarding guide updated