From b3f1e5e305a9ee1a963d82b0983c6ac872f7f1d5 Mon Sep 17 00:00:00 2001 From: Robert Fink Date: Thu, 17 Apr 2025 00:12:46 -0400 Subject: [PATCH 1/4] Enhance CI workflow to validate Mermaid diagrams and update README with detailed examples --- .github/workflows/checks.yml | 18 ++++++++ mermaid_diagrams/README.md | 35 ++++++++++++-- mermaid_diagrams/generic-paas.mmd | 77 +++++++++++++++---------------- 3 files changed, 86 insertions(+), 44 deletions(-) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 520b3ff..2c674a2 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -7,6 +7,7 @@ on: pull_request: paths: - javascriptapp/** + - mermaid_diagrams/**/*.mmd jobs: build-and-test: @@ -30,3 +31,20 @@ jobs: env: OPENWEATHER_API_KEY: ${{ secrets.OPENWEATHER_API_KEY }} run: npm test + + validate-mermaid: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@v2 + + - name: Install Mermaid CLI + run: npm install -g @mermaid-js/mermaid-cli + + - name: Find and validate Mermaid diagrams + run: | + for file in $(find mermaid_diagrams -name '*.mmd'); do + echo "Validating $file" + mmdc -i "$file" -o /dev/null || exit 1 + done 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 From 12b5c04d174291bac871f63357c544fb0abb35d2 Mon Sep 17 00:00:00 2001 From: Robert Fink Date: Thu, 17 Apr 2025 00:20:24 -0400 Subject: [PATCH 2/4] fix for stubborn mmdc --- .github/workflows/checks.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 2c674a2..80cf792 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -46,5 +46,5 @@ jobs: run: | for file in $(find mermaid_diagrams -name '*.mmd'); do echo "Validating $file" - mmdc -i "$file" -o /dev/null || exit 1 + mmdc --input "$file" --output /dev/null || exit 1 done From 2b6bad339f3ebf147d60ee9aaf4e580173fc35ff Mon Sep 17 00:00:00 2001 From: Robert Fink Date: Thu, 17 Apr 2025 00:23:33 -0400 Subject: [PATCH 3/4] even more mmdc shenanigans --- .github/workflows/checks.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 80cf792..de5cfd1 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -46,5 +46,6 @@ jobs: run: | for file in $(find mermaid_diagrams -name '*.mmd'); do echo "Validating $file" - mmdc --input "$file" --output /dev/null || exit 1 + mmdc --input "$file" --output "${file}.svg" || exit 1 + rm -f "${file}.svg" # Clean up the temporary output file done From 3222d24265923d17773b288623bb3d2bb33db1df Mon Sep 17 00:00:00 2001 From: Robert Fink Date: Thu, 17 Apr 2025 00:33:27 -0400 Subject: [PATCH 4/4] ditch the mmdc stuff for now --- .github/workflows/checks.yml | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index de5cfd1..520b3ff 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -7,7 +7,6 @@ on: pull_request: paths: - javascriptapp/** - - mermaid_diagrams/**/*.mmd jobs: build-and-test: @@ -31,21 +30,3 @@ jobs: env: OPENWEATHER_API_KEY: ${{ secrets.OPENWEATHER_API_KEY }} run: npm test - - validate-mermaid: - if: github.event_name == 'pull_request' - runs-on: ubuntu-latest - steps: - - name: Check out code - uses: actions/checkout@v2 - - - name: Install Mermaid CLI - run: npm install -g @mermaid-js/mermaid-cli - - - name: Find and validate Mermaid diagrams - run: | - for file in $(find mermaid_diagrams -name '*.mmd'); do - echo "Validating $file" - mmdc --input "$file" --output "${file}.svg" || exit 1 - rm -f "${file}.svg" # Clean up the temporary output file - done