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 — outputting PNG, PDF, or draw.io — plus a hosted web frontend that removes the need for any local install.
What it is and why it exists
This repository is a fork of awslabs/diagram-as-code, maintained by me as part of my architecture portfolio at fernando.moretes.com.
The problem it solves is straightforward: architecture diagrams built manually in visual tools go stale quickly, are hard to version, and don't integrate with CI/CD pipelines. Writing topology in YAML treats the diagram as code — reviewable in pull requests, auto-generated in pipelines, and co-located with IaC.
Relative to upstream, this fork adds two concrete contributions. First, native .drawio export via the --drawio flag, with a generation pipeline implemented in Go (internal/ctl/drawio.go). Second, a full web frontend hosted on Vercel — live at dac.moretes.com — with a Monaco editor, PNG/draw.io toggle, built-in templates, and one-click download. The frontend backend is a Go Vercel Function, with no headless browser or GUI dependency.
The project is useful both as a standalone tool and as a Go library (pkg/diagram) for integration with other systems — IaC tooling, AI agents, or custom drawing interfaces.
Highlights
pkg/diagram package for use as a Go library in external tooling.How the pieces fit together
Two usage paths: local CLI (Go binary) and web frontend (Vercel). Both share the same Go rendering core.
- Developer · (CLI)
- Browser · User
- input.yaml · architecture spec
- awsdac · Go binary
- output.png · / .drawio / .pdf
- Monaco Editor · YAML input
- Vercel Function · Go handler
- pkg/diagram · render core
- PNG / draw.io · download
- AWS Definition · Files (YAML)
- internal/ctl · drawio.go
Installation and usage
- 1
Option 1 — npm (recommended, all platforms)
Requires Node.js 14+. Downloads the correct binary for your OS and CPU automatically. ``
bash npm install -g awsdac awsdac --version`` - 2
Option 2 — Go install (requires Go 1.21+)
``
bash go install github.com/fernandofatech/diagram-as-code/cmd/awsdac@latest`` - 3
Option 3 — Build from source
``
bash git clone https://github.com/fernandofatech/diagram-as-code.git cd diagram-as-code make build # produces ./awsdac`` Prerequisites: Go 1.21+ · Node.js 18+ (web frontend only) - 4
Generate a PNG diagram
``
bash awsdac examples/alb-ec2.yaml # default output: output.png awsdac my-architecture.yaml -o my-diagram.png -f`` - 5
Export to draw.io
``
bash awsdac examples/alb-ec2.yaml --drawio -o output.drawio`If thedrawiobinary is available locally, PNG/PDF can be exported from the generated.drawio` file. - 6
Use the web frontend (no install)
Go to dac.moretes.com, write or paste your YAML in the Monaco editor, select output format (PNG or draw.io), and click download. No CLI or account needed.
# examples/alb-ec2.yaml (structure representative of the bundled examples)
Diagram:
DefinitionFiles:
- Type: URL
Url: "https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/aws.yaml"
Resources:
Canvas:
Type: AWS::Diagram::Canvas
Children:
- VPC
VPC:
Type: AWS::EC2::VPC
Children:
- ALB
- EC2Instance1
- EC2Instance2
ALB:
Type: AWS::ElasticLoadBalancingV2::LoadBalancer
Direction: right
EC2Instance1:
Type: AWS::EC2::Instance
EC2Instance2:
Type: AWS::EC2::Instance
Links:
- Source: ALB
SourcePosition: E
Target: EC2Instance1
TargetPosition: W
- Source: ALB
SourcePosition: E
Target: EC2Instance2
TargetPosition: WHow it works internally
The CLI core is written in Go. Given a YAML file, the awsdac binary loads AWS resource definition files (also YAML, hosted in the official repository or locally via --override-def-file). These files map CloudFormation types (AWS::EC2::Instance, AWS::ElasticLoadBalancingV2::LoadBalancer, etc.) to SVG icons and layout rules.
The layout engine automatically adjusts the position and size of groups — no manual coordinate definition required. The diagram is rendered directly in Go with no dependency on external image libraries or headless browsers, making it suitable for containerized CI/CD environments.
For draw.io export, the pipeline in internal/ctl/drawio.go serializes the graph to draw.io's XML format. When the drawio binary is available in PATH, it can be called for subsequent conversion to PNG or PDF, keeping .drawio as the source of truth.
The web frontend at dac.moretes.com is a TypeScript/JavaScript application hosted on Vercel. The Monaco editor sends YAML to a Go Vercel Function, which invokes the same pkg/diagram package used by the CLI. The response is the binary file (PNG or draw.io) streamed directly to the browser. No state is persisted on the server.
The local dev server cmd/api-dev allows testing the API handler without the Vercel CLI, which speeds up the backend development cycle.
This fork exists for two practical reasons. First, I wanted native draw.io export — upstream generates only PNG/PDF. Second, I wanted a way to demonstrate diagrams-as-code in my portfolio without requiring visitors to install anything. The web frontend solves that. The core code tracks upstream closely; the additions are isolated in internal/ctl/drawio.go, pkg/diagram, and the frontend directory.
Frequently asked questions
What is the difference between this fork and the original awslabs/diagram-as-code?
This fork adds native .drawio export via the --drawio flag, the public pkg/diagram package for library use, and a full web frontend hosted at dac.moretes.com. The PNG rendering core and YAML structure are compatible with upstream.
Can I use the web frontend for confidential diagrams?
The YAML is sent to a Vercel Function for rendering and is not persisted. That said, for sensitive architectures I recommend using the CLI locally or running the dev server (cmd/api-dev) in a controlled environment.
Can the exported draw.io file be manually edited afterwards?
Yes. The .drawio file is standard XML compatible with draw.io/diagrams.net. You can open it, adjust manually, and save. The recommendation is to keep the YAML as source of truth and regenerate when needed, but ad-hoc manual edits are viable.
How do I integrate with a CI/CD pipeline?
Install via npm install -g awsdac in the build step or use the Docker image. Run awsdac input.yaml -o diagram.png -f and commit or publish the generated artifact. There is no GUI or display dependency.
Who this project is for
Use this repository if you want to treat AWS architecture diagrams as versioned code — especially if you already work with IaC and want diagrams in the same pipeline. The web frontend at dac.moretes.com is useful for fast iteration and sharing diagrams without requiring tool installation. The draw.io export is the key differentiator over upstream: if your team uses draw.io/diagrams.net as a collaborative tool, you can generate a structured starting point from YAML and refine visually afterwards. It is not the right tool if you need highly customized diagrams with pixel-perfect positioning — the automatic layout engine makes decisions for you. For standard AWS architectures documented in YAML, it works well.
Architecture, AWS, AI and market deep dives — straight to your inbox. Free.
No spam · unsubscribe anytime