diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 88fff94f..3a799454 100644
--- a/.github/copilot-instructions.md
+++ b/.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
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 3a74d06a..961901aa 100644
--- a/.vscode/extensions.json
+++ b/.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"
]
}
diff --git a/.vscode/settings.json b/.vscode/settings.json
index e3dede2e..f878eff4 100644
--- a/.vscode/settings.json
+++ b/.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__",
diff --git a/assets/diagrams/README.md b/assets/diagrams/README.md
index 010336d0..70c2f920 100644
--- a/assets/diagrams/README.md
+++ b/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
+
+ ```
+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)
diff --git a/assets/diagrams/out/afd-apim-aca-architecture/Azure Front Door, API Management & Container Apps Architecture.svg b/assets/diagrams/out/afd-apim-aca-architecture/Azure Front Door, API Management & Container Apps Architecture.svg
deleted file mode 100644
index a6dc9c58..00000000
--- a/assets/diagrams/out/afd-apim-aca-architecture/Azure Front Door, API Management & Container Apps Architecture.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/assets/diagrams/out/apim-aca-architecture/API Management & Container Apps Architecture.svg b/assets/diagrams/out/apim-aca-architecture/API Management & Container Apps Architecture.svg
deleted file mode 100644
index 6bdeac1a..00000000
--- a/assets/diagrams/out/apim-aca-architecture/API Management & Container Apps Architecture.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/assets/diagrams/out/apim-simple-architecture/Simple API Management Architecture.svg b/assets/diagrams/out/apim-simple-architecture/Simple API Management Architecture.svg
deleted file mode 100644
index 52c286e9..00000000
--- a/assets/diagrams/out/apim-simple-architecture/Simple API Management Architecture.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/assets/diagrams/out/appgw-pe-apim-aca-architecture/Azure Application Gateway, API Management & Container Apps Architecture.svg b/assets/diagrams/out/appgw-pe-apim-aca-architecture/Azure Application Gateway, API Management & Container Apps Architecture.svg
deleted file mode 100644
index 2a5ea1db..00000000
--- a/assets/diagrams/out/appgw-pe-apim-aca-architecture/Azure Application Gateway, API Management & Container Apps Architecture.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/assets/diagrams/src/afd-apim-aca-architecture.md b/assets/diagrams/src/afd-apim-aca-architecture.md
new file mode 100644
index 00000000..26b93882
--- /dev/null
+++ b/assets/diagrams/src/afd-apim-aca-architecture.md
@@ -0,0 +1,20 @@
+# Azure Front Door, API Management & Container Apps Architecture
+
+```mermaid
+flowchart LR
+ apps([fa:fa-mobile Apps]):::appStyle
+ afd[fa:fa-door-open Azure Front Door]:::azureStyle
+ apim[fa:fa-cloud API Management]:::azureStyle
+ aca[fa:fa-box Container Apps]:::azureStyle
+ appinsights[fa:fa-chart-line Application Insights]:::azureStyle
+ loganalytics[fa:fa-database Log Analytics]:::azureStyle
+
+ apps -->|API Consumers| afd
+ afd -->|Routes traffic| apim
+ apim -->|Backend| aca
+ apim -->|Sends telemetry| appinsights
+ appinsights -->|Stores data| loganalytics
+
+ classDef appStyle fill:#ADD8E6,stroke:#333,stroke-width:2px
+ classDef azureStyle fill:#0078D4,stroke:#333,stroke-width:2px,color:#fff
+```
diff --git a/assets/diagrams/src/afd-apim-aca-architecture.puml b/assets/diagrams/src/afd-apim-aca-architecture.puml
deleted file mode 100644
index 3270d11b..00000000
--- a/assets/diagrams/src/afd-apim-aca-architecture.puml
+++ /dev/null
@@ -1,24 +0,0 @@
-@startuml "Azure Front Door, API Management & Container Apps Architecture"
-
-!include ./base.puml
-
-title Azure Front Door, API Management & Container Apps Architecture
-
-' Main components
-AzureFrontDoor(afd, "Azure Front Door", "")
-AzureAPIManagement(apim, "API Management", "")
-AzureContainerApp(aca, "Container Apps", "")
-AzureApplicationInsights(appinsights, "Application Insights", "")
-AzureLogAnalyticsWorkspace(loganalytics, "Log Analytics", "")
-
-' Custom components
-collections "Apps" as apps #LightBlue
-
-' Relationships
-apps --> afd : "API Consumers"
-afd --> apim : "Routes traffic"
-apim --> aca : "Backend"
-apim -right-> appinsights : "\nSends\ntelemetry\n"
-appinsights -down-> loganalytics : "Stores data"
-
-@enduml
\ No newline at end of file
diff --git a/assets/diagrams/src/apim-aca-architecture.md b/assets/diagrams/src/apim-aca-architecture.md
new file mode 100644
index 00000000..26d6c2b7
--- /dev/null
+++ b/assets/diagrams/src/apim-aca-architecture.md
@@ -0,0 +1,18 @@
+# API Management & Container Apps Architecture
+
+```mermaid
+flowchart LR
+ apps([fa:fa-mobile Apps]):::appStyle
+ apim[fa:fa-cloud API Management]:::azureStyle
+ aca[fa:fa-box Container Apps]:::azureStyle
+ appinsights[fa:fa-chart-line Application Insights]:::azureStyle
+ loganalytics[fa:fa-database Log Analytics]:::azureStyle
+
+ apps -->|API Consumers| apim
+ apim -->|Backend APIs| aca
+ apim -->|Sends telemetry| appinsights
+ appinsights -->|Stores telemetry| loganalytics
+
+ classDef appStyle fill:#ADD8E6,stroke:#333,stroke-width:2px
+ classDef azureStyle fill:#0078D4,stroke:#333,stroke-width:2px,color:#fff
+```
diff --git a/assets/diagrams/src/apim-aca-architecture.puml b/assets/diagrams/src/apim-aca-architecture.puml
deleted file mode 100644
index 7de60a8f..00000000
--- a/assets/diagrams/src/apim-aca-architecture.puml
+++ /dev/null
@@ -1,22 +0,0 @@
-@startuml "API Management & Container Apps Architecture"
-
-!include ./base.puml
-
-title API Management & Container Apps Architecture
-
-' Main components
-AzureAPIManagement(apim, "API Management", "")
-AzureContainerApp(aca, "Container Apps", "")
-AzureApplicationInsights(appinsights, "Application Insights", "")
-AzureLogAnalyticsWorkspace(loganalytics, "Log Analytics", "")
-
-' Custom components
-collections "Apps" as apps #LightBlue
-
-' Relationships
-apps --> apim : "API Consumers"
-apim --> aca : "Backend APIs"
-apim -right-> appinsights : "\nSends\ntelemetry\n"
-appinsights -down-> loganalytics : "Stores telemetry"
-
-@enduml
\ No newline at end of file
diff --git a/assets/diagrams/src/apim-simple-architecture.md b/assets/diagrams/src/apim-simple-architecture.md
new file mode 100644
index 00000000..5b047ba2
--- /dev/null
+++ b/assets/diagrams/src/apim-simple-architecture.md
@@ -0,0 +1,19 @@
+# Simple API Management Architecture
+
+```mermaid
+flowchart LR
+ apps([fa:fa-mobile Apps]):::appStyle
+ apis([fa:fa-plug APIs]):::apiStyle
+ apim[fa:fa-cloud API Management]:::azureStyle
+ appinsights[fa:fa-chart-line Application Insights]:::azureStyle
+ loganalytics[fa:fa-database Log Analytics]:::azureStyle
+
+ apps -->|API Consumers| apim
+ apis -.->|Deployed to| apim
+ apim -->|Sends telemetry| appinsights
+ appinsights -->|Stores telemetry| loganalytics
+
+ classDef appStyle fill:#ADD8E6,stroke:#333,stroke-width:2px
+ classDef apiStyle fill:#90EE90,stroke:#333,stroke-width:2px
+ classDef azureStyle fill:#0078D4,stroke:#333,stroke-width:2px,color:#fff
+```
diff --git a/assets/diagrams/src/apim-simple-architecture.puml b/assets/diagrams/src/apim-simple-architecture.puml
deleted file mode 100644
index 929a9780..00000000
--- a/assets/diagrams/src/apim-simple-architecture.puml
+++ /dev/null
@@ -1,22 +0,0 @@
-@startuml "Simple API Management Architecture"
-
-!include ./base.puml
-
-title Simple API Management Architecture
-
-' Main components
-AzureAPIManagement(apim, "API Management", "")
-AzureApplicationInsights(appinsights, "Application Insights", "")
-AzureLogAnalyticsWorkspace(loganalytics, "Log Analytics", "")
-
-' Custom components
-collections "Apps" as apps #LightBlue
-collections "APIs" as apis #LightGreen
-
-' Define the relationships between components
-apps --> apim : "API Consumers"
-apis -up-> apim : "Deployed to"
-apim -right-> appinsights : "\nSends\ntelemetry\n"
-appinsights -down-> loganalytics : "Stores telemetry"
-
-@enduml
\ No newline at end of file
diff --git a/assets/diagrams/src/appgw-pe-apim-aca-architecture.md b/assets/diagrams/src/appgw-pe-apim-aca-architecture.md
new file mode 100644
index 00000000..82a577bf
--- /dev/null
+++ b/assets/diagrams/src/appgw-pe-apim-aca-architecture.md
@@ -0,0 +1,20 @@
+# Azure Application Gateway, API Management & Container Apps Architecture
+
+```mermaid
+flowchart LR
+ apps([fa:fa-mobile Apps]):::appStyle
+ appgw[fa:fa-shield-alt Application Gateway WAF]:::azureStyle
+ apim[fa:fa-cloud API Management]:::azureStyle
+ aca[fa:fa-box Container Apps]:::azureStyle
+ appinsights[fa:fa-chart-line Application Insights]:::azureStyle
+ loganalytics[fa:fa-database Log Analytics]:::azureStyle
+
+ apps -->|API Consumers| appgw
+ appgw -->|Routes traffic via Private Endpoint| apim
+ apim -->|Backend| aca
+ apim -->|Sends telemetry| appinsights
+ appinsights -->|Stores data| loganalytics
+
+ classDef appStyle fill:#ADD8E6,stroke:#333,stroke-width:2px
+ classDef azureStyle fill:#0078D4,stroke:#333,stroke-width:2px,color:#fff
+```
diff --git a/assets/diagrams/src/appgw-pe-apim-aca-architecture.puml b/assets/diagrams/src/appgw-pe-apim-aca-architecture.puml
deleted file mode 100644
index 04268680..00000000
--- a/assets/diagrams/src/appgw-pe-apim-aca-architecture.puml
+++ /dev/null
@@ -1,24 +0,0 @@
-@startuml "Azure Application Gateway, API Management & Container Apps Architecture"
-
-!include ./base.puml
-
-title Azure Application Gateway, API Management & Container Apps Architecture
-
-' Main components
-AzureApplicationGateway(appgw, "Application Gateway (WAF)", "")
-AzureAPIManagement(apim, "API Management", "")
-AzureContainerApp(aca, "Container Apps", "")
-AzureApplicationInsights(appinsights, "Application Insights", "")
-AzureLogAnalyticsWorkspace(loganalytics, "Log Analytics", "")
-
-' Custom components
-collections "Apps" as apps #LightBlue
-
-' Relationships
-apps --> appgw : "API Consumers"
-appgw --> apim : "Routes traffic (via Private Endpoint)"
-apim --> aca : "Backend"
-apim -right-> appinsights : "\nSends\ntelemetry\n"
-appinsights -down-> loganalytics : "Stores data"
-
-@enduml
diff --git a/assets/diagrams/src/base.puml b/assets/diagrams/src/base.puml
deleted file mode 100644
index cb52f59b..00000000
--- a/assets/diagrams/src/base.puml
+++ /dev/null
@@ -1,15 +0,0 @@
-' base.puml - Common PlantUML includes and settings
-
-' Import Azure PlantUML libraries
-!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
-!includeurl AzurePuml/AzureCommon.puml
-!includeurl AzurePuml/AzureSimplified.puml
-!includeurl AzurePuml/Web/AzureAPIManagement.puml
-!includeurl AzurePuml/DevOps/AzureApplicationInsights.puml
-!includeurl AzurePuml/Analytics/AzureLogAnalyticsWorkspace.puml
-!includeurl AzurePuml/Containers/AzureContainerApp.puml
-!includeurl AzurePuml/Networking/AzureFrontDoor.puml
-!includeurl AzurePuml/Networking/AzureApplicationGateway.puml
-
-skinparam titleFontSize 24
-left to right direction