FAQ
Where the drawing plays, dark mode, and how archgram compares with Mermaid, draw.io, D2 and Structurizr.
The questions people ask about archgram, the same as on the home page. Something missing? Ask on GitHub.
What is archgram?#
archgram is an open-source CLI tool for software architecture diagrams. Write a YAML or JSON spec, or let Claude Code, Codex, Cursor or Gemini CLI draw one from your code. It writes one self-contained SVG that follows light and dark mode and animates the path a request takes. The file drops into a GitHub README or any docs page, and the animation plays wherever an image shows.
Does the animation play in a README or a docs page?#
Yes. The flows are animated with SMIL inside the SVG, which needs no script, so the drawing moves in an <img>: in a GitHub README, on npm and in any docs page.
Does it follow dark mode?#
One SVG carries both themes and follows the reader's system setting. To follow GitHub's own theme instead, draw with --split-themes and put the two files in a <picture> with prefers-color-scheme.
Does it need a server, a browser or the network?#
No. archgram is one native binary, and the SVG is self-contained: no script, no external file, no web font, so it shows the same wherever it is opened.
How is it different from Mermaid?#
Mermaid draws many kinds of diagram from text and is rendered by the page that shows it; GitHub renders it in Markdown. archgram draws one kind, the architecture of a system, into an SVG file ahead of time: it routes the lines around the cards, animates the flows and embeds its font, so the file looks the same everywhere. For a sequence diagram or a chart, Mermaid is the better tool.
How is it different from draw.io or Excalidraw?#
draw.io and Excalidraw are canvases you arrange by hand, which suits a sketch. archgram places everything from the spec, so the diagram lives in git beside the code and changes in a diff when the system does.
How is it different from D2 or PlantUML?#
D2 is a language for many kinds of diagram, and PlantUML draws UML from text, such as sequence, class and deployment diagrams. archgram draws one kind, the architecture of a system, from a spec in plain YAML or JSON that an agent can write from the code; it routes the lines, animates the flows inside the SVG and gives the same file on every machine. For UML, PlantUML is the better tool; for a diagram in many shapes, D2 is.
How is it different from Structurizr and the C4 model?#
Structurizr models a system once in its DSL and draws several C4 views from that model; it is the C4 model's reference implementation. archgram draws one diagram per spec, the parts and the path a request takes, as an animated SVG for a README or a docs page. To keep several C4 views in step, Structurizr is the better tool.
Can a coding agent draw my architecture from the code?#
Yes, with the archgram skill: it reads the code, draws a part only where a file backs it and an edge only where a line of code makes it, and lists both.
How do I keep architecture diagrams in sync with the code?#
Keep the spec in git beside the code. archgram redraws the diagram from it, and its agent skill can write the spec again from the code, so the diagram changes in the same pull request as the system.
Can it use my design system's colours?#
Yes: --theme-file maps archgram's colour roles to your design tokens (W3C Design Tokens), and refuses colours that fall short of contrast.
Will the same spec give the same file tomorrow?#
Yes, byte for byte, on every machine, so a diagram changes in git only when the system does.