diff --git a/README.md b/README.md
index e69de29..563ef1d 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,204 @@
+# GDevelop MMO Test Project
+
+A small multiplayer game experiment built with **GDevelop**, **MQTT**, and **JSON Server**.
+
+The goal of this project is to learn how real-time multiplayer game systems work by building a simple top-down multiplayer environment from scratch.
+
+This is not intended to be a production MMO. It is a learning project focused on networking concepts, client/server communication, player synchronization, and game architecture.
+
+## Project Goals
+
+* Learn multiplayer game architecture
+* Experiment with real-time player movement synchronization
+* Build a lightweight backend using self-hosted tools
+* Learn how game clients communicate with servers
+* Explore Docker-based deployment
+* Create a foundation that could support small LAN multiplayer games
+
+## Current Technology Stack
+
+### Game Client
+
+**GDevelop**
+
+Used for:
+
+* Game logic
+* Scenes/rooms
+* Player movement
+* Object spawning
+* UI
+* Networking events
+
+### Real-Time Communication
+
+**MQTT (Mosquitto)**
+
+Used for:
+
+* Player join events
+* Player movement events
+* Player leave events
+* Room-based communication
+
+Players communicate through MQTT topics based on their current room.
+
+### Database/API
+
+**JSON Server**
+
+Used for:
+
+* Player accounts
+* Persistent player information
+* Player location data
+* Player status
+
+Current player data includes:
+
+* Username
+* Password
+* Player color
+* Current room
+* Last room
+* X/Y position
+* Online status
+
+## Current Multiplayer Design
+
+Players are separated into rooms/scenes.
+
+When a player enters a room:
+
+1. The client updates its current room.
+2. The client queries JSON Server for existing players in that room.
+3. Existing players are spawned locally.
+4. The player publishes a join message over MQTT.
+
+Example join message:
+
+```json
+{
+  "type": "join",
+  "player_id": 1,
+  "x": 320,
+  "y": 192,
+  "color": "player_color"
+}
+```
+
+## Movement Synchronization
+
+The current movement system uses MQTT messages to synchronize players.
+
+Movement events include:
+
+### Move Start
+
+Sent when a movement key is pressed.
+
+Example:
+
+```json
+{
+  "type": "move_start",
+  "player_id": 1,
+  "angle": 0
+}
+```
+
+### Move Stop
+
+Sent when the key is released.
+
+Includes the player's final position:
+
+```json
+{
+  "type": "move_stop",
+  "player_id": 1,
+  "x": 450,
+  "y": 200
+}
+```
+
+This allows clients to predict movement locally while periodically correcting position.
+
+## Backend Services
+
+A future goal is to package the backend into Docker containers.
+
+Planned services:
+
+* MQTT broker
+* JSON Server
+* Python utility service
+
+The Python service may eventually handle:
+
+* Server time
+* Day/night cycle management
+* Player timeout detection
+* Offline status cleanup
+* Server-side events
+
+## Project Structure
+
+Planned structure:
+
+```
+GameProject/
+│
+├── gdevelop/
+│   ├── Game project files
+│   └── Assets
+│
+├── docker/
+│   ├── MQTT configuration
+│   ├── JSON Server configuration
+│   └── Utility services
+│
+├── database/
+│   └── db.json
+│
+└── README.md
+```
+
+## Current Status
+
+Working:
+
+* Player registration
+* Player login
+* Room switching
+* MQTT communication
+* Player spawning
+* Multiple players visible in the same room
+* Basic player synchronization
+
+In Progress:
+
+* Improved movement synchronization
+* Better player disconnect handling
+* Server-controlled time system
+* Additional game mechanics
+
+## Future Ideas
+
+Possible future features:
+
+* Real-time day/night cycle
+* Calendar events
+* NPCs
+* Persistent world state
+* Inventory system
+* Chat system
+* Small LAN multiplayer deployment
+
+## Disclaimer
+
+This project is primarily a learning exercise.
+
+The current architecture is designed for experimentation and small-scale multiplayer use. It is not intended to be a secure public-facing MMO backend.
+
+Security, authentication, and server authority would need significant improvements before public deployment.