Tools / Diagrams as code

Nagare

A small text language that renders architecture diagrams and charts to SVG. Diagrams live in version control next to the code they describe, and are reviewed like code.

A first diagram

Declare components, give them attributes and connect them:

@layout(w:950,h:400)

browser:Browser(url: "https://shop.example.com", text: "Shop", x:50,y:100,w:200,h:150)
vps:VM(title: "prod@ubuntu", x:300,y:&browser.c,w:600,h:300) {
    nginx:Server(title: "nginx", icon: "nginx", port: 80, x:50,y:&browser.c,w:200,h:50)
    app:Server(title: "App", icon: "golang", port: 8080, x:350,y:&browser.c,w:200,h:50)
}

@browser.request(target: @nginx)
@nginx.request(target: @app)
https://shop.example.comShop prod@ubuntunginxnginx · :80 Appgolang · :8080
The SVG Nagare renders from the text above.

Examples

Each example is the complete source followed by the SVG it produces. Copy one into a .nagare file and render it with the CLI.

A checkout flow, animated

Components nest inside a VM. Each request line draws an arrow, with the sides worked out from the layout. A Database has activity lights, and the last two lines blink them for a write, then a read. The animation is plain SVG, so it plays wherever the image is shown, with no script.

@layout(w:1000,h:450)

shop:Browser(url: "https://shop.example.com", text: "Checkout", x:30,y:120,w:230,h:170)
gw:APIGateway(title: "gateway", method: "POST", route: "/orders", x:310,y:&shop.c,w:180,h:60)
vm:VM(title: "prod@ubuntu", x:540,y:40,w:430,h:200) {
    api:Server(title: "orders-api", icon: "golang", port: 8080, x:30,y:60,w:170,h:50)
    mailer:BackgroundWorker(title: "mailer", job: "send-receipt", x:240,y:60,w:160,h:50)
}
db:Database(title: "orders", engine: "postgres", x:570,y:300,w:120,h:120)
events:MessageQueue(title: "order.created", kind: "nats", x:770,y:325,w:200,h:70)

@shop.request(target: @gw)
@gw.request(target: @api)
@api.request(target: @db)
@api.request(target: @mailer)
@mailer.request(target: @events)

@db.write(begin:"0.5s",dur:"1.5s")
@db.read(begin:"2.5s",dur:"1.5s")
https://shop.example.comCheckout gatewayPOST /orders prod@ubuntuorders-apigolang · :8080 mailersend-receipt · @e… orderspostgres order.creatednats
The red light is a write, the green light a read. This page replays the animation every few seconds.

Primary and replica

Give each action a begin and a dur to tell a story in order: the write lands on the primary, reaches the replica, and the report reads from the replica.

@layout(w:760,h:320)

api:Server(title: "orders-api", icon: "golang", port: 8080, x:40,y:130,w:200,h:56)
primary:Database(title: "primary", engine: "postgres", x:360,y:20,w:120,h:120)
replica:Database(title: "replica", engine: "postgres", x:360,y:180,w:120,h:120)
reports:Server(title: "reports", port: 9000, x:560,y:212,w:170,h:56)

@api.request(target: @primary)
@api.request(target: @replica)
@reports.request(target: @replica)

@primary.write(begin:"0.5s",dur:"1.5s")
@replica.write(begin:"2s",dur:"1s")
@replica.read(begin:"3.5s",dur:"1.5s")
orders-apigolang · :8080 primarypostgres replicapostgres reports:9000
Three actions on a timeline: write, replicate, read.

A publishing pipeline, dark theme

theme: dark in @layout switches the palette. y: &ci.c centres a component on another one, so the row stays aligned when sizes change.

@layout(w:1000,h:240,theme:dark)

ci:Terminal(title: "ci", cwd: "~/site", command: "gengo generate --plain", x:20,y:30,w:280,h:170)
dist:Artifact(title: "dist", filename: "site.tar.gz", size: "1.2 MB", x:350,y:&ci.c,w:170,h:60)
edge:CDN(title: "edge", provider: "pages", region: "global", x:570,y:&ci.c,w:170,h:60)
reader:Browser(url: "https://example.com/blog", text: "Blog", x:790,y:30,w:190,h:170)

@ci.request(target: @dist)
@dist.request(target: @edge)
@reader.request(target: @edge)
ci~/site$ gengo generate --plain distsite.tar.gz · 1.… edgepages · global https://example.com…Blog
Terminal, Artifact, CDN and Browser components on the dark theme.

A chart

Input that starts with chart is drawn as a chart. Series, colours and styles are pipe-separated, one column per series.

chart
title: Requests per second
xaxis: number

series: api | cache hits
color: #c8452c | #2f6f8f
style: line | dashed
data:
  0: 120 | 40
  1: 180 | 90
  2: 260 | 170
  3: 240 | 190
  4: 310 | 260
Requests per second-0.10.71.62.43.34.1-31.043.4117.8192.2266.6341.0apicache hits
Two series, one solid and one dashed.

Install

The install script downloads the latest release for your platform, verifies its checksum and puts nagare in ~/.local/bin.

$ curl -fsSL https://raw.githubusercontent.com/saasuke-labs/nagare/main/install/install.sh | bash

Archives for every platform are on the releases page.

Three ways to use it

Command line

Render a file to SVG:

$ nagare -input diagram.nagare -output diagram.svg

HTTP server

Run nagare with no input file to start a server on port 8080 (change it with -port), then post diagram text to /render:

$ nagare -port 3000
$ curl -X POST http://localhost:3000/render \
    -H "Content-Type: text/plain" \
    --data-binary @diagram.nagare

The server also hosts a playground at its root URL: a live editor with instant preview, examples and diagrams saved in your browser.

Go library

$ go get github.com/saasuke-labs/nagare
import "github.com/saasuke-labs/nagare/pkg/nagare"

svg, err := nagare.RenderToSVG(diagramCode)
if err != nil {
    log.Fatal(err)
}
fmt.Println(svg)

Syntax

Components

A component is id:Type(attributes). The id is optional; without one it is generated.

browser:Browser(url: "https://example.com", text: "Home")
db:Database(title: "orders")
Server(title: "worker")

Available types: Browser, VM, Server, Terminal, Database, MessageQueue, CDN, APIGateway, BackgroundWorker, Package, Artifact, Rectangle, plus the primitives Cylinder and Led.

Position and size

x, y, w and h place a component. A value like y:&browser.c aligns to another component, here the centre of browser.

Nesting

Containers such as VM hold other components in a block. Children are positioned relative to their parent.

vps:VM(title: "ubuntu") {
    nginx:Server(title: "nginx", port: 80)
    app:Server(title: "App", port: 8080)
}

Connections

A request action draws a solid arrow from one component to another, and a response action a dashed one. Nagare picks the sides to join from where the two components sit.

@browser.request(target: @nginx)
@nginx.response(target: @browser)

Add dir to choose the direction yourself: lr, rl, tb or bt (left to right, right to left, top to bottom, bottom to top).

@api.request(target: @db, dir: tb)

For full control, join two anchors directly. Anchors are compass points: n, ne, e, se, s, sw, w, nw.

browser.e --> nginx.w

Canvas

A @layout line sets the canvas size, useful when a diagram has to fit a fixed space.

@layout(w: 800, h: 600)

Themes and colours

Every component is drawn from one visual system: the same card shape, stroke, corner radius and type scale, with an icon and accent colour per type. The canvas is transparent, so a diagram sits on whatever background the page has.

Pick the theme in the layout line. light is the default.

@layout(w: 800, h: 600, theme: dark)

Colour attributes override the theme on a single component:

AttributeApplies to
bgCard, window chrome or cylinder fill.
fgText colour.
accentIcon and highlight colour, where the component has one.
contentBgContent area of Browser and VM.

If an fg override would be unreadable on its background, Nagare uses a contrasting text colour instead.

Charts

The same engine draws charts. A chart can mix series styles and axes in one definition:

series: jog | walk | total distance | jog blocks
style: bar | bar | line | marker
stack: session | session | none | none
yaxis: time | time | distance | blocks
type: duration | duration | number | number
  • line, dashed and dotted draw lines.
  • bar draws columns. Bar series that share a stack group are stacked.
  • marker draws a point with its value above it.

Dates work on the x axis and durations on the y axis. Bar widths adapt to how dense the data is.

Inside a Gengo site

Gengo renders any nagare code block in your Markdown to an inline SVG at build time, with no exported image to keep in sync.

Licence

Nagare is open source under the MIT licence.

Using Nagare at work?

Saasuke Labs is independent and maintained in the open. Sponsorship pays for maintenance, documentation and releases.