Commit

REFACTORING_PLAN.md

@@ -0,0 +1,160 @@
+# 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?