echoes-of-the-ash/docs/development/HANDLER_REFACTORING_SUMMARY.md

Handler Refactoring Summary

Code Metrics

Before Refactoring

• Single file: bot/handlers.py (~1,308 lines)
• Giant function: button_handler() with 1000+ lines of if/elif chains
• Maintainability: Very difficult to navigate and modify

After Refactoring

• 7 organized modules: Total ~1,786 lines (well-structured)
• Main router: handlers.py (377 lines) - clean routing logic
• 6 specialized modules:
  • action_handlers.py (367 lines) - World interaction
  • inventory_handlers.py (355 lines) - Inventory management
  • corpse_handlers.py (234 lines) - Corpse looting
  • combat_handlers.py (171 lines) - Combat actions
  • profile_handlers.py (147 lines) - Profile & stats
  • pickup_handlers.py (135 lines) - Item pickup

Architecture

bot/
├── handlers.py              # Main router & utilities
│   ├── send_or_edit_with_image()
│   ├── start()
│   ├── export_map()
│   ├── spawn_stats()
│   └── button_handler()     # Routes to specialized handlers
│
├── action_handlers.py       # World & Inspection
│   ├── get_player_status_text()
│   ├── handle_inspect_area()
│   ├── handle_attack_wandering()
│   ├── handle_inspect_interactable()
│   ├── handle_action()
│   ├── handle_main_menu()
│   ├── handle_move_menu()
│   └── handle_move()
│
├── inventory_handlers.py    # Inventory Management
│   ├── handle_inventory_menu()
│   ├── handle_inventory_item()
│   ├── handle_inventory_use()
│   ├── handle_inventory_drop()
│   ├── handle_inventory_equip()
│   └── handle_inventory_unequip()
│
├── pickup_handlers.py       # Item Collection
│   ├── handle_pickup_menu()
│   └── handle_pickup()
│
├── combat_handlers.py       # Combat System
│   ├── handle_combat_attack()
│   ├── handle_combat_flee()
│   ├── handle_combat_use_item_menu()
│   ├── handle_combat_use_item()
│   └── handle_combat_back()
│
├── profile_handlers.py      # Character Stats
│   ├── handle_profile()
│   ├── handle_spend_points_menu()
│   └── handle_spend_point()
│
└── corpse_handlers.py       # Looting System
    ├── handle_loot_player_corpse()
    ├── handle_take_corpse_item()
    ├── handle_scavenge_npc_corpse()
    └── handle_scavenge_corpse_item()

Key Improvements

1. Separation of Concerns

Each module handles a specific domain of functionality:

• Action Handlers → World exploration & interaction
• Inventory Handlers → Item management
• Combat Handlers → Battle mechanics
• Profile Handlers → Character progression
• Corpse Handlers → Looting system
• Pickup Handlers → Item collection

2. Single Responsibility Principle

Each function has one clear purpose:

• ✅ handle_inventory_use() - Use items
• ✅ handle_combat_attack() - Attack in combat
• ✅ handle_pickup() - Pick up items
• ❌ button_handler() - Do everything

3. Improved Error Handling

# Centralized error handling in router
try:
    if action_type == "inspect_area":
        await handle_inspect_area(query, user_id, player)
    # ... more routes
except Exception as e:
    logger.error(f"Error handling {action_type}: {e}", exc_info=True)
    await query.answer("An error occurred.", show_alert=True)

4. Better Code Navigation

• Jump to specific functionality in seconds
• IDE autocomplete works better
• Easier to review code changes
• Reduced cognitive load

5. Testability

Each handler can now be tested independently:

# Easy to test
await handle_inventory_use(mock_query, user_id, player, data)

# vs. testing 1000 lines of if/elif

Migration Path

All functionality has been preserved. The refactoring only changed the organization, not the behavior.

Verified Compatible

• ✅ All action types still handled
• ✅ Same function signatures
• ✅ Same error handling behavior
• ✅ No breaking changes to external code

Backup Files

Original files saved in backups/:

• handlers_original.py
• handlers.py.old

Future Enhancements

1. Add Type Hints

   async def handle_inventory_use(
       query: CallbackQuery,
       user_id: int,
       player: dict,
       data: list[str]
   ) -> None:
   

2. Create Base Handler Class

   class BaseHandler:
       def __init__(self, query, user_id, player):
           self.query = query
           self.user_id = user_id
           self.player = player
   

3. Add Unit Tests

   def test_handle_inventory_use():
       # Test consumable usage
       # Test inventory updates
       # Test error cases
   

4. Add Handler Decorators

   @requires_combat
   async def handle_combat_attack(...):
   
   @requires_stamina(10)
   async def handle_action(...):
   

Conclusion

This refactoring transforms a monolithic 1,308-line file with a 1000+ line function into a well-organized, modular architecture with:

• ✅ Clear separation of concerns
• ✅ Easy navigation and maintenance
• ✅ Better error handling
• ✅ Improved testability
• ✅ No breaking changes

Result: The codebase is now much easier to understand, modify, and extend.