nodes:

id: unique-id provider: aws # Provider name (e.g., aws, gcp, azure) kind: compute.lambda # Service category.type label: "Display Name" # optional parent: container-id # optional, for nesting in VPC/Subnet layout: # optional for child nodes (auto-positioned) x: 100 # optional for child nodes y: 200 # optional for child nodes w: 200 # required for containers (VPC/Subnet) h: 150 # required for containers

edges:

id: edge-1 from: source-node-id to: target-node-id label: "optional label" # optional


## Auto-Layout

Child nodes (with `parent`) can omit `layout` entirely for automatic positioning:

```yaml
nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    layout: { x: 0, y: 0, w: 800, h: 600 }  # Container: explicit layout

  - id: ec2_1
    provider: aws
    kind: compute.ec2
    parent: vpc
    # No layout - auto-positioned at (40, 40)

  - id: ec2_2
    provider: aws
    kind: compute.ec2
    parent: vpc
    # No layout - auto-positioned at (200, 40)

Auto-layout rules:

3 columns per row
60px padding, 160px horizontal spacing, 140px vertical spacing
Explicit x/y overrides auto-positioning
Cannot specify only x or only y (both or neither)

Node Kind Categories

The kind field uses a hierarchical format: category.type or category.subcategory.type

Container Types (require w/h in layout)

Kind	Description
`network.vpc`	Virtual Private Cloud
`network.subnet`	Subnet within VPC

Resource Types

Category	Kind Examples
`compute`	`compute.lambda`, `compute.ec2`, `compute.ecs`, `compute.eks`
`compute.lb`	`compute.lb.alb`, `compute.lb.nlb`, `compute.lb.elb`
`database`	`database.dynamodb`, `database.rds`, `database.aurora`
`storage`	`storage.s3`, `storage.efs`, `storage.ebs`
`integration`	`integration.apiGateway`, `integration.sns`, `integration.sqs`, `integration.eventBridge`
`security`	`security.iam`, `security.cognito`, `security.waf`
`analytics`	`analytics.kinesis`, `analytics.athena`, `analytics.glue`

Examples

Simple Lambda + S3

version: 1
docId: lambda-s3-example
title: "Lambda S3 Integration"

nodes:
  - id: fn
    provider: aws
    kind: compute.lambda
    label: "Process Upload"
    layout:
      x: 100
      y: 100
  - id: bucket
    provider: aws
    kind: storage.s3
    label: "uploads-bucket"
    layout:
      x: 300
      y: 100

edges:
  - id: fn-to-bucket
    from: fn
    to: bucket

API with Database

version: 1
docId: api-db-example
title: "REST API Architecture"

nodes:
  - id: api
    provider: aws
    kind: integration.apiGateway
    label: "REST API"
    layout:
      x: 100
      y: 200
  - id: handler
    provider: aws
    kind: compute.lambda
    label: "Handler"
    layout:
      x: 300
      y: 200
  - id: db
    provider: aws
    kind: database.dynamodb
    label: "Users Table"
    layout:
      x: 500
      y: 200

edges:
  - id: api-to-handler
    from: api
    to: handler
    label: "invoke"
  - id: handler-to-db
    from: handler
    to: db
    label: "read/write"

VPC with Nested Resources

version: 1
docId: vpc-example
title: "VPC Architecture"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "Production VPC"
    layout:
      x: 50
      y: 50
      w: 600
      h: 400
  - id: public-subnet
    provider: aws
    kind: network.subnet
    label: "Public Subnet"
    parent: vpc
    layout:
      x: 70
      y: 100
      w: 250
      h: 300
  - id: alb
    provider: aws
    kind: compute.lb.alb
    label: "Application LB"
    parent: public-subnet
    layout:
      x: 100
      y: 150
  - id: lambda
    provider: aws
    kind: compute.lambda
    label: "API Handler"
    parent: public-subnet
    layout:
      x: 100
      y: 280

edges:
  - id: alb-to-lambda
    from: alb
    to: lambda

Validation

# Validate and build to JSON
bun run packages/cli/src/index.ts build diagram.yaml

# Serve with live reload (default port: 3456)
bun run packages/cli/src/index.ts serve diagram.yaml

Common Errors

Missing Required Fields

Error: Missing required field "version"
Error: Missing required field "docId"

Ensure version and docId are at the document root.

Duplicate IDs

Error: Duplicate node id: "my-node"

Each node and edge must have a unique id.

Missing Edge ID

Error: Edge must have an id

All edges require an id field.

Missing Layout

Error: layout is required for top-level nodes
Error: layout.x is required for top-level nodes

Top-level nodes (without parent) must have a layout with x and y. Child nodes can omit layout for auto-positioning.

Partial Coordinates

Error: layout.x and layout.y must be both specified or both omitted

You cannot specify only x or only y. Either provide both, or omit both for auto-layout.

Invalid Parent Reference

Error: Node "child" references unknown parent: "missing-vpc"

Ensure parent references an existing container node.

Missing Edge Target

Error: Edge references unknown node: "missing-id"

Ensure from and to reference existing node IDs.

YAML Syntax Error

Error: YAML parse error at line 5

Check indentation (2 spaces) and proper quoting.

Tips

Use descriptive IDs: user-api not n1
Labels can include spaces and special characters (use quotes)
Use parent to nest resources inside VPC/Subnet containers
Container nodes (VPC, Subnet) require w and h in layout
Child nodes can omit layout entirely for automatic grid positioning
Use comments with # for documentation
The kind field is flexible - use any string that makes sense for your architecture

yaml-authoring

YAML Diagram Authoring

Basic Structure