diff --git a/mermaid_diagrams/README.md b/mermaid_diagrams/README.md
index bc70682..cbdc83d 100644
--- a/mermaid_diagrams/README.md
+++ b/mermaid_diagrams/README.md
@@ -1,5 +1,34 @@
-# Diagrams
+# Mermaid Diagrams
+
+This folder contains examples of using [Mermaid](https://mermaid.js.org/) to create diagrams for notional Platform-as-a-Service (PaaS) architectures and related workflows. These examples demonstrate how to visually represent complex systems and processes using Mermaid's syntax.
+
+## Examples
+
+### 1. **Cloud Foundry PaaS on AWS**
+   - A diagram illustrating the architecture of a Cloud Foundry-based PaaS deployed on AWS.
+   - This example highlights the key components and their relationships within the PaaS environment.
+
+### 2. **User Request Flow in a Multi-Partition Application**
+   - Two optional paths for user requests to flow in an application built across AWS Commercial and AWS GovCloud partitions.
+   - These diagrams show how requests are routed and processed in a multi-partition setup.
+
+### 3. **Mermaid-Based Menu**
+   - An example of creating a menu using Mermaid's `click` directive to link to other diagrams or resources.
+   - **Note**: The `click` directive does not work in GitHub's Mermaid preview. To view this menu with full functionality, use the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) or host it in an environment that supports interactive Mermaid features.
+
+## How to Use
+1. Clone this repository:
+```
+   git clone https://github.com/YourUsername/example-projects.git
+```
+2. Navigate to the mermaid_diagrams folder:
+```
+cd example-projects/mermaid_diagrams
+```
+3. Open the .mmd files in a text editor or use the Mermaid Live Editor to render the diagrams.
+
+## References
+- [Mermaid Documentation](https://mermaid.js.org/)
+- [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/)
 
-This is a working area for Mermaid diagrams representing notional PaaS arthitecture
 
-Ref: https://mermaid.js.org/
diff --git a/mermaid_diagrams/generic-paas.mmd b/mermaid_diagrams/generic-paas.mmd
index be5170e..5eacb16 100644
--- a/mermaid_diagrams/generic-paas.mmd
+++ b/mermaid_diagrams/generic-paas.mmd
@@ -1,6 +1,12 @@
-%%Generic PaaS diagram
+---
+title: Generic PaaS Architecture
+config:
+  layout: elk
+  elk:
+    mergeEdges: true
+---
 
-flowchart TD
+flowchart TB
 
 %%External entities or services
 customer{Web App Customers}
@@ -10,52 +16,41 @@ admin{System Administrators}
 subgraph Cloud PaaS
   subgraph AWS Commercial Org
     subgraph Web Access Account
-      route53[route53]
-      cloudfront[cloudfront]
+      route53[Route 53]
+      cloudfront[CloudFront]
     end
     subgraph Commercial Transit Account
-      awsnetfirewall[AWS Advanced Network Firewall]
+      awsnetfirewall[AWS Network Firewall]
       awsXit[AWS Transit Gateway]
     end
   end
   subgraph AWS GovCloud Org
-      subgraph prod1[Prod Account 1]
-        subgraph VPC Prod
-          ALB[ALB]
-          subgraph Container Management
-          auth[auth]
-          appContainer{Web Front End}
-          end
-        end
-      end
-      subgraph security[Monitoring and Security Account]
-        vulnScanner[Vulnerability Scanners]
-        awsXitVuln[AWS Transit Gateway]
-        logging[Centralized Logging]
-      end
-      subgraph transitG[GovCloud Transit Account]
-        awsXitG[AWS Transit Gateway]
-        awsnetfirewallG[AWS Advanced Network Firewall]
-      end
-      subgraph orchestration[Orchestration Account]
-        orchestrator[Platform Orchestrator Tools]
-      end
-      subgraph dev[Dev Account]
-        devResources[Dev Resources]
-      end
-      subgraph stage[Staging Account]
-        stageResources[Staging Resources]
-      end
+    subgraph Prod Accounts
+      ALB[Application Load Balancer]
+      appContainer{Web Front End}
+      auth[Authentication Service]
+    end
+    subgraph Security
+      vulnScanner[Vulnerability Scanners]
+      logging[Centralized Logging]
+    end
+    subgraph Transit
+      awsXitG[AWS Transit Gateway]
+      awsnetfirewallG[AWS Network Firewall]
+    end
+    subgraph Orchestration
+      orchestrator[Platform Orchestrator Tools]
+    end
+    subgraph Dev and Stage
+      devResources[Dev Resources]
+      stageResources[Staging Resources]
+    end
   end
 end
 
 %%Connections
-cloudfront -- Web HTTPS 443 --> ALB
-customer -- Web HTTPS 443 --> cloudfront
-ALB -- Web HTTPS 443 --> appContainer
-admin -- Web or CLI --> awsnetfirewall
-awsnetfirewall -- Web or CLI --> awsXit
-awsXit -- Web or CLI --> awsXitG
-awsXitG --> orchestration
-orchestration <--control--> dev & stage & prod1
-security <-.audits.-> dev & stage & prod1 & transitG
+customer -->|HTTPS 443| cloudfront -->|HTTPS 443| ALB -->|HTTPS 443| appContainer
+admin -->|Web or CLI| awsnetfirewall --> awsXit --> awsXitG
+awsXitG --> orchestrator
+orchestrator --> devResources & stageResources & appContainer
+Security -.audits.-> devResources & stageResources & appContainer