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)

npm install -g awsdac

Requires Node.js 14+. The installer automatically downloads the correct binary for your OS and CPU architecture.

macOS

# via npm (recommended)
npm install -g awsdac

# via Homebrew
brew install awsdac

Linux

# via npm (recommended)
npm install -g awsdac

# via Go
go install github.com/fernandofatech/diagram-as-code/cmd/awsdac@latest

# or download the binary from GitHub Releases and move to /usr/local/bin/

Windows

# via npm (recommended)
npm install -g awsdac

# via Go
go install github.com/fernandofatech/diagram-as-code/cmd/awsdac@latest
# or download awsdac.exe from GitHub Releases and add 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 (for npm install): Node.js 14+ Prerequisites (from source): Go 1.21+ · Node.js 18+ (only for the web frontend)

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
  -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)

Example

$ awsdac examples/alb-ec2.yaml

$ awsdac privatelink.yaml -o custom-output.png

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

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

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.