C4-Builder
Developer or AI agent [Person]

Writes markdown and PlantUML, D2 or BPMN diagrams and keeps them in git next to the code.

Edits the model and checks every edit[c4builder check]
C4-Builder [CLI, maintained fork]

Architecture as code that an agent writes, checks and reads

Builds a folder of markdown and diagrams into a documentation site. Rendering is local and deterministic, checking a diagram takes seconds, and plugins publish OpenSpec specs and OpenAPI contracts next to the C4 model.

npm i -g @alfacapital-tech/c4builder
Builds[c4builder --site -w]
Documentation [docsify site]

This site is built by c4builder from the repository's docs/ folder.

 Design log [openspec plugin]

The project's specs and changes: why c4builder works the way it does. In Russian.

The agent checks its own work

  1. Edit. The agent changes a .puml or .md in src/: adds a container, a relationship, a page.
  2. Check. c4builder check renders the diagram with the same engine as the build and returns an exit code and the line of the error. No network, no human.
  3. Build. c4builder --site -w rebuilds the site on every save, and the human sees the result in the browser.
$ c4builder check src/context.puml
✗ src/context.puml: строка 12: Fatal parsing error
$ c4builder check src/context.puml
✓ src/context.puml
$ c4builder
built in 1.9 seconds

More on the Agents page. CLI messages are partly in Russian for now: строка means "line".

For agents

Skills

The project layout, the edit → check → build loop, C4-PlantUML conventions, installation and diagnostics — in two skills for Claude Code, Codex, Cursor and other agents. A new project greets the agent with AGENTS.md.

npx skills add AlfaCapital-Tech/C4-Builder/skills

llms.txt

The site serves an index for agents and the full text in one file, with diagrams inserted as PlantUML source: the model is read directly, no pictures.

More on the Agents page.

Getting started

npm

npm i -g @alfacapital-tech/c4builder
c4builder --new --name demo -y
cd demo
c4builder --site -w

Node.js 22.17+. Java 17+ is optional: without it, c4builder downloads a JRE itself. No Graphviz needed.

Docker

docker run --rm -v "$PWD:/pwd" \
  ghcr.io/alfacapital-tech/c4builder:latest \
  c4builder

The image has Node, a JRE, PlantUML, fonts and D2. It also works as a CI job image.

How this fork differs from upstream

The original C4-Builder has not been developed since 2024. At Alfa-Capital it builds an architecture repository of more than a hundred diagrams, so we continue the project and adapt it to working with agents.

Offline and deterministic
The PlantUML jar, the font and the engines ship with the package; layout is computed by Smetana. Identical SVG on a laptop, in CI and in Docker; the build needs no network.
Checking individual diagrams
c4builder check with an exit code and a line number — for agents, pre-commit hooks and CI.
Plugins
openspec publishes specs and changes on the site, openapi — offline swagger-ui pages for service contracts.
D2 and PNG
A second diagram engine and rasterization via resvg with the same font.
BPMN processes
BPMN 2.0 XML without coordinates: the build validates the model, lays out pools and lanes and draws the process in the standard bpmn.io notation.
Maintenance
TypeScript, golden rendering tests, CI on every pull request, releases to npm and GHCR.

Documentation