Context-Heavy Diagrams

Diagrams that carry their own context, and live in git

Architecture diagrams get unreadable once they hold enough detail to be useful. Context-Heavy Diagrams (CHD) keeps the canvas clean and puts the detail in the file: notes, tags, images, and links to deeper diagrams on each element. It is free, open source, and runs offline on your own machine.

Star it on GitHub (opens in new tab) Read the README (opens in new tab)
Context-Heavy Diagrams showing a large railway service landscape: dozens of services grouped by business domain and connected by data flows, with the notes for the selected Customer Profile Service open on the right.
A realistic service landscape, with the notes for the selected service open beside it.

What sets it apart

Context on the element

Notes, tags, and links to deeper diagrams belong to the box they describe, so one diagram can serve both the overview and the detail.

Version controllable

Diagrams as plain, human-readable files in your repo, whose changes can be tracked and visually compared. Avoid depending on a separate wiki that drifts out of date.

AI you can review

Assistants can read and edit diagrams through integrations built for it, and every change can be inspected afterwards.

Local and private

No account, no server, and no network access. Your diagrams stay on your machine.

See it in action

The Highlights panel colours every service by its data sensitivity, from no personal data to sensitive personal data, while the notes for the selected Customer Profile Service describe its data and legal position.
Highlights recolour the whole diagram by any tag, so one diagram can answer any compliance question.
The AI menu of the application, open above a payment service diagram. An orange warning says that what an AI assistant reads is sent to its provider. Below it are three options: enable AI assistance in a folder, install the Claude Desktop extension, and copy AI instructions.
Built for AI, with CLI, MCP servers, skills and prepared prompts.
The change review window after an AI assistant edited the diagram files. Added elements are outlined in green and changed ones in orange, and a list of changes on the right lets each one be reviewed or reverted.
After you or a collaborator, human or AI, makes changes, a review screen shows exactly what was added and changed, with a revert for each change.
The change review window for a payment service diagram. A new Idempotency Store component, outlined in green and connected below the Retry and Reconciliation Engine, is the only change listed, with a button to remove it.
An example of a more ordinary minor evolution of a diagram: one added entity and its connecting edge.
A plain git diff of the diagram file in a terminal, showing two additions in green: a new Idempotency Store node and a new connection labelled checks charge keys in. Nothing else in the file changed.
The same minor diff: one added entity and one added edge.

Is it for you?

It is built for architects and developers, from strategic overviews down to technical detail, and it works as a general diagramming tool too. It fits best when the context and the relationships between views are the point, and when you want diagrams you can review like code.

It is not the right tool for everything. If you need real-time collaboration, standard notations with large shape libraries, or an enterprise architecture platform, use a tool built for that. CHD works well alongside such tools, but is not a replacement for them. The comparison page goes through other tools and use cases in detail.

Compare with other tools (opens in new tab) Getting started (opens in new tab)

Status

An early release, developed in the open. The README has the current state, what is supported, and how to get it.