Diagrist

Diagrams as code, checked like code.

Get started Open the editor Gallery GitHub

Diagrist turns small text files (.dgr) into diagrams. The language is strict on purpose: every statement, argument and attribute is listed in a table, a check names what it found and what is allowed, and the same file always gives the same SVG, byte for byte. So a diagram can be reviewed, diffed and fixed like code, by people who keep diagrams next to their code in git and by coding agents.

Picture
Source

# A user signs in: the app asks the auth service, which answers with a token or an error.
diagram sequence "Sign in" subtitle="Valid or invalid credentials"
actor user "User"
participant app ":App"
participant auth ":AuthService"
msg user -> app "open()"
msg app -> auth "login(name, password)"
alt "valid"
  msg auth --> app "token"
  else "invalid"
    msg auth --> app "error"
msg app --> user "page"

Open in the editor ↗

Strict on purpose

A mistake is reported with its position, a stable code and what would be correct. Rules check the meaning too, such as a call that never gets a reply.

Same file, same picture

The output is deterministic down to the byte, so a picture only changes in a pull request when its source does.

Made for agents

The grammar of every kind and every finding come as JSON, and an agent skill tells an agent how to look things up, write, check and fix.

Stays on your machine

The command line runs locally. The live editor compiles in your browser and keeps the source in the address, so no diagram reaches a server.

UML, C4 and code

The UML kinds are laid out by Diagrist itself. C4 diagrams place their elements in a named grid that the file declares, so the author decides what stands next to what; a flow numbers the steps of a path, and an adr explains a mark in a bar below the picture.

Picture
Source

# Bike rental, C4 level 1: the system as a black box with the people who use it and the systems around it.
diagram context "Bike rental" subtitle="System context, draft for discussion"
grid cols people,core,partners
grid rows top,main,bottom

person rider    "Rider"            tech="rents by app, pays per minute"  at people/main
person service  "Service crew"     tech="moves and repairs bikes"        at people/bottom
system rental   "Bike rental"      tech="app, rides, billing"            at core/main emph mark=E1
system stations "Stations"         tech="locks and chargers"             at partners/top
system payments "Payment provider" tech="card and direct debit"          at partners/main
system maps     "Map service"      tech="locations and routes"           at partners/bottom

flow ride accent
  rider  -> rental   "unlocks a bike" via=App
  rental -> stations "opens the lock" via=MQTT
  rental -> payments "charges the ride" via=HTTPS

flow upkeep primary
  stations ~> rental  "reports battery levels" via=MQTT
  rental   -> service "plans jobs" via=App

edge rental -> maps "shows free bikes" via=HTTPS

adr E1 "Who controls the locks?" = "The rental itself" => "Lock logic and firmware stay in one hand."

Open in the editor ↗

A mistake looks like this:

order.dgr:4:29  L105  error: `participant` has no attribute `stereotyp`. Allowed: `stereotype=`, `tone=`.
  participant pay ":Payments" stereotyp="external"
                              ^^^^^^^^^^^^^^^^^^^^

GalleryEvery example of the repository, ready to change in the live editor.

Getting startedBuild Diagrist, write a first file, check and build it.

The languageHow a file is written, every kind, every diagnostic code.

Live editor and embeddingWrite in the browser, embed a diagram in Confluence.

For agentsGrammar and findings as JSON, the agent skill, llms.txt.

Live editorlive.diagrist.com: write and share a diagram in the browser.