diff --git a/README.md b/README.md
index b93a395..ffd2923 100644
--- a/README.md
+++ b/README.md
@@ -23,16 +23,74 @@ NAYSAYER helps the data platform team by automatically approving merge requests
 2. **Deploy to Kubernetes/OpenShift**:
    ```bash
    # Configure GitLab token in config/secrets.yaml
-kubectl apply -f config/
+    kubectl apply -f config/
    ```
 
 3. **Configure GitLab webhook** in your dataproduct-config repository:
+
    - URL: `https://your-naysayer-domain.com/webhook`
    - Trigger: Merge Request events
    - Secret: (optional)
 
 ## How It Works
 
+### Working Diagram and Code walkthrough
+
+```mermaid
+flowchart TB
+    %% External System
+    GitLab["Redhat GitLab"]:::external
+    GitLab -->|"Merge Request Event"| Webhook["POST /webhook (Webhook Receiver)"]:::transport
+
+  subgraph "NAYSAYER Container / Pod"
+        direction TB
+        ConfigLoader["Config Loader 
+        (internal/config)"]:::infra
+        Logger["Structured Logger (internal/logging)"]:::infra
+        Health["GET /health
+        (Health Checker)"]:::transport
+        Webhook
+        RulesManager["Rules Manager  (internal/rules/manager)"]:::business
+        WarehouseAnalyzer["Warehouse Analyzer \n(internal/rules/warehouse)"]:::business
+        Decision{"All decreases?"}:::business
+        AutoApprove["Auto-approve Path"]:::business
+        ManualReview["Manual review Path"]:::business
+        GitLabClient["GitLab API Client (internal/gitlab/client)"]:::infra
+    end
+
+    %% ConfigMap/Secrets
+    ConfigMap[(ConfigMap/Secrets Config)]:::infra
+    ConfigMap -->|loads| ConfigLoader
+
+    %% Internal Flow
+    Webhook -->|decode payload| RulesManager
+    RulesManager -->|invoke analyzer| WarehouseAnalyzer
+    WarehouseAnalyzer -->|evaluate diffs| Decision
+    Decision -->|yes| AutoApprove
+    Decision -->|no| ManualReview
+    AutoApprove -->|POST approval| GitLabClient
+    GitLabClient -->|GET changes| RulesManager
+
+    %% Health Check Flow
+    Health -->|returns 200| GitLab
+
+    %% Click Events
+    click Webhook "https://github.com/redhat-data-and-ai/naysayer/blob/main/cmd/main.go"
+    click Health "https://github.com/redhat-data-and-ai/naysayer/blob/main/internal/webhook/health.go"
+    click ConfigLoader "https://github.com/redhat-data-and-ai/naysayer/blob/main/internal/config/config.go"
+    click ConfigMap "https://github.com/redhat-data-and-ai/naysayer/tree/main/config/"
+    click GitLabClient "https://github.com/redhat-data-and-ai/naysayer/blob/main/internal/gitlab/client.go"
+    click RulesManager "https://github.com/redhat-data-and-ai/naysayer/blob/main/internal/rules/manager.go"
+    click WarehouseAnalyzer "https://github.com/redhat-data-and-ai/naysayer/blob/main/internal/rules/warehouse/analyzer.go"
+    click Logger "https://github.com/redhat-data-and-ai/naysayer/blob/main/internal/logging/logger.go"
+
+    %% Styles
+    classDef external fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32;
+    classDef transport fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
+    classDef business fill:#fff8e1,stroke:#f9a825,color:#f9a825;
+    classDef infra fill:#fff3e0,stroke:#ef6c00,color:#ef6c00;
+```
+
 NAYSAYER analyzes changes in `product.yaml` files within the dataproduct-config repository structure:
 
 ```
@@ -75,7 +133,7 @@ warehouses:
 ## Repository Integration
 
 NAYSAYER is designed specifically for the dataproduct-config repository at:
-`/Users/isequeir/go/src/gitlab.com/ddis/repos/dataproduct-config`
+`go/src/gitlab.com/ddis/repos/dataproduct-config`
 
 It understands the DDIS dataproduct structure and focuses only on `product.yaml` files.
 
@@ -186,7 +244,7 @@ The bot analyzes diffs like this:
 
 ```bash
 # Test with mock GitLab webhook payload
-curl -X POST localhost:3000/webhook \
+curl -X POST your-server:3000/webhook \
   -H "Content-Type: application/json" \
   -d '{
     "object_attributes": {
@@ -392,4 +450,4 @@ The goal is to keep this focused on file-based warehouse analysis. Before adding
 
 ## License
 
-Dual licensed under Apache 2.0 and MIT licenses.
\ No newline at end of file
+Dual licensed under Apache 2.0 and MIT licenses.