Документация на русском · English documentation · Site

C4-Builder

Architecture as code that an agent writes, checks and reads.

C4-Builder is a CLI that builds a folder of markdown files and PlantUML, D2, BPMN, Mermaid or Wireflow diagrams into documentation: a docsify site, a markdown file per folder, or a single file. Folders follow the C4 model (system → container → component), and git keeps the history of architecture decisions next to the code.

Why this fork

The original C4-Builder by Adrian Victor Lupu has not been developed since March 2024. At Alfa-Capital it builds an architecture repository of more than a hundred diagrams, so we continue it as a maintained fork, adapted to working with AI agents:

• Deterministic offline rendering. The PlantUML jar, the diagram font and the engines ship with the package; layout is computed by PlantUML's built-in Smetana engine, no Graphviz. The same sources produce the same SVG on a laptop, in CI and in Docker, with no network access.
• c4builder check validates individual .puml/.iuml/.d2/.bpmn/.mmd/.wireflow.json files with the build's own engine and returns an exit code and the error line — fast feedback for agents, pre-commit hooks and CI.
• Plugins. openspec publishes an OpenSpec store (specs and changes) as a site section; openapi renders service contracts as offline swagger-ui pages.
• D2 as a second diagram engine, deterministic PNG via resvg, and optional Java: without a system Java, c4builder downloads a private JRE.
• BPMN processes written as BPMN 2.0 XML without coordinates: the build validates the model and lays it out with horizontal pools and lanes.
• Mermaid .mmd files and ```mermaid blocks are rendered at build time by real mermaid, without a browser: images in every output instead of client-side rendering.
• Wireflow user flows: a .wireflow.json export of the editor becomes an image with screen cards, notes and transitions, without a browser or network.
• Review from the page. In c4builder --site -w a selection becomes a question in the source .md or feedback for the agent; c4builder feedback --wait --as <name> hands the batch to the agent, and the page reloads with its edits.
• Maintained. TypeScript, golden rendering snapshots, CI on every pull request, releases to npm and GHCR. The PDF output of the original was removed.

Quick start

Requires Node.js ≥ 22.17. Java 17+ is optional.

npm i -g @alfacapital-tech/c4builder

c4builder --new --name demo -y   # project from the template, full config, no prompts
cd demo
c4builder                        # build into docs/
c4builder --site -w              # live preview at http://localhost:3000

Since 0.5.0, c4builder new and c4builder config work too (0.4.0 has only the flags). Without -y, c4builder asks for the project name and the first build runs the setup wizard.

The agent loop — edit a diagram, check it, look at the result:

c4builder check src/context.puml   # exit code 0 or 1, "✗ file: line N: message" on error
c4builder --site -w                # rebuilds and reloads the browser on every save

For agents: c4builder skills installs the agent skills of the installed version into the project (c4builder --new does it for a new one), and "generateLLMS": true adds llms.txt / llms-full.txt (diagram sources included) to the site.

Or with Docker (Node, JRE, PlantUML, fonts and D2 included):

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

Release candidates are published under the rc tag: npm i -g @alfacapital-tech/c4builder@rc.

Documentation

The full reference lives on the documentation site, in Russian (primary) and English:

What changed in each version: CHANGELOG.md. Why things are the way they are: the design log (OpenSpec store) on the site.

Contributing

npm ci && npm run build
npm test            # all tests, golden rendering snapshots included
npm run check       # biome lint and format

Behaviour changes are described in OpenSpec (openspec/changes/) first, add a line to ## Unreleased in CHANGELOG.md and update the documentation pages in both languages (docs/ru/src, docs/en/src). Details are on the Development page.

Credits and license

C4-Builder was created by Adrian Victor Lupu; this fork is maintained by Alfa Capital Technologies. Upstream changes and their contributors are listed in the changelog. MIT license, see license.