Diagrams as code

TL;DR

1. Name the sources

Each entry of sources is one diagram. Paths start at the folder that holds the settings file.

1{2  "$schema": "https://docs.plotwork.dev/schemas/plotwork.config.json",3  "sources": [4    {5      "name": "infra",6      "from": "infra/**/*.tf",7      "format": "terraform",8      "out": "docs/infra.diagram"9    },10    {11      "name": "api",12      "from": "openapi.yaml",13      "format": "openapi",14      "view": "map",15      "out": "docs/api.md#endpoints"16    },17    {18      "name": "services",19      "from": [20        "compose.yaml",21        "compose.override.yaml"22      ],23      "format": "compose",24      "out": "docs/architecture.md#services"25    },26    {27      "name": "schema",28      "from": "prisma/schema.prisma",29      "format": "prisma",30      "out": "docs/schema.diagram",31      "options": {32        "tables": [33          "User",34          "Org*"35        ]36      }37    }38  ]39}

Two sources that write one file, or a view the format does not draw, are S101 on their line of the settings file. A from that matches no file is S103.

A Markdown out needs a fence that says where the diagram goes. It may be empty; the first run fills it and writes the picture block under it, as sync does:

1## Services2
3```diagram id=services4```

One picture for both themes

A light SVG opened on GitHub, or put in a page with a plain ![](infra.svg), shows its white cards in dark mode too. GitHub picks a dark file only from a <picture> element with a prefers-color-scheme: dark source. With schemes set to auto, each diagram gets one SVG that holds both schemes and switches inside the file with the same media query, so the file itself, a link to it, and a plain <img> all show the scheme the reader uses. The two schemes are painted from one layout, so the picture is the same as the two files, and the one file is smaller than the two together.

1{2  "defaults": {3    "schemes": "auto"4  },5  "sources": [6    {7      "name": "infra",8      "from": "infra/**/*.tf",9      "format": "terraform",10      "out": "docs/infra.diagram"11    }12  ]13}

Use auto for any diagram people see on GitHub. A Markdown fence's picture block is then one <img> instead of a <picture>. Switching a repository to auto removes each .dark.svg that Plotwork drew there, so no file is left behind; a check before that run reports the removal as drift. A file under that name that Plotwork did not draw is never touched. sync reads the same default for the fences it draws.

A git-log source reads a file. Write it in an earlier step, such as git log --oneline --graph -n 40 > docs/history.txt, or the check fails on every new commit.

2. Generate

npx @buun_group/plotwork generate

A drifted diagram prints its changes by meaning, from the same comparison as compare_diagrams: reordered or reformatted lines are no change, and a renamed id is a rename.

drift: docs/infra.diagram (infra, terraform from infra/**/*.tf)  Added 1 node (logs). Removed 1 edge (web -> db).  + node logs  - edge web -> dbfailed: 4 diagram(s) checked, 1 drifted, 0 error(s)

The output is the same for the same files on every machine. A generated file starts with a comment that names its source and its overrides file:

# Generated by plotwork generate from the source infra (terraform: infra/**/*.tf).# The next run writes over this file. Put changes in docs/infra.overrides.json, or run plotwork generate --capture# after an edit to keep it there, then run plotwork generate.

3. Overrides

An overrides file is JSON beside the diagram. It is applied after every import, so a change to the Terraform and a change to a label never fight.

1{2  "$schema": "https://docs.plotwork.dev/schemas/plotwork.overrides.json",3  "header": {4    "options": {5      "direction": "right",6      "legend": "off"7    }8  },9  "items": {10    "aws_s3_bucket.assets": {11      "label": "Assets bucket",12      "tone": "orange"13    },14    "aws_instance.web": {15      "group": "compute",16      "type": "function"17    },18    "aws_internet_gateway.gw": {19      "hide": true20    }21  },22  "groups": {23    "compute": {24      "label": "Compute",25      "type": "app-tier",26      "parent": "aws_vpc.main"27    }28  },29  "edges": [30    {31      "from": "aws_instance.web",32      "to": "aws_lb.web",33      "label": "health",34      "arrow": "-->"35    },36    {37      "from": "aws_db_instance.orders",38      "to": "aws_db_subnet_group.orders",39      "hide": true40    }41  ],42  "lines": [43    {44      "statement": "node runbook step \"Runbook\" sub=\"Rotated nightly\"",45      "into": "compute"46    }47  ]48}

How a thing is named

An entry names a thing by the name the file gives it, which does not change when the file grows. The id in the diagram can: two resources named web become web and web_2 in the order they are read.

The id in the diagram works for every format too, when it is stable enough for you.

When the importer changes

A new version of the importer can draw the same files differently: a Terraform stack whose local modules are now framed, or whose for_each copies are now drawn one by one. A stack the new rules have nothing to say about (no module, no for_each or count) is drawn exactly as before, byte for byte. When an upgrade does redraw a diagram, generate --check reports it as drift; run plotwork generate once, review the change, and commit it.

When the file changes

An entry whose thing is gone is a warning, S201, on its line of the overrides file: Stale override for aws_s3_bucket.logs: the import no longer draws it. An entry the diagram cannot take, such as an added group whose id is taken, is S202. Neither fails a run; remove or rename the entry. A change that leaves the diagram with an error, such as an unknown node type, is that error, on its line of the generated file.

Keep a hand edit

npx @buun_group/plotwork generate --capture --source infra

--capture compares the file you edited with what the import and the current overrides make, writes each difference into the overrides file (labels, options, types, moves, hidden and added boxes, groups, edges, and lines), and then makes the diagram again, so it comes back the same with its comment on top. A source split into several diagrams is captured part by part, each against its own file, into its one overrides file.

4. Fail a pull request on drift

1name: diagrams2
3on:4  pull_request:5
6permissions:7  contents: read8
9jobs:10  drift:11    runs-on: ubuntu-latest12    steps:13      - uses: actions/checkout@v714        with:15          persist-credentials: false16      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1417        with:18          command: generate

The samples pin the latest release of the Action by its commit. @v1 becomes available at the first stable release.

Each drifted diagram is an error annotation on its file, and the job summary has a table of every diagram: where it comes from, the nodes and edges added and removed, its status, a link to its file, and the engine's table of what changed. A job summary cannot show a picture from the runner, so the changes are written out; the pull request from write mode, and a published diagram, show the pictures.

5. Write the diagrams back

Open a pull request

On a push to the default branch, or on a schedule, write mode makes the diagrams again and pushes them to one branch with one pull request. Each run replaces that branch with one commit on the latest base and edits the open pull request rather than opening another. Once nothing drifts, the next run closes that pull request with a comment and deletes its branch, when the branch's last commit is the action's own.

1name: diagrams-regenerate2
3on:4  push:5    branches: [main]6  schedule:7    - cron: '0 4 * * *'8
9permissions:10  contents: read11
12jobs:13  regenerate:14    runs-on: ubuntu-latest15    permissions:16      contents: write17      pull-requests: write18    steps:19      - uses: actions/checkout@v720      - id: plotwork21        uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1422        with:23          command: generate24          mode: write25          pr-branch: plotwork/diagrams26          pr-title: 'docs: regenerate diagrams from their sources'

on-drift: pr refuses a pull_request run: such a run is on a merge commit, not on a branch.

Commit to the branch

1on:2  pull_request:3
4permissions:5  contents: read6
7jobs:8  regenerate:9    runs-on: ubuntu-latest10    permissions:11      contents: write12    steps:13      - uses: actions/checkout@v714        with:15          ref: ${{ github.head_ref }}16      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1417        with:18          command: generate19          mode: write20          on-drift: commit21          commit-message: 'docs: regenerate diagrams'

The commit carries the trailer Plotwork-Generated: true. A run started by that commit does nothing, so a token that does start workflows never loops. A pull request from a fork cannot be pushed to with the workflow's token. on-drift: fail writes the diagrams in the workspace and fails, for a later step of your own.

6. Publish

With publish: true and a key in PLOTWORK_API_KEY, write mode publishes each source that has a publish section.

1{2  "name": "infra",3  "from": "infra/**/*.tf",4  "format": "terraform",5  "out": "docs/infra.diagram",6  "publish": {7    "organization": "acme",8    "folder": "Platform/Infra"9  }10}

1name: diagrams-publish2
3on:4  push:5    branches: [main]6
7permissions:8  contents: read9
10jobs:11  publish:12    runs-on: ubuntu-latest13    permissions:14      contents: write15      pull-requests: write16    steps:17      - uses: actions/checkout@v718      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1419        with:20          command: generate21          mode: write22          publish: true23        env:24          PLOTWORK_API_KEY: ${{ secrets.PLOTWORK_API_KEY }}

The key is masked in the log and never printed. The repository's defaults and brand.organization go with the source, so the hosted picture takes the organisation's brand and icon packs when its plan includes them. The links are in the job summary, with the pictures, and in the published output.

7. Inputs and outputs

8. Limits

See also