### Install Diagram-as-Code with Go

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/introduction.md

For Go developers, install the awsdac CLI tool using the go install command.

```bash
go install github.com/awslabs/diagram-as-code/cmd/awsdac@latest
```

--------------------------------

### Install awsdac MCP Server via Go

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/mcp-server.md

For Go developers, install the awsdac MCP server binary using the go install command.

```bash
go install github.com/awslabs/diagram-as-code/cmd/awsdac-mcp-server@latest
```

--------------------------------

### Install awsdac CLI

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Install the awsdac CLI tool using Homebrew for macOS or Go for other systems. Also includes installation for the MCP server binary.

```bash
# macOS
brew install awsdac
```

```bash
# Go (1.21+)
go install github.com/awslabs/diagram-as-code/cmd/awsdac@latest
```

```bash
# MCP server binary (Go)
go install github.com/awslabs/diagram-as-code/cmd/awsdac-mcp-server@latest
```

--------------------------------

### Example AI Assistant Prompts for Diagram Generation

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Examples of prompts to use with AI assistants for generating AWS architecture diagrams, saving them to files, or retrieving format documentation.

```text
# Example AI assistant prompts:

"Generate an AWS architecture diagram showing a VPC with a public subnet
 containing two EC2 instances behind an Application Load Balancer."

"Generate an AWS architecture diagram for a three-tier web application
 and save it to /tmp/architecture.png"

"Show me the diagram-as-code YAML format documentation"
```

--------------------------------

### Configure awsdac-mcp-server for AI Assistants

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/mcp-server.md

Example JSON configuration for awsdac-mcp-server in Claude Desktop or Cline. Ensure the 'command' path is correct for your installation.

```json
{
  "mcpServers": {
    "awsdac-mcp-server": {
      "command": "/opt/homebrew/bin/awsdac-mcp-server",
      "args": [],
      "type": "stdio"
    }
  }
}
```

--------------------------------

### Install awsdac CLI with Go

Source: https://github.com/awslabs/diagram-as-code/blob/main/README.md

Install the awsdac CLI tool using the Go package manager. Requires Go 1.21 or higher.

```bash
$ go install github.com/awslabs/diagram-as-code/cmd/awsdac@latest
```

--------------------------------

### 1-Indexed Repetition with seq and add

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/template.md

Combine `seq` and `add` functions to achieve 1-indexed iteration for resource naming or configuration. This example demonstrates creating VPCs with indices starting from 1.

```go-template
    {{- range $i := seq 3}}{{$vpc := (add $i 1)}}
    VPC{{$vpc}}:
      Type: AWS::EC2::VPC
      Title: "VPC"
      Children:
        - VPC{{$vpc}}AvailabilityZone1
        - VPC{{$vpc}}AvailabilityZone2
    {{- end}}
```

--------------------------------

### Web Application Workflow Example

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/cloudformation.md

Demonstrates the two-step process for generating and customizing a diagram for a web application from its CloudFormation template.

```bash
# Generate DAC file
awsdac web-app.yaml --cfn-template --dac-file -o web-app-dac.yaml

# Edit web-app-dac.yaml to improve layout

# Generate final diagram
awsdac web-app-dac.yaml -o web-app-final.png
```

--------------------------------

### Install awsdac CLI with Homebrew

Source: https://github.com/awslabs/diagram-as-code/blob/main/README.md

Install the awsdac CLI tool on macOS using Homebrew.

```bash
$ brew install awsdac
```

--------------------------------

### Simple VPC CloudFormation Template

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/cloudformation.md

Example CloudFormation template defining a VPC and two subnets.

```yaml
Resources:
  MyVPC:
    Type: AWS::EC2::VPC
  PublicSubnet:
    Type: AWS::EC2::Subnet
  PrivateSubnet:
    Type: AWS::EC2::Subnet
```

--------------------------------

### Install awsdac MCP Server via Homebrew

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/mcp-server.md

Use this command to install the awsdac CLI tool, which includes the MCP server binary, on macOS using Homebrew.

```bash
brew install awsdac
```

--------------------------------

### LCA Identification Example

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/unordered-children.md

This example illustrates the first step of the reordering algorithm: identifying the Lowest Common Ancestor (LCA) for a given link. The LCA is crucial for determining the scope of reordering needed.

```text
Example: Resource1 → Resource6
LCA = ResourceA
```

--------------------------------

### Add Go bin to PATH

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

If the 'awsdac' command is not found after installation via Go, verify and add your GOPATH/bin to your PATH.

```bash
# Verify GOPATH/bin is in PATH
echo $PATH | grep go/bin

# If not, add to PATH
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

--------------------------------

### Get awsdac Version

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

Retrieve the installed version of the `awsdac` tool. This is useful when reporting bugs or checking compatibility.

```bash
awsdac --version
```

--------------------------------

### Verify awsdac-mcp-server Installation

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/mcp-server.md

Check if the awsdac-mcp-server binary is installed and accessible in your system's PATH.

```bash
which awsdac-mcp-server
# Output: /opt/homebrew/bin/awsdac-mcp-server (or similar)
```

--------------------------------

### DAC File Structure Example

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Defines the basic structure of a Diagram-as-Code YAML file, including sections for DefinitionFiles, Resources, and Links.

```yaml
Diagram:
  DefinitionFiles:         # Icon/resource definitions (URL or local file)
    - Type: URL
      Url: "https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml"
  Resources:               # All diagram resources and their hierarchy
    Canvas:
      Type: AWS::Diagram::Canvas
  Links:                   # Connections between resources
    - Source: ResourceA
      Target: ResourceB
```

--------------------------------

### Organize Web Tier Resources with Comments

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/best-practices.md

Provides an example of organizing resources within a 'WebTier' using a `VerticalStack` and includes comments for better readability and maintainability. Use comments to clarify the purpose of resource groups.

```yaml
# Web Tier Resources
WebTier:
  Type: AWS::Diagram::VerticalStack
  Children:
    - ALB
    - WebInstances
```

--------------------------------

### Use Relative Links for Internal Documentation

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/contributing-docs.md

When linking to other documentation files within the project, use relative paths. This example links to a 'resource-types.md' file.

```markdown
See [Resource Types](resource-types.md) for details.
```

--------------------------------

### Indicate Version-Specific Features with Badges

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/contributing-docs.md

Use version badges, such as '[Beta]', to indicate features that are specific to certain versions of the software. This example shows a heading with a beta badge.

```markdown
## CloudFormation Conversion [Beta]
```

--------------------------------

### Add Homebrew bin to PATH

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

If the 'awsdac' command is not found after installation via Homebrew, add the Homebrew bin directory to your PATH.

```bash
# Verify installation
brew list awsdac

# If not in PATH, add Homebrew bin to PATH
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

--------------------------------

### Define a Single Resource

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/resource-types.md

Example of defining a single resource, in this case, an AWS EC2 Subnet using a preset. This demonstrates the basic structure for declaring a resource with its type and optional presets.

```yaml
Subnet:
  Type: AWS::EC2::Subnet
  Preset: PublicSubnet
```

--------------------------------

### Find awsdac-mcp-server Binary Location

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/mcp-server.md

Commands to locate the awsdac-mcp-server binary if it's not in your PATH or if installed via Go.

```bash
# Check if awsdac-mcp-server is in your PATH
which awsdac-mcp-server

# Or check common Go install locations
ls ~/go/bin/awsdac-mcp-server
ls $GOPATH/bin/awsdac-mcp-server  # if GOPATH is set
```

--------------------------------

### Internet Gateway on North Border

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/border-children.md

Example of attaching an Internet Gateway to the North (top) edge of a VPC.

```yaml
VPC:
  Type: AWS::EC2::VPC
  BorderChildren:
    - Position: N
      Resource: IGW
```

--------------------------------

### SpanResources Overlay Example

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/resource-types.md

Illustrates using SpanResources to create a visual overlay that spans across multiple resources, such as an Auto Scaling Group spanning subnets. The overlay is defined at the same level as other resources and references targets via SpanResources.

```yaml
PublicSubnet1:
  Type: AWS::EC2::Subnet
  Children:
    - Instance1
PublicSubnet2:
  Type: AWS::EC2::Subnet
  Children:
    - Instance2
Instance1:
  Type: AWS::EC2::Instance
Instance2:
  Type: AWS::EC2::Instance

# Overlay spanning both subnets
ASG:
  Type: AWS::AutoScaling::AutoScalingGroup
  BorderType: Dashed
  SpanResources:
    - PublicSubnet1
    - PublicSubnet2

```

--------------------------------

### Define a Resource with EC2 Instance Children

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/resource-types.md

This example shows a Subnet resource containing an EC2 Instance as a child. The 'Children' attribute is used to establish a parent-child relationship, visually nesting the instance within the subnet in the diagram.

```yaml
Subnet:
  Type: AWS::EC2::Subnet
  Preset: PublicSubnet
  Children:
    - Instance
Instance:
  Type: AWS::EC2::Instance
```

--------------------------------

### Identifying LCA Children Example

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/unordered-children.md

This step identifies which direct children of the Lowest Common Ancestor (LCA) contain the source and target resources of a link. This information is used to determine the relative ordering of these parent containers.

```text
Source (Resource1) belongs to: ResourceB
Target (Resource6) belongs to: ResourceD
```

--------------------------------

### Specify Language for Syntax Highlighting

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/contributing-docs.md

Always specify the language for code blocks to enable syntax highlighting. This example shows a YAML resource definition.

```yaml
Resources:
  VPC:
    Type: AWS::EC2::VPC
```

--------------------------------

### Generate Diagrams with Go Templates

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Enable Go template support with the `-t` flag to create dynamic DAC files. Custom functions like `seq`, `add`, `mul`, and `mkarr` are available for advanced templating.

```bash
awsdac architecture.tmpl.yaml -t -o output.png
```

```yaml
# architecture.tmpl.yaml — generates 3 identical VPCs across regions
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
      Direction: vertical
      Children:
        - AWSCloud
    AWSCloud:
      Type: AWS::Diagram::Cloud
      Direction: horizontal
      Children:
        {{- range $i := seq 3}}
        - Region{{$i}}
        {{- end}}
    {{- range $i := seq 3}}{{$n := (add $i 1)}}
    Region{{$i}}:
      Type: AWS::Region
      Title: "Region {{$n}}"
      Direction: vertical
      Children:
        - VPC{{$i}}
    VPC{{$i}}:
      Type: AWS::EC2::VPC
      Title: "VPC {{$n}}"
      Children:
        - Subnet{{$i}}
    Subnet{{$i}}:
      Type: AWS::EC2::Subnet
      Preset: PublicSubnet
      Children:
        - Instance{{$i}}
    Instance{{$i}}:
      Type: AWS::EC2::Instance
    {{- end}}
  Links:
    - Source: Instance0
      Target: Instance1
      TargetArrowHead:
        Type: Open
    - Source: Instance1
      Target: Instance2
      TargetArrowHead:
        Type: Open

```

--------------------------------

### Generate Diagram from Simple VPC Template

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/cloudformation.md

Command to generate a diagram directly from the simple VPC CloudFormation template.

```bash
awsdac vpc-simple.yaml --cfn-template
```

--------------------------------

### Make Binary Executable

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

If you encounter a 'Permission denied' error when running 'awsdac', make the binary executable.

```bash
# Make binary executable
chmod +x $(which awsdac)
```

--------------------------------

### DefinitionFiles Configuration

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Specifies how to load icon definitions and resource presets, supporting both remote URLs and local file paths.

```yaml
Diagram:
  DefinitionFiles:
    # Load from official awsdac GitHub repository (recommended)
    - Type: URL
      Url: "https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml"

    # Load from a local file (for custom or offline use)
    - Type: LocalFile
      LocalFile: "./definitions/my-custom-definition.yaml"
```

--------------------------------

### VPN Gateway on South Border

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/border-children.md

Example of attaching a VPN Gateway to the South (bottom) edge of a VPC.

```yaml
VPC:
  Type: AWS::EC2::VPC
  BorderChildren:
    - Position: S
      Resource: VPNGateway
```

--------------------------------

### AWS::Diagram::HorizontalStack Example

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/resource-types.md

Defines a horizontal stack of resources. Alignment can be controlled using the 'align' attribute.

```yaml
AWS::Diagram::HorizontalStack
```

--------------------------------

### AWS::Diagram::VerticalStack Example

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/resource-types.md

Defines a vertical stack of resources. Alignment can be controlled using the 'align' attribute.

```yaml
AWS::Diagram::VerticalStack
```

--------------------------------

### Specify Definition File via URL

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/introduction.md

In the DefinitionFiles section, use Type: URL to reference pre-defined resource definitions from a remote YAML file.

```yaml
    DefinitionFiles:
      - Type: URL
        Url: https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml
```

--------------------------------

### Transit Gateway Attachment on West Border

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/border-children.md

Example of attaching a Transit Gateway Attachment to the West (left) edge of a VPC.

```yaml
VPC:
  Type: AWS::EC2::VPC
  BorderChildren:
    - Position: W
      Resource: TGWAttachment
```

--------------------------------

### Verify MCP Server Binary Path

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

Before configuring the MCP server, verify the correct path to the 'awsdac-mcp-server' binary using the 'which' command.

```bash
which awsdac-mcp-server
# Use the output path in your config
```

--------------------------------

### Build mapcheck Static Analyzer

Source: https://github.com/awslabs/diagram-as-code/blob/main/CONTRIBUTING.md

Compile the `mapcheck` static analyzer from its source code. Ensure you are in the tool's directory before building.

```bash
cd tools/mapcheck
go build -o mapcheck main.go
```

--------------------------------

### Specify Definition File URL

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

If a resource type is not found, verify that the 'DefinitionFiles' section in your diagram configuration correctly points to the URL of the definition file.

```yaml
Diagram:
  DefinitionFiles:
    - Type: URL
      Url: https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml
```

--------------------------------

### Basic BorderChildren Usage

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/border-children.md

Demonstrates placing an Internet Gateway on the North border and a VPN Gateway on the South border of a VPC.

```yaml
Resources:
  VPC:
    Type: AWS::EC2::VPC
    BorderChildren:
      - Position: N
        Resource: InternetGateway
      - Position: S
        Resource: VPNGateway
    Children:
      - PublicSubnet
      - PrivateSubnet
      
  InternetGateway:
    Type: AWS::EC2::InternetGateway
    
  VPNGateway:
    Type: AWS::EC2::VPNGateway
```

--------------------------------

### Direct CloudFormation Conversion

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/cloudformation.md

Use this for a quick visualization of CloudFormation resources. The output filename defaults to 'output.png'.

```bash
awsdac template.yaml --cfn-template
```

--------------------------------

### LCA Direction Check Example

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/unordered-children.md

This step verifies the layout direction of the identified Lowest Common Ancestor (LCA). The LCA's direction (horizontal or vertical) influences how its children are reordered.

```text
ResourceA.Direction = "horizontal"
```

--------------------------------

### Mixed Manual and Auto-positioning for Links

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/auto-positioning.md

Combine manual positioning for specific connection points with auto-positioning for others. This allows for precise control where needed while leveraging automatic calculations elsewhere.

```yaml
Links:
  - Source: ALB
    SourcePosition: E      # Manual
    Target: Instance3
    TargetPosition: auto   # Automatic
```

--------------------------------

### Configure awsdac-mcp-server in Claude Desktop Config

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Configure the awsdac-mcp-server binary path in the MCP client config file for AI-assisted diagram generation.

```json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "awsdac-mcp-server": {
      "command": "/opt/homebrew/bin/awsdac-mcp-server",
      "args": [],
      "type": "stdio"
    }
  }
}
```

```json
// With custom log file
{
  "mcpServers": {
    "awsdac-mcp-server": {
      "command": "/opt/homebrew/bin/awsdac-mcp-server",
      "args": ["--log-file", "/tmp/awsdac-mcp.log"],
      "type": "stdio"
    }
  }
}
```

--------------------------------

### Nested UnorderedChildren Configuration

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/unordered-children.md

Demonstrates how `UnorderedChildren: true` can be applied to nested resources, such as subnet groups within a VPC. This allows for automatic reordering of subnets within their respective groups, optimizing the layout of complex diagrams based on link connections.

```yaml
Resources:
  VPC:
    Type: AWS::EC2::VPC
    Direction: vertical
    Options:
      UnorderedChildren: true
    Children:
      - SubnetGroup1
      - SubnetGroup2
  
  SubnetGroup1:
    Type: AWS::Diagram::HorizontalStack
    Options:
      UnorderedChildren: true
    Children:
      - Subnet1
      - Subnet2
  
  SubnetGroup2:
    Type: AWS::Diagram::HorizontalStack
    Options:
      UnorderedChildren: true
    Children:
      - Subnet3
      - Subnet4

Links:
  - Source: Instance1  # In Subnet1
    Target: Instance4  # In Subnet4
```

--------------------------------

### Basic awsdac CLI Usage

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Generate a PNG diagram from a DAC YAML file. Supports custom output filenames, remote file URLs, and template processing.

```bash
# Basic usage — outputs output.png
awsdac architecture.yaml
```

```bash
# Custom output filename
awsdac architecture.yaml -o my-diagram.png
```

```bash
# Use a remote YAML file directly
awsdac https://raw.githubusercontent.com/awslabs/diagram-as-code/main/examples/alb-ec2.yaml
```

```bash
# Process file as a Go text/template before rendering
awsdac architecture.tmpl.yaml -t
```

```bash
# Verbose logging
awsdac architecture.yaml -v
```

--------------------------------

### Define Link with Manual Positioning

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/links.md

Specify source, target, and their exact positions on the resource for a straight link. Optional parameters include line width, color, and style.

```yaml
Diagrams:
  Resources:
    ALB: ...
    PublicSubnet1Instance: ...
  Links:
    - Source: ALB # (required)
      SourcePosition: NNE # (required)
      Target: PublicSubnet1Instance # (required)
      TargetPosition: S # (required)
      LineWidth: 1 # (optional)
      LineColor: 'rgba(255,255,255,255)' # (optional)
      LineStyle: `normal|dashed` (optional)
```

--------------------------------

### Use HorizontalStack and VerticalStack for Layout

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Demonstrates using AWS::Diagram::HorizontalStack and AWS::Diagram::VerticalStack to control the layout of child resources. These are invisible containers for precise placement.

```yaml
Resources:
  VPC:
    Type: AWS::EC2::VPC
    Direction: vertical          # Stack children top-to-bottom
    Children:
      - SubnetRow                # Row of subnets
      - ALB                      # ALB below the subnet row

  SubnetRow:
    Type: AWS::Diagram::HorizontalStack   # Subnets placed side-by-side
    Children:
      - PublicSubnet1
      - PublicSubnet2

  # For top/bottom alignment within horizontal stack:
  SidePanel:
    Type: AWS::Diagram::VerticalStack
    Align: center                # center, top, bottom
    Children:
      - Service1
      - Service2

  PublicSubnet1:
    Type: AWS::EC2::Subnet
    Preset: PublicSubnet
  PublicSubnet2:
    Type: AWS::EC2::Subnet
    Preset: PublicSubnet
  ALB:
    Type: AWS::ElasticLoadBalancingV2::LoadBalancer
    Preset: Application Load Balancer
  Service1:
    Type: AWS::Lambda::Function
  Service2:
    Type: AWS::DynamoDB::Table
```

--------------------------------

### Basic Repetition with seq

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/template.md

Use the `seq` function within a `range` loop to repeat a block of YAML, generating multiple resources with sequential indices. This is useful for creating similar resources like VPCs in different zones.

```go-template
    {{- range $i := seq 3}}
    VPC{{$i}}:
      Type: AWS::EC2::VPC
      Title: "VPC"
      Children:
        - VPC{{$i}}AvailabilityZone0
        - VPC{{$i}}AvailabilityZone1
    {{- end}}
```

--------------------------------

### Configure Auto-positioning for Links

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

Ensure links automatically find optimal positions by setting 'SourcePosition' and 'TargetPosition' to 'auto' or omitting them entirely.

```yaml
Links:
  - Source: ALB
    SourcePosition: auto  # or omit entirely
    Target: Instance
    TargetPosition: auto  # or omit entirely
```

--------------------------------

### Convert CloudFormation to Diagram as Code

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Generate diagrams directly from CloudFormation templates or create an editable DAC file for customization. Use the `--cfn-template` flag for conversion.

```bash
# Direct conversion: CloudFormation template → PNG
awsdac cfn-stack.yaml --cfn-template -o cfn-diagram.png

# Two-step: CloudFormation template → editable DAC YAML → PNG
awsdac cfn-stack.yaml --cfn-template --dac-file -o editable.yaml
# (edit editable.yaml to adjust layout, titles, links)
awsdac editable.yaml -o final-diagram.png
```

```yaml
# Example CloudFormation template (cfn-stack.yaml)
Resources:
  MyVPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.0.0.0/16
  PublicSubnet:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref MyVPC
      CidrBlock: 10.0.1.0/24
  PrivateSubnet:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref MyVPC
      CidrBlock: 10.0.2.0/24
  WebServer:
    Type: AWS::EC2::Instance
    Properties:
      SubnetId: !Ref PublicSubnet

```

--------------------------------

### Basic UnorderedChildren Configuration

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/advanced/unordered-children.md

Configure a resource to allow its children to be reordered automatically by setting `UnorderedChildren: true` in its Options. This is useful for resources like VPCs where the order of child elements might not be critical and can be optimized for link clarity.

```yaml
Resources:
  ParentResource:
    Type: AWS::EC2::VPC
    Direction: horizontal
    Options:
      UnorderedChildren: true
    Children:
      - Child1
      - Child2
      - Child3
```

--------------------------------

### Specify Output Filename

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/introduction.md

Use the -o flag to specify a custom filename for the generated diagram image.

```bash
awsdac -o custom-name.png
```

--------------------------------

### Beta: Generate Diagram from CloudFormation

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Beta feature to generate a diagram directly from a CloudFormation template. Can also generate a corresponding DAC YAML file.

```bash
# [Beta] Generate diagram from a CloudFormation template
awsdac cfn-template.yaml --cfn-template -o infra.png
```

```bash
# [Beta] Generate both a DAC YAML file and a diagram from a CloudFormation template
awsdac cfn-template.yaml --cfn-template --dac-file -o output.yaml
```

--------------------------------

### Run mapcheck Static Analyzer

Source: https://github.com/awslabs/diagram-as-code/blob/main/CONTRIBUTING.md

Execute the `mapcheck` static analyzer on the codebase. Use specific paths to analyze only certain directories or files.

```bash
# Run mapcheck on the entire codebase
./tools/mapcheck/mapcheck ./...
```

```bash
# Run mapcheck on specific files or directories
./tools/mapcheck/mapcheck internal/ctl/
```

--------------------------------

### mapcheck Safe Map Access Patterns

Source: https://github.com/awslabs/diagram-as-code/blob/main/CONTRIBUTING.md

Illustrates unsafe and safe map access patterns in Go. The safe patterns use the comma-ok idiom to check for key existence.

```go
// ❌ Unsafe - may panic if key doesn't exist
value := myMap[key]
```

```go
// ✅ Safe - recommended patterns
value, ok := myMap[key]  // Check existence
value, _ := myMap[key]   // Ignore existence check
_, ok := myMap[key]      // Only check existence
```

--------------------------------

### Define a User Resource in Diagram as Code

Source: https://github.com/awslabs/diagram-as-code/blob/main/cmd/awsdac-mcp-server/prompts/generate_dac_from_user_requirements.txt

Use this YAML structure to represent a user in your diagram. It defines the resource type and applies a 'User' preset.

```yaml
    User:
      Type: AWS::Diagram::Resource
      Preset: "User"
```

--------------------------------

### View MCP Server Logs

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/mcp-server.md

Tail the default MCP server log file to view real-time debugging information.

```bash
tail -f /tmp/awsdac-mcp-server.log
```

--------------------------------

### Override Definition File

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Override the default definition file used for icons and resource presets, useful for testing or custom icon sets.

```bash
# Override the definition file (for testing/custom icons)
awsdac architecture.yaml --override-def-file ./my-definitions.yaml
```

--------------------------------

### Complete ALB + EC2 in Two Availability Zones Diagram-as-Code

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

A full Diagram-as-Code YAML file defining an ALB distributing traffic to EC2 instances in two public subnets, with an Internet Gateway on the VPC border. Save this as alb-ec2.yaml and run `awsdac alb-ec2.yaml -o alb-ec2.png`.

```yaml
# Save as alb-ec2.yaml, then run: awsdac alb-ec2.yaml -o alb-ec2.png
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
      Direction: vertical
      Children:
        - AWSCloud
        - User
    AWSCloud:
      Type: AWS::Diagram::Cloud
      Direction: vertical
      Preset: AWSCloudNoLogo
      Align: center
      Children:
        - VPC
    VPC:
      Type: AWS::EC2::VPC
      Direction: vertical
      Children:
        - VPCPublicStack
        - ALB
      BorderChildren:
        - Position: S
          Resource: IGW
    VPCPublicStack:
      Type: AWS::Diagram::HorizontalStack
      Children: 
        - PublicSubnet1
        - PublicSubnet2
    PublicSubnet1:
      Type: AWS::EC2::Subnet
      Preset: PublicSubnet
      Children:
        - Instance1
    Instance1:
      Type: AWS::EC2::Instance
    PublicSubnet2:
      Type: AWS::EC2::Subnet
      Preset: PublicSubnet
      Children:
        - Instance2
    Instance2:
      Type: AWS::EC2::Instance
    ALB:
      Type: AWS::ElasticLoadBalancingV2::LoadBalancer
      Preset: Application Load Balancer
    IGW:
      Type: AWS::EC2::InternetGateway
      IconFill:
        Type: rect
    User:
      Type: AWS::Diagram::Resource
      Preset: User

  Links:
    - Source: User
      SourcePosition: N
      Target: IGW
      TargetPosition: S
      TargetArrowHead:
        Type: Open
    - Source: IGW
      SourcePosition: N
      Target: ALB
      TargetPosition: S
      TargetArrowHead:
        Type: Open
    - Source: ALB
      SourcePosition: NNW
      Target: Instance1
      TargetPosition: SSE
      TargetArrowHead:
        Type: Open
    - Source: ALB
      SourcePosition: NNE
      Target: Instance2
      TargetPosition: SSW
      TargetArrowHead:
        Type: Open

```

--------------------------------

### Generate Diagram from URL

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/introduction.md

Generate an AWS infrastructure diagram by providing the URL to a DAC YAML file. The output is saved as output.png by default.

```bash
awsdac https://raw.githubusercontent.com/awslabs/diagram-as-code/main/examples/alb-ec2.yaml
```

--------------------------------

### Customizing Links with Positions and Arrowheads

Source: https://context7.com/awslabs/diagram-as-code/llms.txt

Connect resources using directional lines with optional manual positioning and various arrowhead styles. Auto-positioning is used if positions are omitted.

```yaml
Links:
  # Auto-positioning (positions inferred from layout)
  - Source: ALB
    Target: Instance1

  # Manual positions with arrowhead
  - Source: ALB
    SourcePosition: NNW
    Target: PublicSubnet1Instance
    TargetPosition: SSE
    TargetArrowHead:
      Type: Open            # Open or Default
      Width: Default        # Narrow / Default / Wide
      Length: 2

  # Orthogonal (right-angle) link
  - Source: NLB
    SourcePosition: N
    Target: Instance1
    TargetPosition: E
    Type: orthogonal
    TargetArrowHead:
      Type: Open

  # Colored line with label
  - Source: User
    SourcePosition: W
    Target: IGW
    TargetPosition: W
    Type: orthogonal
    LineColor: 'rgba(0,125,125,255)'
    LineWidth: 2
    LineStyle: dashed
    TargetArrowHead:
      Type: Open
    Labels:
      SourceRight:
        Title: "SSH access"
        Color: 'rgba(0,125,125,255)'
      TargetLeft:
        Title: "port 22"

  # Both source and target arrowheads
  - Source: ServiceA
    SourcePosition: E
    SourceArrowHead:
      Type: Open
    Target: ServiceB
    TargetPosition: W
    TargetArrowHead:
      Type: Open

```

--------------------------------

### Generate Diagram with Custom Output File

Source: https://github.com/awslabs/diagram-as-code/blob/main/README.md

Generate a diagram from a YAML input file and specify a custom output file name. The '-o' flag is used for this purpose.

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

--------------------------------

### Add Custom Titles to Resources

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/introduction.md

Assign custom labels to resources using the 'Title' parameter for better clarity in the diagram.

```yaml
Resources:
  S3:
    Type: AWS::S3::Bucket
    Preset: "Bucket with objects"
+   Title: "S3 (image data bucket)"
```

--------------------------------

### Manually Adjust Link Positions

Source: https://github.com/awslabs/diagram-as-code/blob/main/doc/troubleshooting.md

For precise control over link placement, manually adjust link positions using 16-wind rose notation (e.g., N, SSE, WNW).

```yaml
Links:
  - Source: ALB
    SourcePosition: SSE  # Adjust position
    Target: Instance
    TargetPosition: N
```