Kelsidavis-WoWee/docs/architecture.md

# Architecture Overview

## System Design

Wowee follows a modular architecture with clear separation of concerns:

```
┌─────────────────────────────────────────────┐
│           Application (main loop)            │
│  - State management (auth/realms/game)      │
│  - Update cycle (60 FPS)                    │
│  - Event dispatch                           │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┴────────┐
       │                │
┌──────▼──────┐  ┌─────▼──────┐
│   Window    │  │   Input    │
│  (SDL2)     │  │ (Keyboard/ │
│             │  │   Mouse)   │
└──────┬──────┘  └─────┬──────┘
       │                │
       └───────┬────────┘
               │
    ┌──────────┴──────────┐
    │                     │
┌───▼────────┐   ┌───────▼──────┐
│  Renderer  │   │  UI Manager  │
│ (OpenGL)   │   │   (ImGui)    │
└───┬────────┘   └──────────────┘
    │
    ├─ Camera
    ├─ Scene Graph
    ├─ Shaders
    ├─ Meshes
    └─ Textures
```

## Core Systems

### 1. Application Layer (`src/core/`)

**Application** - Main controller
- Owns all subsystems
- Manages application state
- Runs update/render loop
- Handles lifecycle (init/shutdown)

**Window** - SDL2 wrapper
- Creates window and OpenGL context
- Handles resize events
- Manages VSync and fullscreen

**Input** - Input management
- Keyboard state tracking
- Mouse position and buttons
- Mouse locking for camera control

**Logger** - Logging system
- Thread-safe logging
- Multiple log levels (DEBUG, INFO, WARNING, ERROR, FATAL)
- Timestamp formatting

### 2. Rendering System (`src/rendering/`)

**Renderer** - Main rendering coordinator
- Manages OpenGL state
- Coordinates frame rendering
- Owns camera and scene

**Camera** - View/projection matrices
- Position and orientation
- FOV and aspect ratio
- View frustum (for culling)

**Scene** - Scene graph
- Mesh collection
- Spatial organization
- Visibility determination

**Shader** - GLSL program wrapper
- Loads vertex/fragment shaders
- Uniform management
- Compilation and linking

**Mesh** - Geometry container
- Vertex buffer (position, normal, texcoord)
- Index buffer
- VAO/VBO/EBO management

**Texture** - Texture management
- Loading (will support BLP format)
- OpenGL texture object
- Mipmap generation

**Material** - Surface properties
- Shader assignment
- Texture binding
- Color/properties

### 3. Networking (`src/network/`)

**Socket** (Abstract base class)
- Connection interface
- Packet send/receive
- Callback system

**TCPSocket** - Linux TCP sockets
- Non-blocking I/O
- Raw TCP (replaces WebSocket)
- Packet framing

**Packet** - Binary data container
- Read/write primitives
- Byte order handling
- Opcode management

### 4. Authentication (`src/auth/`)

**AuthHandler** - Auth server protocol
- Connects to port 3724
- SRP authentication flow
- Session key generation

**SRP** - Secure Remote Password
- SRP6a algorithm
- Big integer math
- Salt and verifier generation

**Crypto** - Cryptographic functions
- SHA1 hashing (OpenSSL)
- Random number generation
- Encryption helpers

### 5. Game Logic (`src/game/`)

**GameHandler** - World server protocol
- Connects to port 8129
- Packet handlers for all opcodes
- Session management

**World** - Game world state
- Map loading
- Entity management
- Terrain streaming

**Player** - Player character
- Position and movement
- Stats and inventory
- Action queue

**Entity** - Game entities
- NPCs and creatures
- Base entity functionality
- GUID management

**Opcodes** - Protocol definitions
- Client→Server opcodes (CMSG_*)
- Server→Client opcodes (SMSG_*)
- WoW 3.3.5a specific

### 6. Asset Pipeline (`src/pipeline/`)

**MPQManager** - Archive management
- Loads .mpq files (via StormLib)
- File lookup
- Data extraction

**BLPLoader** - Texture parser
- BLP format (Blizzard texture format)
- DXT compression support
- Mipmap extraction

**M2Loader** - Model parser
- Character/creature models
- Skeletal animation data
- Bone hierarchies
- Animation sequences

**WMOLoader** - World object parser
- Buildings and structures
- Static geometry
- Portal system
- Doodad placement

**ADTLoader** - Terrain parser
- 16x16 chunks per map
- Height map data
- Texture layers (up to 4)
- Liquid data (water/lava)
- Object placement

**DBCLoader** - Database parser
- Game data tables
- Creature/spell/item definitions
- Map and area information

### 7. UI System (`src/ui/`)

**UIManager** - ImGui coordinator
- ImGui initialization
- Event handling
- Render dispatch

**AuthScreen** - Login interface
- Username/password input
- Server address configuration
- Connection status

**RealmScreen** - Server selection
- Realm list display
- Population info
- Realm type (PvP/PvE/RP)

**CharacterScreen** - Character selection
- Character list with 3D preview
- Create/delete characters
- Enter world button

**GameScreen** - In-game UI
- Chat window
- Action bars
- Character stats
- Minimap

## Data Flow Examples

### Authentication Flow
```
User Input (username/password)
    ↓
AuthHandler::authenticate()
    ↓
SRP::calculateVerifier()
    ↓
TCPSocket::send(LOGON_CHALLENGE)
    ↓
Server Response (LOGON_CHALLENGE)
    ↓
AuthHandler receives packet
    ↓
SRP::calculateProof()
    ↓
TCPSocket::send(LOGON_PROOF)
    ↓
Server Response (LOGON_PROOF) → Success
    ↓
Application::setState(REALM_SELECTION)
```

### Rendering Flow
```
Application::render()
    ↓
Renderer::beginFrame()
    ├─ glClearColor() - Clear screen
    └─ glClear() - Clear buffers
    ↓
Renderer::renderWorld(world)
    ├─ Update camera matrices
    ├─ Frustum culling
    ├─ For each visible chunk:
    │   ├─ Bind shader
    │   ├─ Set uniforms (matrices, lighting)
    │   ├─ Bind textures
    │   └─ Mesh::draw() → glDrawElements()
    └─ For each entity:
        ├─ Calculate bone transforms
        └─ Render skinned mesh
    ↓
UIManager::render()
    ├─ ImGui::NewFrame()
    ├─ Render current UI screen
    └─ ImGui::Render()
    ↓
Renderer::endFrame()
    ↓
Window::swapBuffers()
```

### Asset Loading Flow
```
World::loadMap(mapId)
    ↓
MPQManager::readFile("World/Maps/{map}/map.adt")
    ↓
ADTLoader::load(adtData)
    ├─ Parse MCNK chunks (terrain)
    ├─ Parse MCLY chunks (textures)
    ├─ Parse MCVT chunks (vertices)
    └─ Parse MCNR chunks (normals)
    ↓
For each texture reference:
    MPQManager::readFile(texturePath)
    ↓
    BLPLoader::load(blpData)
    ↓
    Texture::loadFromMemory(imageData)
    ↓
Create Mesh from vertices/normals/texcoords
    ↓
Add to Scene
    ↓
Renderer draws in next frame
```

## Threading Model

Currently **single-threaded**:
- Main thread: Window events, update, render
- Network I/O: Non-blocking in main thread
- Asset loading: Synchronous in main thread

**Future multi-threading opportunities:**
- Asset loading thread pool (background texture/model loading)
- Network thread (dedicated for socket I/O)
- Physics thread (if collision detection is added)

## Memory Management

- **Smart pointers:** Used throughout (std::unique_ptr, std::shared_ptr)
- **RAII:** All resources (OpenGL, SDL) cleaned up automatically
- **No manual memory management:** No raw new/delete
- **OpenGL resources:** Wrapped in classes with proper destructors

## Performance Considerations

### Rendering
- **Frustum culling:** Only render visible chunks
- **Batching:** Group draw calls by material
- **LOD:** Distance-based level of detail (TODO)
- **Occlusion:** Portal-based visibility (WMO system)

### Asset Streaming
- **Lazy loading:** Load chunks as player moves
- **Unloading:** Free distant chunks
- **Caching:** Keep frequently used assets in memory

### Network
- **Non-blocking I/O:** Never stall main thread
- **Packet buffering:** Handle multiple packets per frame
- **Compression:** Some packets are compressed (TODO)

## Error Handling

- **Logging:** All errors logged with context
- **Graceful degradation:** Missing assets show placeholder
- **State recovery:** Network disconnect → back to auth screen
- **No crashes:** Exceptions caught at application level

## Configuration

Currently hardcoded, future config system:
- Window size and fullscreen
- Graphics quality settings
- Server addresses
- Keybindings
- Audio volume

## Testing Strategy

**Unit Testing** (TODO):
- Packet serialization/deserialization
- SRP math functions
- Asset parsers with sample files

**Integration Testing** (TODO):
- Full auth flow against test server
- Realm list retrieval
- Character selection

**Manual Testing:**
- Visual verification of rendering
- Performance profiling
- Memory leak checking (valgrind)

## Build System

**CMake:**
- Modular target structure
- Automatic dependency discovery
- Cross-platform (Linux focus, but portable)
- Out-of-source builds

**Dependencies:**
- SDL2 (system)
- OpenGL/GLEW (system)
- OpenSSL (system)
- GLM (system or header-only)
- ImGui (submodule in extern/)
- StormLib (system, optional)

## Code Style

- **C++17 standard**
- **Namespaces:** wowee::core, wowee::rendering, etc.
- **Naming:** PascalCase for classes, camelCase for functions/variables
- **Headers:** .hpp extension
- **Includes:** Relative to project root

---

This architecture provides a solid foundation for a full-featured native WoW client!