echoes-of-the-ash/REFACTORING_PLAN.md

Project Refactoring Plan

Current Status

✅ Completed

1. Moved unused files to old/ folder:

   • bot/ - Old Telegram bot code (no longer used)
   • web-map/ - Old map editor
   • All .md documentation files
   • Old migration scripts
   • Old Dockerfiles

2. Created new API module structure:

   api/
   ├── core/           # Core functionality (config, security, websockets)
   ├── routers/        # API route handlers
   ├── services/       # Business logic services
   └── ...existing files...
   

3. Created core modules:

   • ✅ api/core/config.py - All configuration and constants
   • ✅ api/core/security.py - JWT, auth, password hashing
   • ✅ api/core/websockets.py - WebSocket ConnectionManager

🔄 Next Steps

Backend API Refactoring

Router Files to Create (in api/routers/):

1. auth.py - /api/auth/* endpoints (register, login, me)
2. characters.py - /api/characters/* endpoints (list, create, select, delete)
3. game.py - /api/game/* endpoints (state, location, profile, move, inspect, interact, pickup, use_item)
4. combat.py - /api/game/combat/* endpoints (initiate, action) + PvP combat
5. equipment.py - /api/game/equip/* endpoints (equip, unequip, repair)
6. crafting.py - /api/game/craft/* endpoints (craftable, craft_item)
7. corpses.py - /api/game/corpses/* and /api/internal/corpses/* endpoints
8. websocket.py - /ws/game/* WebSocket endpoint

Helper Files to Create (in api/services/):

1. helpers.py - Utility functions (distance calculation, stamina cost, armor durability, etc.)
2. models.py - Pydantic models (all request/response models)

Final api/main.py will contain ONLY:

• FastAPI app initialization
• Middleware setup (CORS)
• Static file mounting
• Router registration
• Lifespan context (startup/shutdown)
• ~100 lines instead of 5500+

Frontend Refactoring

Components to Extract from Game.tsx:

In pwa/src/components/game/:

1. Compass.tsx - Navigation compass with stamina costs
2. LocationView.tsx - Location description and image
3. Surroundings.tsx - NPCs, players, items, corpses, interactables
4. InventoryPanel.tsx - Inventory management
5. EquipmentPanel.tsx - Equipment slots
6. CombatView.tsx - Combat interface (PvE and PvP)
7. ProfilePanel.tsx - Player stats and info
8. CraftingPanel.tsx - Crafting interface
9. DeathOverlay.tsx - Death screen

Shared hooks (in pwa/src/hooks/):

1. useWebSocket.ts - WebSocket connection and message handling
2. useGameState.ts - Game state management
3. useCombat.ts - Combat state and actions

Type definitions (in pwa/src/types/):

1. game.ts - Game entities (Player, Location, Item, NPC, etc.)
2. combat.ts - Combat-related types
3. websocket.ts - WebSocket message types

Final Game.tsx will contain ONLY:

• Component composition
• State management coordination
• WebSocket message routing
• ~300-400 lines instead of 3300+

📋 Estimated File Count

Before:

• Backend: 1 massive file (5574 lines)
• Frontend: 1 massive file (3315 lines)
• Total: 2 files, ~9000 lines

After:

• Backend: ~15 files, average ~200-400 lines each
• Frontend: ~15 files, average ~100-300 lines each
• Total: ~30 files, all maintainable and focused

🎯 Benefits

1. Easier to navigate - Each file has a single responsibility
2. Easier to test - Isolated components and functions
3. Easier to maintain - Changes don't affect unrelated code
4. Easier to understand - Clear module boundaries
5. Better IDE support - Faster autocomplete, better error detection
6. Team-friendly - Multiple developers can work without conflicts

Implementation Strategy

Phase 1: Backend (4-5 hours)

1. Create all router files with endpoints
2. Create service/helper files
3. Extract Pydantic models
4. Refactor main.py to just registration
5. Test all endpoints still work

Phase 2: Frontend (3-4 hours)

1. Create type definitions
2. Extract hooks
3. Create component files
4. Refactor Game.tsx to use components
5. Test all functionality still works

Phase 3: TypeScript Configuration (30 minutes)

1. Create/update tsconfig.json
2. Add proper type definitions
3. Fix VSCode errors

Phase 4: Testing & Documentation (1 hour)

1. Verify all features work
2. Update README with new structure
3. Create architecture diagram

Questions Before Proceeding

1. Should I continue with the full refactoring now?

   • This will take significant time (8-10 hours of work)
   • Will create 30+ new files
   • Will require thorough testing

2. Do you want me to do it all at once or in phases?

   • All at once: Complete transformation
   • Phases: Backend first, then frontend, then testing

3. Any specific preferences for file organization?

   • Current plan follows standard FastAPI/React best practices
   • Open to adjustments

Recommendation

I recommend doing this in phases with testing after each:

1. Phase 1: Backend refactoring (today) - Most critical, easier to test
2. Phase 2: Frontend refactoring (next session) - Can verify backend works first
3. Phase 3: TypeScript fixes (quick win)
4. Phase 4: Final testing and documentation

This approach:

• Allows for testing and validation at each step
• Reduces risk of breaking everything at once
• Gives you time to review and provide feedback
• Easier to roll back if issues arise

Would you like me to proceed with Phase 1: Backend Refactoring now?