Diagram-as-code

This command line interface (CLI) tool enables drawing infrastructure diagrams for Amazon Web Services through YAML code. It facilitates diagram-as-code without relying on image libraries.

The CLI tool promotes code reuse, testing, integration, and automating the diagramming process. It allows managing diagrams with Git by writing human-readable YAML.

Example templates are here. Check out the Introduction Guide as well for additional information.

Features

• Compliant with AWS architecture guidelines
  Easily generate diagrams that follow AWS diagram guidelines.
• Flexible
  Automatically adjust the position and size of groups.
• Lightweight & CI/CD-friendly
  Start quickly on a container; no dependency on headless browser or GUI.
• Integrate with your Infrastructure as Code
  Generate diagrams to align with your IaC code without managing diagrams manually.
• As a drawing library
  Use as Golang Library and integrate with other IaC tools, AI, or drawing GUI tools.
• Extensible
  Add definition files to create non-AWS diagrams as well.

About This Fork

This is a fork of awslabs/diagram-as-code maintained by Fernando Azevedo — fernando.moretes.com.

Fork repository: github.com/fernandofatech/diagram-as-code

This fork extends the original CLI tool with new features and a fully hosted web frontend:

Web Frontend (New)

A browser-based editor that lets you write YAML and generate diagrams in PNG or draw.io format — no CLI or local install required. Hosted 100% on Vercel.

Try it live: dac.moretes.com

Key features:

• Monaco-powered YAML editor with syntax highlighting
• PNG and draw.io format toggle
• Built-in example templates (ALB+EC2, VPC+NAT, ALB+AutoScaling, Multi-Region)
• One-click download for generated diagrams
• Go serverless backend via Vercel Functions

CLI Extensions (vs upstream)

• Native .drawio export via --drawio flag or -o output.drawio
• Draw.io export pipeline in Go (internal/ctl/drawio.go, drawio_assets.go)
• PNG/PDF can optionally be exported from generated .drawio files when the drawio binary is available, keeping .drawio as the source of truth for local CLI and non-serverless environments
• Public wrapper package pkg/diagram for embedding in external tools
• cmd/api-dev local dev server for testing the API handler without Vercel CLI

Getting started

npm — all platforms (recommended)

Requires Node.js 14+. Downloads the correct binary automatically for your OS and CPU.

npm install -g awsdac
awsdac --version

---

macOS

# via npm (recommended)
npm install -g awsdac

# via Homebrew
brew install awsdac

---

Linux

# via npm (recommended)
npm install -g awsdac

# via Go (requires Go 1.21+)
go install github.com/fernandofatech/diagram-as-code/cmd/awsdac@latest

# via binary — download and install manually
curl -LO https://github.com/fernandofatech/diagram-as-code/releases/latest/download/awsdac-$(curl -s https://api.github.com/repos/fernandofatech/diagram-as-code/releases/latest | grep tag_name | cut -d'"' -f4)_linux-amd64.zip
unzip awsdac-*_linux-amd64.zip
sudo mv awsdac-*_linux-amd64/awsdac /usr/local/bin/
awsdac --version

---

Windows

# via npm (recommended)
npm install -g awsdac

# via Go (requires Go 1.21+)
go install github.com/fernandofatech/diagram-as-code/cmd/awsdac@latest

# via binary — download from GitHub Releases, extract and add to PATH:
# https://github.com/fernandofatech/diagram-as-code/releases/latest
# Download: awsdac-vX.Y.Z_windows-amd64.zip
# Extract awsdac.exe and add the folder to your PATH

---

From source (all platforms)

git clone https://github.com/fernandofatech/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)

Usage

Usage:
  awsdac <input filename> [flags]

Flags:
      --allow-untrusted-definitions  Allow loading definition files from untrusted URLs (not from official repository)
  -c, --cfn-template               [beta] Create diagram from CloudFormation template
  -d, --dac-file                   [beta] Generate YAML file in dac (diagram-as-code) format from CloudFormation template
      --drawio                     Generate draw.io (.drawio) file instead of PNG
      --pdf                        Generate PDF file instead of PNG
  -f, --force                      Overwrite output file without confirmation
  -h, --help                       help for awsdac
      --height int                 Resize output image height (0 means no resizing)
  -o, --output string              Output file name (default "output.png")
      --override-def-file string   For testing purpose, override DefinitionFiles to another url/local file
  -t, --template                   Processes the input file as a template according to text/template
  -v, --verbose                    Enable verbose logging
      --version                    version for awsdac
      --width int                  Resize output image width (0 means no resizing)

Examples

Generate PNG (default)

awsdac examples/alb-ec2.yaml

Custom output filename

awsdac my-architecture.yaml -o my-diagram.png

Force overwrite without confirmation

awsdac my-architecture.yaml -o output.png -f

Generate draw.io file

awsdac examples/alb-ec2.yaml --drawio -o output.drawio

# or just use .drawio extension — flag is inferred automatically
awsdac examples/alb-ec2.yaml -o output.drawio

Generate PDF

awsdac examples/alb-ec2.yaml --pdf -o output.pdf

Resize output image

awsdac examples/alb-ec2.yaml --width 1920 --height 1080 -o output.png

Use a Go template file

awsdac examples/tgw-nwfw-tmpl.yaml -t -o output.png

Convert CloudFormation template to diagram

awsdac my-cfn-template.yaml -c -o output.png

Convert CloudFormation template to DAC YAML (for further editing)

awsdac my-cfn-template.yaml -c -d -o my-diagram.yaml

Verbose logging

awsdac examples/alb-ec2.yaml -v

Use a local definition file instead of the remote one

awsdac my-diagram.yaml --override-def-file ./my-definitions.yaml

Check version

awsdac --version

How Draw.io Export Works

1. The YAML file is parsed with the same resource/link model used by PNG rendering.
2. The same layout engine is executed (Scale and ZeroAdjust) to keep geometry consistent.
3. Children are reordered from link topology to keep ordering aligned with PNG output.
4. Resources are exported as draw.io cells and links are exported as draw.io edges in mxGraphModel.
5. Official AWS SVG icons are loaded from the AWS Asset Package and embedded as data URIs for leaf resources.

PNG/PDF Export Source of Truth

When the drawio binary is installed in the runtime environment, DAC YAML to PNG and PDF generation can be routed through a generated .drawio file first and then exported by draw.io itself. This keeps local CLI output aligned with .drawio output and makes draw.io the rendering source of truth.

If the drawio binary is not available, the project falls back to the native Go PNG/PDF renderer so existing environments continue to work.

Documentation

Getting Started

• Introduction Guide - Quick start (10 minutes) and core concepts
• Troubleshooting - Common issues and solutions

Core Features

• Resource Types - Available AWS resources and diagram elements
• Links - Connecting resources with arrows and lines

Tools & Integration

• MCP Server - AI assistant integration
• CloudFormation Conversion [Beta] - Convert CloudFormation templates to diagrams

Advanced Features

• Templates - Using Go templates for dynamic diagrams
• UnorderedChildren - Automatic child reordering for optimal layouts
• Auto-positioning - Smart link positioning
• Link Grouping Offset - Prevent link overlap
• BorderChildren - Place resources on borders

Guides

• Best Practices - Design patterns and diagram standards
• Gitflow Workflow - Branching model for PRs, tests, review, and release flow
• AI Documentation - Context, architecture, guardrails, and development model for AI agents
• Agent Entry Point - Primary project instructions for coding agents

Contributing

• Documentation Guidelines - How to contribute to documentation

---

Development Guide

For contributing guidelines, please see CONTRIBUTING.md.

Project Structure

• cmd/ - CLI tools (awsdac, awsdac-mcp-server, api-dev)
• internal/ - Core implementation
  • cache/ - Caching logic
  • ctl/ - Core control logic
  • definition/ - Definition file handling
  • font/ - Font management
  • types/ - Core types and structures
  • vector/ - Vector operations
• pkg/diagram/ - Public wrapper around internal/ctl (importable by external packages)
• api/ - Vercel serverless handler (POST /api/generate)
• web/ - Next.js 14 frontend (Monaco editor + diagram preview)
• test/ - Integration tests
• tools/ - Development tools
• examples/ - Example YAML files
• doc/ - Documentation

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

Portfolio / Portfólio

• Live / Ao vivo: Diagram as Code
• GitHub: fernandofatech/diagram-as-code
• Author / Autor: Fernando Francisco Azevedo · LinkedIn · GitHub

PT-BR: Diagram-as-code project/fork connected to Fernando Moretes architecture portfolio. Este repositório público faz parte do ecossistema de portfólio de Fernando Moretes.

EN: Diagram-as-code project/fork connected to Fernando Moretes architecture portfolio. This public repository is part of Fernando Moretes' portfolio ecosystem.