diff --git a/readme.md b/readme.md
index a32eab00cd1b6342b8ed2babc6411da26ede372d..ebf0b594d0024cc969b5730caf2856263856d1c7 100644
--- a/readme.md
+++ b/readme.md
@@ -2,214 +2,202 @@
 
 ## 🎮 Overview
 
-This project connects a **browser-based Geometry Dash–style game** with an **Arduino board**.
-The player controls the jumping character using:
+This project is a comprehensive IoT gaming system connecting a **React-based Geometry Dash–style game** with an **Arduino board** and a **real-time monitoring dashboard**.
 
-* A **physical button** connected to the Arduino
-* Or the **space bar** on the keyboard
-* (Optional) Touch input on mobile
+The system is fully containerized using Docker and orchestrated via Docker Compose.
 
-The Arduino communicates with a **Node.js backend**, which relays player actions to the **browser game** using WebSockets. The game sends back **score** and **death statistics**, which the backend forwards to the Arduino. The Arduino displays these values on a **7-segment display**.
+**Key Interactions:**
 
-The whole system is fully bidirectional:
+  * **Player Input:** Controls the character via an **Arduino Button**, Keyboard, or Touch.
+  * **Game Control:** Adjust game speed in real-time using an **Arduino Physical Rotator**.
+  * **Feedback:** Score and Death counts are sent back to the Arduino **7-Segment Display**.
+  * **Monitoring:** A dedicated Monitor Server broadcasts game events to a **React Dashboard** for real-time analytics.
+  * **Persistence:** Game data is buffered and synced to a **PostgreSQL database**.
 
-```
-Arduino (Button) → Node Backend → Game Browser (Jump Input)
-Game Browser (Score/Deaths) → Node Backend → Arduino (Seven Segment Display)
-```
-
----
+-----
 
 # 🧱 **Project Architecture**
 
+The system is split into four main containerized services + a database.
+
 ```
-┌──────────────────────┐     WebSocket       ┌────────────────────────┐
-│  Browser Game (JS)   │  <-------------->   │ Node.js Backend        │
-│ - Canvas runner      │                     │ - Express static server│
-│ - Jump logic         │                     │ - WebSocket server     │
-│ - Obstacle system    │                     │ - SerialPort interface │
-└──────────────────────┘                     └───────────┬────────────┘
-                                                         │ Serial USB
-                                                         ▼
-                                        ┌────────────────────────────────┐
-                                        │ Arduino                        │
-                                        │ - Button input                 │
-                                        │ - Seven segment display output │
-                                        └────────────────────────────────┘
+                           ┌──────────────────┐
+                           │    PostgreSQL    │
+                           │   (Persistence)  │
+                           └────────▲─────────┘
+                                    │ (Buffer 10s)
+                                    │
+┌─────────────────┐        ┌────────▼─────────┐        ┌──────────────────┐
+│  Game Client    │ <----> │   Game Server    │ -----> │  Monitor Server  │
+│ (React + Vite)  │   WS   │ (Node + Serial)  │   WS   │      (Node)      │
+└─────────────────┘        └────────┬─────────┘        └────────┬─────────┘
+                                    │                           │
+                                    │ Serial / USB              │ WS
+                                    ▼                           ▼
+                       ┌──────────────────────────────┐    ┌──────────────────┐
+                       │           Arduino            │    │  Monitor Client  │
+                       │ - Button (Jump)              │    │  (React + Vite)  │
+                       │ - Rotator (Game Speed)       │    └──────────────────┘
+                       │ - 7-Segment (Score Display)  │
+                       └──────────────────────────────┘
 ```
 
----
+
+-----
 
 # 🛠️ **Technologies Used**
 
-### **Frontend**
+### **Frontend (Game & Monitor)**
 
-* HTML5 Canvas
-* CSS responsive layout (mobile-friendly)
-* Vanilla JavaScript game engine
-* WebSocket client
-* Keyboard & touch controls
+  * **React** with **Vite**
+  * TypeScript
+  * HTML5 Canvas (Game Logic)
+  * CSS Responsive Layout
+  * WebSocket Client
 
-### **Backend**
+### **Backend (Game & Monitor Servers)**
 
-* Node.js + Express
-* WebSocket (ws)
-* SerialPort (for Arduino communication)
+  * **Node.js** + Express
+  * **WebSocket** (ws) for real-time communication
+  * **SerialPort** (Hardware Interface)
+  * **PostgreSQL** (Data Persistence)
+  * **Docker** & **Docker Compose** (Containerization)
 
 ### **Hardware**
 
-* Arduino
-* Push button (for jump input)
-* Seven-segment display (via SevSeg library)
+  * Arduino Board
+  * Push Button (Jump Input)
+  * **Physical Rotator/Potentiometer** (Speed Control)
+  * Seven-Segment Display (SevSeg Library)
 
----
+-----
 
-# 🔌 **Setup Instructions**
+# 🔌 **Setup & Installation**
 
-## 1️⃣ Install Dependencies
+The entire stack is Dockerized. You do not need to install Node or Postgres locally to run the full system.
 
-### **Node backend**
+## 1️⃣ Hardware Setup
 
-```bash
-npm install express ws serialport
-```
+1.  Connect the **Button**, **Rotator**, and **7-Segment Display** to your Arduino.
+2.  Upload the sketch found in `arduino/controller/controller.ino`.
+3.  Ensure the Arduino is connected via USB to the machine running the containers.
+
+## 2️⃣ Docker Start (Recommended)
+
+We use **Docker Compose** to bring up services in the correct order:
 
-### **Arduino**
+1.  **PostgreSQL Database**
+2.  **Game Server** (Connects to DB & Arduino)
+3.  **Monitor Server** (Connects to Game Server)
+4.  **Clients** (Game & Monitor Frontends)
 
-Install the **SevSeg** library:
+Run the following command in the root directory:
 
-**Arduino IDE → Sketch → Include Library → Manage Libraries → Search “SevSeg”**
+```bash
+docker-compose up --build
+```
 
----
+*Note: You may need to map the specific USB port in `docker-compose.yml` depending on your OS (e.g., `/dev/ttyUSB0` or `COM3`).*
+
+-----
 
 # 📁 **Project Structure**
 
 ```
-/project
-│
-├── public/
-│   ├── index.html
-│   ├── style.css
-│   └── game.js
-│
-├── server.js        # Node.js backend
-├── arduino.js (optional - for simulation)
-└── README.md
+  .
+  ├── arduino
+  │   └── controller
+  │       └── controller.ino      # Arduino Sketch (Button, Rotator, SevSeg)
+  ├── docker-compose.yml          # Orchestration for DB, Servers, Clients
+  ├── game
+  │   ├── client                  # React + Vite Game Frontend
+  │   │   ├── Dockerfile
+  │   │   └── src/                # Game Logic & Canvas
+  │   └── server                  # Node.js Game Backend
+  │       ├── db/                 # Postgres Connection & Schemas
+  │       ├── Dockerfile
+  │       └── server.js           # Handles Serial, WS, and DB buffering
+  ├── monitor
+  │   ├── client                  # React + Vite Dashboard Frontend
+  │   │   ├── Dockerfile
+  │   │   └── src/                # Charts & Stats Components
+  │   └── server                  # Node.js Monitor Backend
+  │       ├── Dockerfile
+  │       └── monitor-arduino.js  # Broadcasts events to dashboards
+  └── readme.md
 ```
 
----
+-----
 
-# 🖥️ **Frontend Game Features**
+# 🖥️ **Frontend Features**
 
-* Geometry Dash–style gameplay
-* Ground + obstacles moving right→left
-* Player jumps with:
-  * Arduino button (via WebSocket)
-  * Spacebar on keyboard
-  * Touch on mobile
-* Scoring system:
-  * +1 for every obstacle cleared
-* Death detection and game over UI
-* Restart button
-* Fully responsive + centered canvas
+### **Game Client (React)**
 
----
+  * Geometry Dash–style gameplay via Canvas.
+  * **Input Methods:** Arduino Button, Keyboard (Space), Mobile Touch.
+  * **Speed Control:** Listens for speed updates triggered by the **Arduino Rotator**.
 
-# 🌐 **WebSocket Protocol**
+### **Monitor Client (React)**
 
-### **Browser → Backend (Game Events)**
+  * Real-time dashboard visualization.
+  * Displays live Score, Death counts, and Sensor data.
+  * Receives broadcasted data from the Monitor Server.
 
-#### Score update:
+-----
 
-```json
-{
-  "type": "score",
-  "score": 12
-}
-```
+# 💾 **Data Persistence & Protocol**
 
-#### Death event:
+### **Database Strategy**
 
-```json
-{
-  "type": "death",
-  "deaths": 3
-}
-```
+To prevent database throttling during high-frequency game events, the Game Server implements an **In-Memory Buffer**:
 
-### **Backend → Browser (Jump Input)**
+1.  Game events (Score, Death, Jump) are stored temporarily in RAM.
+2.  **Every 10 seconds**, the buffer is flushed and bulk-inserted into **PostgreSQL**.
+3.  **Storage Format:** Records include the Event Data, **Sensor ID**, and **Timestamp**.
 
-Sent when Arduino button is pressed:
+### **WebSocket Protocol**
 
-```json
-{
-  "action": "jump"
-}
-```
+#### **Arduino → Game Server**
 
----
+  * `JUMP` → Trigger player jump.
+  * `SPEED:<value>` → Update game speed based on rotator position.
 
-# 🔁 **Backend Responsibilities**
+#### **Game Server → Monitor Server**
 
-* Serve the frontend game files
-* Maintain WebSocket connections
-* Receive serial events from Arduino (`"JUMP"`)
-* Forward `"jump"` action to browser clients
-* Receive score/death stats from browser
-* Format and send them to Arduino via serial:
+Forwards all game events to the monitor network.
 
-  * `S<number>` for score
-  * `D<number>` for deaths
+#### **Backend → Arduino**
 
-Example:
+  * `S<number>` → Update Score on 7-Segment.
+  * `D<number>` → Update Deaths on 7-Segment.
 
-```
-S15\n   → show score 15 on seven segment
-D3\n    → show deaths 3 on seven segment
-```
+-----
 
----
+# 🔧 **Arduino Logic**
 
-# 🔧 **Arduino Responsibilities**
+The Arduino sketch handles three main tasks:
 
-* Detect button press → send `"JUMP\n"` via Serial
-* Receive messages from backend:
+1.  **Input (Button):** Detects press and sends `JUMP` via Serial.
+2.  **Input (Rotator):** Reads analog value from potentiometer, maps it to a speed factor, and sends `SPEED:<val>` via Serial.
+3.  **Output (Display):** Parses incoming serial data (`S##`, `D##`) to update the 7-segment display.
 
-  * `S##` → update score display
-  * `D##` → update death count
-* Use SevSeg to draw numbers on seven-segment display
+-----
 
-Pseudo-protocol:
+# 🧪 **Testing & Simulation**
 
-```
-PC to Arduino:
-  S42 → set score to 42  
-  D7  → set death count to 7  
+If you do not have the hardware attached, you can still run the stack. The Docker containers will attempt to connect to Serial, but the web interface will function independently (controlled via Keyboard).
 
-Arduino to PC:
-  JUMP → player pressed the button
-```
+To test the **Monitor Dashboard**:
 
----
+1.  Open the Game Client (`http://localhost:port`).
+2.  Open the Monitor Client (`http://localhost:port`).
+3.  Play the game; stats will update in real-time on the Monitor.
 
-# 🧪 **Testing Without Arduino (Virtual Serial Ports)**
 
-You can create paired virtual serial ports (e.g., using `socat` on Linux/macOS or com0com on Windows).
 
-Then run the simulator:
 
-```bash
-node arduino.js
-```
 
-Press Enter to simulate a button press → game character jumps.
 
----
 
-# 📱 **Responsive UI Features**
 
-* Canvas centered via flexbox
-* Scales with `aspect-ratio`
-* Score & Game Over UI positioned relative to game container
-* Mobile-friendly touch support