Keep a diagram true

A diagram drawn by hand falls behind the code without anyone noticing. archgram can tell you when that happens. Each part and each line names the code behind it, and archgram checks that the code is still there.

Name the code behind each part#

Give a part, a node, the file that backs it. Give a line, an edge, the file with a few words copied from the line of code that makes it, after a #. Here, docs/diagrams/architecture.archgram.yaml:

archgram: 1
title: orders
description: A worker writes orders to Postgres.
nodes:
  - { id: worker, kind: service, label: Worker, source: ../../src/worker.ts }
  - { id: db, kind: database, label: Postgres, tech: postgresql }
edges:
  - { from: worker, to: db, source: "../../src/worker.ts#db.insert(order)" }

• A path from the spec's folder. From docs/diagrams/, paths start with ../../. Write / on every system, and each name with the capitals it has on disk.
• A list for a part that stands for several, such as source: [../../src/charge.ts, ../../src/refund.ts].
• A few words from one line, at least 3 characters, copied exactly. archgram looks for them anywhere in the file, so the source holds while the file changes around them. A comment counts too, so pick words from the code itself.
• Quote a source that holds a # in YAML. Unquoted, a space before # starts a comment and drops the words.
• No source for what lives outside the code, such as a browser or a person.

Sources are never drawn. A spec gives the same SVG with or without them. The archgram skill writes them for you when it draws from your code.

Check it#

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

pnpm exec archgram check docs/diagrams/architecture.archgram.yaml

yarn archgram check docs/diagrams/architecture.archgram.yaml

While everything is there, check says how many sources it found.

docs/diagrams/architecture.archgram.yaml: valid (2 nodes, 1 edges, 2 sources found)

When db.insert(order) is no longer in src/worker.ts, it says which line lost its code, at the spec's line and column, and fails.

docs/diagrams/architecture.archgram.yaml:8:37: edge worker → db: `../../src/worker.ts` does not hold `db.insert(order)`
1 problem in docs/diagrams/architecture.archgram.yaml

archgram build warns of the same and still draws, so a lost source never stops a drawing. Only check fails on it.

Fix what it found#

Find where the code went. If it moved, point the source at its new place. If the part or the call is gone, remove it from the spec. Then check again.

With the skill, ask your agent.

Update the architecture diagram.

It starts from what check says has lost its code, changes only that and what is new in the code, and keeps the diagram's direction.

Check it in CI#

check exits with an error when a source is gone, so a CI step fails on the pull request that broke the diagram. In GitHub Actions, for a project that lists archgram in its package.json:

name: Diagrams
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm ci
      - run: npx archgram check docs/diagrams/architecture.archgram.yaml

What it cannot see#

• What the code gained. check finds a part or a call that is gone, not a new one that was never drawn. Ask the agent to update the diagram, or read the change yourself.
• A change that keeps the words. If the line still holds the same words but now does something else, the source still holds.
• Words found elsewhere. Words the file holds in more than one place are found as long as one of them is there.

What archgram reads#

Sources are looked up only under your project's folder, the nearest folder above the spec that holds .git. A path that leads outside it is refused. archgram never follows a symbolic link, never names .git or a file that commonly holds secrets, such as .env or a private key, and reads a file only to look for the words, printing and keeping nothing of it. A spec without sources looks nothing up.