diff --git a/README.md b/README.md
index 02d12b7..edba2fd 100644
--- a/README.md
+++ b/README.md
@@ -2,14 +2,120 @@
 
 <small>For more about LNBits extension check [this tutorial](https://github.com/lnbits/lnbits/wiki/LNbits-Extensions)</small>
 
-`nostrclient` is an always-on extension that can open multiple connections to nostr relays and act as a multiplexer for other clients: You open a single websocket to `nostrclient` which then sends the data to multiple relays. The responses from these relays are then sent back to the client.
+## Overview
 
-![2023-03-08 18 11 07](https://user-images.githubusercontent.com/93376500/225265727-369f0f8a-196e-41df-a0d1-98b50a0228be.jpg)
+`nostrclient` is an always-on Nostr relay multiplexer that simplifies connecting to multiple Nostr relays. Instead of your Nostr client managing connections to dozens of relays, you connect to a single WebSocket endpoint provided by `nostrclient`, which then fans out your requests to all configured relays and aggregates the responses back to you.
 
-### Troubleshoot
+### Why Use This?
 
-The `Test Endpoint` functionality heps the user to check that the `nostrclient` web-socket endpoint works as expected.
+- **Simplified Client Configuration** - Connect to one endpoint instead of managing multiple relay connections
+- **Always-On Connectivity** - Your LNbits instance maintains persistent connections to relays
+- **Resource Efficient** - Share relay connections across multiple clients
+- **Subscription Management** - Automatic subscription ID rewriting prevents conflicts between clients
 
-The LNbits user can DM itself (or a temp account) from `nostrclient` and verify that the messages are sent and received correctly.
+## Architecture
+
+```mermaid
+flowchart LR
+    A[Client A] -->|WebSocket| N
+    B[Client B] -->|WebSocket| N
+    C[Client C] -->|WebSocket| N
+
+    N[nostrclient<br/>Router] -->|Fan Out| R1[Relay A]
+    N -->|Fan Out| R2[Relay B]
+    N -->|Fan Out| R3[Relay C]
+    N -->|Fan Out| R4[Relay D]
+
+    R1 -.->|Aggregate| N
+    R2 -.->|Aggregate| N
+    R3 -.->|Aggregate| N
+    R4 -.->|Aggregate| N
+```
+
+**Key Feature:** The router rewrites subscription IDs to prevent conflicts when multiple clients use the same IDs.
+
+## Features
+
+- **Multi-Relay Multiplexing** - Connect to multiple Nostr relays through a single WebSocket
+- **Public & Private Endpoints** - Configurable public and private WebSocket access
+- **Automatic Reconnection** - Failed relays are automatically retried with exponential backoff
+- **Subscription Deduplication** - Events are deduplicated before being sent to clients
+- **Health Monitoring** - Track relay connection status, latency, and error rates
+- **Test Endpoint** - Send test messages to verify your setup is working
+
+## How It Works
+
+1. **Client Connection** - Your Nostr client connects to the nostrclient WebSocket endpoint
+2. **Subscription Rewriting** - Each subscription ID is rewritten to prevent conflicts between multiple clients
+3. **Fan-Out** - Subscription requests are sent to all configured relays
+4. **Aggregation** - Events from all relays are collected and deduplicated
+5. **Response** - Events are sent back to the client with the original subscription ID
+
+## Configuration
+
+### WebSocket Endpoints
+
+- **Public Endpoint**: `/api/v1/relay` - Available to anyone (if enabled)
+- **Private Endpoint**: `/api/v1/{encrypted_id}` - Requires valid encrypted endpoint ID
+
+Configure endpoint access in the extension settings:
+- `private_ws` - Enable/disable private WebSocket access
+- `public_ws` - Enable/disable public WebSocket access
+
+### Adding Relays
+
+Use the nostrclient UI to add/remove Nostr relays. The extension will automatically:
+- Connect to new relays
+- Publish existing subscriptions to new relays
+- Monitor relay health and reconnect as needed
+
+## Testing
+
+### Test Endpoint Functionality
+
+The `Test Endpoint` feature helps verify that your nostrclient WebSocket endpoint works correctly.
+
+**How to test:**
+1. Navigate to the nostrclient extension in LNbits
+2. Use the Test Endpoint feature
+3. Send a DM to yourself (or a temporary account)
+4. Verify that messages are sent and received correctly
 
 https://user-images.githubusercontent.com/2951406/236780745-929c33c2-2502-49be-84a3-db02a7aabc0e.mp4
+
+## Troubleshooting
+
+### Connection Issues
+
+- **Check relay status** - View relay health in the nostrclient UI
+- **Verify endpoint configuration** - Ensure public_ws or private_ws is enabled
+- **Check logs** - Review LNbits logs for connection errors
+
+### Subscription Not Receiving Events
+
+- **Verify relays are connected** - Check the relay status in the UI
+- **Test with known event** - Use the Test Endpoint to verify connectivity
+- **Check relay compatibility** - Some relays may not support all Nostr features
+
+## Development
+
+This extension uses `uv` for dependency management.
+
+### Quick Start
+
+```bash
+# Format code
+make format
+
+# Run type checks and linting
+make check
+
+# Run tests
+make test
+```
+
+For more development commands, see the [Makefile](./Makefile).
+
+## License
+
+MIT License - see [LICENSE](./LICENSE)