DIAGRAM AS CODE

ArchDSL

A minimal text language for building architecture diagrams. Write code, get a visual diagram. Paste into AI, get a diagram back. No drag-and-drop required.

Nodes Edges Groups Text & Sticky Step Numbers Full Example Use with AI

Nodes

The core building block. Every service, component, or system in your diagram is a node.

Declare a node with a short unique ID, a display label, and optional styling options.

syntax

node(id) "Label" [option: value] [option: value]

Options

OPTION	DESCRIPTION	EXAMPLE VALUE
`icon`	Service icon — prefix:Name format	`aws:S3`
`color`	Accent colour for the node card	`#8C4FFF`
`sub`	Subtitle shown below the label	`Load Balancer`
`num`	Step number (shown with # toggle)	`3`

Icon prefixes

aws:

AWS services

lucide:

General icons

si:

Brand logos

abbr:

Short text label

Icon name examples: aws:S3, aws:EC2, aws:RDS, lucide:Globe, lucide:Server, si:SiGithub, abbr:API

example

node(api) "API Gateway" [icon: aws:ApiGateway] [color: #8C4FFF] [sub: REST]
node(db)  "RDS"         [icon: aws:RDS]        [color: #527FFF] [sub: Aurora]
node(cdn) "CloudFront"  [icon: aws:CloudFront] [color: #8C4FFF] [sub: CDN]

renders as

API Gateway

REST

RDS

Aurora

CloudFront

CDN

Edges

Connect nodes with directed arrows. Spaces around the arrow are optional.

solid arrow

api -> db

api

dashed arrow

api --> cache

api

cache

with label

api -> db "reads data"
cdn --> s3 "static assets"

edges with labels

api

reads data

cdn

static assets

Spaces around → and --> are optional. All three are valid:
api->db · api -> db · api ->db

Groups

Group related nodes inside a labelled, coloured container box.

syntax

group(id) "Label" [color: #hex] [opacity: 0-100] {
  nodeId1
  nodeId2
}

(id) — unique ID for the group container.
opacity — fill opacity, 0 (invisible) to 100 (full colour). Default is 15.

example

node(db)    "RDS"         [icon: aws:RDS]        [color: #527FFF]
node(cache) "ElastiCache" [icon: aws:ElastiCache] [color: #C7131F]

group(data) "Data Layer" [color: #3b82f6] [opacity: 15] {
  db
  cache
}

renders as

RDS

database

ElastiCache

cache

DATA LAYER

Children inside { } can be on separate lines or space-separated on one line. The diagram auto-lays them out — you don't set positions.

Text & Sticky Notes

Add floating labels or sticky notes anywhere on the canvas.

syntax

text(id)   "Plain text label"
sticky(id) "A note with context or explanation"

text node

Plain text label

sticky note

📝 A note with context or explanation

Step Numbers

Number nodes to show sequence — useful for request flows and step-by-step walkthroughs.

example

node(client) "Client"    [icon: lucide:Globe]  [color: #64748b] [num: 1]
node(api)    "API"       [icon: lucide:Zap]    [color: #8b5cf6] [num: 2]
node(db)     "Database"  [icon: aws:RDS]       [color: #527FFF] [num: 3]

client -> api "HTTP request"
api    -> db  "SQL query"

renders as (with Show Numbers toggled on)

Client

HTTP request

API

SQL query

Database

Numbers are hidden by default. Toggle them on with the # button in the bottom toolbar.

Full Example

A complete AWS 3-tier architecture. Copy it into the diagram code panel to see it rendered.

aws-3tier.archdsl

// AWS 3-Tier Web Architecture
// Docs: node · text · sticky · group · edges (-> solid, --> dashed)

node(r53) "Route 53"    [icon: aws:Route53]    [color: #8C4FFF] [sub: DNS]      [num: 1]
node(cf)  "CloudFront"  [icon: aws:CloudFront] [color: #8C4FFF] [sub: CDN]      [num: 2]
node(s3)  "S3"          [icon: aws:S3]         [color: #569A31] [sub: Static]   [num: 3]
node(alb) "ALB"         [icon: aws:ELB]        [color: #8C4FFF] [sub: Load Balancer]
node(ec2) "EC2"         [icon: aws:EC2]        [color: #FF9900] [sub: Web Tier]
node(app) "EC2"         [icon: aws:EC2]        [color: #FF9900] [sub: App Tier]
node(rds) "RDS"         [icon: aws:RDS]        [color: #527FFF] [sub: Aurora]
node(ec)  "ElastiCache" [icon: aws:ElastiCache][color: #C7131F] [sub: Redis]
node(cog) "Cognito"     [icon: aws:Cognito]    [color: #C7131F] [sub: Auth]

group(web)  "Web Tier"  [color: #8C4FFF] [opacity: 10] { ec2 }
group(app)  "App Tier"  [color: #FF9900] [opacity: 10] { app }
group(data) "Data Layer"[color: #527FFF] [opacity: 10] { rds ec }

r53 -> cf
cf  -> alb
cf  -> s3
alb -> ec2
ec2 -> app
app -> rds
app -> ec   "cache"
cog -> alb  "auth"

Use with AI

Give an AI assistant the spec, describe your system, and it generates valid ArchDSL you can paste straight in.

The format is compact enough for any LLM to generate reliably without hallucinating syntax. Copy the system prompt below into your AI chat, then describe the architecture you want.

system prompt — copy this

You are generating ArchDSL code for a visual architecture diagram tool.

ArchDSL format:
  node(id) "Label" [icon: PREFIX:Name] [color: #hex] [sub: subtitle] [num: N]
  text(id) "Label"
  sticky(id) "Note content"
  group(id) "Label" [color: #hex] [opacity: 0-100] {
    nodeId1
    nodeId2
  }
  source -> target          // solid edge
  source --> target         // dashed edge
  source -> target "label"  // with label

Icon prefixes: aws: · lucide: · si: · abbr:
Examples: aws:S3, aws:EC2, aws:RDS, lucide:Globe, lucide:Server, si:SiGithub, abbr:API

Rules:
- IDs must be short, unique, no spaces (e.g. api, db, cache, cdn)
- Colors are hex (e.g. #8C4FFF for purple, #FF9900 for orange, #527FFF for blue)
- Spaces around -> and --> are optional
- Group children are node IDs, one per line or space-separated
- Left-to-right or top-to-bottom flow is preferred

Output only valid ArchDSL, no markdown fences.

Tip: after pasting the prompt, just say something like "generate a microservices architecture with an API gateway, 3 services, a message queue, and a shared database." The output can be pasted directly into the diagram code panel.

Ready to try it?

Open Architecture Diagram