diagram-as-code
Generate AWS diagrams from YAML — Go CLI with a hosted web frontend.
git clone https://github.com/fernando-moretes/tool-diagram-as-code.gitListen to guide
generated on playGenerated only on first play
Powered by Amazon Polly + OmniVoice
diagram-as-code is my fork of awslabs/diagram-as-code: a Go CLI that converts human-readable YAML into AWS architecture diagrams (PNG or draw.io), extended with a hosted web frontend on Vercel and native draw.io export.
What it is and why it exists
Architecture diagrams age poorly when they live in GUI tools disconnected from code. This project treats diagrams as engineering artifacts: versioned in Git, generated in pipeline, reviewable in pull requests.
The upstream (awslabs/diagram-as-code) already handles the CLI case well. My fork adds two concrete things:
- Native draw.io export — the
--drawioflag (or-o output.drawio) generates a.drawiofile directly from Go, with no headless browser dependency. The localdrawiobinary can optionally be used to export PNG/PDF from the.drawiofile, keeping it as the source of truth.
- Web frontend — a Monaco editor hosted at dac.moretes.com that accepts YAML, calls a serverless backend (Vercel Functions in Go), and returns PNG or draw.io for download. No local install, no GUI dependency.
The project also exposes a public pkg/diagram package for embedding diagram generation in external tools, and includes cmd/api-dev for running the API handler locally without the Vercel CLI.
Fork highlights
--drawio flag, implemented in internal/ctl/drawio.go.cmd/api-dev for local development without the Vercel CLI.pkg/diagram package for embedding diagram generation in external IaC, AI, or GUI tools.How the pieces fit together
Two usage paths: local CLI (Go binary) and web frontend (Vercel). Both share the same Go rendering core.
- Engineer · (CLI)
- Engineer · (Browser)
- awsdac · binary
- input.yaml · (YAML)
- output.png · or .drawio
- Monaco Editor · (dac.moretes.com)
- Vercel Function · (Go handler)
- pkg/diagram · (Go core)
- PNG / draw.io · download
- cmd/api-dev · (local server)
Installation and usage
- 1
Option 1 — npm (recommended, all platforms)
Requires Node.js 14+. Downloads the correct binary automatically for your OS and CPU. ``
bash npm install -g awsdac awsdac --version`` - 2
Option 2 — Go install (requires Go 1.21+)
``
bash go install github.com/fernando-moretes/tool-diagram-as-code/cmd/awsdac@latest`` - 3
Option 3 — Build from source
``
bash git clone https://github.com/fernando-moretes/tool-diagram-as-code.git cd diagram-as-code make build # produces ./awsdac (or awsdac.exe on Windows)`` Prerequisites: Go 1.21+ · Node.js 18+ (web frontend only) - 4
Generate PNG from an example template
``
bash awsdac examples/alb-ec2.yaml # default output: output.png`` - 5
Generate draw.io file
``
bash awsdac examples/alb-ec2.yaml --drawio -o output.drawio`` This is a fork extension — it does not exist in the upstream. - 6
Use the web frontend (no install)
Go to dac.moretes.com, write or paste YAML in the Monaco editor, choose the format (PNG or draw.io), and click download. Example templates are available directly in the interface.
- 7
Run the local API dev server
``
bash go run ./cmd/api-dev`` Emulates the Vercel handler locally without needing the Vercel CLI.
Diagram:
DefinitionFiles:
- Type: URL
Url: "https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml"
Resources:
Canvas:
Type: AWS::Diagram::Canvas
Children:
- VPC
VPC:
Type: AWS::EC2::VPC
Children:
- ALB
- EC2a
- EC2b
ALB:
Type: AWS::ElasticLoadBalancingV2::LoadBalancer
Direction: right
Children: []
EC2a:
Type: AWS::EC2::Instance
EC2b:
Type: AWS::EC2::Instance
Links:
- From: ALB
To: EC2a
- From: ALB
To: EC2bHow it works internally
The project core is a Go YAML parser that reads the diagram definition and resolves resource types against definition files — by default, the official AWS file hosted in the upstream repository. Each type (AWS::EC2::Instance, AWS::ElasticLoadBalancingV2::LoadBalancer, etc.) maps to an SVG icon and layout metadata.
The layout engine positions groups and resources automatically: you don't specify coordinates. The result is rendered as PNG using Go's standard image library — no Chromium, no Puppeteer, no OS dependency beyond the binary itself.
For draw.io export, I implemented internal/ctl/drawio.go and drawio_assets.go, which serialize the internal graph to draw.io's XML format. AWS icon assets are embedded in the binary via go:embed, so the final binary is self-contained.
The web frontend is a TypeScript/React SPA with a Monaco editor. On "Generate", the YAML is POSTed to a Vercel Function written in Go that instantiates the same pkg/diagram used by the CLI. The response is a binary blob (PNG or draw.io) that the browser offers for download. cmd/api-dev is a minimal HTTP server that exposes the same handler for local development.
The separation into pkg/diagram is deliberate: any external tool can import the package and generate diagrams programmatically, without going through the CLI.
This is a fork with a clear purpose: extend the upstream with draw.io export and a functional web frontend, both connected to my portfolio at fernando.moretes.com. The extension code (draw.io, API handler, frontend) is mine; the core rendering engine comes from awslabs. Credit where it's due.
Frequently asked questions
What is the difference between this fork and the upstream awslabs/diagram-as-code?
The upstream covers PNG and PDF via CLI. This fork adds native draw.io export (--drawio), a web frontend hosted on Vercel, the pkg/diagram package for library use, and cmd/api-dev for local API development.
Do I need to install anything to use the web frontend?
No. The frontend at dac.moretes.com runs entirely in the browser and calls a serverless backend. No local installation is required.
Can I use non-AWS diagrams?
Yes. The DefinitionFiles field in the YAML accepts custom URLs or local files. You can create your own definition file with arbitrary icons and types.
How do I integrate diagram generation into another Go tool?
Import github.com/fernando-moretes/tool-diagram-as-code/pkg/diagram. The package exposes the rendering API without depending on the CLI.
Does the `drawio` binary need to be installed for draw.io export?
Not for generating the .drawio file — that is done natively in Go. The drawio binary is only needed if you want to export PNG or PDF from the generated .drawio, and it is optional.
Who this project is for
Use this project if you want to maintain AWS architecture diagrams as code — versioned, reviewable, and generatable in CI/CD — without depending on GUI tools. The Go CLI is suited for automation pipelines and headless environments. The web frontend at dac.moretes.com is useful for quick iteration or for sharing with people who don't have Go installed. The draw.io export is the fork's differentiator: if you use draw.io as your primary diagramming tool and want .drawio as an editable source of truth, this is the option. It is not a substitute for interactive diagramming tools in projects where real-time visual collaboration is the primary requirement.
Architecture, AWS, AI and market deep dives — straight to your inbox. Free.
No spam · unsubscribe anytime