# 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?