diagram-as-code
Generate AWS diagrams from YAML — Go CLI with a hosted web frontend.
git clone https://github.com/fernandofatech/diagram-as-code.gitListen to guide
generated on playGenerated only on first play
Powered by Amazon Polly + OmniVoice
diagram-as-code is a Go CLI that converts YAML files into AWS infrastructure diagrams — supporting PNG and draw.io output — complemented by a Monaco-powered web editor hosted at dac.moretes.com.
What it is and why it exists
This repository is a fork of awslabs/diagram-as-code that I maintain as part of my architecture portfolio. The original project solves a real problem: infrastructure diagrams typically live in visual tools disconnected from code, go stale quickly, and cannot be reviewed in pull requests.
The diagram-as-code approach treats diagrams as engineering artifacts — versioned in Git, generatable in CI/CD, auditable, and reusable. You describe your architecture in human-readable YAML and the CLI produces a PNG image or a .drawio file without depending on a headless browser, GUI, or external image libraries.
My fork adds two primary contributions on top of upstream: native draw.io export via the --drawio flag, with a full Go pipeline (internal/ctl/drawio.go); and a complete web frontend hosted on Vercel, allowing diagram generation directly in the browser with no local install. The serverless backend is implemented as Vercel Functions in Go, and the frontend uses Monaco Editor with ready-to-use example templates.
Key features
--drawio flag or -o output.drawio extension.pkg/diagram package for embedding in IaC tools, AI agents, or external drawing GUIs.How the system works
Two usage paths: local CLI (Go binary) and serverless web frontend on Vercel. Both share the same Go rendering core.
- YAML File · architecture input
- awsdac CLI · Go binary
- Render Core · pkg/diagram
- output.png · or output.drawio
- Browser · Monaco Editor
- Vercel Function · Go API handler
- Render Core · (same pkg/diagram)
- PNG / draw.io · download
- AWS Icon Defs · YAML definition files
Installation and usage
- 1
Install via npm (recommended, all platforms)
Requires Node.js 14+. Automatically downloads the correct binary for your OS and architecture.
- 2
Install via Go (requires Go 1.21+)
Use
go installto compile and install directly from the published module. - 3
Install via Homebrew (macOS)
Convenient macOS alternative without needing Node.js or Go installed.
- 4
Build from source
Clone the repository and run
make build. Produces the./awsdacbinary (orawsdac.exeon Windows). Requires Go 1.21+. - 5
Generate a PNG diagram
Pass a YAML file as argument. The default output file is
output.png. - 6
Generate a draw.io file
Use the
--drawioflag or specify an output file with.drawioextension via-o. - 7
Use the web frontend without installing anything
Visit dac.moretes.com, write or paste your YAML in the Monaco editor, choose PNG or draw.io, and click download.
# Install (npm — all platforms)
npm install -g awsdac
awsdac --version
# Install via Go
go install github.com/fernandofatech/diagram-as-code/cmd/awsdac@latest
# Build from source
git clone https://github.com/fernandofatech/diagram-as-code.git
cd diagram-as-code
make build
# Generate PNG (default output: output.png)
awsdac examples/alb-ec2.yaml
# Generate PNG with custom output name
awsdac my-architecture.yaml -o my-diagram.png
# Generate draw.io file
awsdac examples/alb-ec2.yaml --drawio -o output.drawio
# Force overwrite without confirmation
awsdac my-architecture.yaml -o output.png -f
# Generate from CloudFormation template (beta)
awsdac my-stack.yaml --cfn-template -o cfn-diagram.png
# Verbose output for debugging
awsdac my-architecture.yaml -vHow it works internally
The CLI core is written entirely in Go and has no dependency on external image libraries or a headless browser. The rendering process reads the input YAML, resolves AWS components against definition files (which map resource types to official AWS SVG icons), automatically calculates group positioning and sizing, and produces output in the requested format.
For PNG export, the pipeline generates the image file directly in Go. For draw.io, the pipeline in internal/ctl/drawio.go and drawio_assets.go serializes the internal diagram representation into draw.io's XML format. If the drawio binary is available in PATH, you can convert the .drawio to PNG or PDF locally, keeping .drawio as the source of truth.
The public pkg/diagram package exposes the rendering API for use as a Go library in external tools — useful for integrating diagram generation into IaC pipelines, AI agents, or custom applications.
The web frontend is a TypeScript/JavaScript application hosted on Vercel. The Monaco editor (the same engine as VS Code) provides YAML syntax highlighting. Generation requests are sent to Vercel Functions implemented in Go, which execute the same rendering core as the CLI. The local dev server cmd/api-dev allows testing the API handler without the Vercel CLI.
CI/CD integration
Because it has no GUI or headless browser dependency, awsdac runs without additional setup in any standard CI runner. Add a step that executes awsdac architecture.yaml -o docs/architecture.png -f and commit the generated PNG alongside the YAML — your diagrams stay permanently in sync with your infrastructure code.
Frequently asked questions
What is the difference between this fork and the upstream awslabs/diagram-as-code?
This fork adds native draw.io export (the --drawio flag), the public pkg/diagram package for library use, the complete web frontend hosted at dac.moretes.com with Monaco editor, and the local dev server cmd/api-dev.
Can I create diagrams for non-AWS services?
Yes. The CLI is extensible via custom definition files. You can point to your own definition files using --override-def-file, which allows creating diagrams for any infrastructure type.
Does the web frontend store my YAML or diagrams?
The frontend is stateless — YAML is sent to the Vercel Function, the diagram is generated and returned directly to the browser. No data is persisted on the server.
How do I use `pkg/diagram` as a library in another Go project?
Add github.com/fernandofatech/diagram-as-code as a dependency in your go.mod and import pkg/diagram. The package exposes the same rendering API the CLI uses internally.
Who this project is for
This project is useful for engineers and architects who already use IaC and want to keep AWS architecture diagrams in sync with code — without leaving the Git/PR workflow and without depending on manual visual tools. The YAML format is simple enough to be generated by scripts or AI agents, which opens up interesting automation possibilities. The web frontend at dac.moretes.com works well for quick demos, team onboarding, or one-off generation without local setup. If you need editable diagrams downstream, the draw.io export is the right path. If the goal is pipeline automation, the lightweight CLI binary is the appropriate choice. This is not a tool for free-form artistic diagrams — it is deliberately focused on AWS infrastructure with compliance to AWS icon guidelines.
Architecture, AWS, AI and market deep dives — straight to your inbox. Free.
No spam · unsubscribe anytime