diff --git a/README.md b/README.md
index c200b51..c5cb731 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
 
 ## About
 
-Waylume Server is the backend component of the Waylume premium VPN service. It interfaces with WireGuard to provide secure VPN tunnels and integrates with Supabase for horizontal scalability. The server is designed to be easily deployed with Docker and can be spun up quickly to expand VPN infrastructure.
+Waylume Server is the backend component of the Waylume premium VPN service. It provides a REST API for WireGuard VPN management and integrates with Supabase for server registration and heartbeat monitoring. The server is designed to be easily deployed with Docker and can be spun up quickly to expand VPN infrastructure.
 
-The server is written in dart and uses ipc/process.run to interact with WireGuard. It is designed to be lightweight and efficient, making it suitable for deployment on various platforms, including cloud services and local servers.
+The server is written in Dart and uses process execution to interact with WireGuard tools. It is designed to be lightweight and efficient, making it suitable for deployment on various platforms, including cloud services and local servers.
 
 ## Architecture
 
@@ -19,4 +19,149 @@ The server is written in dart and uses ipc/process.run to interact with WireGuar
                                                └─────────────────┘
 ```
 
-Client applications communicate exclusively through Supabase, which stores information about available Waylume servers. Each server manages WireGuard connections and registers itself with Supabase for automatic discovery and load distribution.
\ No newline at end of file
+Client applications communicate through Supabase to discover available Waylume servers. Each server manages WireGuard connections via REST API and registers itself with Supabase for automatic discovery and load distribution.
+
+## Features
+
+### Core Functionality
+- **WireGuard Interface Management**: Automatic initialization and configuration of WireGuard server interface
+- **Peer Management**: Create, delete, and configure VPN peers dynamically
+- **Traffic Control**: Speed limiting and data cap enforcement per peer
+- **Server Registration**: Automatic registration with Supabase backend
+- **Health Monitoring**: Continuous heartbeat system for server availability
+
+### API Endpoints
+- `POST /api/peers` - Create new VPN peer with generated keys and configuration
+- `DELETE /api/peers/{publicKey}` - Remove VPN peer
+- `PUT /api/peers/{publicKey}/speed-limit` - Set bandwidth limits for peer
+- `PUT /api/peers/{publicKey}/data-cap` - Set data usage limits for peer
+- `GET /api/peers/{publicKey}/config` - Retrieve peer configuration (not implemented)
+
+### Security Features
+- Peer isolation using iptables rules (prevents peer-to-peer communication)
+- Traffic shaping and quota enforcement
+- Automatic IP address assignment within 10.0.0.0/8 range
+- Secure key generation for each peer
+
+## Prerequisites
+
+- Docker and Docker Compose
+- WireGuard kernel module support
+- Supabase project with `waylume_servers` table
+
+## Environment Variables
+
+Create a `.env` file with the following variables:
+
+```env
+# Supabase Configuration
+SUPABASE_URL=your_supabase_url
+SUPABASE_KEY=your_supabase_anon_key
+
+# Server Configuration
+SERVER_ID=unique_server_identifier
+EXTERNAL_PORT=3000
+```
+
+## Quick Start
+
+### Using Docker Compose (Recommended)
+
+1. Clone the repository
+2. Create your `.env` file with required variables
+3. Run the server:
+
+```bash
+docker-compose up -d
+```
+
+The server will be available on port 3000 (or your configured `EXTERNAL_PORT`).
+
+### Building from Source
+
+1. Install Dart SDK (3.9.0-100.2.beta or later)
+2. Install dependencies:
+```bash
+dart pub get
+```
+3. Compile and run:
+```bash
+dart compile exe lib/main.dart -o waylume_server
+./waylume_server
+```
+
+## Docker Configuration
+
+The Docker setup includes:
+- WireGuard tools and kernel module support
+- iptables for traffic control and peer isolation
+- Network capabilities (`NET_ADMIN`) for interface management
+- UDP port 51820 for WireGuard traffic
+- TCP port 3000 for REST API
+
+## API Usage Examples
+
+### Create a new peer
+```bash
+curl -X POST http://localhost:3000/api/peers
+```
+
+Response:
+```json
+{
+  "success": true,
+  "peer": {
+    "privateKey": "...",
+    "publicKey": "...",
+    "ip": "10.0.0.2"
+  },
+  "config": "[Interface]\nPrivateKey = ...\n..."
+}
+```
+
+### Set speed limit for peer
+```bash
+curl -X PUT http://localhost:3000/api/peers/{publicKey}/speed-limit \
+  -H "Content-Type: application/json" \
+  -d '{"speedKbps": 1000}'
+```
+
+### Set data cap for peer
+```bash
+curl -X PUT http://localhost:3000/api/peers/{publicKey}/data-cap \
+  -H "Content-Type: application/json" \
+  -d '{"dataCapMB": 1024}'
+```
+
+### Delete a peer
+```bash
+curl -X DELETE http://localhost:3000/api/peers/{publicKey}
+```
+
+## Network Architecture
+
+- **WireGuard Interface**: `wg0` on `10.0.0.1/24`
+- **Peer IP Range**: `10.0.0.2` - `10.255.255.254`
+- **WireGuard Port**: `51820/udp`
+- **API Port**: `3000/tcp`
+
+## Logging
+
+The server provides detailed request logging including:
+- Client IP addresses (with proxy header support)
+- User agents
+- Request methods and paths
+- Timestamps
+
+## Development
+
+The project structure:
+```
+lib/
+├── config/          # Supabase configuration
+├── core/            # Utility functions
+├── services/        # Core services (server, heartbeat, wireguard)
+├── web/             # HTTP routes and handlers
+├── wireguard/       # WireGuard-specific functionality
+└── main.dart        # Application entry point
+```
\ No newline at end of file