Skip to content

feat(deploy-on-aws): add architecture diagram generation skill#84

Open
MichaelWalker-git wants to merge 16 commits intoawslabs:mainfrom
MichaelWalker-git:feat/diagram-skill
Open

feat(deploy-on-aws): add architecture diagram generation skill#84
MichaelWalker-git wants to merge 16 commits intoawslabs:mainfrom
MichaelWalker-git:feat/diagram-skill

Conversation

@MichaelWalker-git
Copy link

@MichaelWalker-git MichaelWalker-git commented Mar 7, 2026

Summary

  • Adds a diagram skill to the deploy-on-aws plugin that generates architecture diagrams using the Python diagrams DSL
  • Replaces the aws-diagram-mcp-server (being deprecated in awslabs/mcp) with a lighter-weight skill that runs diagram code directly via the agent's Bash tool
  • Supports AWS (29 service categories), Kubernetes, on-premises, SaaS, flowcharts, and custom icons

What's included

File Lines Purpose
skills/diagram/SKILL.md 80 Core skill: workflows, critical rules, prerequisites, error handling
references/dsl-syntax.md 110 DSL syntax: Diagram/Cluster/Edge constructors, connections, provider import paths
references/aws-services.md 111 AWS service categories, common icons, 5 runnable examples
references/non-aws-providers.md 122 K8s, on-prem, flowchart providers, 4 runnable examples

Also updates:

  • plugin.json — adds diagram/architecture keywords, bumps to v1.2.0
  • marketplace.json — mirrors plugin.json updates
  • README.md — adds diagram trigger phrases to deploy-on-aws skill table

Prerequisites

The skill requires GraphViz and the Python diagrams package installed locally. SKILL.md documents install commands and error handling for missing dependencies.

Context

This is part of the deprecation plan for aws-diagram-mcp-server (awslabs/mcp#2597, #2598, #2599). The skill approach was chosen over keeping the MCP server because diagram generation is a write-then-run pattern that fits naturally into agent skills.

Test plan

  • Install plugin: claude --plugin-dir ./plugins/deploy-on-aws
  • Verify diagram skill auto-triggers on "draw an architecture diagram"
  • Generate AWS diagram from aws-services.md examples
  • Generate K8s diagram from non-aws-providers.md examples
  • Generate flowchart from non-aws-providers.md examples
  • Verify mise run build passes
  • Verify mise run lint:manifests passes
  • Verify mise run lint:cross-refs passes

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

Add a diagram skill to the deploy-on-aws plugin that generates
architecture diagrams using the Python diagrams DSL. This skill
replaces the aws-diagram-mcp-server with a lighter-weight approach
that runs diagram code directly via the agent's Bash tool.

Includes:
- Core SKILL.md with workflows, critical rules, and prerequisites
- DSL syntax reference (Diagram, Cluster, Edge, all providers)
- AWS service categories with 5 runnable examples
- Non-AWS providers (K8s, on-prem, flowchart, custom) with 4 examples
- Updated plugin.json and marketplace.json with diagram keywords
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new diagram skill to the deploy-on-aws plugin to generate architecture diagrams via the Python diagrams DSL, and updates plugin/marketplace metadata and top-level docs to surface the new capability.

Changes:

  • Introduces plugins/deploy-on-aws/skills/diagram/SKILL.md with workflow, rules, and prerequisites for diagram generation.
  • Adds diagram DSL/provider reference docs with runnable examples (AWS and non-AWS).
  • Updates plugin metadata (plugin.json, marketplace.json) and root README.md to advertise the new skill and keywords/version bump.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
plugins/deploy-on-aws/skills/diagram/SKILL.md New skill definition + workflow/rules/prereqs for generating diagrams.
plugins/deploy-on-aws/skills/diagram/references/dsl-syntax.md DSL syntax reference (constructors, edges, clusters, patterns).
plugins/deploy-on-aws/skills/diagram/references/aws-services.md AWS import categories + AWS-focused runnable examples.
plugins/deploy-on-aws/skills/diagram/references/non-aws-providers.md Non-AWS provider categories + K8s/on-prem/flowchart/custom icon examples.
plugins/deploy-on-aws/.claude-plugin/plugin.json Adds diagram-related keywords and bumps plugin version to 1.2.0.
.claude-plugin/marketplace.json Mirrors plugin metadata updates (description/keywords/tags/version).
README.md Adds diagram trigger phrases to the deploy-on-aws skill table.

- Remove "sequence diagrams" claim (diagrams DSL doesn't produce UML
  sequence diagrams, only flowchart-based process flows)
- Standardize on python3 instead of python in workflow commands
- Fix output verification to not assume PNG format
- Use ALB import instead of ELB("ALB") to avoid icon/label mismatch
- Replace urlretrieve with local icon file paths in custom node examples
  to avoid external network dependencies and untrusted content
- Fix db_primary - [RDS()] list operator to use variable assignment
  (- operator works between nodes, not node-to-list)
Normalize markdown table column widths to pass dprint check.
Copilot AI review requested due to automatic review settings March 9, 2026 16:23
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

- Replace ELB("ALB") with ALB("ALB") in Clusters and Nested Clusters
  examples (was missed in first fix round)
- Add .gitignore note for generated-diagrams/ output directory
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Update the Diagram() constructor reference snippet to use
generated-diagrams/ as the filename path, matching the skill's
critical rules and other examples.
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

- Clarify PNG is default output format, not the only format
- Fix invalid Edge() placeholder syntax with a real example
- Remove unused Lambda import from basic structure example
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

- Wrap Diagram constructor in context manager so snippet is runnable
- Fix mixed >> << operators in on-prem example to use consistent >>
- Use python3 -m pip install for consistency with python3 workflow
Copilot AI review requested due to automatic review settings March 17, 2026 14:27
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

@krokoko
Copy link
Contributor

krokoko commented Mar 19, 2026

Diagram titles and node labels pass through to GraphViz. When outputting SVG, unsanitized user input with HTML/script tags could become an XSS vector if the SVG is later served on a web page. The skill provides no input sanitization guidance.

- Remove Redshift from database category (only exists in analytics)
- Clarify TB direction is a skill convention, not the library default
- Move Namespace to k8s.group, add LimitRange/Limits to clusterconfig
- Add SVG sanitization guidance to prevent XSS via unsanitized labels

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 19, 2026 18:22
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

@scottschreckengaust
Copy link
Member

scottschreckengaust commented Mar 19, 2026

Code review

Found 3 issues:

  1. Predefined class does not exist in diagrams.programming.flowchart -- the correct class name is PredefinedProcess. The Flowchart Shapes reference block and the "Order Processing Flow" example both use Predefined, which will produce ImportError when an agent runs the generated code.

Predefined, # Double-border rectangle -- predefined process
Delay, # Half-oval -- wait/delay
)
```

from diagrams import Diagram
from diagrams.programming.flowchart import Action, Decision, Delay, InputOutput, Predefined
with Diagram("Order Processing", show=False, filename="generated-diagrams/flow"):
start = Predefined("Start")
order = InputOutput("Order Received")
check = Decision("In Stock?")
process = Action("Process Order")
wait = Delay("Backorder")
ship = Action("Ship Order")
end = Predefined("End")
start >> order >> check

  1. Fluentd class does not exist in diagrams.onprem.logging (or anywhere in the diagrams library). The On-Premises Categories table and the "On-Premises with Colored Edges" example use Fluentd, which will fail with ImportError. The closest available class is FluentBit.

| `onprem.logging` | Fluentd, Loki |
| `onprem.queue` | Kafka, RabbitMQ, Celery |
| `onprem.network` | Nginx, HAProxy, Traefik |

from diagrams.onprem.inmemory import Redis
from diagrams.onprem.logging import Fluentd
from diagrams.onprem.monitoring import Grafana, Prometheus
from diagrams.onprem.network import Nginx
from diagrams.onprem.queue import Kafka
with Diagram("On-Prem Service", show=False, filename="generated-diagrams/onprem"):
ingress = Nginx("ingress")
metrics = Prometheus("metric")
metrics << Edge(color="firebrick", style="dashed") << Grafana("monitoring")
with Cluster("Service Cluster"):
grpcsvc = [Server("grpc1"), Server("grpc2"), Server("grpc3")]
with Cluster("Sessions HA"):
primary = Redis("session")
primary - Edge(color="brown", style="dashed") - Redis("replica")
grpcsvc >> Edge(color="brown") >> primary
with Cluster("Database HA"):
db = PostgreSQL("users")
db - Edge(color="brown", style="dotted") - PostgreSQL("replica")

  1. Four incorrect class names in the AWS Service Categories table will cause ImportError: DynamoDB should be Dynamodb, EventBridge should be Eventbridge, CloudWatch should be Cloudwatch, CloudFormation should be Cloudformation. The diagrams library uses single-capital naming for these classes.

| `compute` | `diagrams.aws.compute` | EC2, Lambda, ECS, EKS, Fargate, Batch |
| `database` | `diagrams.aws.database` | RDS, Aurora, DynamoDB, ElastiCache, Redshift, Neptune |
| `integration` | `diagrams.aws.integration` | SQS, SNS, StepFunctions, EventBridge, MQ |
| `management` | `diagrams.aws.management` | CloudWatch, CloudFormation, SystemsManager |
| `ml` | `diagrams.aws.ml` | Sagemaker, Rekognition, Comprehend, Bedrock |

🤖 Generated with Claude Code

- If this code review was useful, please react with 👍. Otherwise, react with 👎.

PR-84-ddf99d31.md

MichaelWalker-git and others added 2 commits March 19, 2026 11:41
…to examples

Critical fixes (would cause ImportError):
- Predefined -> PredefinedProcess (diagrams.programming.flowchart)
- Fluentd -> Fluentbit (diagrams.onprem.logging)
- DynamoDB -> Dynamodb (diagrams.aws.database)
- EventBridge -> Eventbridge (diagrams.aws.integration)
- CloudWatch -> Cloudwatch, CloudFormation -> Cloudformation (diagrams.aws.management)

Important fixes:
- Add direction="TB" to all examples missing it (skill convention)
- Fix misleading flow direction comments in dsl-syntax.md
- Fix AWS category count from 29 to 26
- Update README plugin description to mention diagram generation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…mments

- Add import allowlist: ONLY diagrams.* modules, never os/subprocess/etc.
- Add safe file path rule for Custom nodes (no absolute/traversal paths)
- Pin diagrams version range (>=0.23,<1.0), suggest venv, add sudo warning
- Expand error handling: syntax errors, runtime errors, empty output
- Make Clusters and Nested Clusters snippets fully runnable with imports

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 19, 2026 19:13
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.


Generate architecture diagrams using the Python [diagrams](https://diagrams.mingrammer.com/) package. Write a Python script, run it, and produce an image (PNG by default).

Supports AWS (26 service categories), Kubernetes, on-premises, GCP, SaaS, and custom icons via the `diagrams` DSL.
Copy link

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description says the diagram skill supports AWS "29 service categories", but the skill docs and references currently state/list 26 categories. Please reconcile the number either by updating the docs (if 29 is correct) or adjusting the PR description so they match to avoid confusion for users/maintainers.

Copilot uses AI. Check for mistakes.
- Use `Cluster()` to group related resources (VPCs, subnets, namespaces)
- Use `Edge(label="HTTPS", color="darkgreen", style="dashed")` for labeled or styled connections
- **SVG sanitization**: When using `outformat="svg"`, sanitize all diagram titles, node labels, and edge labels — strip HTML tags and special characters (`<`, `>`, `&`, `"`, `'`) before passing them to the `diagrams` DSL. Unsanitized input rendered as SVG can become an XSS vector if served on a web page.
- **Import allowlist**: ONLY import from `diagrams.*` modules. NEVER import `os`, `sys`, `subprocess`, `shutil`, `socket`, `requests`, `urllib`, or any non-diagrams module. Before executing, review the generated script to confirm it contains ONLY diagrams DSL code.
Copy link

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Import allowlist" rule says to only import from diagrams.* modules, but all examples (and typical usage) require from diagrams import Diagram, Cluster, Edge. As written, this rule would incorrectly reject valid scripts. Consider rewording to allow imports from the diagrams package (both diagrams and diagrams.*) while still forbidding non-diagrams modules.

Suggested change
- **Import allowlist**: ONLY import from `diagrams.*` modules. NEVER import `os`, `sys`, `subprocess`, `shutil`, `socket`, `requests`, `urllib`, or any non-diagrams module. Before executing, review the generated script to confirm it contains ONLY diagrams DSL code.
- **Import allowlist**: ONLY import from the `diagrams` package (e.g., `import diagrams`, `from diagrams import Diagram, Cluster, Edge`, or `from diagrams.aws.compute import EC2`). NEVER import `os`, `sys`, `subprocess`, `shutil`, `socket`, `requests`, `urllib`, or any non-diagrams module. Before executing, review the generated script to confirm it contains ONLY diagrams DSL code.

Copilot uses AI. Check for mistakes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants