Migrate architecture diagrams from PlantUML to Mermaid

.github/copilot-instructions.md

@@ -63,7 +63,7 @@ In case of any conflicting instructions, the following hierarchy shall apply. If
 
 - `/`: Root directory containing the main files and folders. Bicep configuration is stored in `bicepconfig.json`.
 - The following folders are all at the root level:
-    - `assets/`: PlantUML diagrams and images. Static assets such as these should be placed here. Any diagrams should be placed in the /diagrams/src subfolder.
+    - `assets/`: Mermaid diagrams and images. Static assets such as these should be placed here. Any diagrams should be placed in the /diagrams/src subfolder.
     - `infrastructure/`: Contains Jupyter notebooks for setting up various API Management infrastructures. When modifying samples, these notebooks should not need to be modified.
     - `samples/`: Various policy and scenario samples that can be applied to the infrastructures.
     - `setup/`: General setup scripts and configurations for the repository and dev environment setup.
@@ -101,13 +101,17 @@ In case of any conflicting instructions, the following hierarchy shall apply. If
 
 - Use these [configuration settings](https://github.com/microsoft/vscode-jupyter/blob/dd568fde/package.nls.json) as a reference for the VS Code Jupyter extension configuration.
 
-### PlantUML Instructions
+### Mermaid Instructions
 
-- Ensure you verify that all include links are correct and up to date. This link provides a starting point: https://github.com/plantuml-stdlib/Azure-PlantUML/blob/master/AzureSymbols.md
 - Keep diagrams simple. For Azure, include major components, not individual aspects of components. For example, there is no need for individual policies in WAFs or APIs in API Management, Smart Detector Alert Rules, etc.
 - Less is more. Don't be too verbose in the diagrams.
 - Never include subscription IDs, resource group names, or any other sensitive information in the diagrams. That data is not relevant.
-- Don't use the "legend" command if the information is relatively obvious.
+- Use flowchart diagrams for architecture diagrams with left-to-right direction (flowchart LR).
+- Apply consistent styling using classDef for Azure components and custom elements.
+- Use Azure blue (#0078D4) for Azure services, light blue (#ADD8E6) for apps, and light green (#90EE90) for APIs.
+- Use Font Awesome icons (fa:fa-icon-name syntax) to enhance visual clarity where appropriate.
+  - Common icons: fa:fa-cloud (cloud services), fa:fa-database (databases), fa:fa-box (containers), fa:fa-mobile (apps), fa:fa-shield-alt (security)
+  - Note: Mermaid does not support official Azure icons/stencils; use Font Awesome as a best-effort alternative.
 
 ### API Management Policy XML Instructions
 

.vscode/extensions.json

@@ -7,6 +7,7 @@
         "ms-vscode.azurecli",
         "GitHub.copilot",
         "GitHub.copilot-chat",
-        "donjayamanne.vscode-default-python-kernel"
+        "donjayamanne.vscode-default-python-kernel",
+        "bierner.markdown-mermaid"
     ]
 }

.vscode/settings.json

@@ -17,11 +17,6 @@
   "jupyter.kernels.trusted": [
     "./.venv/Scripts/python.exe"
   ],
-  "plantuml.diagramsRoot": "assets/diagrams/src",
-  "plantuml.exportFormat": "svg",
-  "plantuml.exportOutDir": "assets/diagrams/out",
-  "plantuml.java": "C:\\Program Files\\OpenJDK\\jdk-22.0.2\\bin\\java.exe",
-  "plantuml.render": "Local",
   "python.analysis.exclude": [
     "**/node_modules",
     "**/__pycache__",

assets/diagrams/README.md

@@ -1,52 +1,75 @@
-# PlantUML Diagrams
+# Mermaid Diagrams
 
-This directory contains PlantUML diagrams for the Azure API Management architecture.
-Azure Symbols are on [GitHub][azure-symbols].
+This directory contains Mermaid diagrams for the Azure API Management architecture.
 
-## Using PlantUML in VS Code
+## About Azure Icons in Mermaid
+
+**Important**: Unlike PlantUML, Mermaid does not have native Azure-specific stencils or icons. The diagrams in this repository use:
+
+1. **Font Awesome icons** (e.g., `fa:fa-cloud`, `fa:fa-database`) to provide visual context
+2. **Color coding** to distinguish component types:
+   - Azure blue (#0078D4) for Azure services
+   - Light blue (#ADD8E6) for applications
+   - Light green (#90EE90) for APIs
+3. **Clear labels** with Azure service names
+
+### Why Not Official Azure Icons?
+
+- Microsoft provides [official Azure icons](https://learn.microsoft.com/en-us/azure/architecture/icons/) as SVG/PNG files
+- These are designed for tools like Visio, PowerPoint, or Draw.io
+- Mermaid does not support importing custom icon sets directly
+- For high-fidelity branded diagrams, use tools like Draw.io or Visio with official Azure icons
+
+### Font Awesome Icon Support
+
+The diagrams use Font Awesome icons (v5+) with the `fa:fa-icon-name` syntax. Icon support depends on your rendering environment:
+
+- ✅ **Mermaid Live Editor**: Full support
+- ✅ **VS Code with Mermaid extension**: Supported (requires Font Awesome stylesheet)
+- ✅ **GitHub Markdown**: Supported in most renderers
+- ⚠️ **Azure DevOps Wiki**: Limited support (may not render icons)
+- ⚠️ **Some static site generators**: May require Font Awesome CDN configuration
+
+## Using Mermaid in VS Code
 
 1. **Prerequisites**:
-   - Java is installed (e.g. OpenJDK 22)
-   - PlantUML VS Code extension is installed
-   - Graphviz (optional, for more complex diagrams)
-   - Configure PlantUML settings in `.vscode\settings.json`. Ensure that you set the `plantuml.java` path appropriately for your Java executable:
-
-   ```json
-   "plantuml.render": "Local",
-   "plantuml.exportFormat": "svg",
-   "plantuml.java": "C:\\Program Files\\OpenJDK\\jdk-22.0.2\\bin\\java.exe",
-   "plantuml.diagramsRoot": "assets/diagrams/src",
-   "plantuml.exportOutDir": "assets/diagrams/out"
-   ```
+   - Mermaid VS Code extension is installed (recommended: `bierner.markdown-mermaid`)
+   - No additional software required - Mermaid renders natively in Markdown
 
 2. **Viewing Diagrams**:
-   - Open any `.puml` file in this directory
-   - Right-click in the editor and select "PlantUML: Preview Current Diagram"
-   - Alternatively, use the Alt+D keyboard shortcut
+   - Open any `.md` file in the `src` directory
+   - The Mermaid diagrams will render automatically in VS Code's Markdown preview
+   - Use `Ctrl+Shift+V` (Windows/Linux) or `Cmd+Shift+V` (macOS) to open Markdown preview
+   - Right-click in the editor and select "Markdown: Open Preview to the Side" for side-by-side view
 
 3. **Exporting Diagrams**:
-   - Right-click in the editor and select "PlantUML: Export Current Diagram"
-   - Select your desired output format (PNG, SVG, PDF, etc.)
+   - Use the Mermaid CLI for exporting: `npm install -g @mermaid-js/mermaid-cli`
+   - Export to SVG: `mmdc -i diagram.md -o diagram.svg`
+   - Export to PNG: `mmdc -i diagram.md -o diagram.png`
+   - Alternatively, use online tools like [Mermaid Live Editor](https://mermaid.live) for quick exports
 
 ## Troubleshooting
 
-If you encounter issues with PlantUML:
-
-1. **Java Path Issues**:
-   - Ensure Java is on your system PATH
-   - If VS Code terminal can't find Java, try restarting VS Code
-   - You may need to configure the specific Java path in VS Code settings
-
-2. **PlantUML Extension Configuration**:
-   - Open VS Code settings (Ctrl+,)
-   - Search for "plantuml"
-   - Set "plantuml.java" to the path of your Java executable if needed
-   - You can also set "plantuml.jarPath" to a specific PlantUML jar file
+If you encounter issues with Mermaid:
 
-3. **Alternative Rendering**:
-   - If local rendering fails, try using the PlantUML server:
-   - Change "plantuml.render" setting to "PlantUMLServer"
+1. **Diagrams Not Rendering**:
+   - Ensure the Mermaid extension is installed and enabled
+   - Check that Markdown preview is active
+   - Try reloading VS Code
 
+2. **Icons Not Showing**:
+   - Font Awesome icons may not render in all environments
+   - The diagram structure and labels will still be clear without icons
+   - For web rendering, ensure Font Awesome CSS is loaded:
+     ```html
+     <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css">
+     ```
 
+3. **Syntax Errors**:
+   - Validate your Mermaid syntax using [Mermaid Live Editor](https://mermaid.live)
+   - Check for proper indentation and formatting
+   - Ensure all node IDs are unique
 
-[azure-symbols]: https://github.com/plantuml-stdlib/Azure-PlantUML/blob/master/AzureSymbols.md
+4. **Export Issues**:
+   - For CLI exports, ensure `@mermaid-js/mermaid-cli` is installed globally
+   - Check that Puppeteer dependencies are installed (required for mermaid-cli)