diff --git a/README.md b/README.md
index b07db13..429878b 100644
--- a/README.md
+++ b/README.md
@@ -1,42 +1,121 @@
+# ISP Wiremap Application
 
+A web-based mapping application for managing ISP network infrastructure with real-time collaboration features.
 
-## run migrations
+## Tech Stack
+
+- **Backend:** FastAPI with Python 3, PostgreSQL 15 with PostGIS
+- **Frontend:** React 19 with TypeScript, Vite, Leaflet for mapping
+- **Authentication:** JWT tokens with bcrypt password hashing
+- **Real-time:** WebSockets for collaborative editing
+
+## Getting Started
+
+### Run Migrations
+
+```bash
 docker compose exec python alembic upgrade head
+```
 
+### Start the Application
+
+```bash
+docker compose up -d
+```
+
+The application will be available at `http://localhost:8000`
+
+## User Management
+
+### Create Admin User
+
+Interactively create a new admin user with username, email, and password:
+
+```bash
+docker compose exec python python scripts/create_admin.py
+```
+
+### List Users
+
+View all users in the system with their details (username, email, admin status, creation date):
+
+```bash
+docker compose exec python python scripts/manage_users.py list
+```
+
+### Reset User Password
+
+Reset a user's password by providing their username, email, or user ID:
+
+```bash
+docker compose exec python python scripts/manage_users.py reset-password <username|email|user_id>
+```
+
+### Delete User
+
+Delete a user from the system (requires confirmation, affects all their maps and shares):
+
+```bash
+docker compose exec python python scripts/manage_users.py delete <username|email|user_id>
+```
+
+### Toggle Admin Status
+
+Grant or revoke admin privileges for a user:
+
+```bash
+docker compose exec python python scripts/manage_users.py toggle-admin <username|email|user_id>
+```
+
+## Production Deployment
+
+Example Docker Compose configuration for production:
 
 ```yaml
 services:
-   app:
-      hostname: mapmaker
-      image: git.shihaam.dev/sarlink/mapmaker/api
-      env_file: .env
-      volumes:
-        - ./storage/images:/var/www/html/storage/images
-      depends_on:
-        - postgres
+  app:
+    hostname: mapmaker
+    image: git.shihaam.dev/sarlink/mapmaker/api
+    env_file: .env
+    volumes:
+      - ./storage/images:/var/www/html/storage/images
+    depends_on:
+      - postgres
 
-   nginx:
-      hostname: mapmaker-nginx
-      image: git.shihaam.dev/sarlink/mapmaker/nginx
-      volumes_from:
-        - app
-      ports:
-        - 8000:80
-      depends_on:
-        - app
+  nginx:
+    hostname: mapmaker-nginx
+    image: git.shihaam.dev/sarlink/mapmaker/nginx
+    volumes_from:
+      - app
+    ports:
+      - 8000:80
+    depends_on:
+      - app
 
-   postgres:
-      image: postgis/postgis:15-3.3
-      hostname: database
-      restart: always
-      environment:
-       POSTGRES_USER: mapmaker
-       POSTGRES_PASSWORD: mapmaker
-       POSTGRES_DB: mapmaker
-      volumes:
-        - ./storage/database:/var/lib/postgresql/data
-#     ports:
-#       - "5432:5432"
+  postgres:
+    image: postgis/postgis:15-3.3
+    hostname: database
+    restart: always
+    environment:
+      POSTGRES_USER: mapmaker
+      POSTGRES_PASSWORD: mapmaker
+      POSTGRES_DB: mapmaker
+    volumes:
+      - ./storage/database:/var/lib/postgresql/data
+    # ports:
+    #   - "5432:5432"
 ```
-## prod docker compose.yml
 
+## Environment Configuration
+
+Copy `.env.example` to `.env` and configure the required variables:
+
+- `SECRET_KEY` - JWT secret key for token signing
+- `DATABASE_URL` - PostgreSQL connection string
+- `ALLOW_REGISTRATION` - Enable/disable public user registration (default: false)
+- `ACCESS_TOKEN_EXPIRE_MINUTES` - JWT access token lifetime (default: 30)
+- `REFRESH_TOKEN_EXPIRE_DAYS` - JWT refresh token lifetime (default: 7)
+
+## License
+
+GPL v2