diff --git a/README.md b/README.md
index 216709f93..1db93bd19 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,81 @@
 # Ryan R-Type
 
+**Ryan R-Type** is a modern networked multiplayer space shooter game inspired by the classic R-Type arcade game. Built with a client-server architecture in C++20, it features real-time multiplayer gameplay, a custom Entity-Component-System (ECS), and advanced networking protocols.
+
+## 🚀 Features
+
+- 🎮 **Multiplayer Support**: Up to 4 players in cooperative gameplay
+- 🌐 **Real-time Networking**: UDP-based communication with client-server architecture
+- 🎨 **Modern Graphics**: SFML-powered rendering with dynamic effects
+- 🔧 **Configurable Server**: Customizable port, IP, and tick rate
+- 🕹️ **Custom ECS**: High-performance entity management system
+- 🎯 **Lobby System**: Create and join game lobbies with unique codes
+- 📊 **HTTP API**: RESTful API for game statistics and management
+- 🔒 **Cross-platform**: Supports Windows, Linux, and macOS
+
+## 📋 System Requirements
+
+### Minimum Requirements
+- **OS**: Windows 10+, Linux (Ubuntu 20.04+), macOS 11+
+- **Compiler**: GCC 11+, Clang 12+, or MSVC 2019+
+- **CMake**: Version 3.23 or higher
+- **RAM**: 512 MB
+- **Network**: Internet connection for multiplayer
+
+### Development Requirements
+- **C++ Compiler** with C++20 support
+- **CMake**: 3.23+
+- **vcpkg**: Package manager for dependencies
+- **Git**: Version control
+
+## ⚡ Quick Start
+
+### Running Pre-built Binaries
+
+```bash
+# Start the server (default: 127.0.0.1:4242)
+./r-type_server
+
+# In another terminal, start the client
+./r-type_client -n Player1
+```
+
+### Multiplayer Setup
+
+```bash
+# Server on a specific IP and port
+./r-type_server -p 8080 -i 0.0.0.0
+
+# Clients connect to the server
+./r-type_client -p 8080 -i <server_ip> -n Alice
+./r-type_client -p 8080 -i <server_ip> -n Bob
+```
+
 ## Installing Ryan R-Type
 
-### Via Releases
+### Via Releases (Recommended)
+
+Download the latest pre-built binaries from our [releases page](https://github.com/AlbanRSS/doc-rtype/releases).
+
+**Installation steps:**
 
-To install our project, you just need to go to our release page and follow the release's instructions to download it.
+1. Download the appropriate archive for your platform:
+   - **Windows**: `r-type-windows-x64.zip`
+   - **Linux**: `r-type-linux-x64.tar.gz`
+   - **macOS**: `r-type-macos-x64.tar.gz`
+
+2. Extract the archive:
+   ```bash
+   # Linux/macOS
+   tar -xzf r-type-*.tar.gz
+   cd r-type
+   
+   # Windows: Use Windows Explorer or
+   unzip r-type-windows-x64.zip
+   cd r-type
+   ```
+
+3. Run the executables (see [Quick Start](#-quick-start) section)
 
 ### Via cloning
 
@@ -28,19 +99,21 @@ After compiling the project, you can run the server and client executables.
 
 #### Running the Server
 ```bash
-./r-type_server -p <port> -i <ip_address> -n <nb_clients>
+./r-type_server -p <port> -i <ip_address>
 ```
 
 Arguments:
-- `-p <port>`: Specify the port number (required)
-- `-i <ip_address>`: Specify the IP address to bind to (required)
-- `-n <nb_clients>`: Specify the maximum number of clients (1-4, default: 1) (required)
+- `-p <port>`: Specify the port number (default: 4242) (optional)
+- `-i <ip_address>`: Specify the IP address to bind to (default: 127.0.0.1) (optional)
+- `-tps <tps>`: Specify the TPS (ticks per second) (default: 20) (optional)
 - `-d`: Enable debug mode (optional)
 - `-h`: Display help message (optional)
 
+Note: Port 5173 is reserved for HTTP server.
+
 Example:
 ```bash
-./r-type_server -p 4242 -i 127.0.0.1 -n 4
+./r-type_server -p 4242 -i 127.0.0.1 -tps 20
 ```
 
 #### Running the Client
@@ -60,7 +133,88 @@ Example:
 ./r-type_client -p 4242 -i 127.0.0.1 -n Player1
 ```
 
-## Contributing
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### Server: Port Already in Use
+```bash
+# Error: Address already in use
+# Solution: Use a different port
+./r-type_server -p 8080 -i 127.0.0.1
+```
+
+#### Client: Connection Refused
+```bash
+# Possible causes:
+# 1. Server is not running
+# 2. Wrong IP or port
+# 3. Firewall blocking connection
+
+# Verify server is running on the correct port
+./r-type_server -p 4242 -i 0.0.0.0
+
+# Connect with matching port
+./r-type_client -p 4242 -i <server_ip>
+```
+
+#### Compilation Errors
+```bash
+# If vcpkg dependencies fail to install
+./scripts/install_dependencies.sh
+
+# Clean build directory and rebuild
+./scripts/clean_project.sh
+./scripts/compile_project.sh
+```
+
+#### HTTP Server Port Conflict
+Port 5173 is reserved for the HTTP API server. If you need to run the game server on a different port:
+```bash
+./r-type_server -p 4243  # Use any port except 5173
+```
+
+#### Permission Denied on Scripts
+```bash
+# Unix systems: Make scripts executable
+chmod +x ./scripts/*.sh
+```
+
+### Performance Issues
+
+**High Latency:**
+- Ensure stable network connection
+- Try reducing TPS: `./r-type_server -tps 15`
+- Check firewall/router settings
+
+**Low FPS:**
+- Update graphics drivers
+- Close resource-intensive applications
+- Check system meets minimum requirements
+
+### Debug Mode
+
+Enable debug mode for detailed logging:
+```bash
+# Server
+./r-type_server -d
+
+# Client
+./r-type_client -d
+```
+
+### Getting Help
+
+If you encounter issues not covered here:
+1. Check the [documentation](https://albanrss.github.io/doc-rtype/)
+2. Search [existing issues](https://github.com/AlbanRSS/doc-rtype/issues)
+3. Create a new issue with:
+   - Your OS and version
+   - Steps to reproduce
+   - Error messages/logs
+   - Expected vs actual behavior
+
+## 🤝 Contributing
 
 For contribution guidelines, including prerequisites and commit conventions, please refer to [HOWTOCONTRIBUTE.md](HOWTOCONTRIBUTE.md).
 
@@ -68,11 +222,13 @@ For contribution guidelines, including prerequisites and commit conventions, ple
 
 ### Docusaurus
 
-The **Docusaurus** documentation regroups the entirety of the project documentation, protocole server gui and clinet information, but also how to contribute to the project and how to use the project itlsef.
+The **Docusaurus** documentation contains the entirety of the project documentation, including protocol specifications, server/client information, contribution guidelines, and usage instructions.
+
+📖 **Access the online documentation**: https://albanrss.github.io/doc-rtype/
 
-Access the documentation at https://albanrss.github.io/doc-rtype/
+#### Running Documentation Locally
 
-To run the documentation travel to the `/documentation` folder than run the following :
+To run the documentation locally, navigate to the `/documentation` folder and run the following:
 
 ``` bash
 cd documentation/docusaurus/
@@ -82,33 +238,42 @@ npm start
 Then you can find the documentation at http://localhost:3000/
 
 
-#### Prerequisite :
+#### Prerequisites
 
-To run the Docusaurus documentation you will need to have the docusaurus librairy installed on your device.
+To run the Docusaurus documentation locally:
+- **Node.js**: Version 18.0 or higher
+- **npm**: Version 8.0 or higher
 
-- [Docusaurus](https://docusaurus.io/docs/installation)
+The Docusaurus library will be automatically installed when running `npm install`.
+
+For more information, see the [Docusaurus installation guide](https://docusaurus.io/docs/installation).
 
 
 ### Doxygen
 
-The **Doxygen** module allows you to generate pdf documentation and schemas of the project architecure and logic.
+The **Doxygen** module generates PDF documentation and diagrams of the project architecture and logic.
 
-To update the documentation run the following :
+To generate the documentation, run:
 
-``` bash
-./scripts/generateDoc.sh
+```bash
+./scripts/generate_doc.sh
 ```
 
-#### Prerequisite :
+The generated documentation will be available in `documentation/doc/`.
 
-To run the doxygen generations script you will need to have the Doxygen and pdf-Latex Library, you can find there install guide here
+#### Prerequisites
 
-- [Doxygen](https://www.doxygen.nl/manual/install.html)
-- [PDF Latex](https://www.latex-project.org/get/)
+To run the Doxygen generation script, you need:
+- **Doxygen**: Version 1.9.0 or higher
+- **LaTeX**: For PDF generation (pdflatex)
+- **Graphviz**: For generating diagrams (optional but recommended)
 
-You also need to make sure that the script is executable.
+Installation guides:
+- [Doxygen Installation](https://www.doxygen.nl/manual/install.html)
+- [LaTeX Installation](https://www.latex-project.org/get/)
+- [Graphviz Installation](https://graphviz.org/download/)
 
-``` bash
-cd ./script
-chmod +x generateDoc.sh
+**Make the script executable:**
+```bash
+chmod +x ./scripts/generate_doc.sh
 ```
diff --git a/client/gsm/states/scenes/InGame/InGameState.cpp b/client/gsm/states/scenes/InGame/InGameState.cpp
index 4ac29d57b..c5ece0ed8 100644
--- a/client/gsm/states/scenes/InGame/InGameState.cpp
+++ b/client/gsm/states/scenes/InGame/InGameState.cpp
@@ -508,7 +508,8 @@ void InGameState::drawInGameMetrics(std::shared_ptr<gfx::IWindow> window, float
         std::count(metricsText.begin(), metricsText.end(), '\n')) + 1;
     size_t totalHeight = textHeight + (numLines - 1) * 5;
     size_t baseX = static_cast<size_t>(constants::MAX_WIDTH - 5.0f);
-    size_t baseY = static_cast<size_t>(constants::MAX_HEIGHT - totalHeight - 15.0f);
+    size_t baseY = static_cast<size_t>(constants::MAX_HEIGHT -
+        static_cast<float>(totalHeight) - 15.0f);
 
     std::istringstream iss(metricsText);
     std::string line;
diff --git a/documentation/docusaurus/docs/CLIENT/client-architecture.md b/documentation/docusaurus/docs/CLIENT/client-architecture.md
new file mode 100644
index 000000000..db81c2552
--- /dev/null
+++ b/documentation/docusaurus/docs/CLIENT/client-architecture.md
@@ -0,0 +1,832 @@
+---
+sidebar_position: 3
+---
+
+# Client Architecture
+
+Detailed technical documentation of the R-Type client architecture.
+
+## Overview
+
+The client is responsible for:
+- **Rendering**: Visual display of game state
+- **Input handling**: Keyboard, mouse, and gamepad
+- **Audio playback**: Music and sound effects
+- **Network communication**: Sync with server
+- **Local prediction**: Smooth gameplay despite network latency
+- **UI management**: Menus and HUD
+
+## Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "Client Core"
+        MAIN[main.cpp]
+        CORE[Core]
+        UTILS[Utils CLI Parser]
+    end
+    
+    subgraph "Network Layer"
+        CN[ClientNetwork]
+        PS[PacketSender]
+        PR[PacketReceiver]
+    end
+    
+    subgraph "Game State Machine"
+        GSM[GameStateMachine]
+        MENU[MenuState]
+        GAME[InGameState]
+        PAUSE[PauseState]
+        LOBBY[LobbyState]
+    end
+    
+    subgraph "Systems"
+        RS[RenderSystem]
+        AS[AudioSystem]
+        IS[InputSystem]
+        ANS[AnimationSystem]
+        PS_SYSTEM[ParallaxSystem]
+    end
+    
+    subgraph "Resource Management"
+        RM[ResourceManager]
+        TM[TextureManager]
+        SM[SoundManager]
+        FM[FontManager]
+    end
+    
+    subgraph "UI"
+        UI_MGR[UIManager]
+        WIDGETS[UI Widgets]
+        HUD[HUD Elements]
+    end
+    
+    MAIN --> CORE
+    CORE --> CN
+    CORE --> GSM
+    CORE --> RM
+    
+    GSM --> MENU
+    GSM --> GAME
+    GSM --> PAUSE
+    GSM --> LOBBY
+    
+    GAME --> RS
+    GAME --> AS
+    GAME --> IS
+    GAME --> ANS
+    GAME --> PS_SYSTEM
+    
+    RM --> TM
+    RM --> SM
+    RM --> FM
+    
+    GAME --> UI_MGR
+    UI_MGR --> WIDGETS
+    UI_MGR --> HUD
+    
+    CN --> PS
+    CN --> PR
+```
+
+## Core Components
+
+### Core Class
+
+**File:** `client/Core.cpp`, `client/Core.hpp`
+
+Central coordinator for the client application.
+
+**Responsibilities:**
+- Initialize all subsystems
+- Manage main game loop
+- Coordinate between systems
+- Handle window events
+
+**Key Methods:**
+```cpp
+class Core {
+public:
+    Core();
+    ~Core();
+    
+    void startNetwork();              // Initialize network connection
+    void initFirstScene();           // Set up initial game state
+    void run();                      // Main game loop
+    
+    std::shared_ptr<ClientNetwork> getNetwork();
+    
+private:
+    void processEvents();            // Handle window events
+    void update(float deltaTime);    // Update game logic
+    void render();                   // Draw frame
+};
+```
+
+**Game Loop:**
+```cpp
+void Core::run() {
+    sf::Clock clock;
+    
+    while (window->isOpen()) {
+        float deltaTime = clock.restart().asSeconds();
+        
+        processEvents();          // Input handling
+        network->receive();       // Network updates
+        update(deltaTime);        // Game logic
+        render();                // Draw
+        
+        // Frame rate limiting
+        sf::sleep(sf::milliseconds(16));  // ~60 FPS
+    }
+}
+```
+
+### ClientNetwork
+
+**File:** `client/ClientNetwork.cpp`, `client/ClientNetwork.hpp`
+
+Manages all network communication with the server.
+
+**Features:**
+- UDP socket management
+- Packet sending/receiving
+- Connection state tracking
+- Heartbeat mechanism
+
+**Key Methods:**
+```cpp
+class ClientNetwork {
+public:
+    void connect(const std::string& ip, uint16_t port);
+    void disconnect();
+    
+    void send(const Packet& packet);
+    void receive();  // Process incoming packets
+    
+    bool isConnected() const;
+    uint8_t getClientId() const;
+    
+    void setPort(uint16_t port);
+    void setIp(const std::string& ip);
+    void setName(const std::string& name);
+    void setDebugMode(bool debug);
+    
+private:
+    void handlePacket(const Packet& packet);
+    void sendHeartbeat();
+};
+```
+
+**Connection Flow:**
+```cpp
+// 1. Initialize network
+network->setIp("127.0.0.1");
+network->setPort(4242);
+network->setName("Player1");
+
+// 2. Connect to server
+network->connect();
+
+// 3. Game loop
+while (running) {
+    network->receive();  // Process packets
+    // ... game logic
+    network->send(inputPacket);  // Send player input
+}
+
+// 4. Disconnect
+network->disconnect();
+```
+
+## Game State Machine
+
+**File:** `client/gsm/GameStateMachine.cpp`
+
+Manages different game screens and transitions.
+
+### State Interface
+
+```cpp
+class IState {
+public:
+    virtual ~IState() = default;
+    
+    virtual void enter() = 0;      // Called when entering state
+    virtual void exit() = 0;       // Called when leaving state
+    virtual void update(float dt) = 0;
+    virtual void render() = 0;
+    virtual void handleEvent(const sf::Event& event) = 0;
+};
+```
+
+### Available States
+
+#### MenuState
+- Main menu display
+- Button navigation
+- Option selection
+
+#### LobbyState
+- Lobby creation/joining
+- Player list display
+- Ready status management
+- Chat system
+
+#### InGameState
+- Active gameplay
+- HUD rendering
+- Player controls
+- Game logic
+
+#### PauseState
+- Game paused overlay
+- Settings access
+- Resume/quit options
+
+### State Transitions
+
+```cpp
+class GameStateMachine {
+public:
+    void changeState(std::unique_ptr<IState> newState);
+    void pushState(std::unique_ptr<IState> state);  // Stack states
+    void popState();                                 // Return to previous
+    
+    void update(float deltaTime);
+    void render();
+    void handleEvent(const sf::Event& event);
+    
+private:
+    std::vector<std::unique_ptr<IState>> stateStack;
+};
+```
+
+**Example Usage:**
+```cpp
+// From menu to lobby
+gsm->changeState(std::make_unique<LobbyState>());
+
+// Pause game (stack states)
+gsm->pushState(std::make_unique<PauseState>());
+
+// Resume (pop pause state)
+gsm->popState();
+```
+
+## Systems
+
+### RenderSystem
+
+**File:** `client/systems/rendering/RenderSystem.cpp`
+
+Handles all visual rendering.
+
+**Features:**
+- Sprite rendering
+- Layer management
+- Camera/viewport
+- Parallax backgrounds
+- Particle effects
+
+```cpp
+class RenderSystem : public ASystem {
+public:
+    void update(float deltaTime) override;
+    
+private:
+    void renderEntities();
+    void renderUI();
+    void renderParallax();
+    void sortByLayer();
+    
+    std::shared_ptr<sf::RenderWindow> window;
+    sf::View camera;
+};
+```
+
+**Rendering Pipeline:**
+```
+1. Clear window
+2. Set camera view
+3. Render background layers (parallax)
+4. Sort entities by layer
+5. Render entities (sprites)
+6. Render particle effects
+7. Render UI (HUD)
+8. Display frame
+```
+
+### InputSystem
+
+**File:** `client/systems/input/InputSystem.cpp`
+
+Processes user input from multiple sources.
+
+**Supported Devices:**
+- Keyboard
+- Mouse
+- Gamepad (Xbox, PlayStation, Generic)
+
+```cpp
+class InputSystem : public ASystem {
+public:
+    void update(float deltaTime) override;
+    void handleEvent(const sf::Event& event);
+    
+    bool isActionPressed(InputAction action) const;
+    Vector2D getMovementVector() const;
+    
+private:
+    void updateKeyboard();
+    void updateGamepad();
+    
+    InputMappingManager mappings;
+    std::map<InputAction, bool> actionStates;
+};
+```
+
+**Input Actions:**
+```cpp
+enum class InputAction {
+    MoveUp,
+    MoveDown,
+    MoveLeft,
+    MoveRight,
+    Shoot,
+    Special,
+    Pause,
+    Chat
+};
+```
+
+### AudioSystem
+
+**File:** `client/systems/audio/`
+
+Manages music and sound effect playback.
+
+**Components:**
+- **MusicSystem**: Background music management
+- **SoundSystem**: Sound effects playback
+
+```cpp
+class MusicSystem : public ASystem {
+public:
+    void playMusic(const std::string& musicId);
+    void stopMusic();
+    void setVolume(float volume);  // 0.0 - 100.0
+    void setMusicVolume(float volume);
+    
+private:
+    sf::Music currentMusic;
+    std::map<std::string, std::string> musicPaths;
+};
+
+class SoundSystem : public ASystem {
+public:
+    void playSound(const std::string& soundId);
+    void playSoundAt(const std::string& soundId, Vector2D position);
+    void setSFXVolume(float volume);
+    
+private:
+    std::vector<sf::Sound> activeSounds;
+    std::map<std::string, sf::SoundBuffer> soundBuffers;
+};
+```
+
+**Positional Audio:**
+```cpp
+// Play sound at entity position
+auto transform = registry->getComponent<TransformComponent>(entity);
+soundSystem->playSoundAt("explosion", {transform->x, transform->y});
+```
+
+### AnimationSystem
+
+**File:** `client/systems/animation/AnimationSystem.cpp`
+
+Manages sprite animations.
+
+```cpp
+class AnimationSystem : public ASystem {
+public:
+    void update(float deltaTime) override;
+    
+private:
+    void updateAnimations(float deltaTime);
+    void changeAnimation(Entity entity, const std::string& animName);
+};
+```
+
+**AnimationComponent:**
+```cpp
+struct AnimationComponent : public IComponent {
+    std::string currentAnim;
+    int currentFrame;
+    float frameTime;
+    float elapsed;
+    bool loop;
+    
+    std::map<std::string, Animation> animations;
+};
+
+struct Animation {
+    std::vector<sf::IntRect> frames;
+    float frameDuration;
+};
+```
+
+## UI System
+
+### UIManager
+
+**File:** `client/ui/UIManager.cpp`
+
+Manages all UI elements and widgets.
+
+**Features:**
+- Widget hierarchy
+- Event handling
+- Layout management
+- Theme support
+
+```cpp
+class UIManager {
+public:
+    void addWidget(std::shared_ptr<Widget> widget);
+    void removeWidget(const std::string& id);
+    
+    void update(float deltaTime);
+    void render(sf::RenderWindow& window);
+    void handleEvent(const sf::Event& event);
+    
+private:
+    std::vector<std::shared_ptr<Widget>> widgets;
+    std::shared_ptr<Widget> focusedWidget;
+};
+```
+
+### Widget Types
+
+#### Button
+```cpp
+class Button : public Widget {
+public:
+    void setOnClick(std::function<void()> callback);
+    void setText(const std::string& text);
+    void setTexture(const sf::Texture& texture);
+};
+```
+
+#### TextBox
+```cpp
+class TextBox : public Widget {
+public:
+    void setText(const std::string& text);
+    std::string getText() const;
+    void setEditable(bool editable);
+};
+```
+
+#### Slider
+```cpp
+class Slider : public Widget {
+public:
+    void setValue(float value);  // 0.0 - 1.0
+    float getValue() const;
+    void setOnValueChanged(std::function<void(float)> callback);
+};
+```
+
+#### Label
+```cpp
+class Label : public Widget {
+public:
+    void setText(const std::string& text);
+    void setFont(const sf::Font& font);
+    void setColor(const sf::Color& color);
+};
+```
+
+## Resource Management
+
+### ResourceManager
+
+**File:** `client/initResourcesManager/`
+
+Central resource loading and caching system.
+
+**Managed Resources:**
+- Textures (PNG, JPG)
+- Sounds (WAV, OGG)
+- Fonts (TTF)
+- Shaders (GLSL)
+- Configurations (JSON)
+
+```cpp
+class ResourceManager {
+public:
+    static ResourceManager& getInstance();
+    
+    // Texture management
+    sf::Texture& getTexture(const std::string& id);
+    void loadTexture(const std::string& id, const std::string& path);
+    
+    // Sound management
+    sf::SoundBuffer& getSoundBuffer(const std::string& id);
+    void loadSound(const std::string& id, const std::string& path);
+    
+    // Font management
+    sf::Font& getFont(const std::string& id);
+    void loadFont(const std::string& id, const std::string& path);
+    
+    // Shader management
+    sf::Shader& getShader(const std::string& id);
+    void loadShader(const std::string& id, const std::string& vertex,
+                    const std::string& fragment);
+    
+    void unloadAll();
+    
+private:
+    std::map<std::string, sf::Texture> textures;
+    std::map<std::string, sf::SoundBuffer> sounds;
+    std::map<std::string, sf::Font> fonts;
+    std::map<std::string, sf::Shader> shaders;
+};
+```
+
+**Usage:**
+```cpp
+// Load resources
+auto& rm = ResourceManager::getInstance();
+rm.loadTexture("player", "assets/sprites/player.png");
+rm.loadSound("shoot", "assets/sounds/shoot.wav");
+
+// Use resources
+sf::Sprite sprite(rm.getTexture("player"));
+sf::Sound sound(rm.getSoundBuffer("shoot"));
+```
+
+## Client Prediction
+
+### Local Prediction
+
+To compensate for network latency, the client predicts player movement locally.
+
+**Strategy:**
+1. Client sends input to server
+2. Client immediately applies input locally (prediction)
+3. Server processes input and sends authoritative state
+4. Client reconciles with server state
+
+```cpp
+void ClientNetwork::handleMovementPrediction() {
+    // Apply input immediately (prediction)
+    auto transform = registry->getComponent<TransformComponent>(localPlayer);
+    transform->x += input.dx * deltaTime;
+    transform->y += input.dy * deltaTime;
+    
+    // Store predicted state
+    predictionHistory.push_back({frameNumber, transform->x, transform->y});
+    
+    // Send input to server
+    sendInputPacket(input);
+}
+
+void ClientNetwork::reconcileWithServer(const ServerState& serverState) {
+    auto transform = registry->getComponent<TransformComponent>(localPlayer);
+    
+    // Check if prediction was correct
+    float errorX = abs(transform->x - serverState.x);
+    float errorY = abs(transform->y - serverState.y);
+    
+    if (errorX > RECONCILIATION_THRESHOLD || errorY > RECONCILIATION_THRESHOLD) {
+        // Correct to server state
+        transform->x = serverState.x;
+        transform->y = serverState.y;
+        
+        // Replay inputs after server frame
+        replayInputs(serverState.frameNumber);
+    }
+}
+```
+
+### Entity Interpolation
+
+Other entities are interpolated between received server states for smooth movement.
+
+```cpp
+void ClientNetwork::interpolateEntities(float deltaTime) {
+    auto view = registry->view<TransformComponent, NetworkComponent>();
+    
+    for (Entity entity : view) {
+        if (entity == localPlayer) continue;  // Don't interpolate local player
+        
+        auto transform = registry->getComponent<TransformComponent>(entity);
+        auto network = registry->getComponent<NetworkComponent>(entity);
+        
+        // Interpolate between previous and current server state
+        float alpha = network->interpolationTime / network->interpolationDelay;
+        transform->x = lerp(network->prevX, network->targetX, alpha);
+        transform->y = lerp(network->prevY, network->targetY, alpha);
+        
+        network->interpolationTime += deltaTime;
+    }
+}
+```
+
+## Configuration
+
+### Settings Management
+
+**File:** `client/SettingsManager.cpp`
+
+Manages persistent client settings.
+
+```cpp
+class SettingsManager {
+public:
+    static SettingsManager& getInstance();
+    
+    void load();  // Load from saves/settings.json
+    void save();  // Save to saves/settings.json
+    
+    // Graphics
+    void setResolution(int width, int height);
+    void setFullscreen(bool fullscreen);
+    void setVSync(bool vsync);
+    void setFPSLimit(int limit);
+    
+    // Audio
+    void setMasterVolume(float volume);
+    void setMusicVolume(float volume);
+    void setSFXVolume(float volume);
+    
+    // Gameplay
+    void setPlayerName(const std::string& name);
+    void setAutoReconnect(bool enabled);
+    
+    // Getters
+    int getWidth() const;
+    int getHeight() const;
+    bool isFullscreen() const;
+    // ... etc
+    
+private:
+    SettingsConfig config;
+};
+```
+
+**Settings File Format:**
+```json
+{
+  "graphics": {
+    "resolution": {"width": 1920, "height": 1080},
+    "fullscreen": false,
+    "vsync": true,
+    "fpsLimit": 60
+  },
+  "audio": {
+    "masterVolume": 80,
+    "musicVolume": 70,
+    "sfxVolume": 85
+  },
+  "network": {
+    "defaultServer": "127.0.0.1",
+    "defaultPort": 4242,
+    "autoReconnect": true
+  },
+  "gameplay": {
+    "playerName": "Player1",
+    "showFPS": false
+  }
+}
+```
+
+## Performance Optimization
+
+### Frame Rate Management
+
+```cpp
+// Target frame time (60 FPS = 16.67ms)
+const float TARGET_FRAME_TIME = 1.0f / 60.0f;
+
+void Core::run() {
+    sf::Clock clock;
+    float accumulator = 0.0f;
+    
+    while (window->isOpen()) {
+        float deltaTime = clock.restart().asSeconds();
+        accumulator += deltaTime;
+        
+        // Fixed timestep for game logic
+        while (accumulator >= TARGET_FRAME_TIME) {
+            update(TARGET_FRAME_TIME);
+            accumulator -= TARGET_FRAME_TIME;
+        }
+        
+        // Render with interpolation
+        render(accumulator / TARGET_FRAME_TIME);
+    }
+}
+```
+
+### Asset Streaming
+
+Large assets loaded asynchronously:
+
+```cpp
+void ResourceManager::loadAssetsAsync() {
+    std::thread([this]() {
+        loadTexture("background1", "assets/bg1.png");
+        loadTexture("background2", "assets/bg2.png");
+        // ... more assets
+    }).detach();
+}
+```
+
+### Entity Culling
+
+Only render entities in view:
+
+```cpp
+bool isInView(const TransformComponent& transform, const sf::View& view) {
+    sf::FloatRect viewBounds(
+        view.getCenter() - view.getSize() / 2.f,
+        view.getSize()
+    );
+    
+    return viewBounds.contains(transform.x, transform.y);
+}
+
+void RenderSystem::update(float deltaTime) {
+    auto view = registry->view<TransformComponent, SpriteComponent>();
+    
+    for (Entity entity : view) {
+        auto transform = registry->getComponent<TransformComponent>(entity);
+        
+        if (isInView(*transform, camera)) {
+            // Render only visible entities
+            renderEntity(entity);
+        }
+    }
+}
+```
+
+## Directory Structure
+
+```
+client/
+├── main.cpp                  # Entry point
+├── Core.cpp/hpp              # Main game loop
+├── ClientNetwork.cpp/hpp     # Network communication
+├── Utils.cpp/hpp             # CLI parsing
+├── constants.hpp             # Client constants
+│
+├── components/               # Client-specific components
+│   ├── SpriteComponent.hpp
+│   ├── AnimationComponent.hpp
+│   └── CameraComponent.hpp
+│
+├── gsm/                      # Game State Machine
+│   ├── GameStateMachine.cpp
+│   └── states/
+│       ├── MenuState.cpp
+│       ├── LobbyState.cpp
+│       ├── InGameState.cpp
+│       └── PauseState.cpp
+│
+├── systems/                  # Client systems
+│   ├── rendering/
+│   │   ├── RenderSystem.cpp
+│   │   ├── ParallaxSystem.cpp
+│   │   └── AnimationSystem.cpp
+│   ├── audio/
+│   │   ├── MusicSystem.cpp
+│   │   └── SoundSystem.cpp
+│   └── input/
+│       └── InputSystem.cpp
+│
+├── ui/                       # User interface
+│   ├── UIManager.cpp
+│   ├── Widget.cpp
+│   └── widgets/
+│       ├── Button.cpp
+│       ├── TextBox.cpp
+│       └── Slider.cpp
+│
+├── initResourcesManager/     # Resource management
+│   └── ResourceManager.cpp
+│
+└── packet/                   # Packet handling
+    ├── ClientSentPacket.cpp
+    └── ClientReceivedPacket.cpp
+```
+
+## See Also
+
+- [Client User Guide](./user-guide.md)
+- [Server Architecture](../SERVER/server-intro.md)
+- [Network Protocol](../NETWORK/network-intro.md)
+- [ECS Documentation](../ECS/ecs-intro.md)
diff --git a/documentation/docusaurus/docs/CLIENT/client-intro.md b/documentation/docusaurus/docs/CLIENT/client-intro.md
index 4856cbb80..42c37a3c8 100644
--- a/documentation/docusaurus/docs/CLIENT/client-intro.md
+++ b/documentation/docusaurus/docs/CLIENT/client-intro.md
@@ -4,29 +4,529 @@ sidebar_position: 1
 
 # R-Type — Client Overview
 
-This page gives a short, practical introduction to the R‑Type client component: what it contains, how to build and run it for development, and where to look for common features (input, rendering, audio, UI).
+This page provides a comprehensive introduction to the R‑Type client component: what it contains, how to build and run it for development, and where to look for common features (input, rendering, audio, UI).
 
 ## Purpose
 
-The client implements the graphical and audio front-end for the game: rendering, input handling, local state interpolation, UI, and audio playback. It connects to the server for multiplayer state and uses the project's common libraries for ECS, resource management and packets.
+The client implements the graphical and audio front-end for the game:
+- **Rendering**: Visual display using SFML
+- **Input handling**: Keyboard, mouse, and gamepad support
+- **Local state interpolation**: Smooth gameplay despite network latency
+- **UI management**: Menus, HUD, and widgets
+- **Audio playback**: Music and sound effects
 
-## Important client folders and files
+It connects to the server for multiplayer state synchronization and uses the project's common libraries for ECS, resource management, and network packets.
 
-- `client/` — main client source tree
-	- `main.cpp`, `Core.cpp/.hpp` — application entry and lifecycle
-	- `initResourcesManager/GraphicalInputProvider.cpp` — keyboard/mouse/gamepad initialization
-	- `systems/` — client-side ECS systems (rendering, audio, input handling)
-	- `components/` — rendering components (sprites, animations, text, health bars)
-	- `ui/` — UI elements, navigation and managers
+## Quick Links
 
-- `assets/` — shared assets used by the client (shaders, sprites, sounds, fonts)
-	- `assets/shaders/` — color-blind and high-contrast shaders (e.g. `deuteranopia.frag`)
+- **[User Guide](./user-guide.md)**: How to play the game
+- **[Client Architecture](./client-architecture.md)**: Technical implementation details
+- **[Installation](../INTRO/installation.md)**: Setup instructions
 
-- `saves/` — persisted settings and user data (including `accessibility.json`, `keybinds.json`)
+## Key Features
 
-## Key features and where to find them
+### Graphics
+- **SFML-based rendering**: Hardware-accelerated 2D graphics
+- **Sprite animations**: Frame-based animation system
+- **Parallax backgrounds**: Multi-layer scrolling backgrounds
+- **Particle effects**: Explosions and visual effects
+- **Layer management**: Z-ordering for proper rendering
 
-- Input remapping and mapping structures: `common/InputMapping/` (`InputMapping.hpp`, `InputMappingManager.hpp`, `InputAction.hpp`).
-- Rendering systems: `client/systems/rendering/` (game zone, parallax, hitboxes, animations).
-- Audio: `client/systems/audio/MusicSystem.cpp`, `SoundSystem.cpp`.
-- Network/packets: `client/packet/` and `common/packet/` for serialization and default handlers.
+### Input
+- **Multiple input devices**: Keyboard, mouse, gamepad
+- **Remappable controls**: Full key/button remapping
+- **Input mapping system**: Action-based input abstraction
+- **Gamepad support**: Xbox, PlayStation, and generic controllers
+
+### Audio
+- **Background music**: OGG Vorbis streaming
+- **Sound effects**: WAV format with pooling
+- **Positional audio**: 3D sound positioning
+- **Volume controls**: Separate music/SFX volume
+
+### Networking
+- **UDP communication**: Low-latency multiplayer
+- **Client prediction**: Local movement prediction
+- **Entity interpolation**: Smooth remote entity movement
+- **Packet handling**: Custom binary protocol
+
+### Accessibility
+- **Color-blind modes**: Deuteranopia, Protanopia, Tritanopia shaders
+- **High contrast mode**: Enhanced visibility
+- **UI scaling**: Adjustable interface size
+- **Alternative indicators**: Numeric health, audio cues
+
+## Important Client Folders and Files
+
+### Core Files
+
+```
+client/
+├── main.cpp                    # Application entry point
+├── Core.cpp / Core.hpp         # Main game loop and lifecycle
+├── ClientNetwork.cpp/hpp       # Network communication
+├── Utils.cpp/hpp               # CLI argument parsing
+├── constants.hpp               # Client-side constants
+└── SettingsManager.cpp/hpp     # Persistent settings
+```
+
+### Game State Management
+
+```
+client/gsm/
+├── GameStateMachine.cpp        # State management
+└── states/
+    ├── MenuState.cpp           # Main menu
+    ├── LobbyState.cpp          # Lobby creation/joining
+    ├── InGameState.cpp         # Active gameplay
+    └── PauseState.cpp          # Pause overlay
+```
+
+### Systems
+
+```
+client/systems/
+├── rendering/
+│   ├── RenderSystem.cpp        # Main rendering
+│   ├── ParallaxSystem.cpp      # Background scrolling
+│   └── AnimationSystem.cpp     # Sprite animations
+├── audio/
+│   ├── MusicSystem.cpp         # Background music
+│   └── SoundSystem.cpp         # Sound effects
+└── input/
+    └── InputSystem.cpp         # Input processing
+```
+
+### Components
+
+```
+client/components/
+├── SpriteComponent.hpp         # Visual representation
+├── AnimationComponent.hpp      # Animation data
+├── CameraComponent.hpp         # Viewport control
+└── UIComponent.hpp             # UI elements
+```
+
+### UI System
+
+```
+client/ui/
+├── UIManager.cpp               # UI management
+├── Widget.cpp                  # Base widget class
+└── widgets/
+    ├── Button.cpp              # Clickable buttons
+    ├── TextBox.cpp             # Text input/display
+    ├── Slider.cpp              # Value sliders
+    └── Label.cpp               # Text labels
+```
+
+### Resource Management
+
+```
+client/initResourcesManager/
+└── GraphicalInputProvider.cpp  # Resource initialization
+```
+
+### Network
+
+```
+client/packet/
+├── ClientSentPacket.cpp        # Outgoing packets
+└── ClientReceivedPacket.cpp    # Incoming packet handling
+```
+
+## Shared Resources
+
+### Assets
+
+```
+assets/
+├── fonts/                      # TrueType fonts for UI
+├── musics/                     # Background music (OGG)
+├── shaders/                    # GLSL shaders
+│   ├── deuteranopia.frag       # Color-blind shader
+│   ├── protanopia.frag
+│   └── tritanopia.frag
+├── sounds/                     # Sound effects (WAV)
+├── sprites/                    # Game sprites (PNG)
+└── ui/                         # UI textures
+```
+
+### Configuration
+
+```
+saves/
+├── settings.json               # Graphics, audio, network settings
+├── keybinds.json              # Custom key mappings
+├── accessibility.json          # Accessibility options
+├── scores.json                # High scores
+└── users.json                 # Player profiles
+```
+
+### Common Libraries
+
+```
+common/
+├── ECS/                       # Entity-Component-System
+├── components/                # Shared game components
+├── systems/                   # Shared game systems
+├── packet/                    # Network packet definitions
+└── InputMapping/              # Input abstraction
+    ├── InputMapping.hpp
+    ├── InputMappingManager.hpp
+    └── InputAction.hpp
+```
+
+## Building the Client
+
+### Prerequisites
+
+- **C++ Compiler**: GCC 11+, Clang 12+, or MSVC 2019+
+- **CMake**: 3.23+
+- **vcpkg**: For dependency management
+- **SFML**: 2.6+ (auto-installed via vcpkg)
+
+### Compilation
+
+**Unix (Linux/macOS):**
+```bash
+./scripts/install_dependencies.sh
+./scripts/compile_project.sh
+
+# Client binary
+./r-type_client
+```
+
+**Windows:**
+```cmd
+.\scripts\install_dependencies.bat
+.\scripts\compile_project.bat
+
+REM Client binary
+.\r-type_client.exe
+```
+
+### CMake Configuration
+
+```bash
+# Configure
+cmake --preset unix-release
+
+# Build
+cmake --build build/unix-release --target r-type_client
+
+# Run
+./build/unix-release/r-type_client
+```
+
+## Running the Client
+
+### Basic Usage
+
+```bash
+# Connect to localhost with default name
+./r-type_client
+
+# Specify server and player name
+./r-type_client -i 192.168.1.100 -p 4242 -n Alice
+
+# Enable debug logging
+./r-type_client -d
+```
+
+### Command-Line Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `-i <ip>` | Server IP address | 127.0.0.1 |
+| `-p <port>` | Server port | 4242 |
+| `-n <name>` | Player name | Auto-generated |
+| `-d` | Enable debug mode | Disabled |
+| `-h` | Display help | - |
+
+## Key Features and Where to Find Them
+
+### Input Remapping
+
+**Location:** `common/InputMapping/`
+
+**Files:**
+- `InputMapping.hpp`: Individual key-action binding
+- `InputMappingManager.hpp`: Manages all bindings
+- `InputAction.hpp`: Action definitions
+
+**Usage:**
+```cpp
+// Define actions
+enum class InputAction {
+    MoveUp, MoveDown, MoveLeft, MoveRight,
+    Shoot, Special, Pause
+};
+
+// Load mappings
+InputMappingManager mappings;
+mappings.load("saves/keybinds.json");
+
+// Check input
+if (mappings.isActionPressed(InputAction::Shoot)) {
+    // Fire weapon
+}
+```
+
+### Rendering Systems
+
+**Location:** `client/systems/rendering/`
+
+**Files:**
+- `RenderSystem.cpp`: Main sprite rendering
+- `ParallaxSystem.cpp`: Multi-layer backgrounds
+- `AnimationSystem.cpp`: Frame-based animations
+- `HitboxRenderSystem.cpp`: Debug collision visualization
+
+**Rendering Order:**
+1. Parallax background (far → near)
+2. Game entities (sorted by layer)
+3. Particle effects
+4. UI / HUD
+5. Debug overlays (if enabled)
+
+### Audio Systems
+
+**Location:** `client/systems/audio/`
+
+**Files:**
+- `MusicSystem.cpp`: Background music management
+- `SoundSystem.cpp`: Sound effect playback
+
+**Features:**
+- Music streaming (OGG Vorbis)
+- Sound pooling for effects
+- Positional 3D audio
+- Volume mixing (master, music, SFX)
+
+### Network Packet Handling
+
+**Location:** `client/packet/` and `common/packet/`
+
+**Client Sent Packets:**
+- `CONNECTION_CLIENT`: Initial connection request
+- `EVENT`: Player input events
+- `CLIENT_READY`: Ready status
+- `REQUEST_LOBBY`: Create lobby
+- `CONNECT_TO_LOBBY`: Join lobby
+- `DISCONNECTION`: Clean disconnect
+
+**Client Received Packets:**
+- `ACCEPTATION`: Connection accepted with client ID
+- `SPAWN_ENTITY`: New entity in game
+- `DEATH_ENTITY`: Entity destruction
+- `CAN_START`: Game start signal
+- `END_GAME`: Game over with results
+- `SERVER_STATUS`: Lobby information
+- `LOBBY_CODE`: Lobby code assignment
+
+### UI Components
+
+**Location:** `client/ui/`
+
+**Widget Hierarchy:**
+```
+Widget (base class)
+├── Button
+├── TextBox
+├── Slider
+├── Label
+├── Image
+└── Container
+    ├── Panel
+    └── ScrollPanel
+```
+
+**Example Usage:**
+```cpp
+// Create a button
+auto button = std::make_shared<Button>();
+button->setText("Start Game");
+button->setPosition(100, 200);
+button->setOnClick([]() {
+    // Start game logic
+});
+
+uiManager->addWidget(button);
+```
+
+## Client Architecture Patterns
+
+### Game State Machine
+
+States manage different screens:
+- **MenuState**: Main menu, navigation
+- **LobbyState**: Multiplayer lobby
+- **InGameState**: Active gameplay
+- **PauseState**: Pause overlay
+
+**State Lifecycle:**
+```cpp
+enter()  → update() → render() → exit()
+   ↓         ↓          ↓         ↓
+ Setup    Game Loop   Draw    Cleanup
+```
+
+### Client Prediction
+
+To compensate for network latency:
+
+1. **Predict**: Apply input immediately on client
+2. **Send**: Transmit input to server
+3. **Receive**: Get authoritative state from server
+4. **Reconcile**: Correct if prediction was wrong
+
+```cpp
+// Prediction
+localPlayer.x += input.dx;
+
+// Reconciliation
+if (abs(localPlayer.x - serverState.x) > threshold) {
+    localPlayer.x = serverState.x;  // Correct
+}
+```
+
+### Entity Interpolation
+
+Remote entities are interpolated between server updates for smooth movement:
+
+```cpp
+// Interpolate from previous to current server state
+entity.x = lerp(prevState.x, currentState.x, alpha);
+```
+
+## Performance Considerations
+
+### Frame Rate
+
+- **Target**: 60 FPS
+- **VSync**: Optional (can be toggled)
+- **Frame limiting**: Configurable in settings
+
+### Memory Management
+
+- **Resource caching**: Textures/sounds loaded once
+- **Entity pooling**: Reuse bullet/effect entities
+- **Component cleanup**: Automatic via shared_ptr
+
+### Network Optimization
+
+- **Packet batching**: Multiple inputs per packet
+- **Delta compression**: Only send changes
+- **Client prediction**: Reduce perceived latency
+
+## Development Workflow
+
+### Adding a New System
+
+1. Create system class inheriting from `ASystem`
+2. Implement `update(float deltaTime)` method
+3. Register system in game state
+4. Add to update loop
+
+```cpp
+class MySystem : public ASystem {
+public:
+    void update(float deltaTime) override {
+        auto view = registry->view<MyComponent>();
+        for (Entity e : view) {
+            // Process entities
+        }
+    }
+};
+
+// In InGameState
+systems.push_back(std::make_shared<MySystem>());
+```
+
+### Adding a New UI Widget
+
+1. Inherit from `Widget` base class
+2. Implement render and event handling
+3. Add to `UIManager`
+
+```cpp
+class MyWidget : public Widget {
+public:
+    void render(sf::RenderWindow& window) override {
+        // Draw widget
+    }
+    
+    void handleEvent(const sf::Event& event) override {
+        // Process input
+    }
+};
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Build with tests
+cmake --preset unix-release -DBUILD_TESTS=ON
+cmake --build build/unix-release
+
+# Run tests
+ctest --test-dir build/unix-release
+```
+
+### Debug Tools
+
+**Debug Overlay (F3):**
+- FPS counter
+- Entity count
+- Network ping
+- Memory usage
+
+**Debug Rendering:**
+- Collision hitboxes
+- Entity IDs
+- Velocity vectors
+
+## Common Issues
+
+### Graphics Not Displaying
+
+- Verify SFML is properly installed
+- Check assets folder exists
+- Update graphics drivers
+- Run from project root directory
+
+### Audio Not Working
+
+- Verify audio files exist
+- Check system volume
+- Update audio drivers
+- Test with different audio backend
+
+### Input Not Responding
+
+- Check keybindings in `saves/keybinds.json`
+- Verify input device is connected
+- Test with different input device
+- Reset keybinds to default
+
+### Network Connection Failed
+
+- Verify server is running
+- Check firewall settings
+- Use correct IP and port
+- Test with localhost first
+
+## Additional Resources
+
+- **[User Guide](./user-guide.md)**: Complete gameplay guide
+- **[Client Architecture](./client-architecture.md)**: Detailed technical documentation
+- **[Troubleshooting](../INTRO/troubleshooting.md)**: Common problems and solutions
+- **[Network Protocol](../NETWORK/network-intro.md)**: Protocol specification
+- **[ECS Documentation](../ECS/ecs-intro.md)**: Entity-Component-System details
+
+---
+
+The client provides a rich, responsive gaming experience with support for various input devices, accessibility features, and smooth multiplayer gameplay.
diff --git a/documentation/docusaurus/docs/CLIENT/user-guide.md b/documentation/docusaurus/docs/CLIENT/user-guide.md
new file mode 100644
index 000000000..caf1cad79
--- /dev/null
+++ b/documentation/docusaurus/docs/CLIENT/user-guide.md
@@ -0,0 +1,496 @@
+---
+sidebar_position: 2
+---
+
+# Client User Guide
+
+Complete guide for playing and using the R-Type game client.
+
+## Installation
+
+See the [Installation Guide](../INTRO/installation.md) for detailed setup instructions.
+
+**Quick Start:**
+```bash
+# Download and run
+./r-type_client -n YourName
+```
+
+## Main Menu
+
+When you launch the client, you'll see the main menu with several options:
+
+### Menu Options
+
+1. **Play**: Start or join a game
+2. **Settings**: Configure game options
+3. **Credits**: View development team
+4. **Quit**: Exit the game
+
+## Playing the Game
+
+### Creating a Lobby
+
+1. Click **"Play"** from the main menu
+2. Select **"Create Lobby"**
+3. Share the generated 8-character lobby code with friends
+4. Wait for players to join (up to 4 players)
+5. Click **"Start Game"** when ready
+
+**As Lobby Master:**
+- You control when the game starts
+- First player to create the lobby is the master
+- Can kick players (if implemented)
+
+### Joining a Lobby
+
+1. Click **"Play"** from the main menu
+2. Select **"Join Lobby"**
+3. Enter the 8-character lobby code
+4. Wait for the lobby master to start
+
+**Tips:**
+- Lobby codes are case-insensitive
+- Codes contain only letters and numbers (no 0, O, I, L to avoid confusion)
+- Codes expire after game completion
+
+## Controls
+
+### Default Keyboard Controls
+
+| Action | Key |
+|--------|-----|
+| Move Up | `W` or `↑` |
+| Move Down | `S` or `↓` |
+| Move Left | `A` or `←` |
+| Move Right | `D` or `→` |
+| Shoot | `Space` |
+| Special Attack | `Shift` |
+| Pause | `Escape` or `P` |
+
+### Gamepad Controls
+
+| Action | Button |
+|--------|--------|
+| Move | Left Stick or D-Pad |
+| Shoot | A / Cross |
+| Special Attack | B / Circle |
+| Pause | Start |
+
+**Gamepad Support:**
+- Xbox controllers
+- PlayStation controllers
+- Generic USB gamepads
+
+### Remapping Controls
+
+1. Go to **Settings** → **Controls**
+2. Click on the action you want to remap
+3. Press the new key/button
+4. Changes are saved automatically
+
+**Keybind File:** `saves/keybinds.json`
+
+## Gameplay
+
+### Objective
+
+### Health System
+
+- **Health Bar**: Displayed at the top of the screen
+- **Lives**: Start with 3 lives (configurable)
+- **Respawn**: Lose a life when health reaches zero
+- **Game Over**: When all lives are lost
+
+### Power-Ups
+
+Power-ups are placed in levels (see `configs/entities/powerUp/`) and trigger server-side scripts on pickup. Common pickups:
+
+- `force` (Force Pod): attaches to the player as a companion. Levels 1–4 change the player's projectile prefab and, at higher levels, the fire rate and special projectiles (level2 → `magnet`, level3 → `bombShot`, level4 → `beamShoot` and fire rate 0.3). Interaction functions: `OnInteract`, `ActivateOrDeactivateForce`, `addForceLevel`. Only one `force` of type `force` may be equipped per player.
+- `flyingForce`: small companion shooter that follows the player. Up to 2 can be equipped. Provides continuous fire using `basic_shot` (configured by `ShootingStatsComponent` in the prefab).
+- `powerUpAddForceLevel`: consumes itself to call `addForceLevel` on the player (increments force level, caps at 4).
+- `powerUpAddLife`: grants an extra life via the `AddLife` interaction mapping.
+- `powerUpSpeed`: instantly increases player speed by +200 (see `powerUpSpeed.lua`).
+- `powerUpChargeTime`: reduces the player's charge/reload time by 10% (min 0.1s) when picked up.
+
+Notes:
+- Power-up definitions and visuals are in `configs/entities/powerUp/*.json` and associated scripts in `configs/scripts/`.
+- Pickup behavior (instant consume vs attach) is implemented server-side via the `ScriptingComponent`.
+
+### Force Pod (details)
+
+The Force Pod family (`force`, `flyingForce`) behaves as follows:
+- `force`: attachable companion. When attached it follows the player and modifies shooting behavior according to its `level`. Can be activated/deactivated (see in-game control). Script: `configs/scripts/force.lua`.
+- `flyingForce`: autonomous companion shooter. Automatically positions relative to the player and fires using its `ProjectilePrefabComponent`. Script: `configs/scripts/flyingForce.lua`.
+
+Controls:
+- Auto-follow by default.
+- Hold `Shift` to lock position (if supported by UI).
+
+### Scoring
+
+Points are awarded for:
+- Destroying enemies: 100-1000 points
+- Boss defeat: 10,000+ points
+- Power-up collection: 500 points
+- Combo multiplier: Up to 4x
+
+**High Scores:**
+- Saved locally in `saves/scores.json`
+- Displayed on main menu
+- Track personal bests
+
+## Multiplayer
+
+### Cooperative Play
+
+- **Up to 4 players** per game
+- Shared score pool
+- Respawn at checkpoints
+- Friendly fire: OFF (configurable)
+
+### Communication
+
+- **Text chat**: Press `T` to open chat
+- **Quick messages**: Press `F1-F4` for preset messages
+  - F1: "Help!"
+  - F2: "Follow me"
+  - F3: "Nice!"
+  - F4: "Sorry"
+
+### Connection Quality
+
+Indicator in top-right corner:
+- 🟢 **Green**: Good (&lt;50ms)
+- 🟡 **Yellow**: Fair (50-100ms)
+- 🔴 **Red**: Poor (&gt;100ms)
+- ⚫ **Gray**: Disconnected
+
+**Network Issues:**
+- Client uses prediction to smooth gameplay
+- May see rubber-banding with high ping
+- Server is authoritative (prevents cheating)
+
+## Settings
+
+### Graphics
+
+- **Resolution**: Window size selection
+- **Fullscreen**: Toggle fullscreen mode
+- **VSync**: Vertical synchronization
+- **FPS Limit**: Cap frame rate (30, 60, 120, unlimited)
+
+### Audio
+
+- **Master Volume**: Overall volume (0-100%)
+- **Music Volume**: Background music
+- **SFX Volume**: Sound effects
+- **Mute**: Quick mute toggle
+
+### Accessibility
+
+See [Accessibility Features](#accessibility-features) for detailed options.
+
+- **Color Blind Modes**
+- **High Contrast Mode**
+- **UI Scaling**
+- **Alternative Damage Indicators**
+
+### Network
+
+- **Server IP**: Default connection address
+- **Server Port**: Default connection port
+- **Auto-reconnect**: Attempt to reconnect on disconnect
+- **Interpolation**: Client-side prediction amount
+
+## Accessibility Features
+
+R-Type includes comprehensive accessibility options.
+
+### Color Blind Modes
+
+**Available Modes:**
+- Normal (Default)
+- Deuteranopia (Red-Green)
+- Protanopia (Red-Green)
+- Tritanopia (Blue-Yellow)
+
+**How to Enable:**
+1. Settings → Accessibility
+2. Select color blind mode
+3. Shader applied in real-time
+
+### High Contrast Mode
+
+Increases visibility of game elements:
+- Brighter sprites
+- Enhanced outlines
+- Clearer UI elements
+
+### UI Scaling
+
+Adjust interface size:
+- **Small**: 80% scale
+- **Normal**: 100% scale (default)
+- **Large**: 125% scale
+- **Extra Large**: 150% scale
+
+### Alternative Health Indicators
+
+- **Numeric**: Show exact HP numbers
+- **Audio Cues**: Low health warning sound
+- **Screen Flash**: Health loss indicator
+
+### Configurable Controls
+
+- Full key remapping
+- Mouse support for menu navigation
+- Gamepad with customizable dead zones
+
+### Configuration File
+
+Settings saved in: `saves/accessibility.json`
+
+```json
+{
+  "colorBlindMode": "deuteranopia",
+  "highContrast": true,
+  "uiScale": 1.25,
+  "showNumericHealth": true,
+  "audioHealthWarning": true
+}
+```
+
+## Pause Menu
+
+Press `Escape` or `P` during gameplay:
+
+- **Resume**: Continue playing
+- **Settings**: Adjust options mid-game
+- **Controls**: View control scheme
+- **Quit to Menu**: Return to main menu
+- **Quit Game**: Exit application
+
+**Note:** In multiplayer, game continues while you're paused.
+
+## Performance Optimization
+
+### Low FPS Issues
+
+If experiencing low frame rate:
+
+1. **Lower Resolution**: Settings → Graphics → Resolution
+2. **Disable VSync**: May improve responsiveness
+3. **Close Background Apps**: Free up system resources
+4. **Update Drivers**: Ensure graphics drivers are current
+
+### High Ping
+
+To reduce network latency:
+
+1. Use wired Ethernet connection
+2. Close bandwidth-heavy applications
+3. Connect to geographically closer servers
+4. Check firewall isn't blocking UDP port
+
+### System Monitor
+
+Press `F3` to toggle debug overlay (if enabled):
+- FPS counter
+- Ping to server
+- Entity count
+- Memory usage
+
+## Troubleshooting
+
+### Game Won't Start
+
+```bash
+# Check log files
+cat logs/client.log
+
+# Verify OpenGL support
+glxinfo | grep "OpenGL version"  # Linux
+
+# Run with debug flag
+./r-type_client -d
+```
+
+### Cannot Connect to Server
+
+1. Verify server is running
+2. Check IP and port are correct
+3. Disable firewall temporarily
+4. Try localhost: `./r-type_client -i 127.0.0.1`
+
+### Graphics Issues
+
+- **Black screen**: Update graphics drivers
+- **Missing textures**: Verify assets folder exists
+- **Flickering**: Try disabling VSync
+
+### Audio Issues
+
+- **No sound**: Check system volume and game settings
+- **Crackling**: Update audio drivers
+- **Desync**: Restart the client
+
+### Lobby Issues
+
+- **Invalid lobby code**: Codes are case-sensitive, check for typos
+- **Lobby full**: Maximum 4 players per lobby
+- **Cannot create lobby**: Server may be at capacity
+
+For more help, see [Troubleshooting Guide](../INTRO/troubleshooting.md).
+
+## Advanced Features
+
+### Replay System
+
+Games are automatically recorded:
+
+**Location:** `saves/replays/`
+
+**Playing Replays:**
+1. Main Menu → Replays
+2. Select a saved replay
+3. Use controls to pause/rewind
+
+**Replay Controls:**
+- `Space`: Pause/Resume
+- `←/→`: Rewind/Fast-forward
+- `Escape`: Exit replay
+
+### Statistics
+
+View your game statistics:
+- Total games played
+- Win/loss ratio
+- Highest score
+- Total enemies defeated
+- Total playtime
+
+**Access:** Main Menu → Statistics
+
+### Profiles
+
+Create multiple player profiles:
+- Separate settings per profile
+- Individual high scores
+- Custom keybindings
+
+**Manage:** Main Menu → Profiles
+
+## Tips & Strategies
+
+### Beginner Tips
+
+1. **Stay Mobile**: Constant movement helps avoid enemy fire
+2. **Power-Up Priority**: Focus on weapon upgrades early
+3. **Force Pod Usage**: Position it to cover your weak spots
+4. **Boss Patterns**: Learn and memorize attack patterns
+5. **Multiplayer**: Communicate with team for better coordination
+
+### Advanced Strategies
+
+1. **Grazing**: Stay close to bullets for bonus points (if enabled)
+2. **Combo System**: Chain kills without taking damage
+3. **Resource Management**: Save special attacks for bosses
+4. **Position Optimization**: Learn safe spots on each stage
+5. **Force Pod Tech**: Advanced positioning techniques
+
+### Enemy Types (examples)
+
+Below are common enemy prefabs used in levels (see `configs/entities/enemies/`):
+
+- **Bat**
+  - Health: 50
+  - Damage (contact): 25
+  - Behavior: vertical follow; shoots bursts (3 shots, spread ~10°) using `bat_basic_shot`.
+  - Score: ~100
+  - Strategy: avoid melee contact, strafe to dodge spread shots, prioritize when near player.
+
+- **Canon**
+  - Health: 50
+  - Behavior: stationary or border-following turret; fires single powerful projectiles (fireRate 0.6, projectileSpeed 700).
+  - Score: ~150
+  - Strategy: use cover and timing to dodge attack animation; destroy quickly before sustained fire.
+
+- **Snake Head** (`snake_head`)
+  - Health: 200
+  - Behavior: spawns and controls snake segments; scripted coordinated movement (`snake_behavior.lua`).
+  - Score: ~500
+  - Strategy: target the head to disable spawn control, avoid being trapped by segments.
+
+- **Basic Enemy**
+  - Generic prefab used for simple waves. Health, damage and behavior vary by prefab configuration.
+
+### Bosses
+
+Boss encounters are scripted and multi-phase. Two example bosses (configs in `configs/entities/boss/`):
+
+- **Boss 1** (`boss1`) — Hilda-Berg style blimp
+  - Health: 2000
+  - Behavior: multi-mode fight (figure-eight movement, normal shooting mode, charge/ram mode). Periodically summons smaller enemies and uses different animation states for attacks. See `configs/scripts/boss1.lua` for phase/mode logic.
+  - Strategy: learn pattern cycles — avoid charge windows, focus fire after telegraphed animations, exploit summon downtime.
+
+- **Boss 2** (`boss2`) — Multi-part body + head
+  - Health: composite (body + head parts). The body spawns a controllable head part that executes attack patterns (`boss2.lua` + `boss2head.lua`).
+  - Strategy: prioritize head/parts as appropriate; destroying parts often reduces attack capability.
+
+Notes:
+- Exact values (health, damage, projectile stats) live in the prefab JSON files and their scripts: `configs/entities/enemies/*.json` and `configs/scripts/*.lua`.
+- Use the Level Editor (`LevelEditor` UI) to inspect prefab fields (`PowerUps`, `Waves`) and preview enemy spawn behavior.
+
+## FAQ
+
+**Q: Can I play offline?**
+A: No, R-Type requires a server connection. You can run a local server.
+
+**Q: How many players can join?**
+A: Up to 4 players per lobby.
+
+**Q: Are saves shared between devices?**
+A: No, saves are local to each installation.
+
+**Q: Can I mod the game?**
+A: Not officially supported, but asset files are accessible.
+
+**Q: Is there controller vibration?**
+A: Currently not implemented.
+
+**Q: What platforms are supported?**
+A: Windows 10+, Linux (Ubuntu 20.04+), macOS 11+
+
+## Keyboard Shortcuts Reference
+
+| Key | Action |
+|-----|--------|
+| `F1-F4` | Quick chat messages |
+| `F3` | Toggle debug info |
+| `F11` | Toggle fullscreen |
+| `T` | Open text chat |
+| `P` | Pause |
+| `Escape` | Pause menu / Back |
+| `Enter` | Confirm |
+| `Tab` | Scoreboard |
+
+## Credits & Support
+
+### Development Team
+
+See in-game credits for full team list.
+
+### Support
+
+- **Documentation**: https://albanrss.github.io/doc-rtype/
+- **GitHub Issues**: Report bugs and request features
+- **Community**: Join discussions on GitHub
+
+### Version
+
+Check current version: Main Menu → About
+
+---
+
+Enjoy playing R-Type! 🚀
diff --git a/documentation/docusaurus/docs/DEVELOPERS/creating-maps-mobs-projectiles.md b/documentation/docusaurus/docs/DEVELOPERS/creating-maps-mobs-projectiles.md
new file mode 100644
index 000000000..4b3cf79fb
--- /dev/null
+++ b/documentation/docusaurus/docs/DEVELOPERS/creating-maps-mobs-projectiles.md
@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+---
+
+# Creating Maps, Mobs and Projectiles via JSON Configs
+
+This guide explains how to add/modify maps, enemies (mobs) and projectiles using JSON files in the `configs/` folder.
+
+## Main Locations
+- Entity prefabs (mobs, bosses, power-ups): `configs/entities/enemies/`, `configs/entities/boss/`, `configs/entities/powerUp/`
+- Projectiles / projectile prefabs: often defined in `configs/entities/projectiles/` or included in the entity prefab via `ProjectilePrefabComponent`
+- Scripts (behavior): `configs/scripts/` (Lua files)
+- Maps / waves: `configs/map/` (e.g. `level1.json`)
+
+## General Principles
+- Entities are defined by JSON files that list components (HealthComponent, DamageComponent, ScriptingComponent, ShootingStatsComponent, ProjectilePrefabComponent, etc.).
+- Dynamic behavior is implemented in Lua (in `configs/scripts/`). Common hooks are: `init`, `update`, `death`, `OnInteract`, `ActivateOrDeactivateForce`, `addForceLevel`.
+- Maps reference prefabs by name in the `waves` (for enemies) and `powerUps` arrays.
+
+## Steps to Add a New Enemy (Mob)
+1. Create a JSON file in `configs/entities/enemies/` (e.g. `my_mob.json`).
+2. Declare the necessary components:
+
+```json
+{
+  "name": "my_mob",
+  "components": {
+    "HealthComponent": { "hp": 120 },
+    "DamageComponent": { "damage": 20 },
+    "ScoreComponent": { "score": 250 },
+    "ScriptingComponent": { "scriptPath": "configs/scripts/my_mob.lua" },
+    "ShootingStatsComponent": { "fireRate": 0.5, "shotCount": 1, "spread": 0 },
+    "ProjectilePrefabComponent": { "prefab": "basic_bullet" }
+  }
+}
+```
+
+3. (Optional) Add the behavioral script `configs/scripts/my_mob.lua` and expose the `init`/`update`/`death` functions as needed. The engine calls these functions via the `ScriptingComponent`.
+
+4. Add an entry in the map to spawn the enemy:
+
+```json
+{
+  "waves": [
+    {
+      "spawn_time": 8.0,
+      "prefab": "my_mob",
+      "position": { "x": 900, "y": 200 }
+    }
+  ]
+}
+```
+
+## Steps to Add a Projectile
+1. Create a projectile prefab (if your project uses a dedicated folder): `configs/entities/projectiles/basic_bullet.json`.
+2. Minimal projectile example:
+
+```json
+{
+  "name": "basic_bullet",
+  "components": {
+    "DamageComponent": { "damage": 10 },
+    "ProjectileComponent": { "speed": 700, "direction": { "x": -1, "y": 0 } },
+    "ColliderComponent": { "radius": 6 }
+  }
+}
+```
+
+3. Reference this prefab from an enemy via `ProjectilePrefabComponent` or dynamically create the projectile in the Lua script with the `createShootIntent` / `createMoveIntent` API.
+
+## Best Practices
+- Name your prefabs clearly (`enemy_snake_head`, `boss_blaster`, `powerup_force_level`).
+- Separate data (JSON) from logic (Lua). JSONs describe static components, scripts handle temporal behaviors and phase transitions.
+- Test incrementally: add the entity to a debug map (early spawn) to verify collisions / shots / animations.
+- Respect existing constants and hooks: see `common/constants.hpp` for expected scripting function names (e.g. `ONINTERACT_FUNCTION`, `INIT_FUNCTION`).
+
+## Useful Tools
+- Visualize a level by opening `configs/map/level1.json` and searching for `powerUps` / `waves` for concrete examples.
+- Consult existing scripts (`configs/scripts/force.lua`, `boss1.lua`, `flyingForce.lua`) for reusable patterns.
+
+## Quick Troubleshooting
+- If an entity doesn't spawn: check the `prefab` name in the map, validate the JSON (format) and look at server logs (`[SERVER]` messages).
+- If a Lua script doesn't execute: verify the `scriptPath` in the `ScriptingComponent` and that the script implements expected hooks.
+
+## Final Notes
+- This guide covers the basic flow. For advanced behaviors (composite bosses, segments, attached forces), study existing scripts in `configs/scripts/` which show complete examples of scripting API and `ResourceManager` interaction.
+
+Reference files: `configs/entities/enemies/*`, `configs/entities/boss/*`, `configs/entities/powerUp/*`, `configs/entities/projectiles/*`, `configs/scripts/*`, `configs/map/*`.
+
diff --git a/documentation/docusaurus/docs/ECS/api.md b/documentation/docusaurus/docs/ECS/api.md
index ab258c8dc..991d12a86 100644
--- a/documentation/docusaurus/docs/ECS/api.md
+++ b/documentation/docusaurus/docs/ECS/api.md
@@ -4,24 +4,699 @@ sidebar_position: 2
 
 # ECS API Reference
 
-This page documents common operations for the project's Entity-Component-System (ECS).
+Complete API documentation for the R-Type Entity-Component-System framework.
 
-## Core operations
-- `createEntity()` → returns `EntityId`
-- `destroyEntity(EntityId)`
-- `addComponent<Entity, ComponentType>(entity, component)`
-- `removeComponent<ComponentType>(entity)`
-- `getComponent<ComponentType>(entity)` → optional / pointer
+## Registry Class
 
-## Queries and Systems
-- `view<Components...>()` returns iterable of entities matching all `Components`.
-- Systems should operate on `views` and avoid mutating entity lists while iterating; use command buffers to enqueue create/destroy operations.
+The `Registry` is the central manager for all entities and components.
 
-## Network sync components
-- Components used for network sync must include a `dirty` flag and a small `version` integer to allow delta encoding and reconciliation.
+### Entity Management
 
-## Threading & Safety
-- ECS reads can run in parallel for disjoint component sets. Writes must be serialized or use job/command-buffer patterns.
+#### `createEntity()`
+Creates a new entity and returns its unique identifier.
+
+```cpp
+Entity entity = registry->createEntity();
+```
+
+**Returns:** `Entity` (size_t) - Unique entity identifier
+
+**Example:**
+```cpp
+auto registry = std::make_shared<Registry>();
+Entity player = registry->createEntity();
+Entity enemy = registry->createEntity();
+```
+
+#### `destroyEntity(Entity entityId)`
+Destroys an entity and removes all its components.
+
+```cpp
+void destroyEntity(Entity entityId);
+```
+
+**Parameters:**
+- `entityId`: The entity to destroy
+
+**Example:**
+```cpp
+Entity bullet = registry->createEntity();
+// ... later
+registry->destroyEntity(bullet);
+```
+
+**Callback Support:**
+```cpp
+registry->setOnEntityDestroyed([](Entity e) {
+    std::cout << "Entity " << e << " destroyed" << std::endl;
+});
+```
+
+#### `clearAllEntities()`
+Removes all entities and clears all component arrays.
+
+```cpp
+void clearAllEntities();
+```
+
+**Example:**
+```cpp
+// Clean up when changing game state
+registry->clearAllEntities();
+```
+
+#### `getMaxEntityId()`
+Returns the highest entity ID currently allocated.
+
+```cpp
+Entity getMaxEntityId() const;
+```
+
+**Returns:** `Entity` - Maximum entity ID
+
+### Component Management
+
+#### `registerComponent<T>()`
+Registers a component type with the registry (usually called automatically).
+
+```cpp
+template <typename T>
+void registerComponent();
+```
+
+**Example:**
+```cpp
+registry->registerComponent<TransformComponent>();
+registry->registerComponent<HealthComponent>();
+```
+
+**Note:** This is typically called automatically when adding a component.
+
+#### `addComponent<T>(Entity, std::shared_ptr<T>)`
+Adds a component to an entity.
+
+```cpp
+template <typename T>
+void addComponent(Entity entityId, std::shared_ptr<T> component);
+```
+
+**Parameters:**
+- `entityId`: Target entity
+- `component`: Shared pointer to the component
+
+**Example:**
+```cpp
+Entity player = registry->createEntity();
+
+// Add transform component
+auto transform = std::make_shared<TransformComponent>(100.0f, 200.0f);
+registry->addComponent<TransformComponent>(player, transform);
+
+// Add health component
+auto health = std::make_shared<HealthComponent>(100);
+registry->addComponent<HealthComponent>(player, health);
+```
+
+**Thread Safety:** Uses mutex lock, safe for concurrent access.
+
+#### `getComponent<T>(Entity)`
+Retrieves the first component of type T from an entity.
+
+```cpp
+template <typename T>
+std::shared_ptr<T> getComponent(Entity entityId) const;
+```
+
+**Returns:** `std::shared_ptr<T>` - Pointer to component, or `nullptr` if not found
+
+**Example:**
+```cpp
+auto transform = registry->getComponent<TransformComponent>(player);
+if (transform) {
+    transform->x += 10.0f;
+    transform->y += 5.0f;
+}
+```
+
+#### `getComponents<T>(Entity)`
+Retrieves all components of type T from an entity (for multi-component support).
+
+```cpp
+template <typename T>
+std::vector<std::shared_ptr<T>> getComponents(Entity entityId) const;
+```
+
+**Returns:** `std::vector<std::shared_ptr<T>>` - Vector of all matching components
+
+**Example:**
+```cpp
+// Entity can have multiple damage components queued
+auto damages = registry->getComponents<DamageToApplyComponent>(entity);
+for (auto& damage : damages) {
+    totalDamage += damage->damage;
+}
+```
+
+#### `hasComponent<T>(Entity)`
+Checks if an entity has a specific component type.
+
+```cpp
+template <typename T>
+bool hasComponent(Entity entityId) const;
+```
+
+**Returns:** `bool` - True if entity has the component
+
+**Example:**
+```cpp
+if (registry->hasComponent<HealthComponent>(entity)) {
+    auto health = registry->getComponent<HealthComponent>(entity);
+    health->currentHealth -= 10;
+}
+```
+
+#### `removeAllComponents<T>(Entity)`
+Removes all components of type T from an entity.
+
+```cpp
+template <typename T>
+void removeAllComponents(Entity entityId);
+```
+
+**Example:**
+```cpp
+// Remove all damage components after processing
+registry->removeAllComponents<DamageToApplyComponent>(entity);
+```
+
+#### `removeOneComponent<T>(Entity)`
+Removes the first component of type T from an entity.
+
+```cpp
+template <typename T>
+void removeOneComponent(Entity entityId);
+```
+
+**Example:**
+```cpp
+// Remove one damage component after processing
+registry->removeOneComponent<DamageToApplyComponent>(entity);
+```
+
+### View System
+
+#### `view<Components...>()`
+Creates a view to iterate entities that have ALL specified components.
+
+```cpp
+template <typename... Components>
+View<Components...> view();
+```
+
+**Returns:** `View<Components...>` - Iterable view object
+
+**Example:**
+```cpp
+// Iterate all entities with Transform AND Velocity
+auto view = registry->view<TransformComponent, VelocityComponent>();
+
+for (Entity entity : view) {
+    auto transform = registry->getComponent<TransformComponent>(entity);
+    auto velocity = registry->getComponent<VelocityComponent>(entity);
+    
+    transform->x += velocity->vx * deltaTime;
+    transform->y += velocity->vy * deltaTime;
+}
+```
+
+**Multiple Component Types:**
+```cpp
+// Entities must have ALL three components
+auto renderView = registry->view<TransformComponent, SpriteComponent, RenderableTag>();
+
+for (Entity entity : renderView) {
+    // Render only visible entities
+}
+```
+
+**Performance:** Views use lazy evaluation and iterate only matching entities.
+
+## View Class
+
+Iterator for entities with specific component combinations.
+
+### Iteration
+
+```cpp
+View<Components...> view = registry->view<Transform, Sprite>();
+
+// Range-based for loop (recommended)
+for (Entity entity : view) {
+    // Process entity
+}
+
+// Traditional iterator
+for (auto it = view.begin(); it != view.end(); ++it) {
+    Entity entity = *it;
+}
+```
+
+### Member Functions
+
+#### `begin()`
+Returns iterator to the first matching entity.
+
+```cpp
+auto begin() -> iterator;
+```
+
+#### `end()`
+Returns iterator past the last matching entity.
+
+```cpp
+auto end() -> iterator;
+```
+
+## Component Base Classes
+
+### IComponent
+
+Base interface for all components.
+
+```cpp
+class IComponent {
+public:
+    virtual ~IComponent() = default;
+};
+```
+
+**Usage:**
+```cpp
+class MyComponent : public IComponent {
+public:
+    // Your data members
+    int value;
+    std::string name;
+};
+```
+
+## System Base Classes
+
+### ASystem
+
+Abstract base class for all systems.
+
+```cpp
+class ASystem {
+public:
+    virtual ~ASystem() = default;
+    
+    virtual void update(float deltaTime) = 0;
+    
+    void setRegistry(std::shared_ptr<Registry> registry);
+    
+protected:
+    std::shared_ptr<Registry> registry;
+};
+```
+
+**Creating a System:**
+```cpp
+class MySystem : public ASystem {
+public:
+    void update(float deltaTime) override {
+        auto view = registry->view<MyComponent>();
+        
+        for (Entity entity : view) {
+            auto comp = registry->getComponent<MyComponent>(entity);
+            // Process component
+        }
+    }
+};
+```
+
+**System Setup:**
+```cpp
+auto system = std::make_shared<MySystem>();
+system->setRegistry(registry);
+
+// In game loop
+system->update(deltaTime);
+```
+
+## Common Component Types
+
+### TransformComponent
+
+Position, rotation, and scale in 2D space.
+
+```cpp
+class TransformComponent : public IComponent {
+public:
+    float x, y;           // Position
+    float rotation;       // Rotation in radians
+    float scaleX, scaleY; // Scale factors
+    
+    TransformComponent(float x = 0, float y = 0);
+};
+```
+
+### VelocityComponent
+
+Movement speed and direction.
+
+```cpp
+class VelocityComponent : public IComponent {
+public:
+    float vx, vy;  // Velocity in x and y
+    
+    VelocityComponent(float vx = 0, float vy = 0);
+};
+```
+
+### SpriteComponent
+
+Visual representation with texture.
+
+```cpp
+class SpriteComponent : public IComponent {
+public:
+    std::string texturePath;
+    sf::Sprite sprite;
+    int layer;  // Rendering layer
+    
+    SpriteComponent(const std::string& path);
+};
+```
+
+### HealthComponent
+
+Hit points and damage state.
+
+```cpp
+class HealthComponent : public IComponent {
+public:
+    int currentHealth;
+    int maxHealth;
+    bool invincible;
+    
+    HealthComponent(int maxHp);
+    bool isDead() const;
+};
+```
+
+### ColliderComponent
+
+Collision detection bounds.
+
+```cpp
+class ColliderComponent : public IComponent {
+public:
+    float width, height;
+    bool isTrigger;  // Trigger or solid collider
+    
+    ColliderComponent(float w, float h);
+};
+```
+
+### Tags
+
+Lightweight marker components for filtering.
+
+```cpp
+class PlayerTag : public IComponent {};
+class EnemyTag : public IComponent {};
+class BulletTag : public IComponent {};
+class LocalPlayerTag : public IComponent {};
+```
+
+**Usage:**
+```cpp
+// Mark as enemy
+registry->addComponent<EnemyTag>(entity, std::make_shared<EnemyTag>());
+
+// Filter enemies only
+auto enemies = registry->view<TransformComponent, EnemyTag>();
+```
+
+## Network Synchronization Components
+
+### NetworkComponent
+
+Tracks network synchronization state.
+
+```cpp
+class NetworkComponent : public IComponent {
+public:
+    bool dirty;           // Needs network update
+    uint32_t version;     // Version for reconciliation
+    uint8_t clientId;     // Owning client
+    
+    NetworkComponent();
+};
+```
+
+**Delta Encoding Pattern:**
+```cpp
+auto networkView = registry->view<TransformComponent, NetworkComponent>();
+
+for (Entity entity : networkView) {
+    auto transform = registry->getComponent<TransformComponent>(entity);
+    auto network = registry->getComponent<NetworkComponent>(entity);
+    
+    if (network->dirty) {
+        sendTransformUpdate(entity, transform);
+        network->dirty = false;
+        network->version++;
+    }
+}
+```
+
+## Entity Factory
+
+Helper class for creating common entity types.
+
+### `createPlayer(Registry&, float x, float y)`
+
+```cpp
+static Entity createPlayer(
+    std::shared_ptr<Registry> registry,
+    float x,
+    float y
+);
+```
+
+**Example:**
+```cpp
+Entity player = EntityFactory::createPlayer(registry, 100, 200);
+```
+
+### `createEnemy(Registry&, const std::string& type)`
+
+```cpp
+static Entity createEnemy(
+    std::shared_ptr<Registry> registry,
+    const std::string& type
+);
+```
+
+**Example:**
+```cpp
+Entity enemy = EntityFactory::createEnemy(registry, "basic_enemy");
+```
+
+## Threading & Concurrency
+
+### Thread Safety Guarantees
+
+The Registry uses a recursive mutex for thread-safe operations:
+
+```cpp
+// Safe from multiple threads
+std::thread t1([&]() { registry->addComponent<A>(e1, comp1); });
+std::thread t2([&]() { registry->addComponent<B>(e2, comp2); });
+```
+
+### Best Practices
+
+**DO:** Read different component types in parallel
+```cpp
+// Thread 1
+auto view1 = registry->view<TransformComponent>();
+
+// Thread 2 (different component type)
+auto view2 = registry->view<HealthComponent>();
+```
+
+**DON'T:** Modify entity list while iterating
+```cpp
+// WRONG - modifying while iterating
+for (Entity e : view) {
+    registry->destroyEntity(e);  // Dangerous!
+}
+
+// CORRECT - use command buffer
+std::vector<Entity> toDestroy;
+for (Entity e : view) {
+    toDestroy.push_back(e);
+}
+for (Entity e : toDestroy) {
+    registry->destroyEntity(e);
+}
+```
 
 ## Serialization
-- Provide `serialize(entity)`/`deserialize(data)` for snapshotting and network broadcast.
+
+### Entity Serialization
+
+```cpp
+// Serialize entity state
+nlohmann::json serializeEntity(Entity entity, Registry& registry) {
+    json data;
+    data["id"] = entity;
+    
+    if (registry.hasComponent<TransformComponent>(entity)) {
+        auto t = registry.getComponent<TransformComponent>(entity);
+        data["transform"] = {{"x", t->x}, {"y", t->y}};
+    }
+    
+    // ... other components
+    return data;
+}
+```
+
+### Component Snapshot
+
+```cpp
+// Take snapshot of all entities with network components
+std::vector<json> takeSnapshot(Registry& registry) {
+    std::vector<json> entities;
+    
+    auto view = registry.view<NetworkComponent>();
+    for (Entity e : view) {
+        entities.push_back(serializeEntity(e, registry));
+    }
+    
+    return entities;
+}
+```
+
+## Performance Tips
+
+### Component Design
+
+```cpp
+// GOOD - Simple, cache-friendly
+class PositionComponent {
+    float x, y;
+};
+
+// BAD - Heavy, not cache-friendly
+class PositionComponent {
+    std::vector<Transform> history;
+    std::map<std::string, Callback> events;
+};
+```
+
+### View Optimization
+
+```cpp
+// GOOD - Iterate once with multi-component view
+auto view = registry->view<A, B, C>();
+for (Entity e : view) {
+    auto a = registry->getComponent<A>(e);
+    auto b = registry->getComponent<B>(e);
+    auto c = registry->getComponent<C>(e);
+    // Process all together
+}
+
+// BAD - Multiple iterations
+for (Entity e : registry->view<A>()) {
+    if (registry->hasComponent<B>(e) && registry->hasComponent<C>(e)) {
+        // Inefficient filtering
+    }
+}
+```
+
+### Memory Management
+
+```cpp
+// Components use shared_ptr for automatic memory management
+auto comp = std::make_shared<MyComponent>(args);
+registry->addComponent<MyComponent>(entity, comp);
+
+// No manual cleanup needed
+// Destroyed automatically when entity is destroyed
+```
+
+## Code Examples
+
+### Complete Entity Creation
+
+```cpp
+// Create a player entity with all components
+Entity createPlayerEntity(std::shared_ptr<Registry> registry) {
+    Entity player = registry->createEntity();
+    
+    // Transform
+    auto transform = std::make_shared<TransformComponent>(100, 200);
+    registry->addComponent<TransformComponent>(player, transform);
+    
+    // Sprite
+    auto sprite = std::make_shared<SpriteComponent>("player.png");
+    registry->addComponent<SpriteComponent>(player, sprite);
+    
+    // Health
+    auto health = std::make_shared<HealthComponent>(100);
+    registry->addComponent<HealthComponent>(player, health);
+    
+    // Velocity
+    auto velocity = std::make_shared<VelocityComponent>(0, 0);
+    registry->addComponent<VelocityComponent>(player, velocity);
+    
+    // Collider
+    auto collider = std::make_shared<ColliderComponent>(32, 32);
+    registry->addComponent<ColliderComponent>(player, collider);
+    
+    // Tag as player
+    registry->addComponent<PlayerTag>(player, std::make_shared<PlayerTag>());
+    
+    return player;
+}
+```
+
+### System Implementation
+
+```cpp
+class DamageSystem : public ASystem {
+public:
+    void update(float deltaTime) override {
+        // Process all entities with health and pending damage
+        auto view = registry->view<HealthComponent, DamageToApplyComponent>();
+        
+        for (Entity entity : view) {
+            auto health = registry->getComponent<HealthComponent>(entity);
+            auto damage = registry->getComponent<DamageToApplyComponent>(entity);
+            
+            // Apply damage
+            health->currentHealth -= damage->damage;
+            
+            // Check for death
+            if (health->isDead()) {
+                registry->addComponent<DestroyEntityComponent>(entity,
+                    std::make_shared<DestroyEntityComponent>());
+            }
+            
+            // Remove processed damage
+            registry->removeOneComponent<DamageToApplyComponent>(entity);
+        }
+    }
+};
+```
+
+---
+
+For more information, see:
+- [ECS Introduction](./ecs-intro.md)
+- [ECS POCs](../POCS/ecs/pocs-ecs.md)
+- [Project Architecture](../INTRO/project_architecure.md)
diff --git a/documentation/docusaurus/docs/ECS/ecs-intro.md b/documentation/docusaurus/docs/ECS/ecs-intro.md
index f52cf7ffe..e66b03e00 100644
--- a/documentation/docusaurus/docs/ECS/ecs-intro.md
+++ b/documentation/docusaurus/docs/ECS/ecs-intro.md
@@ -2,6 +2,429 @@
 sidebar_position: 1
 ---
 
-# R-Type ECS
+# R-Type ECS (Entity-Component-System)
 
-This is the ecs intro
+## Overview
+
+The R-Type project implements a custom **Entity-Component-System (ECS)** architecture, a powerful design pattern that separates game entities into three distinct concepts:
+
+- **Entities**: Unique identifiers (simple integers) representing game objects
+- **Components**: Pure data containers that define entity properties
+- **Systems**: Logic processors that operate on entities with specific components
+
+This architecture provides excellent performance, flexibility, and maintainability for game development.
+
+## Why ECS?
+
+### Traditional Object-Oriented vs ECS
+
+**Traditional OOP Approach:**
+```cpp
+class Enemy : public GameObject {
+    Vector2D position;
+    Sprite sprite;
+    Health health;
+    AI ai;
+    
+    void update() {
+        // Mixed logic for rendering, AI, physics...
+    }
+};
+```
+
+**ECS Approach:**
+```cpp
+// Entity is just an ID
+Entity enemy = registry->createEntity();
+
+// Add components (pure data)
+registry->addComponent(enemy, std::make_shared<TransformComponent>(x, y));
+registry->addComponent(enemy, std::make_shared<SpriteComponent>(texture));
+registry->addComponent(enemy, std::make_shared<HealthComponent>(100));
+registry->addComponent(enemy, std::make_shared<AIComponent>());
+
+// Systems process entities
+MovementSystem->update();  // Operates on Transform + Velocity
+RenderSystem->update();    // Operates on Transform + Sprite
+AISystem->update();        // Operates on AI + Transform
+```
+
+### Benefits of ECS
+
+1. **Separation of Concerns**: Data (components) is separated from logic (systems)
+2. **Composition over Inheritance**: Build entities by composing components
+3. **Cache-Friendly**: Components stored contiguously in memory
+4. **Flexible**: Easy to add/remove components at runtime
+5. **Reusable**: Systems work with any entity that has required components
+6. **Testable**: Systems can be tested independently
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph "Entity Management"
+        E[Entity<br/>uint32_t ID]
+    end
+    
+    subgraph "Component Storage"
+        R[Registry<br/>Manages all components]
+        CA[ComponentArray&lt;Transform&gt;]
+        CB[ComponentArray&lt;Sprite&gt;]
+        CC[ComponentArray&lt;Health&gt;]
+        CD[ComponentArray&lt;...&gt;]
+    end
+    
+    subgraph "Systems"
+        SR[RenderSystem]
+        SM[MovementSystem]
+        SC[CollisionSystem]
+        SA[AISystem]
+    end
+    
+    subgraph "Queries"
+        V[View&lt;Transform, Sprite&gt;]
+    end
+    
+    E --> R
+    R --> CA
+    R --> CB
+    R --> CC
+    R --> CD
+    
+    SR --> V
+    SM --> V
+    SC --> V
+    SA --> V
+    
+    V --> R
+```
+
+## Core Concepts
+
+### Entities
+
+An entity is simply a unique identifier (a `size_t` integer) that serves as an index into component arrays.
+
+```cpp
+namespace ecs {
+    using Entity = size_t;
+}
+
+// Creating an entity
+Entity player = registry->createEntity();  // Returns: 1
+Entity enemy = registry->createEntity();   // Returns: 2
+```
+
+### Components
+
+Components are pure data structures that inherit from `IComponent`. They contain no logic, only state.
+
+**Example Components:**
+
+```cpp
+// Position in 2D space
+class TransformComponent : public IComponent {
+public:
+    float x, y;
+    float rotation;
+    
+    TransformComponent(float x = 0, float y = 0, float rot = 0)
+        : x(x), y(y), rotation(rot) {}
+};
+
+// Visual representation
+class SpriteComponent : public IComponent {
+public:
+    std::string texturePath;
+    int width, height;
+    sf::Sprite sprite;
+};
+
+// Health and damage
+class HealthComponent : public IComponent {
+public:
+    int currentHealth;
+    int maxHealth;
+    
+    bool isDead() const { return currentHealth <= 0; }
+};
+```
+
+### Systems
+
+Systems contain the game logic and operate on entities that have specific components.
+
+```cpp
+class MovementSystem : public ASystem {
+public:
+    void update(float deltaTime) override {
+        // Get all entities with Transform and Velocity components
+        auto view = registry->view<TransformComponent, VelocityComponent>();
+        
+        for (Entity entity : view) {
+            auto transform = registry->getComponent<TransformComponent>(entity);
+            auto velocity = registry->getComponent<VelocityComponent>(entity);
+            
+            // Update position based on velocity
+            transform->x += velocity->vx * deltaTime;
+            transform->y += velocity->vy * deltaTime;
+        }
+    }
+};
+```
+
+### Registry
+
+The `Registry` is the central hub that manages all entities and components.
+
+**Key Responsibilities:**
+- Create and destroy entities
+- Add, remove, and query components
+- Provide views for system iteration
+- Thread-safe operations with mutex
+
+```cpp
+auto registry = std::make_shared<Registry>();
+
+// Entity lifecycle
+Entity entity = registry->createEntity();
+registry->destroyEntity(entity);
+
+// Component management
+registry->addComponent<TransformComponent>(entity, 
+    std::make_shared<TransformComponent>(100, 200));
+auto transform = registry->getComponent<TransformComponent>(entity);
+bool hasTransform = registry->hasComponent<TransformComponent>(entity);
+registry->removeAllComponents<TransformComponent>(entity);
+```
+
+## Component Types
+
+R-Type categorizes components into several types:
+
+### Permanent Components
+Components that persist throughout entity lifetime:
+- `TransformComponent`: Position, rotation, scale
+- `SpriteComponent`: Visual representation
+- `VelocityComponent`: Movement speed
+- `HealthComponent`: Hit points
+- `ColliderComponent`: Collision bounds
+- `OwnerComponent`: Entity ownership (for bullets, etc.)
+
+### Tags
+Lightweight components used for filtering:
+- `PlayerTag`: Marks player entities
+- `EnemyTag`: Marks enemy entities
+- `BulletTag`: Marks projectile entities
+- `LocalPlayerTag`: Marks the local player on client
+
+### Temporary Components
+Short-lived components for inter-system communication:
+- `DamageToApplyComponent`: Queued damage
+- `DestroyEntityComponent`: Mark for deletion
+
+### Network Components
+Components used for multiplayer synchronization:
+- `NetworkComponent`: Network sync state
+- `NetworkOwnerComponent`: Entity ownership across network
+
+## View System
+
+Views provide efficient iteration over entities with specific component combinations.
+
+```cpp
+// Iterate entities with Transform AND Sprite
+auto view = registry->view<TransformComponent, SpriteComponent>();
+
+for (Entity entity : view) {
+    auto transform = registry->getComponent<TransformComponent>(entity);
+    auto sprite = registry->getComponent<SpriteComponent>(entity);
+    
+    // Render sprite at transform position
+    sprite->sprite.setPosition(transform->x, transform->y);
+    window.draw(sprite->sprite);
+}
+```
+
+**View Benefits:**
+- Only iterates entities with ALL requested components
+- Efficient filtering at query time
+- No temporary allocations
+- Cache-friendly iteration
+
+## Design Pattern: Component-Driven
+
+R-Type uses a **Component-Driven** ECS pattern, chosen after evaluating multiple approaches through POCs.
+
+### Inter-System Communication
+
+Systems communicate through temporary components rather than direct calls:
+
+```cpp
+// CollisionSystem detects collision and adds damage component
+if (collision detected) {
+    registry->addComponent<DamageToApplyComponent>(entity,
+        std::make_shared<DamageToApplyComponent>(10));
+}
+
+// DamageSystem processes all pending damage
+auto damageView = registry->view<HealthComponent, DamageToApplyComponent>();
+for (Entity entity : damageView) {
+    auto health = registry->getComponent<HealthComponent>(entity);
+    auto damage = registry->getComponent<DamageToApplyComponent>(entity);
+    
+    health->currentHealth -= damage->damage;
+    
+    // Remove processed damage component
+    registry->removeOneComponent<DamageToApplyComponent>(entity);
+}
+```
+
+**Advantages:**
+- Loose coupling between systems
+- Easy to add new effects
+- Clear data flow
+- Supports command buffer pattern
+
+## Tags/Filters Optimization
+
+R-Type complements the component-driven approach with tags for performance:
+
+```cpp
+// Only process enemy entities
+auto enemyView = registry->view<TransformComponent, HealthComponent, EnemyTag>();
+
+for (Entity enemy : enemyView) {
+    // Process only enemies, ignore players
+}
+```
+
+## Thread Safety
+
+The Registry uses a recursive mutex to ensure thread-safe operations:
+
+```cpp
+template <typename T>
+void Registry::addComponent(Entity entityId, std::shared_ptr<T> component) {
+    std::lock_guard<std::recursive_mutex> lock(_mutex);
+    // Thread-safe component addition
+}
+```
+
+**Best Practices:**
+- Systems can read components in parallel for disjoint sets
+- Writes should use command buffers or be serialized
+- Avoid modifying entity list while iterating (use views)
+
+## Entity Factory
+
+The `EntityFactory` provides convenient methods to create common entity types:
+
+```cpp
+class EntityFactory {
+public:
+    static Entity createPlayer(Registry& registry, float x, float y);
+    static Entity createEnemy(Registry& registry, const std::string& type);
+    static Entity createBullet(Registry& registry, Entity owner);
+    static Entity createPowerUp(Registry& registry, const std::string& type);
+};
+```
+
+## Prefab System
+
+Prefabs define entity templates loaded from JSON configuration files:
+
+```json
+{
+  "name": "basic_enemy",
+  "components": {
+    "transform": {"x": 0, "y": 0},
+    "sprite": {"texture": "enemy.png"},
+    "health": {"maxHealth": 50},
+    "velocity": {"vx": -100, "vy": 0},
+    "collider": {"width": 32, "height": 32}
+  }
+}
+```
+
+```cpp
+// Create entity from prefab
+Entity enemy = PrefabManager::instantiate(registry, "basic_enemy");
+```
+
+## Best Practices
+
+### DO ✅
+
+```cpp
+// Keep components simple (data only)
+class PositionComponent {
+    float x, y;
+};
+
+// Use views for efficient iteration
+auto view = registry->view<Transform, Velocity>();
+
+// Use tags for filtering
+registry->addComponent<EnemyTag>(entity);
+
+// Use temporary components for communication
+registry->addComponent<DamageToApplyComponent>(entity, damage);
+```
+
+### DON'T ❌
+
+```cpp
+// Don't add logic to components
+class PositionComponent {
+    void update() { /* NO! */ }
+};
+
+// Don't modify entity list while iterating
+for (Entity e : view) {
+    registry->destroyEntity(e);  // WRONG! Use command buffer
+}
+
+// Don't store entity references long-term
+Entity* storedEntity = &myEntity;  // Dangerous if entity is destroyed
+```
+
+## Performance Considerations
+
+### Memory Layout
+
+Components are stored in contiguous arrays per type:
+```
+ComponentArray<Transform>: [Transform1][Transform2][Transform3]...
+ComponentArray<Sprite>:    [Sprite1   ][Sprite2   ][Sprite3   ]...
+```
+
+**Benefits:**
+- Cache-friendly iteration
+- Predictable memory access patterns
+- Efficient batch processing
+
+### System Execution Order
+
+Systems run in a defined order each frame:
+```cpp
+1. InputSystem
+2. ScriptingSystem (Lua behaviors)
+3. MovementSystem
+4. CollisionSystem
+5. DamageSystem
+6. AISystem
+7. AnimationSystem
+8. RenderSystem
+9. NetworkSyncSystem
+```
+
+## Next Steps
+
+- **[ECS API Reference](./api.md)**: Detailed API documentation
+- **[POC Documentation](../POCS/ecs/pocs-ecs.md)**: ECS pattern evaluation
+- **[System Examples](../INTRO/project_architecure.md#ecs-entity-component-system-architecture)**: Concrete system implementations
+
+---
+
+The ECS architecture is the foundation of R-Type's game logic, providing the flexibility and performance needed for a fast-paced multiplayer shooter.
diff --git a/documentation/docusaurus/docs/HOW-TO-CONTRIBUTE/coding-conventions.md b/documentation/docusaurus/docs/HOW-TO-CONTRIBUTE/coding-conventions.md
new file mode 100644
index 000000000..e047fe1db
--- /dev/null
+++ b/documentation/docusaurus/docs/HOW-TO-CONTRIBUTE/coding-conventions.md
@@ -0,0 +1,604 @@
+---
+sidebar_position: 2
+---
+
+# Coding Conventions
+
+Code style and best practices for the R-Type project.
+
+## C++ Style Guide
+
+### Naming Conventions
+
+#### Files
+```cpp
+// Classes: PascalCase
+MyClass.cpp
+MyClass.hpp
+
+// Functions/utilities: camelCase
+utilityFunctions.cpp
+utilityFunctions.hpp
+```
+
+#### Classes and Structs
+```cpp
+// PascalCase for class names
+class PlayerEntity { };
+class GameStateMachine { };
+
+// PascalCase for struct names
+struct TransformComponent { };
+struct Vector2D { };
+```
+
+#### Functions and Methods
+```cpp
+// camelCase for functions
+void updatePosition();
+int calculateDamage();
+
+// Getters/setters
+float getSpeed() const;
+void setSpeed(float speed);
+```
+
+#### Variables
+```cpp
+// camelCase for local variables
+int playerHealth = 100;
+std::string userName = "Player";
+
+// camelCase for member variables
+class Player {
+private:
+    int currentHealth;
+    float movementSpeed;
+};
+
+// Or prefix with underscore
+class Player {
+private:
+    int _currentHealth;
+    float _movementSpeed;
+};
+
+// UPPER_CASE for constants
+const int MAX_PLAYERS = 4;
+constexpr float GRAVITY = 9.81f;
+```
+
+#### Namespaces
+```cpp
+// lowercase
+namespace ecs { }
+namespace rserv { }
+namespace constants { }
+```
+
+#### Enums
+```cpp
+// PascalCase for enum name
+enum class PlayerState {
+    Idle,        // PascalCase for values
+    Walking,
+    Jumping
+};
+
+// Usage
+PlayerState state = PlayerState::Idle;
+```
+
+### Code Formatting
+
+#### Indentation
+- **4 spaces** (no tabs)
+- Consistent indentation level
+
+```cpp
+void example() {
+    if (condition) {
+        doSomething();
+        doAnotherThing();
+    }
+}
+```
+
+#### Braces
+Opening brace on same line (K&R style):
+
+```cpp
+// Functions
+void function() {
+    // code
+}
+
+// Conditionals
+if (condition) {
+    // code
+} else {
+    // code
+}
+
+// Loops
+for (int i = 0; i < 10; i++) {
+    // code
+}
+
+// Classes
+class MyClass {
+public:
+    // members
+};
+```
+
+#### Spacing
+
+```cpp
+// Operators: spaces around binary operators
+int result = a + b * c;
+bool isValid = (x > 0) && (y < 100);
+
+// Function calls: no space before parenthesis
+function(arg1, arg2);
+myObject.method(value);
+
+// Control structures: space after keyword
+if (condition) { }
+while (running) { }
+for (int i = 0; i < n; i++) { }
+
+// Commas: space after
+function(arg1, arg2, arg3);
+int array[] = {1, 2, 3, 4};
+
+// Pointers/References: * and & with type
+int* pointer;
+const std::string& reference;
+```
+
+#### Line Length
+- Maximum **100 characters** per line
+- Break long lines logically
+
+```cpp
+// Long function calls
+myObject->doSomethingWithALongName(
+    argument1,
+    argument2,
+    argument3
+);
+
+// Long conditions
+if (veryLongCondition1 &&
+    veryLongCondition2 &&
+    veryLongCondition3) {
+    // code
+}
+```
+
+### Comments
+
+#### Single-line Comments
+```cpp
+// Use // for single-line comments
+int value = 42;  // Inline comment
+```
+
+#### Multi-line Comments
+```cpp
+/*
+** EPITECH PROJECT, 2025
+** ryanR-type
+** File description:
+** MyClass
+*/
+```
+
+#### Documentation Comments
+```cpp
+/**
+ * @brief Calculates the distance between two points
+ * 
+ * @param p1 First point
+ * @param p2 Second point
+ * @return float Distance between points
+ */
+float calculateDistance(const Vector2D& p1, const Vector2D& p2);
+```
+
+### Header Guards
+
+Use `#ifndef` / `#define`:
+
+```cpp
+#ifndef MYCLASS_HPP_
+#define MYCLASS_HPP_
+
+// Header content
+
+#endif /* !MYCLASS_HPP_ */
+```
+
+**Format:** `FILENAME_HPP_` in UPPER_CASE
+
+### Include Order
+
+```cpp
+// 1. Project header (for .cpp files)
+#include "MyClass.hpp"
+
+// 2. System headers
+#include <iostream>
+#include <vector>
+#include <memory>
+
+// 3. Third-party libraries
+#include <SFML/Graphics.hpp>
+#include <nlohmann/json.hpp>
+
+// 4. Project headers
+#include "../common/ECS/Registry.hpp"
+#include "Utils.hpp"
+```
+
+### Modern C++ Features
+
+#### Use Smart Pointers
+```cpp
+// Preferred
+auto player = std::make_shared<Player>();
+auto data = std::make_unique<GameData>();
+
+// Avoid
+Player* player = new Player();  // Manual memory management
+```
+
+#### Use Auto for Complex Types
+```cpp
+// Good
+auto registry = std::make_shared<Registry>();
+auto texture = resourceManager.getTexture("player");
+
+// But be explicit when clarity matters
+int count = 5;  // Not: auto count = 5;
+```
+
+#### Range-Based For Loops
+```cpp
+// Preferred
+for (const auto& item : container) {
+    // process item
+}
+
+// Avoid
+for (size_t i = 0; i < container.size(); i++) {
+    auto item = container[i];
+}
+```
+
+#### Const Correctness
+```cpp
+class MyClass {
+public:
+    // Const methods don't modify object
+    int getValue() const { return _value; }
+    
+    // Non-const methods can modify
+    void setValue(int value) { _value = value; }
+    
+private:
+    int _value;
+};
+
+// Const references for large objects
+void processData(const std::vector<int>& data);
+```
+
+#### Nullptr over NULL
+```cpp
+// Preferred
+Entity* entity = nullptr;
+
+// Avoid
+Entity* entity = NULL;
+```
+
+## ECS Best Practices
+
+### Components
+- **Data only**, no logic
+- Small and focused
+- Inherit from `IComponent`
+
+```cpp
+// GOOD
+class TransformComponent : public IComponent {
+public:
+    float x, y;
+    float rotation;
+    
+    TransformComponent(float x = 0, float y = 0, float rot = 0)
+        : x(x), y(y), rotation(rot) {}
+};
+
+// BAD - has logic
+class TransformComponent : public IComponent {
+public:
+    float x, y;
+    
+    void update(float dt) {  // NO! Logic in component
+        x += speed * dt;
+    }
+};
+```
+
+### Systems
+- **Logic only**, operate on components
+- Use views for iteration
+- Inherit from `ASystem`
+
+```cpp
+class MovementSystem : public ASystem {
+public:
+    void update(float deltaTime) override {
+        auto view = registry->view<TransformComponent, VelocityComponent>();
+        
+        for (Entity entity : view) {
+            auto transform = registry->getComponent<TransformComponent>(entity);
+            auto velocity = registry->getComponent<VelocityComponent>(entity);
+            
+            transform->x += velocity->vx * deltaTime;
+            transform->y += velocity->vy * deltaTime;
+        }
+    }
+};
+```
+
+### Entity Creation
+- Use factory methods
+- Add components in logical order
+- Use shared_ptr for components
+
+```cpp
+Entity createPlayer(std::shared_ptr<Registry> registry, float x, float y) {
+    Entity player = registry->createEntity();
+    
+    registry->addComponent<TransformComponent>(player,
+        std::make_shared<TransformComponent>(x, y));
+    registry->addComponent<SpriteComponent>(player,
+        std::make_shared<SpriteComponent>("player.png"));
+    registry->addComponent<HealthComponent>(player,
+        std::make_shared<HealthComponent>(100));
+    
+    return player;
+}
+```
+
+## Error Handling
+
+### Use Exceptions for Errors
+```cpp
+// Throw exceptions for error conditions
+if (!file.is_open()) {
+    throw std::runtime_error("Failed to open file: " + filename);
+}
+
+// Catch specific exceptions
+try {
+    loadConfig("settings.json");
+} catch (const std::runtime_error& e) {
+    std::cerr << "Config error: " << e.what() << std::endl;
+} catch (const err::IError& e) {
+    std::cerr << "Game error: " << e.getDetails() << std::endl;
+}
+```
+
+### Validate Input
+```cpp
+void setPort(uint16_t port) {
+    if (port < 1024 || port > 65535) {
+        throw std::invalid_argument("Port must be between 1024 and 65535");
+    }
+    _port = port;
+}
+```
+
+### Check Pointers
+```cpp
+auto component = registry->getComponent<HealthComponent>(entity);
+if (component) {
+    component->currentHealth -= damage;
+} else {
+    // Handle missing component
+    std::cerr << "Entity " << entity << " has no HealthComponent" << std::endl;
+}
+```
+
+## Performance Guidelines
+
+### Pass by Reference
+```cpp
+// Large objects: pass by const reference
+void processEntity(const Entity& entity);
+void loadTexture(const std::string& path);
+
+// Small objects (primitives): pass by value
+void setPosition(float x, float y);
+void setId(int id);
+```
+
+### Reserve Vector Capacity
+```cpp
+std::vector<Entity> entities;
+entities.reserve(1000);  // Avoid reallocations
+
+for (int i = 0; i < 1000; i++) {
+    entities.push_back(createEntity());
+}
+```
+
+### Avoid Unnecessary Copies
+```cpp
+// GOOD - reference
+for (const auto& entity : entities) {
+    processEntity(entity);
+}
+
+// BAD - copies each entity
+for (auto entity : entities) {
+    processEntity(entity);
+}
+```
+
+### Use Emplace
+```cpp
+// Preferred - construct in place
+vector.emplace_back(arg1, arg2);
+map.emplace(key, value);
+
+// Less efficient - constructs then copies
+vector.push_back(Object(arg1, arg2));
+```
+
+## File Organization
+
+### Header Files (.hpp)
+```cpp
+/*
+** EPITECH PROJECT, 2025
+** ryanR-type
+** File description:
+** MyClass
+*/
+
+#ifndef MYCLASS_HPP_
+#define MYCLASS_HPP_
+
+// Includes
+#include <memory>
+#include "OtherClass.hpp"
+
+// Namespace
+namespace myproject {
+
+// Class declaration
+class MyClass {
+public:
+    MyClass();
+    ~MyClass();
+    
+    void publicMethod();
+    
+private:
+    void privateMethod();
+    
+    int _memberVariable;
+};
+
+}  // namespace myproject
+
+#endif /* !MYCLASS_HPP_ */
+```
+
+### Implementation Files (.cpp)
+```cpp
+/*
+** EPITECH PROJECT, 2025
+** ryanR-type
+** File description:
+** MyClass
+*/
+
+#include "MyClass.hpp"
+
+#include <iostream>
+
+namespace myproject {
+
+MyClass::MyClass() : _memberVariable(0) {
+    // Constructor
+}
+
+MyClass::~MyClass() {
+    // Destructor
+}
+
+void MyClass::publicMethod() {
+    // Implementation
+}
+
+void MyClass::privateMethod() {
+    // Implementation
+}
+
+}  // namespace myproject
+```
+
+## CMakeLists.txt Conventions
+
+```cmake
+# Project definition
+project(MyProject)
+
+# Source files
+set(SOURCES
+    main.cpp
+    MyClass.cpp
+    Utils.cpp
+)
+
+# Executable
+add_executable(${PROJECT_NAME} ${SOURCES})
+
+# Include directories
+target_include_directories(${PROJECT_NAME}
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
+    PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/../common
+)
+
+# Link libraries
+target_link_libraries(${PROJECT_NAME}
+    PRIVATE sfml-graphics
+    PRIVATE ECS
+    PRIVATE Network
+)
+```
+
+## Git Commit Messages
+
+Follow the project's commit conventions (see [Git Workflow](./git-workflow.md) for details).
+
+**Format:**
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:** feat, fix, docs, style, refactor, test, chore
+
+## Code Review Checklist
+
+Before submitting a PR:
+
+- [ ] Code follows style guidelines
+- [ ] No compiler warnings
+- [ ] All tests pass
+- [ ] New code has tests
+- [ ] Documentation updated
+- [ ] No memory leaks (checked with valgrind/sanitizers)
+- [ ] Commit messages follow conventions
+- [ ] PR description is clear
+
+## Additional Resources
+
+- [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/)
+- [Modern C++ Best Practices](https://github.com/cpp-best-practices/cppbestpractices)
+- [SFML Documentation](https://www.sfml-dev.org/documentation/)
+
+---
+
+Consistent code style makes collaboration easier and code more maintainable!
diff --git a/documentation/docusaurus/docs/HOW-TO-CONTRIBUTE/git-workflow.md b/documentation/docusaurus/docs/HOW-TO-CONTRIBUTE/git-workflow.md
new file mode 100644
index 000000000..49852e568
--- /dev/null
+++ b/documentation/docusaurus/docs/HOW-TO-CONTRIBUTE/git-workflow.md
@@ -0,0 +1,680 @@
+---
+sidebar_position: 3
+---
+
+# Git Workflow
+
+Complete guide for contributing code using Git and GitHub.
+
+## Repository Structure
+
+### Main Branches
+
+- **`main`**: Production-ready code, always stable
+- **`develop`**: Integration branch for features (if used)
+
+### Branch Naming Convention
+
+```
+<type>/<short-description>
+```
+
+**Types:**
+- `feature/`: New feature development
+- `fix/`: Bug fixes
+- `docs/`: Documentation changes
+- `refactor/`: Code refactoring
+- `test/`: Test additions or modifications
+
+**Examples:**
+```bash
+feature/lobby-system
+fix/network-disconnect-bug
+docs/update-readme
+refactor/ecs-registry
+test/add-collision-tests
+```
+
+## Contribution Workflow
+
+### 1. Fork and Clone
+
+**Fork the repository** on GitHub, then clone it:
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/R-Type.git
+cd R-Type
+
+# Add upstream remote
+git remote add upstream https://github.com/AlbanRSS/doc-rtype.git
+```
+
+### 2. Create a Branch
+
+```bash
+# Update your local main
+git checkout main
+git pull upstream main
+
+# Create and switch to new branch
+git checkout -b feature/my-new-feature
+```
+
+### 3. Make Changes
+
+Edit files, add features, fix bugs...
+
+```bash
+# Check status
+git status
+
+# See changes
+git diff
+```
+
+### 4. Commit Changes
+
+**Stage changes:**
+```bash
+# Stage specific files
+git add file1.cpp file2.hpp
+
+# Stage all changes
+git add .
+
+# Stage interactively
+git add -p
+```
+
+**Commit with conventional message:**
+```bash
+git commit -m "feat(client): add player name input field
+
+- Add TextBox widget to lobby screen
+- Validate player name length (3-20 chars)
+- Update SettingsManager to store name
+
+Closes #42"
+```
+
+**Commit message format:**
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### 5. Push Branch
+
+```bash
+# First push
+git push -u origin feature/my-new-feature
+
+# Subsequent pushes
+git push
+```
+
+### 6. Create Pull Request
+
+1. Go to your fork on GitHub
+2. Click **"Compare & pull request"**
+3. Fill in PR template:
+   - **Title**: Brief description
+   - **Description**: Detailed explanation
+   - **Related Issues**: Link issues (#42)
+   - **Screenshots**: If applicable
+4. Request review
+5. Click **"Create pull request"**
+
+### 7. Address Review Feedback
+
+**Make changes based on review:**
+```bash
+# Make requested changes
+git add modified_files
+git commit -m "fix(client): address review feedback"
+git push
+```
+
+**Amend last commit if needed:**
+```bash
+git add .
+git commit --amend --no-edit
+git push --force
+```
+
+### 8. Merge
+
+Once approved, a maintainer will merge your PR.
+
+## Keeping Your Fork Updated
+
+### Sync with Upstream
+
+```bash
+# Fetch upstream changes
+git fetch upstream
+
+# Switch to main
+git checkout main
+
+# Merge upstream changes
+git merge upstream/main
+
+# Push to your fork
+git push origin main
+```
+
+### Rebase Feature Branch
+
+Keep your feature branch up-to-date:
+
+```bash
+# Switch to your feature branch
+git checkout feature/my-feature
+
+# Rebase on latest main
+git rebase main
+
+# If conflicts, resolve them and continue
+git add resolved_files
+git rebase --continue
+
+# Force push (rebase rewrites history)
+git push --force
+```
+
+## Common Git Commands
+
+### Viewing History
+
+```bash
+# Commit log
+git log
+
+# Compact log
+git log --oneline
+
+# Graphical log
+git log --graph --oneline --all
+
+# File history
+git log --follow file.cpp
+
+# Changes in commits
+git show <commit-hash>
+```
+
+### Undoing Changes
+
+**Discard local changes (not staged):**
+```bash
+git restore file.cpp
+
+# All files
+git restore .
+```
+
+**Unstage changes:**
+```bash
+git restore --staged file.cpp
+```
+
+**Undo last commit (keep changes):**
+```bash
+git reset --soft HEAD~1
+```
+
+**Undo last commit (discard changes):**
+```bash
+git reset --hard HEAD~1
+```
+
+**Revert a pushed commit:**
+```bash
+git revert <commit-hash>
+git push
+```
+
+### Stashing Changes
+
+Save work in progress without committing:
+
+```bash
+# Stash changes
+git stash
+
+# Stash with message
+git stash save "WIP: adding feature X"
+
+# List stashes
+git stash list
+
+# Apply most recent stash
+git stash apply
+
+# Apply and remove stash
+git stash pop
+
+# Apply specific stash
+git stash apply stash@{2}
+
+# Drop stash
+git stash drop stash@{0}
+```
+
+### Resolving Conflicts
+
+**When conflicts occur during merge/rebase:**
+
+```bash
+# See conflicting files
+git status
+
+# Edit files to resolve conflicts
+# Look for markers: <<<<<<<, =======, >>>>>>>
+
+# After resolving
+git add resolved_files
+
+# Continue merge
+git merge --continue
+
+# Or continue rebase
+git rebase --continue
+
+# Abort if needed
+git merge --abort
+git rebase --abort
+```
+
+## Branch Management
+
+### Listing Branches
+
+```bash
+# Local branches
+git branch
+
+# Remote branches
+git branch -r
+
+# All branches
+git branch -a
+```
+
+### Switching Branches
+
+```bash
+# Switch to existing branch
+git checkout branch-name
+
+# Create and switch to new branch
+git checkout -b new-branch
+
+# Modern alternative (Git 2.23+)
+git switch branch-name
+git switch -c new-branch
+```
+
+### Deleting Branches
+
+```bash
+# Delete local branch (safe)
+git branch -d feature/old-feature
+
+# Force delete local branch
+git branch -D feature/old-feature
+
+# Delete remote branch
+git push origin --delete feature/old-feature
+```
+
+## Pull Request Best Practices
+
+### PR Checklist
+
+Before creating a PR:
+
+- [ ] Code follows [coding conventions](./coding-conventions.md)
+- [ ] All tests pass locally
+- [ ] New tests added for new features
+- [ ] Documentation updated
+- [ ] Commit messages follow conventions
+- [ ] No merge conflicts with main
+- [ ] PR is focused (one feature/fix per PR)
+
+### PR Template
+
+```markdown
+## Description
+
+Brief description of changes
+
+## Related Issues
+
+Closes #42
+Relates to #38
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring
+- [ ] Performance improvement
+
+## Testing
+
+Describe testing performed:
+- Manual testing steps
+- Automated tests added
+- Edge cases considered
+
+## Screenshots (if applicable)
+
+Add screenshots for UI changes
+
+## Checklist
+
+- [ ] Code follows project style
+- [ ] Tests pass
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented)
+```
+
+### PR Review Process
+
+1. **Automated Checks**: CI/CD runs tests
+2. **Code Review**: Maintainer reviews code
+3. **Feedback**: Address comments
+4. **Approval**: PR approved by maintainer
+5. **Merge**: Maintainer merges PR
+6. **Branch Cleanup**: Delete feature branch
+
+## Commit Message Guidelines
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `feat` | New feature | `feat(client): add chat system` |
+| `fix` | Bug fix | `fix(server): resolve disconnect crash` |
+| `docs` | Documentation | `docs(readme): update installation steps` |
+| `style` | Code style changes | `style(client): format according to guidelines` |
+| `refactor` | Code refactoring | `refactor(ecs): optimize component storage` |
+| `test` | Test additions | `test(network): add packet parsing tests` |
+| `perf` | Performance | `perf(render): optimize sprite batching` |
+| `chore` | Maintenance | `chore(deps): update SFML to 2.6` |
+
+### Scope
+
+Indicates the affected module:
+- `client`: Client code
+- `server`: Server code
+- `ecs`: ECS framework
+- `network`: Network code
+- `ui`: User interface
+- `docs`: Documentation
+- `build`: Build system
+
+### Subject
+
+- Use imperative mood: "add" not "added"
+- Don't capitalize first letter
+- No period at the end
+- Maximum 50 characters
+
+### Body
+
+- Explain **what** and **why**, not how
+- Wrap at 72 characters
+- Separate from subject with blank line
+
+### Footer
+
+- Reference issues: `Closes #42`
+- Breaking changes: `BREAKING CHANGE: ...`
+
+### Examples
+
+**Simple commit:**
+```
+feat(client): add lobby chat system
+```
+
+**Detailed commit:**
+```
+feat(client): add lobby chat system
+
+Implement text chat in lobby for player communication.
+Includes:
+- ChatWidget component
+- Message history (max 100 messages)
+- Auto-scroll to latest message
+- Player name prefixing
+
+Closes #42
+```
+
+**Bug fix:**
+```
+fix(server): prevent crash on client disconnect
+
+Server would crash when client disconnected during gameplay.
+Added null check before accessing client data.
+
+Fixes #87
+```
+
+**Breaking change:**
+```
+refactor(ecs)!: change component API to use shared_ptr
+
+BREAKING CHANGE: Components now require shared_ptr.
+Update all component additions:
+- Old: addComponent<T>(entity, component)
+- New: addComponent<T>(entity, std::make_shared<T>(...))
+
+Relates to #56
+```
+
+## Advanced Git Techniques
+
+### Interactive Rebase
+
+Clean up commit history before PR:
+
+```bash
+# Rebase last 3 commits
+git rebase -i HEAD~3
+
+# In editor, choose actions:
+# pick = keep commit
+# reword = change message
+# squash = combine with previous
+# drop = remove commit
+
+# Save and close editor
+# Follow prompts if needed
+```
+
+### Cherry-Pick Commits
+
+Apply specific commits from another branch:
+
+```bash
+# Copy commit from another branch
+git cherry-pick <commit-hash>
+
+# Multiple commits
+git cherry-pick <hash1> <hash2> <hash3>
+
+# Range of commits
+git cherry-pick <start-hash>..<end-hash>
+```
+
+### Bisect (Find Bug)
+
+Binary search to find which commit introduced a bug:
+
+```bash
+# Start bisect
+git bisect start
+
+# Mark current as bad
+git bisect bad
+
+# Mark known good commit
+git bisect good <commit-hash>
+
+# Git checks out middle commit
+# Test and mark as good or bad
+git bisect good  # or bad
+
+# Repeat until found
+# Git will identify the commit
+
+# Reset when done
+git bisect reset
+```
+
+### Worktrees
+
+Work on multiple branches simultaneously:
+
+```bash
+# Create worktree
+git worktree add ../r-type-feature feature/new-feature
+
+# Now you have two working directories
+cd ../r-type-feature
+
+# Remove worktree when done
+git worktree remove ../r-type-feature
+```
+
+## Git Configuration
+
+### User Setup
+
+```bash
+# Set name and email
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+
+# Check configuration
+git config --list
+```
+
+### Useful Aliases
+
+```bash
+# Add aliases to ~/.gitconfig
+git config --global alias.st status
+git config --global alias.co checkout
+git config --global alias.br branch
+git config --global alias.ci commit
+git config --global alias.lg "log --graph --oneline --all"
+git config --global alias.unstage "restore --staged"
+
+# Use aliases
+git st        # git status
+git co main   # git checkout main
+git lg        # pretty log
+```
+
+### Editor Configuration
+
+```bash
+# Set default editor
+git config --global core.editor "vim"
+# or
+git config --global core.editor "code --wait"  # VS Code
+```
+
+## Troubleshooting
+
+### Forgot to Create Branch
+
+```bash
+# Made commits on main by mistake
+git checkout -b feature/my-changes
+git checkout main
+git reset --hard origin/main
+git checkout feature/my-changes
+```
+
+### Wrong Branch
+
+```bash
+# Made commits on wrong branch
+git stash
+git checkout correct-branch
+git stash pop
+```
+
+### Merge Conflicts
+
+```bash
+# During merge
+git status  # See conflicting files
+
+# Edit files, remove conflict markers
+# <<<<<<<, =======, >>>>>>>
+
+# After resolving
+git add resolved_files
+git merge --continue
+
+# Or abort and try again
+git merge --abort
+```
+
+### Accidentally Committed Secrets
+
+```bash
+# Remove file from history (BE CAREFUL!)
+git filter-branch --tree-filter 'rm -f secrets.json' HEAD
+
+# Better: use BFG Repo-Cleaner
+# https://rtyley.github.io/bfg-repo-cleaner/
+
+# Then force push
+git push --force
+```
+
+### Large File Issues
+
+```bash
+# Remove large file from history
+git filter-branch --tree-filter 'rm -rf large_file.bin' HEAD
+
+# Or use Git LFS for large files
+git lfs install
+git lfs track "*.bin"
+```
+
+## Resources
+
+- [Git Documentation](https://git-scm.com/doc)
+- [GitHub Flow Guide](https://guides.github.com/introduction/flow/)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Oh Shit, Git!?!](https://ohshitgit.com/)
+
+---
+
+Following this workflow ensures smooth collaboration and maintains code quality!
diff --git a/documentation/docusaurus/docs/INTRO/features.md b/documentation/docusaurus/docs/INTRO/features.md
new file mode 100644
index 000000000..2de9335b0
--- /dev/null
+++ b/documentation/docusaurus/docs/INTRO/features.md
@@ -0,0 +1,159 @@
+---
+sidebar_position: 2
+---
+
+# Key Features
+
+**R-Type** offers a comprehensive gaming experience with modern technical implementations.
+
+## 🚀 Multiplayer Experience
+
+### Real-time Multiplayer
+- **Up to 4 players**: Cooperative gameplay with lobby system
+- **Client-server architecture**: Dedicated server with authoritative game state
+- **Network synchronization**: Smooth gameplay with minimal latency
+- **Cross-platform support**: Windows, Linux, and macOS compatibility
+
+### Lobby System
+- **Unique lobby codes**: Create or join games with 8-character alphanumeric codes
+- **Lobby master**: First player controls game start
+- **Player status**: Ready/not ready state management
+- **Dynamic lobbies**: Multiple concurrent game sessions
+
+## 🔧 Technical Excellence
+
+### Modern C++20
+- Leveraging the latest language features and standards
+- Smart pointers for automatic memory management
+- Templates and concepts for type-safe generic programming
+- Coroutines for asynchronous operations
+
+### ECS Architecture
+- **High-performance**: Entity management with cache-friendly design
+- **Component-based**: Flexible and reusable game logic
+- **System pipeline**: Clear separation of concerns
+- **Scalable**: Handles thousands of entities efficiently
+
+### Dynamic Library Loading
+- Runtime platform-specific implementations
+- Modular architecture for easy extension
+- Platform abstraction layer
+- Plugin system for game mechanics
+
+### Custom Networking
+- **UDP-based protocol**: Low-latency communication
+- **Packet management**: Serialization and deserialization
+- **Delta compression**: Only send state changes
+- **Reliability layer**: Critical packet acknowledgment
+
+### Embedded Assets
+- Self-contained executable
+- No external file dependencies in release mode
+- Automatic asset loading from memory
+- Optimized resource management
+
+## 🎮 Game Features
+
+### Classic Gameplay
+- Faithful recreation of the original R-Type experience
+- Side-scrolling shooter mechanics
+- Enemy wave patterns
+- Challenging difficulty progression
+
+### Power-ups and Weapons
+- Multiple ship configurations
+- Upgradeable weapons
+- Special abilities
+- Force pod companion
+
+### Boss Battles
+- Complex AI patterns
+- Multi-phase encounters
+- Weak point mechanics
+- Rewarding difficulty
+
+### Dynamic Elements
+- Enemy spawning system
+- Configurable level maps
+- JSON-based entity definitions
+- Scriptable behaviors
+
+### Score System
+- Persistent scoring
+- Local leaderboards
+- Achievement tracking
+- Replay system
+
+## 🎨 Graphics and Audio
+
+### Visual Effects
+- **SFML rendering**: Hardware-accelerated graphics
+- **Particle systems**: Explosions and effects
+- **Animations**: Smooth sprite animations
+- **Shaders**: Post-processing effects
+
+### Audio System
+- **Background music**: Dynamic soundtrack
+- **Sound effects**: Positional audio
+- **Volume control**: Separate music/SFX settings
+- **Audio mixing**: Multiple simultaneous sounds
+
+## ♿ Accessibility Features
+
+### Input Remapping
+- **Customizable controls**: Full keyboard and gamepad support
+- **Multiple input devices**: Keyboard, mouse, and gamepad
+- **Saved configurations**: Persistent keybinds
+- **Default mappings**: Preset control schemes
+
+### Visual Accessibility
+- **Color-blind modes**: Deuteranopia, Protanopia, Tritanopia shaders
+- **High contrast mode**: Enhanced visibility
+- **UI scaling**: Adjustable interface size
+- **Health bar options**: Alternative damage indicators
+
+## 🔒 Security and Reliability
+
+### Server Security
+- **Input validation**: Sanitize all client data
+- **Rate limiting**: Prevent spam and DoS attacks
+- **Client ID verification**: Ensure authorized actions
+- **Timeout protection**: Auto-disconnect inactive clients
+
+### Error Handling
+- **Graceful degradation**: Handle network failures
+- **Packet loss recovery**: Client-side prediction
+- **Connection resilience**: Automatic reconnection
+- **Debug logging**: Comprehensive error reporting
+
+## 📊 Performance
+
+### Optimizations
+- **Spatial partitioning**: Efficient collision detection
+- **Object pooling**: Reduce allocations
+- **Multi-threading**: Separate game and network threads
+- **Cache-friendly design**: Memory access patterns
+
+### Monitoring
+- **Performance metrics**: FPS, tick time, latency
+- **Network statistics**: Packet loss, bandwidth usage
+- **Server monitoring**: Active lobbies, player count
+- **Debug overlays**: Real-time performance data
+
+## 🌐 HTTP API
+
+### RESTful Endpoints
+- **Lobby management**: Query active lobbies
+- **Player statistics**: Retrieve game data
+- **Server status**: Health checks and metrics
+- **Configuration**: Runtime server settings
+
+### Frontend Integration
+- **Web dashboard**: Monitor server status
+- **Player profiles**: View statistics
+- **Lobby browser**: Join games via web interface
+- **Admin panel**: Server management tools
+
+---
+
+These features combine to create a robust, performant, and accessible multiplayer gaming experience while demonstrating modern software engineering practices.
diff --git a/documentation/docusaurus/docs/INTRO/installation.md b/documentation/docusaurus/docs/INTRO/installation.md
new file mode 100644
index 000000000..e99db910a
--- /dev/null
+++ b/documentation/docusaurus/docs/INTRO/installation.md
@@ -0,0 +1,324 @@
+---
+sidebar_position: 3
+---
+
+# Installation Guide
+
+This guide covers installing and running Ryan R-Type on all supported platforms.
+
+## 📋 System Requirements
+
+### Minimum Requirements
+- **OS**: Windows 10+, Linux (Ubuntu 20.04+), macOS 11+
+- **CPU**: Dual-core 2.0 GHz
+- **RAM**: 512 MB
+- **Graphics**: OpenGL 3.3 compatible GPU
+- **Network**: Internet connection for multiplayer
+- **Storage**: 100 MB available space
+
+### Recommended Requirements
+- **OS**: Windows 11, Linux (Ubuntu 22.04+), macOS 13+
+- **CPU**: Quad-core 3.0 GHz
+- **RAM**: 2 GB
+- **Graphics**: Dedicated GPU with OpenGL 4.5
+- **Network**: Broadband internet connection
+- **Storage**: 500 MB available space
+
+## 🚀 Quick Start
+
+### Pre-built Binaries (Recommended)
+
+Download the latest release for your platform from the [releases page](https://github.com/AlbanRSS/doc-rtype/releases).
+
+#### Windows
+
+1. Download `r-type-windows-x64.zip`
+2. Extract to your preferred location
+3. Run `r-type_server.exe` to start the server
+4. Run `r-type_client.exe` to start the client
+
+#### Linux
+
+```bash
+# Download and extract
+wget https://github.com/AlbanRSS/doc-rtype/releases/latest/download/r-type-linux-x64.tar.gz
+tar -xzf r-type-linux-x64.tar.gz
+cd r-type
+
+# Run server
+./r-type_server
+
+# Run client (in another terminal)
+./r-type_client -n Player1
+```
+
+#### macOS
+
+```bash
+# Download and extract
+curl -LO https://github.com/AlbanRSS/doc-rtype/releases/latest/download/r-type-macos-x64.tar.gz
+tar -xzf r-type-macos-x64.tar.gz
+cd r-type
+
+# Run server
+./r-type_server
+
+# Run client (in another terminal)
+./r-type_client -n Player1
+```
+
+## 🔨 Building from Source
+
+### Prerequisites
+
+#### All Platforms
+- **C++ Compiler** with C++20 support:
+  - GCC 11+ (Linux)
+  - Clang 12+ (macOS)
+  - MSVC 2019+ (Windows)
+- **CMake**: Version 3.23 or higher
+- **vcpkg**: Package manager for dependencies
+- **Git**: Version control system
+
+#### Installing Prerequisites
+
+**Windows:**
+```cmd
+# Install Visual Studio 2019+ with C++ workload
+# Install CMake from https://cmake.org/download/
+# Install Git from https://git-scm.com/
+
+# Install vcpkg
+git clone https://github.com/Microsoft/vcpkg.git
+cd vcpkg
+bootstrap-vcpkg.bat
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+# Install compiler and build tools
+sudo apt update
+sudo apt install -y build-essential cmake git pkg-config
+
+# Install vcpkg
+git clone https://github.com/Microsoft/vcpkg.git
+cd vcpkg
+./bootstrap-vcpkg.sh
+```
+
+**macOS:**
+```bash
+# Install Xcode Command Line Tools
+xcode-select --install
+
+# Install Homebrew
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install dependencies
+brew install cmake git
+
+# Install vcpkg
+git clone https://github.com/Microsoft/vcpkg.git
+cd vcpkg
+./bootstrap-vcpkg.sh
+```
+
+### Building the Project
+
+#### Unix Systems (Linux/macOS)
+
+```bash
+# Clone the repository
+git clone https://github.com/AlbanRSS/doc-rtype.git
+cd R-Type
+
+# Install dependencies
+./scripts/install_dependencies.sh
+
+# Build the project
+./scripts/compile_project.sh
+
+# Binaries will be in the build directory
+ls build/unix/
+```
+
+#### Windows
+
+```cmd
+REM Clone the repository
+git clone https://github.com/AlbanRSS/doc-rtype.git
+cd R-Type
+
+REM Install dependencies
+.\scripts\install_dependencies.bat
+
+REM Build the project
+.\scripts\compile_project.bat
+
+REM Binaries will be in the build directory
+dir build\windows\
+```
+
+### Build Options
+
+The project supports various build configurations:
+
+```bash
+# Debug build (with symbols and debugging info)
+cmake --preset unix-debug
+cmake --build build/unix-debug
+
+# Release build (optimized)
+cmake --preset unix-release
+cmake --build build/unix-release
+
+# With tests
+cmake --preset unix-release -DBUILD_TESTS=ON
+cmake --build build/unix-release
+ctest --test-dir build/unix-release
+```
+
+## 🎮 Running the Game
+
+### Server
+
+```bash
+# Default configuration (127.0.0.1:4242)
+./r-type_server
+
+# Custom port and IP
+./r-type_server -p 8080 -i 0.0.0.0
+
+# With custom TPS and debug mode
+./r-type_server -p 4242 -i 127.0.0.1 -tps 30 -d
+```
+
+#### Server Arguments
+- `-p <port>`: Port number (default: 4242)
+- `-i <ip>`: IP address to bind (default: 127.0.0.1)
+- `-tps <tps>`: Ticks per second (default: 20)
+- `-d`: Enable debug mode
+- `-h`: Display help
+
+### Client
+
+```bash
+# Connect to localhost
+./r-type_client -n Player1
+
+# Connect to remote server
+./r-type_client -p 8080 -i <server_ip> -n Alice
+
+# Debug mode
+./r-type_client -d
+```
+
+#### Client Arguments
+- `-p <port>`: Server port (default: 4242)
+- `-i <ip>`: Server IP (default: 127.0.0.1)
+- `-n <name>`: Player name
+- `-d`: Enable debug mode
+- `-h`: Display help
+
+## 🐳 Docker (Optional)
+
+For containerized deployment:
+
+```bash
+# Build Docker image
+docker build -t rtype-server .
+
+# Run server
+docker run -p 4242:4242/udp rtype-server
+
+# Run with custom configuration
+docker run -p 8080:8080/udp -e PORT=8080 -e TPS=30 rtype-server
+```
+
+## 🔧 Troubleshooting
+
+### Common Installation Issues
+
+#### vcpkg Dependencies Fail
+```bash
+# Clean vcpkg cache
+rm -rf ~/.vcpkg
+./scripts/install_dependencies.sh
+```
+
+#### CMake Configuration Errors
+```bash
+# Clear CMake cache
+rm -rf build/
+cmake --preset unix-release
+```
+
+#### Compiler Not Found
+```bash
+# Set compiler manually
+export CC=/usr/bin/gcc-11
+export CXX=/usr/bin/g++-11
+./scripts/compile_project.sh
+```
+
+#### Missing Libraries
+```bash
+# Linux: Install development libraries
+sudo apt install libx11-dev libxrandr-dev libxcursor-dev libxi-dev \
+                 libudev-dev libgl1-mesa-dev libglu1-mesa-dev
+
+# macOS: Install via Homebrew
+brew install sfml
+```
+
+### Runtime Issues
+
+#### Port Already in Use
+```bash
+# Check what's using the port
+lsof -i :4242  # Linux/macOS
+netstat -ano | findstr :4242  # Windows
+
+# Use a different port
+./r-type_server -p 8080
+```
+
+#### Permission Denied
+```bash
+# Make scripts executable
+chmod +x ./scripts/*.sh
+
+# Make binaries executable
+chmod +x r-type_server r-type_client
+```
+
+#### Missing Assets
+```bash
+# Ensure you're in the correct directory
+cd /path/to/R-Type
+./r-type_server  # Run from project root
+```
+
+## 📦 Uninstallation
+
+### Remove Binaries
+```bash
+# Linux/macOS
+rm -rf build/
+rm r-type_server r-type_client
+
+# Windows
+rmdir /s build
+del r-type_server.exe r-type_client.exe
+```
+
+### Remove Dependencies
+```bash
+# vcpkg packages are in vcpkg/installed/
+# CMake cache is in build/
+# No system-wide files are installed
+```
+
+---
+
+For additional help, see the [Troubleshooting](../INTRO/troubleshooting.md) section or open an issue on GitHub.
diff --git a/documentation/docusaurus/docs/INTRO/project_overview.md b/documentation/docusaurus/docs/INTRO/project_overview.md
index 338fcc2df..eb91facd2 100644
--- a/documentation/docusaurus/docs/INTRO/project_overview.md
+++ b/documentation/docusaurus/docs/INTRO/project_overview.md
@@ -8,52 +8,6 @@ sidebar_position: 1
 
 **R-Type** is a modern reimplementation of the classic 1990s arcade game, built as a multiplayer 2D space shooter using cutting-edge C++20 technologies. This project demonstrates advanced software engineering principles through a client-server architecture, real-time networking, and a custom Entity-Component-System (ECS) framework.
 
-## 🚀 Key Features
-
-### Multiplayer Experience
-- **Real-time multiplayer**: Up to multiple players in cooperative gameplay
-- **Client-server architecture**: Dedicated server with authoritative game state
-- **Network synchronization**: Smooth gameplay with minimal latency
-- **Cross-platform support**: Windows, Linux, and macOS compatibility
-
-### Technical Excellence
-- **Modern C++20**: Leveraging the latest language features and standards
-- **ECS Architecture**: High-performance entity management system
-- **Dynamic Library Loading**: Runtime platform-specific implementations
-- **Custom Networking**: Optimized TCP/UDP protocol stack
-- **Embedded Assets**: Self-contained executable with no external dependencies
-
-### Game Features
-- **Classic Gameplay**: Faithful recreation of the original R-Type experience
-- **Power-ups and Weapons**: Multiple ship configurations and abilities
-- **Boss Battles**: Challenging encounters with complex AI patterns
-- **Procedural Elements**: Dynamic level generation and enemy spawning
-- **Score System**: Competitive leaderboards and achievements
-
-## 🏗️ Architecture Highlights
-
-### Client-Server Model
-```
-🎮 Client Application    🖥️ Server Application
-├── Game State Machine   ├── Game Logic Engine
-├── Graphics Engine      ├── Physics Simulation
-├── Network Client       ├── Network Server
-└── Input Handling       └── State Synchronization
-```
-
-### Core Technologies
-- **Language**: C++20 with modern memory management
-- **Networking**: ASIO-based TCP/UDP communication
-- **Graphics**: SFML with dynamic library loading
-- **Build System**: CMake with vcpkg dependency management
-- **Testing**: Comprehensive unit and integration tests
-
-### Design Patterns
-- **Entity-Component-System**: For game object management
-- **Observer Pattern**: Event-driven architecture
-- **Strategy Pattern**: Platform abstraction
-- **Factory Pattern**: Object creation and prefabs
-
 ## 🎯 Project Goals
 
 ### Educational Objectives
@@ -64,62 +18,116 @@ sidebar_position: 1
 
 ### Technical Achievements
 - **Performance**: 60 FPS gameplay with efficient memory usage
-- **Scalability**: Support for multiple concurrent players
+- **Scalability**: Support for multiple concurrent players (up to 4 per lobby)
 - **Maintainability**: Modular design with clear separation of concerns
 - **Portability**: Cross-platform compatibility with minimal overhead
 
+## 📈 Learning Outcomes
+
+This project serves as a comprehensive example of:
+- **Systems Programming**: Low-level networking and memory management
+- **Game Architecture**: ECS patterns and real-time systems
+- **Cross-Platform Development**: Platform abstraction and portability
+- **Software Engineering**: Testing, documentation, and maintainability
+- **Modern C++**: Templates, smart pointers, and C++20 language features
+
 ## 📊 Project Structure
 
 ```
-ryanR-type/
+R-Type/
 ├── client/           # 🎮 Game client implementation
+│   ├── Core.cpp/hpp  # Main game loop and initialization
+│   ├── systems/      # Client-side ECS systems (rendering, audio)
+│   ├── components/   # Client-specific components
+│   ├── gsm/          # Game State Machine
+│   └── ui/           # User interface components
 ├── server/           # 🖥️ Game server implementation
-├── common/           # 🔧 Shared ECS and utilities
-├── libs/             # 📚 Core networking and multimedia libraries
-├── assets/           # 🎨 Game sprites, fonts, and audio
+│   ├── Server.cpp    # Server core logic
+│   ├── Lobby.cpp     # Lobby management
+│   ├── systems/      # Server-side ECS systems
+│   └── http/         # HTTP API server
+├── common/           # 🔧 Shared code between client and server
+│   ├── ECS/          # Entity-Component-System framework
+│   ├── components/   # Shared game components
+│   ├── systems/      # Shared systems
+│   ├── packet/       # Network packet definitions
+│   └── utils/        # Utility functions
+├── libs/             # 📚 Core libraries
+│   ├── Network/      # ASIO wrapper
+│   ├── Multimedia/   # SFML wrapper
+│   └── Packet/       # Packet serialization
+├── assets/           # 🎨 Game assets
+│   ├── sprites/      # Character and object sprites
+│   ├── sounds/       # Sound effects
+│   ├── musics/       # Background music
+│   ├── fonts/        # TrueType fonts
+│   └── shaders/      # GLSL shaders (color-blind modes)
+├── configs/          # ⚙️ Configuration files
+│   ├── entities/     # Entity definitions
+│   ├── prefab/       # Prefabricated entities
+│   ├── map/          # Map configurations
+│   └── rules/        # Game rules
 ├── tests/            # 🧪 Unit and integration tests
-├── documentation/    # 📖 Docusaurus documentation site
-└── scripts/          # ⚙️ Build and deployment tools
+├── documentation/    # 📖 Project documentation
+│   ├── docusaurus/   # User documentation (this site)
+│   └── Doxyfile      # API documentation config
+├── scripts/          # ⚙️ Build and utility scripts
+│   ├── install_dependencies.sh
+│   ├── compile_project.sh
+│   └── generate_doc.sh
+└── saves/            # 💾 Persistent game data
+    ├── settings.json
+    ├── keybinds.json
+    ├── accessibility.json
+    └── scores.json
 ```
 
-## 🛠️ Development Environment
-
-### Prerequisites
-- **C++ Compiler**: GCC 9+ or Clang 10+ or MSVC 2019+
-- **CMake**: Version 3.23 or higher
-- **vcpkg**: Package manager for dependencies
-- **Git**: Version control system
+## 🏗️ Architecture Overview
 
-### Quick Start
-```bash
-# Clone the repository
-git clone https://github.com/cafe-sur-cour/ryanR-type.git
-cd ryanR-type
-
-# Install dependencies
-./scripts/install_dependencies.sh
+### Client-Server Model
 
-# Build the project on unix
-./scripts/compile_project.sh
+```
+┌─────────────────────┐         ┌─────────────────────┐
+│   Game Client       │◄───────►│   Game Server       │
+│                     │   UDP    │                     │
+│  ┌───────────────┐  │          │  ┌───────────────┐  │
+│  │ Rendering     │  │          │  │ Game Logic    │  │
+│  │ System        │  │          │  │ (Authoritative)│ │
+│  └───────────────┘  │          │  └───────────────┘  │
+│  ┌───────────────┐  │          │  ┌───────────────┐  │
+│  │ Input Handler │  │  Events  │  │ ECS Systems   │  │
+│  └───────────────┘  ├─────────►│  └───────────────┘  │
+│  ┌───────────────┐  │          │  ┌───────────────┐  │
+│  │ Audio System  │  │  State   │  │ Lobby Manager │  │
+│  └───────────────┘  │◄─────────┤  └───────────────┘  │
+│  ┌───────────────┐  │          │  ┌───────────────┐  │
+│  │ Local Predict │  │          │  │ HTTP API      │  │
+│  └───────────────┘  │          │  └───────────────┘  │
+└─────────────────────┘          └─────────────────────┘
+        │                                  │
+        │                                  │
+        └────────► Network Protocol ◄──────┘
+              (PSJM - Custom UDP)
+```
 
-# Build the project on Windows
-./scriptes/compile_project.bat
+### Key Architecture Principles
 
-# Run the server
-./r-type_server
+1. **Server Authority**: Server maintains the single source of truth
+2. **Client Prediction**: Clients predict movement for responsiveness
+3. **ECS Pattern**: Data-oriented design for performance
+4. **Lobby System**: Multiple concurrent game sessions
+5. **Event-Driven**: Observer pattern for loose coupling
 
-# Run the client (in another terminal)
-./r-type_client
-```
+## 🔗 Documentation Sections
 
-## 📈 Learning Outcomes
+Explore detailed documentation in the following sections:
 
-This project serves as a comprehensive example of:
-- **Systems Programming**: Low-level networking and memory management
-- **Game Architecture**: ECS patterns and real-time systems
-- **Cross-Platform Development**: Platform abstraction and portability
-- **Software Engineering**: Testing, documentation, and maintainability
-- **Modern C++**: Templates, smart pointers, and language features
+- **[Key Features](./features.md)**: Complete feature list
+- **[Installation Guide](./installation.md)**: Setup instructions
+- **[Technologies](./technologies.md)**: Tech stack overview
+- **[Architecture](./project_architecure.md)**: Detailed system design
+- **[Technical Choices](./project_choices.md)**: Design decisions
+- **[Troubleshooting](./troubleshooting.md)**: Common issues and solutions
 
 ## 🤝 Contributing
 
@@ -131,10 +139,15 @@ We welcome contributions! Whether you're interested in:
 
 Please see our [Contributing Guide](../HOW-TO-CONTRIBUTE/htc-intro.md) for detailed information.
 
-## 📄 Documentation
+## 📄 Additional Resources
 
-- **[Architecture](./project_architecure.md)**: Detailed technical architecture
+- **[Client Documentation](../CLIENT/client-intro.md)**: Client implementation details
+- **[Server Documentation](../SERVER/server-intro.md)**: Server architecture and protocols
+- **[ECS Documentation](../ECS/)**: Entity-Component-System framework
+- **[Network Protocol](../NETWORK/)**: PSJM protocol specification
+- **[Security](../SECURITY/)**: Security considerations
 
 ---
 
 **R-Type** represents the culmination of modern software engineering practices applied to game development, providing both an entertaining multiplayer experience and a valuable learning resource for developers interested in high-performance, networked applications.
+
diff --git a/documentation/docusaurus/docs/INTRO/technologies.md b/documentation/docusaurus/docs/INTRO/technologies.md
new file mode 100644
index 000000000..31fb0ec19
--- /dev/null
+++ b/documentation/docusaurus/docs/INTRO/technologies.md
@@ -0,0 +1,339 @@
+---
+sidebar_position: 5
+---
+
+# Technologies and Tools
+
+Overview of the technologies, libraries, and tools used in Ryan R-Type.
+
+## 💻 Programming Languages
+
+### C++20
+The entire project is built using modern C++20, leveraging:
+- **Concepts**: Type constraints for templates
+- **Ranges**: Functional-style data manipulation
+- **Coroutines**: Asynchronous programming (future enhancement)
+- **Modules**: Faster compilation (experimental)
+- **std::span**: Safe array views
+- **std::format**: Type-safe string formatting
+- **Designated initializers**: Cleaner struct initialization
+
+**Why C++20?**
+- High performance for game loops
+- Low-level control over memory
+- Rich ecosystem of libraries
+- Cross-platform compatibility
+
+## 🏗️ Build System
+
+### CMake 3.23+
+Modern CMake features used:
+- **Presets**: Standardized build configurations
+- **FetchContent**: Dependency management
+- **Target-based**: Modern CMake practices
+- **Cross-platform**: Windows, Linux, macOS support
+
+```cmake
+# CMake presets
+cmake --preset unix-release
+cmake --preset windows-release
+```
+
+### vcpkg
+Microsoft's C++ package manager for:
+- SFML (graphics)
+- ASIO (networking)
+- nlohmann/json (JSON parsing)
+- doctest (unit testing)
+
+**Benefits:**
+- Reproducible builds
+- Version control for dependencies
+- Cross-platform package management
+
+## 📚 Core Libraries
+
+### SFML (Simple and Fast Multimedia Library)
+
+**Version:** 2.6+  
+**Purpose:** Graphics, audio, and window management
+
+**Features used:**
+- `sf::RenderWindow`: Window creation and rendering
+- `sf::Sprite`: 2D texture rendering
+- `sf::Shader`: GLSL shaders for effects
+- `sf::Music` / `sf::Sound`: Audio playback
+- `sf::Font` / `sf::Text`: Text rendering
+
+**Why SFML?**
+- Easy to use API
+- Cross-platform
+- Active community
+- Good performance for 2D games
+
+### ASIO (Asynchronous I/O)
+
+**Version:** Standalone ASIO (non-Boost)
+**Purpose:** Network communication
+
+**Features used:**
+- `asio::io_context`: Asynchronous I/O operations
+- `asio::ip::udp::socket`: UDP networking
+- `asio::ip::tcp::socket`: TCP for HTTP server
+- `asio::steady_timer`: Timing operations
+
+**Why ASIO?**
+- Header-only library option
+- Excellent performance
+- Async/await patterns
+- Cross-platform networking
+
+### nlohmann/json
+
+**Version:** 3.11+
+**Purpose:** JSON parsing and serialization
+
+**Usage:**
+- Configuration files
+- Entity definitions (prefabs)
+- Map data
+- Save files
+- HTTP API responses
+
+**Why nlohmann/json?**
+- Modern C++ API
+- Intuitive syntax
+- Comprehensive features
+- Well-documented
+
+```cpp
+// Example usage
+json config = json::parse(file);
+std::string ip = config["server"]["ip"];
+```
+
+## 🧪 Testing Framework
+
+### Doctest
+
+**Purpose:** Unit and integration testing
+
+**Features:**
+- Fast compilation
+- Minimal header-only library
+- BDD-style assertions
+- Test fixtures
+- Parameterized tests
+
+```cpp
+TEST_CASE("Vector addition") {
+    Vector2D a{1, 2};
+    Vector2D b{3, 4};
+    REQUIRE(a + b == Vector2D{4, 6});
+}
+```
+
+**Test coverage areas:**
+- ECS components and systems
+- Network packet serialization
+- Collision detection
+- Game logic
+- Utility functions
+
+## 🔧 Development Tools
+
+### Version Control
+
+**Git** with GitHub:
+- Source code management
+- Collaborative development
+- Issue tracking
+- Pull requests
+- GitHub Actions for CI/CD
+
+### Continuous Integration
+
+**GitHub Actions:**
+- Automated builds on push
+- Multi-platform testing (Linux, Windows, macOS)
+- Code quality checks
+- Test execution
+- Documentation deployment
+
+```yaml
+# Example workflow
+name: Build
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+```
+
+### Documentation
+
+**Docusaurus:**
+- Static site generator
+- React-based
+- Markdown documentation
+- Versioning support
+- Search functionality
+- Mobile-responsive
+
+**Doxygen:**
+- API documentation generation
+- UML diagrams
+- Call graphs
+- PDF export
+- Code navigation
+
+### Code Quality
+
+**Tools used:**
+- **clang-format**: Code formatting
+- **clang-tidy**: Static analysis
+- **cppcheck**: Additional linting
+- **valgrind**: Memory leak detection (Linux)
+- **AddressSanitizer**: Runtime error detection
+
+## 🎨 Asset Creation
+
+### Graphics
+- **Sprites**: PNG with alpha transparency
+- **Animations**: Sprite sheets
+- **Fonts**: TrueType fonts (TTF)
+- **Shaders**: GLSL for visual effects
+
+### Audio
+- **Music**: OGG Vorbis format
+- **Sound Effects**: WAV format
+- **Audio Editing**: Audacity
+
+### Design
+- **Sprite Editor**: Aseprite
+- **Image Editor**: GIMP
+- **Vector Graphics**: Inkscape
+
+## 🌐 Networking
+
+### Protocol
+- **UDP**: Low-latency game state updates
+- **Custom Protocol**: PSJM (Project Synchronization J&M)
+- **Magic Number**: 0x93 for packet validation
+- **Serialization**: Manual binary packing
+
+### HTTP API
+- **Beast** (part of Boost): HTTP server
+- **RESTful**: Standard HTTP methods
+- **JSON**: Response format
+- **CORS**: Cross-origin support
+
+## 📦 Project Structure
+
+### Architecture Pattern
+
+**Entity-Component-System (ECS):**
+```
+Entity: uint32_t ID
+Component: Data-only structs
+System: Logic functions operating on components
+```
+
+**Design Patterns:**
+- **Singleton**: Resource managers
+- **Factory**: Entity creation
+- **Observer**: Event system
+- **Strategy**: Platform abstraction
+
+### Dynamic Libraries
+
+**Platform-specific implementations:**
+- `libs/Multimedia/`: SFML wrapper
+- `libs/Network/`: ASIO wrapper
+- `libs/Packet/`: Serialization
+
+**Benefits:**
+- Hot-reloading (development)
+- Platform abstraction
+- Modular codebase
+- Plugin architecture
+
+## 🐳 Deployment
+
+### Docker
+```dockerfile
+FROM ubuntu:22.04
+RUN apt-get update && apt-get install -y \
+    build-essential cmake
+COPY . /app
+WORKDIR /app
+RUN ./scripts/compile_project.sh
+CMD ["./r-type_server"]
+```
+
+### Package Formats
+- **Linux**: AppImage, DEB, RPM
+- **Windows**: ZIP, Installer (NSIS)
+- **macOS**: DMG, APP bundle
+
+## 🔐 Security
+
+### Libraries
+- **OpenSSL**: Future encryption support
+- **libsodium**: Cryptographic operations
+
+### Practices
+- Input validation
+- Buffer overflow protection
+- Safe integer operations
+- Memory safety (smart pointers)
+
+## 📊 Performance Profiling
+
+### Tools
+- **perf** (Linux): CPU profiling
+- **Instruments** (macOS): Performance analysis
+- **Visual Studio Profiler** (Windows)
+- **Tracy Profiler**: Real-time profiling
+
+### Metrics Tracked
+- Frame time
+- Tick time
+- Network latency
+- Memory usage
+- Cache misses
+
+## 🌍 Cross-Platform Compatibility
+
+### Operating Systems
+- **Linux**: Ubuntu 20.04+, Fedora 35+, Arch
+- **Windows**: Windows 10+, Windows 11
+- **macOS**: macOS 11 (Big Sur)+
+
+### Architectures
+- **x86_64**: Primary support
+- **ARM64**: macOS M1/M2 support
+
+### Compilers
+- **GCC**: 11.0+
+- **Clang**: 12.0+
+- **MSVC**: 2019+
+
+## 📚 Learning Resources
+
+### Documentation
+- [SFML Documentation](https://www.sfml-dev.org/documentation/)
+- [ASIO Documentation](https://think-async.com/Asio/asio-1.22.0/doc/)
+- [CMake Documentation](https://cmake.org/documentation/)
+- [C++20 Reference](https://en.cppreference.com/)
+
+### Books
+- "Game Programming Patterns" by Robert Nystrom
+- "Effective Modern C++" by Scott Meyers
+- "Computer Networking: A Top-Down Approach"
+
+---
+
+This technology stack was carefully chosen to balance performance, maintainability, and developer experience while meeting the project's technical requirements.
diff --git a/documentation/docusaurus/docs/INTRO/troubleshooting.md b/documentation/docusaurus/docs/INTRO/troubleshooting.md
new file mode 100644
index 000000000..8f85125f3
--- /dev/null
+++ b/documentation/docusaurus/docs/INTRO/troubleshooting.md
@@ -0,0 +1,527 @@
+---
+sidebar_position: 4
+---
+
+# Troubleshooting Guide
+
+Common issues and their solutions when using Ryan R-Type.
+
+## 🔌 Connection Issues
+
+### Client Cannot Connect to Server
+
+#### Symptom
+```
+Error: Connection refused
+Failed to connect to 127.0.0.1:4242
+```
+
+#### Causes and Solutions
+
+**1. Server Not Running**
+```bash
+# Start the server first
+./r-type_server
+
+# Verify it's running
+ps aux | grep r-type_server  # Linux/macOS
+tasklist | findstr r-type_server  # Windows
+```
+
+**2. Wrong IP or Port**
+```bash
+# Server
+./r-type_server -p 4242 -i 0.0.0.0
+
+# Client must match
+./r-type_client -p 4242 -i <server_ip>
+```
+
+**3. Firewall Blocking Connection**
+```bash
+# Linux: Allow UDP port
+sudo ufw allow 4242/udp
+
+# Windows: Add firewall rule
+netsh advfirewall firewall add rule name="R-Type" dir=in action=allow protocol=UDP localport=4242
+
+# macOS: System Preferences → Security & Privacy → Firewall → Options
+```
+
+**4. Network Configuration**
+```bash
+# Test connectivity
+ping <server_ip>
+
+# Check if port is reachable
+nc -vz -u <server_ip> 4242  # Linux/macOS
+Test-NetConnection -ComputerName <server_ip> -Port 4242  # PowerShell
+```
+
+### High Latency / Lag
+
+#### Symptom
+- Delayed player movements
+- Rubber-banding effects
+- Packet loss warnings
+
+#### Solutions
+
+**1. Reduce Server TPS**
+```bash
+# Lower tick rate for slower networks
+./r-type_server -tps 15
+```
+
+**2. Check Network Quality**
+```bash
+# Test latency
+ping <server_ip>
+
+# Check packet loss
+ping -c 100 <server_ip>  # Linux/macOS
+ping -n 100 <server_ip>  # Windows
+```
+
+**3. Close Bandwidth-Heavy Applications**
+- Stop downloads/uploads
+- Close streaming services
+- Disable background updates
+
+**4. Use Wired Connection**
+- Ethernet cable instead of Wi-Fi
+- Reduces latency and packet loss
+
+### Timeout / Disconnection
+
+#### Symptom
+```
+Player disconnected: timeout
+Connection lost
+```
+
+#### Solutions
+
+**1. Increase Timeout Value** (requires code modification)
+```cpp
+// In server configuration
+constexpr int TIMEOUT_SECONDS = 10;  // Increase if needed
+```
+
+**2. Check Network Stability**
+```bash
+# Monitor connection
+ping -t <server_ip>  # Windows
+ping <server_ip>  # Linux/macOS (Ctrl+C to stop)
+```
+
+**3. Disable Power Saving**
+- Prevent network adapter from sleeping
+- Disable Wi-Fi power management
+
+## 🖥️ Server Issues
+
+### Port Already in Use
+
+#### Symptom
+```
+Error: Address already in use
+bind: Address already in use
+```
+
+#### Solutions
+
+**1. Use Different Port**
+```bash
+./r-type_server -p 8080
+```
+
+**2. Find and Kill Process Using Port**
+```bash
+# Linux/macOS
+lsof -ti:4242 | xargs kill -9
+
+# Windows
+netstat -ano | findstr :4242
+taskkill /PID <PID> /F
+```
+
+**3. Wait for Port Release**
+```bash
+# Ports in TIME_WAIT state will be released automatically
+# Wait 60-120 seconds or restart system
+```
+
+### HTTP Server Port Conflict (5173)
+
+#### Symptom
+```
+Error: Port 5173 is reserved for HTTP server
+Cannot bind to port 5173
+```
+
+#### Solution
+```bash
+# Use any port except 5173
+./r-type_server -p 4242
+./r-type_server -p 8080
+# But NOT -p 5173
+```
+
+### Server Crashes on Startup
+
+#### Symptom
+```
+Segmentation fault
+Server terminated unexpectedly
+```
+
+#### Solutions
+
+**1. Enable Debug Mode**
+```bash
+./r-type_server -d
+# Check logs for detailed error information
+```
+
+**2. Check Configuration Files**
+```bash
+# Verify JSON files are valid
+ls configs/
+# Ensure all required config files exist
+```
+
+**3. Verify Assets**
+```bash
+# Run from project root directory
+cd /path/to/R-Type
+./r-type_server
+```
+
+**4. Check Permissions**
+```bash
+# Ensure executable has permissions
+chmod +x r-type_server
+
+# Check directory permissions
+ls -la configs/ saves/
+```
+
+## 🎮 Client Issues
+
+### Graphics Not Displaying
+
+#### Symptom
+- Black screen
+- Missing textures
+- No sprites visible
+
+#### Solutions
+
+**1. Update Graphics Drivers**
+```bash
+# Linux: Update system
+sudo apt update && sudo apt upgrade
+
+# macOS: Update via App Store
+# Windows: Update via Device Manager or vendor website
+```
+
+**2. Check OpenGL Support**
+```bash
+# Linux
+glxinfo | grep "OpenGL version"
+
+# Should be 3.3 or higher
+```
+
+**3. Run from Correct Directory**
+```bash
+# Assets are loaded relative to executable
+cd /path/to/R-Type
+./r-type_client
+```
+
+### Low FPS / Performance Issues
+
+#### Symptom
+- Game runs slowly
+- Stuttering or freezing
+- FPS below 30
+
+#### Solutions
+
+**1. Close Background Applications**
+```bash
+# Check system resources
+top  # Linux/macOS
+Task Manager  # Windows
+```
+
+**2. Reduce Graphics Settings** (if configurable)
+- Lower resolution
+- Disable post-processing effects
+- Reduce particle effects
+
+**3. Check System Requirements**
+- Verify CPU/RAM meets minimum requirements
+- Ensure no thermal throttling
+
+**4. Update System**
+```bash
+# Linux
+sudo apt update && sudo apt upgrade
+
+# macOS
+softwareupdate --list
+softwareupdate --install --all
+```
+
+### Audio Issues
+
+#### Symptom
+- No sound
+- Crackling audio
+- Audio desync
+
+#### Solutions
+
+**1. Check Volume Settings**
+```bash
+# Verify system audio is not muted
+# Check in-game audio settings (if available)
+```
+
+**2. Update Audio Drivers**
+```bash
+# Linux: Check PulseAudio/ALSA
+pulseaudio --check
+pulseaudio --start
+
+# Install audio libraries if missing
+sudo apt install libopenal1
+```
+
+**3. Check Audio Device**
+```bash
+# Linux: List audio devices
+aplay -l
+
+# Switch default device if needed
+```
+
+### Input Not Working
+
+#### Symptom
+- Keyboard/gamepad not responding
+- Controls don't match expectations
+
+#### Solutions
+
+**1. Check Input Device**
+```bash
+# Linux: Test keyboard
+xev  # X11
+evtest  # Wayland
+
+# Test gamepad
+jstest /dev/input/js0
+```
+
+**2. Verify Keybindings**
+```bash
+# Check saved keybindings
+cat saves/keybinds.json
+```
+
+**3. Reset to Default**
+```bash
+# Remove custom keybinds
+rm saves/keybinds.json
+# Game will recreate with defaults
+```
+
+## 🔧 Compilation Issues
+
+### Build Fails with CMake Errors
+
+#### Symptom
+```
+CMake Error: Could not find a package configuration file
+```
+
+#### Solutions
+
+**1. Install Dependencies**
+```bash
+./scripts/install_dependencies.sh
+```
+
+**2. Clean Build Directory**
+```bash
+./scripts/clean_project.sh
+./scripts/compile_project.sh
+```
+
+**3. Update vcpkg**
+```bash
+cd vcpkg
+git pull
+./bootstrap-vcpkg.sh  # Linux/macOS
+bootstrap-vcpkg.bat  # Windows
+```
+
+### Compiler Errors
+
+#### Symptom
+```
+error: 'concept' does not name a type
+C++20 features not available
+```
+
+#### Solutions
+
+**1. Check Compiler Version**
+```bash
+# Requires GCC 11+, Clang 12+, or MSVC 2019+
+g++ --version
+clang++ --version
+```
+
+**2. Update Compiler**
+```bash
+# Ubuntu
+sudo apt install gcc-11 g++-11
+
+# Set as default
+sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100
+sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 100
+```
+
+**3. Specify Compiler**
+```bash
+export CC=/usr/bin/gcc-11
+export CXX=/usr/bin/g++-11
+./scripts/compile_project.sh
+```
+
+### vcpkg Dependency Installation Fails
+
+#### Symptom
+```
+Error: Failed to download package
+vcpkg install failed
+```
+
+#### Solutions
+
+**1. Check Internet Connection**
+```bash
+ping github.com
+```
+
+**2. Clear vcpkg Cache**
+```bash
+rm -rf ~/.vcpkg
+./scripts/install_dependencies.sh
+```
+
+**3. Manual vcpkg Bootstrap**
+```bash
+cd vcpkg
+./bootstrap-vcpkg.sh --disableMetrics
+./vcpkg integrate install
+```
+
+## 📁 File Permission Issues
+
+### Permission Denied on Scripts
+
+#### Symptom
+```
+bash: ./scripts/compile_project.sh: Permission denied
+```
+
+#### Solution
+```bash
+# Make all scripts executable
+chmod +x ./scripts/*.sh
+
+# Or individually
+chmod +x ./scripts/install_dependencies.sh
+chmod +x ./scripts/compile_project.sh
+```
+
+### Cannot Write to Save Files
+
+#### Symptom
+```
+Error: Cannot write to saves/settings.json
+Permission denied
+```
+
+#### Solutions
+
+**1. Check Directory Permissions**
+```bash
+ls -la saves/
+chmod 755 saves/
+```
+
+**2. Run with Proper User**
+```bash
+# Don't run as root unless necessary
+./r-type_client
+```
+
+**3. Verify Disk Space**
+```bash
+df -h  # Check available space
+```
+
+## 🐛 Debug Mode
+
+Enable detailed logging to diagnose issues:
+
+```bash
+# Server with debug output
+./r-type_server -d
+
+# Client with debug output
+./r-type_client -d
+```
+
+Debug logs include:
+- Network packet details
+- Entity creation/destruction
+- System execution times
+- Error stack traces
+
+## 📞 Getting Additional Help
+
+If your issue isn't covered here:
+
+1. **Check Documentation**
+   - [Online docs](https://albanrss.github.io/doc-rtype/)
+   - [Installation guide](./installation.md)
+   - [Server documentation](../SERVER/server-intro.md)
+
+2. **Search Existing Issues**
+   - [GitHub Issues](https://github.com/AlbanRSS/doc-rtype/issues)
+   - Use search to find similar problems
+
+3. **Create New Issue**
+   Include:
+   - Operating system and version
+   - Compiler version (for build issues)
+   - Complete error message
+   - Steps to reproduce
+   - Debug logs (if applicable)
+
+4. **Ask the Community**
+   - Project discussions
+   - Stack Overflow (tag: r-type)
+
+---
+
+**Pro Tip:** Always run with `-d` flag when reporting bugs to get detailed logs!
diff --git a/documentation/docusaurus/docs/SECURITY/users-account.md b/documentation/docusaurus/docs/SECURITY/users-account.md
index 8b23c37e7..272f44c89 100644
--- a/documentation/docusaurus/docs/SECURITY/users-account.md
+++ b/documentation/docusaurus/docs/SECURITY/users-account.md
@@ -292,7 +292,7 @@ User accounts are stored in `saves/users.json` with the following structure:
 **Related Documentation:**
 - [RFC Protocol Documentation](../SERVER/rfc.md)
 - [Network Architecture](../../static/pdfs/R-Type-Doc.pdf)
-- [Error Handling](./error-handling.md)
+- [Error Handling](./error_handling.md)
 
 **Code Locations:**
 - Encryption: `common/utils/Encryption.hpp` & `Encryption.cpp`
diff --git a/documentation/docusaurus/docs/SERVER/server-intro.md b/documentation/docusaurus/docs/SERVER/server-intro.md
index 756b54a76..f664946f3 100644
--- a/documentation/docusaurus/docs/SERVER/server-intro.md
+++ b/documentation/docusaurus/docs/SERVER/server-intro.md
@@ -58,6 +58,41 @@ Lobby Creation → Player Joining → Game Start → Game Loop → Game End →
                    Send Status     CAN_START   State      Winner
 ```
 
+### Multi-instance (Lobby) — implementation details
+
+The server runs multiple concurrent game instances using a lobby abstraction. Below are the concrete behaviors and implementation notes (source references in `server/`):
+
+- **Lobby creation flow**
+  - Client requests a new lobby by sending a `REQUEST_LOBBY` packet (see `PACKET_REQUEST_LOBBY` / `ServerReceivePacket::requestCode`).
+  - The server generates a unique alphanumeric lobby code (`Utils::createAlphaNumericCode`) and returns it using `PACKET_SEND_LOBBY_CODE` (`Server::sendCodeLobbyPacket`).
+  - A lightweight `LobbyStruct` is pushed to the server's `_lobbyThreads` immediately; when a real lobby instance is required a `Lobby` object is created and added to `_lobbies`. The `Lobby` is initialized with its own `PacketManager` and `ResourceManager`.
+
+- **Joining a lobby**
+  - Clients join by sending `CONNECT_TO_LOBBY` with the lobby code. The server verifies the code exists and the lobby isn't full, then replies with `PACKET_LOBBY_CONNECT_VALUE` indicating success/failure (`ServerReceivePacket::processConnectToLobby`).
+  - On success the client is added to the `LobbyStruct`'s `_clients` list and the authoritative `Lobby` receives the client via `Lobby::addClient()`; the server maps the client ID to the lobby (`_clientToLobby`) and calls `Lobby::syncExistingEntitiesToClient()` to send current game state.
+  - Banned users are rejected during the join flow (server checks `saves/users.json`).
+
+- **Threading model & lifecycle**
+  - Each active `Lobby` runs its own threads: a `networkLoop` and a `gameLoop`. Threads are started when the lobby master requests game start (`Server::processMasterStart` → `Lobby::startNetworkThread()` and `Lobby::startGameThread()`).
+  - The main `Server` loop handles incoming UDP packets and routes lobby-related packets into the proper lobby by enqueueing packets (see `Server::processIncomingPackets()` and `Lobby::enqueuePacket` / `Lobby::processIncomingPackets`).
+  - When a lobby becomes empty the server stops it: `Server` monitors and calls `Lobby::stop()`; resources and threads are cleaned up in `Server::cleanupClosedLobbies()`.
+
+- **Limits & constants**
+  - Maximum players per lobby is defined in code as `constants::MAX_CLIENT_PER_LOBBY` (value: 4). The server checks this when accepting joins.
+  - There is no explicit hard-coded maximum number of concurrent lobbies — practical limits depend on available CPU/memory and the number of threads created per lobby.
+
+- **Start / stop semantics**
+  - Lobby creation returns a lobby code immediately; the authoritative `Lobby` object and its game threads are only started when the lobby master triggers the start sequence.
+  - If the last player leaves a lobby, the server will stop the lobby and remove its threads/structures automatically.
+
+- **Operational notes / best practices**
+  - The server binds a single UDP port (default `-p 4242`) so running multiple server processes on the same host requires different ports or containerization.
+  - For horizontal scaling (many simultaneous lobbies) run multiple server instances behind a load balancer or partition players by region/port; the current architecture keeps all lobbies in a single process and uses per-lobby threads.
+  - Monitor `active lobbies`, `players per lobby`, and `tick time per lobby` from the built-in HTTP/management endpoint (`HttpServer`) for operational visibility (`Server::getServerInfo`).
+
+See server sources for authoritative behavior: `server/Server.cpp`, `server/ServerReceivePacket.cpp`, `server/ServerSentPacket.cpp`, `server/Lobby.cpp`, `server/Lobby.hpp`.
+
+
 ## Network Protocol
 
 The server implements the PSJM protocol, handling the following packet types:
@@ -94,12 +129,14 @@ The server can be configured through `ServerConfig`:
 ```cpp
 struct ServerConfig {
     uint16_t port;           // Server port (default: 4242)
-    size_t maxPlayers;       // Maximum concurrent players
-    float tickRate;          // Updates per second (default: 20)
-    std::string mapPath;     // Path to map configuration
+    std::string ip;          // IP address to bind to (default: 127.0.0.1)
+    int64_t tps;             // Ticks per second (default: 20)
+    bool isDebug;            // Debug mode flag (default: false)
 };
 ```
 
+Note: Maximum concurrent players is fixed at 4 (MAX_CLIENT constant).
+
 ## Game State Management
 
 Each lobby maintains its own authoritative game state, ensuring isolation between concurrent games.
@@ -211,24 +248,30 @@ Key metrics tracked:
 # Default configuration
 ./r-type_server
 
-# Custom port and map
-./r-type_server --port 8080 --map configs/map/level_02.json
+# Custom port and IP
+./r-type_server -p 8080 -i 0.0.0.0
 
-# Verbose logging
-./r-type_server --verbose
+# With custom TPS and debug mode
+./r-type_server -p 4242 -i 127.0.0.1 -tps 30 -d
 ```
 
 ### Command Line Options
 
 ```
+Usage: ./r-type_server [options]
 Options:
-  --port PORT        Server port (default: 4242)
-  --max-players N    Maximum players (default: 4)
-  --map PATH         Map configuration file
-  --tick-rate HZ     Update frequency (default: 20)
-  --verbose          Enable debug logging
+  -p <port>        Specify the port number (default: 4242) (5173 is reserved for HTTP server)
+  -i <ip_address>  Specify the IP address to bind to (default: 127.0.0.1)
+  -tps <tps>       Specify the TPS (ticks per second) (default: 20)
+  -d               Enable debug mode
+  -h               Display this help message
+
+Example:
+  ./r-type_server -p 4243 -i 127.0.0.1
 ```
 
+Note: The maximum number of clients is fixed at 4 (MAX_CLIENT constant).
+
 ## Security Considerations
 
 - **Rate Limiting**: Prevent spam from malicious clients