archgram

Quickstart

Install archgram, write a spec, draw it and put the diagram in your README.

Draw your first diagram by hand. You install archgram, write a short spec, draw it and put it in your README. You need Node 22 or later.

If you would rather have your coding agent write the spec from your code, read Quickstart with your agent instead.

1. Install archgram#

In your project's folder, add archgram as a development dependency.

npm install --save-dev archgram

archgram is one native binary for macOS, Linux and Windows. Your package manager installs the one for your machine, and nothing runs or downloads at install time.

Every command in these docs is shown for npm, pnpm and Yarn; pick yours over any block. In a sentence, a command is written as archgram check, and you run it the same way.

2. Write a spec#

A spec is a small file that says what your system is made of. Save this one as docs/diagrams/linkshort.archgram.yaml.

yaml
archgram: 1
title: linkshort
description: A visit goes through the API to Postgres.
nodes:
  - { id: browser, kind: browser, label: Visitor }
  - { id: api, kind: service, label: API, tech: fastapi }
  - { id: db, kind: database, label: links, tech: postgresql }
edges:
  - { from: browser, to: api }
  - { from: api, to: db }
flows:
  - { name: a visit, steps: [browser, api, db] }

Each part of it says one thing.

KeyWhat it says
archgramThe version of the spec format. It is always 1 for now.
titleThe diagram's name. It becomes the SVG's title.
descriptionThe whole diagram in one or two sentences. Screen readers read it.
nodesThe parts of the system. Each has an id, a kind that picks its icon, and a label. tech adds a logo, such as postgresql.
edgesWhat calls or reads what, from one node to another.
flowsThe path a request takes, step by step. archgram animates it.

3. Draw it#

npm exec -- archgram build docs/diagrams/linkshort.archgram.yaml

archgram writes docs/diagrams/linkshort.svg beside the spec and says the size it drew and the direction it chose. This is the file you get.

A visit goes through the API to Postgres. a visit: Visitor → API → links.A visit goes through the API to Postgres. a visit: Visitor → API → links.

If the spec has a mistake, archgram draws nothing and says where it is, at its line and column. A misspelt id or logo comes with the nearest one that exists.

docs/diagrams/linkshort.archgram.yaml:10:22: no node has the id `dbx`; did you mean `db`?

4. Put it in your README#

The SVG is an ordinary image. Link it like one.

markdown
![A visit goes through the API to Postgres.](docs/diagrams/linkshort.svg)

The flow plays inside the image, on GitHub, on npm and on any docs page, with no script. The file follows the reader's light or dark mode by itself.

GitHub lets each reader choose a theme that can differ from their system's. To follow GitHub's choice instead, draw one file for each theme and let the page pick.

npm exec -- archgram build docs/diagrams/linkshort.archgram.yaml --split-themes

That writes linkshort.light.svg and linkshort.dark.svg. Show them with a <picture>.

html
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/linkshort.dark.svg">
  <img src="docs/diagrams/linkshort.light.svg" alt="A visit goes through the API to Postgres.">
</picture>

5. Check it as the system changes#

Keep the spec in git beside the code. When the system changes, change the spec in the same pull request and draw it again. To check a spec without drawing it, run check.

npm exec -- archgram check docs/diagrams/linkshort.archgram.yaml

It lists every problem at its line and column. When a part names the file behind it, check also tells you when that file or line is gone.

Next#