Diagram DSL: Draw Architecture from Text

Why text

Dragging boxes is good for exploring, but a text description is faster to write, easy to review in a pull request and trivial to change. The ArchBoard DSL turns a few readable lines into real Excalidraw shapes, with icons, bound arrows and an automatic layout, so you can then tweak the result by hand like any other drawing.

Grammar

One statement per line. A node is kind [tech] ["label"]. Give it an id with kind id "label" to refer to it later; a node without an id is referred to by its label in lower case with dashes. Edges join nodes: a -> b (solid), a --> b (dashed), a <-> b (two-way) and a -[label]-> b (labelled). Chain edges on one line, and write [api x3] to draw three replicas. Directives: direction LR or TB, layout tree, radial or layered, and title "…".

Limits: 150 nodes and 12 replicas per diagram. Errors appear as wavy underlines in the editor (Tools, then Diagram from text) and nothing is inserted until the text is valid.

Node kinds

actor, api, apigateway, app, auth, browser, bucket, bus, cache, cdn, ci, cicd, client, container, container_, cron, database, db, dns, eventbus, ext, external, firewall, flags, fn, function, gateway, idp, job, kafka, lambda, lb, loadbalancer, microservice, microsvc, mobile, monitor, mq, node, nosql, observability, people, pipeline, pod, proxy, pubsub, queue, ratelimiter, redis, reverseproxy, s3, scheduler, search, service, sql, storage, stream, svc, thirdparty, timer, topic, user, vault, waf, warehouse, web, worker.

Examples

service api "Orders API" -> db postgres "Orders DB"

service api "Orders API" -> db postgres "Orders DB"
lb "Edge LB" -> [api x3]
api -> queue kafka "order-events" -> worker "Fulfilment"

title "URL shortener"
client "Browser" -> cdn "CDN" -> lb "LB" -> service app "Shortener"
[app x3]
app -> cache redis "Hot links"
app -> db postgres "Links DB"
app -[async]-> queue kafka "click-events" -> worker "Analytics" -> warehouse snowflake "Clicks"

direction LR
client "Web app" -> gateway "API gateway" -> service checkout "Checkout"
checkout -> topic kafka "orders"
orders -> service payments "Payments"
orders -> service inventory "Inventory"
orders -> function lambda "Send email"
payments -> external stripe "Stripe"

service app "Application"
app -[1. get]-> cache redis "Redis"
app --[2. on miss]--> db postgres "Postgres"

browser "Web" -> gateway "API gateway" -> auth auth0 "Auth0"
gateway -> microservice users "Users"
gateway -> microservice orders "Orders"
gateway -> microservice catalog "Catalog"
users -> db postgres "Users DB"
orders -> db mysql "Orders DB"
catalog -> search elasticsearch "Catalog index"

layout right
client "Client" -> service cmd "Command API" -> db postgres "Write model"
cmd -> topic kafka "events"
events -> worker proj "Projector" -> search elasticsearch "Read model"
client --[query]--> service qry "Query API" -> search elasticsearch "Read model"

service pub "Publisher" -> topic sns "orders.created"
orders-created -> worker billing "Billing"
orders-created -> worker shipping "Shipping"
orders-created -> worker notify "Notifications"

direction LR
db mysql "Orders DB" -> storage s3 "Raw zone" -> worker spark "Transform" -> warehouse snowflake "Warehouse"
external "Partner API" -> raw-zone
cron "Nightly job" -> spark

user "Visitors" -> cdn cloudfront "CDN"
cdn --[miss]--> lb "Origin LB" -> service origin "Origin"
[origin x2]
origin -> storage s3 "Assets"

service a "Service A" -> monitor prometheus "Prometheus" -> monitor grafana "Grafana"
service b "Service B" -> prometheus
service c "Service C" -> prometheus

direction LR
client "Developer" -> ci github "GitHub Actions" -> container docker "Image build" -> storage s3 "Registry" -> pod k8s "Kubernetes"
vault "Secrets" -> github-actions

Try it with a template

• URL Shortener
• Pub/Sub Fan-Out