diff --git a/README.md b/README.md
index a9f4b2a..4bdb3cc 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,14 @@ It's designed to be run as a Docker container and integrated with Traefik v3 for
 *   **Node.js & npm/npx (Optional):** Needed only locally to generate VAPID keys easily. Not required for running the container.
 *   **PWA Push Subscription Details:** You need to obtain the Push Subscription object (containing `endpoint`, `keys.p256dh`, `keys.auth`) from your PWA after the user grants notification permission.
 
+## System Architecture
+
+### Subscription Flow
+![Subscription Flow](/diagrams/subscription-flow.png)
+
+### Interaction Flow
+![Interaction Flow](/diagrams/interaction-flow.png)
+
 ## Project Structure
 
 ## Setup
@@ -41,23 +49,7 @@ It's designed to be run as a Docker container and integrated with Traefik v3 for
     ```
     This will output a Public Key and a Private Key.
 
-3.  **Obtain PWA Push Subscription Details:**
-    *   Your PWA needs to use the Push API to request notification permission from the user.
-    *   When permission is granted, the browser's push service provides a `PushSubscription` object.
-    *   This object typically looks like:
-        ```json
-        {
-          "endpoint": "https://updates.push.services.mozilla.com/...",
-          "expirationTime": null,
-          "keys": {
-            "p256dh": "...",
-            "auth": "..."
-          }
-        }
-        ```
-    *   You need to get this JSON object from your PWA (e.g., display it to the user to copy, send it to a setup endpoint - though that's more complex).
-
-4.  **Configure Environment Variables:**
+3.  **Configure Environment Variables:**
     *   Copy the example `.env` file:
         ```bash
         cp .env.example .env
@@ -75,7 +67,7 @@ It's designed to be run as a Docker container and integrated with Traefik v3 for
         *   `TRAEFIK_SERVICE_HOST`: Your public domain for this service (e.g., `webpush.virtonline.eu`).
         *   `TRAEFIK_CERT_RESOLVER`: The name of your TLS certificate resolver configured in Traefik (e.g., `le`, `myresolver`).
 
-5.  **Configure Traefik Labels:**
+4.  **Configure Traefik Labels:**
     *   Copy the example `labels` file:
         ```bash
         cp labels.example labels
@@ -85,9 +77,9 @@ It's designed to be run as a Docker container and integrated with Traefik v3 for
         *   `traefik.http.routers.flic-webhook.tls.certresolver=${TRAEFIK_CERT_RESOLVER}` becomes `traefik.http.routers.flic-webhook.tls.certresolver=myresolver`.
         *   `traefik.http.services.flic-webhook.loadbalancer.server.port=${PORT}` becomes `traefik.http.services.flic-webhook.loadbalancer.server.port=3000`.
 
-6.  **Prepare Subscription Mapping File:**
-    *   Create the `subscriptions.json` file (or edit the template provided).
-    *   Add entries mapping your Flic button's serial number (as a lowercase string key) to the PWA `PushSubscription` object obtained in step 3.
+5.  **Prepare Subscription Mapping File:**
+    *   Edit the `subscriptions.json` file
+    *   Add entries mapping your Flic button's serial number (as a lowercase string key) to the PWA `PushSubscription` object.
         ```json
         {
           "80:e4:da:70:xx:xx:xx:xx": { // <-- Replace with your actual Flic Button Serial (lowercase recommended)
diff --git a/diagrams/interaction-flow.mmd b/diagrams/interaction-flow.mmd
new file mode 100644
index 0000000..700d01e
--- /dev/null
+++ b/diagrams/interaction-flow.mmd
@@ -0,0 +1,8 @@
+stateDiagram-v2
+    [*] --> FlicButton : Button Press
+    FlicButton --> Bluetooth : Transmit Signal
+    Bluetooth --> Phone : Receive Signal
+    Phone --> WebhookWebPushService : Send Webhook
+    WebhookWebPushService --> GooglePushAPI : Forward Notification
+    GooglePushAPI --> PWA : Push Notification
+    PWA --> [*] : Handle Notification
\ No newline at end of file
diff --git a/diagrams/interaction-flow.png b/diagrams/interaction-flow.png
new file mode 100644
index 0000000..6141bb9
Binary files /dev/null and b/diagrams/interaction-flow.png differ
diff --git a/diagrams/subscription-flow.mmd b/diagrams/subscription-flow.mmd
new file mode 100644
index 0000000..cca194e
--- /dev/null
+++ b/diagrams/subscription-flow.mmd
@@ -0,0 +1,7 @@
+stateDiagram-v2
+    [*] --> PWA : User Initiates
+    PWA --> GooglePushAPI : Request Subscription
+    GooglePushAPI --> PWA : Return Subscription Info
+    PWA --> WebhookWebPushService : Store Subscription Info
+    WebhookWebPushService --> PWA : Confirmation
+    [*] --> Complete
\ No newline at end of file
diff --git a/diagrams/subscription-flow.png b/diagrams/subscription-flow.png
new file mode 100644
index 0000000..1a9f594
Binary files /dev/null and b/diagrams/subscription-flow.png differ