archgram

Introduction

What archgram draws, what you get, and the two ways to start: with your coding agent or by hand.

archgram draws software architecture diagrams. You describe a system in a small YAML or JSON file, the spec, and archgram turns it into one SVG. The SVG follows light and dark mode and animates the path a request takes through the system.

The API creates short links and redirects. A redirect reads the URL from the Redis cache, falls back to Postgres on a miss, adds the click to a Redis stream and returns. A worker drains the stream in batches and adds the counts to Postgres, where the stats route reads them. a visit: Visitor → API → Click stream → Worker → links.The API creates short links and redirects. A redirect reads the URL from the Redis cache, falls back to Postgres on a miss, adds the click to a Redis stream and returns. A worker drains the stream in batches and adds the counts to Postgres, where the stats route reads them. a visit: Visitor → API → Click stream → Worker → links.

You never drag a box or route a line. archgram places every part, routes the lines around the cards and draws the flows. Your work is to say what the system is, or to let your coding agent say it for you.

Two ways to start#

  1. With your coding agent. Give the archgram skill to Claude Code, Codex, Cursor, Gemini CLI or another agent that reads skills, then ask it to draw your project. It reads the code, writes the spec, draws the diagram and tells you which file backs each part. Start with Quickstart with your agent.
  2. By hand. Install the command, write the spec yourself and draw it. Start with Quickstart.

Either way, your repository ends up with two files side by side. The spec, which you read and review like code, and the SVG drawn from it.

What you get#

  • One SVG file. No script, no server and no web font inside, so it looks the same wherever it is opened.
  • Light and dark in one file. It follows the reader's system. If your page needs a file for each theme, archgram writes both.
  • Flows that move. The animation lives inside the SVG, so it plays wherever an image shows, in a GitHub README, on npm or on any docs page.
  • The same file every time. The same spec gives the same bytes on every machine, so the diagram changes in git only when the system does.
  • A diagram that knows its code. A part can name the file behind it, and archgram check tells you when that file or line is gone.
  • Your colours, if you want them. Bring your design tokens and archgram draws with them, and tells you when two colours are too close to read.

What it is not for#

archgram draws one kind of diagram, the architecture of a system. For a sequence diagram, a chart or UML, Mermaid or PlantUML is the better tool. For a sketch you arrange by hand, use draw.io or Excalidraw.

What you need#

  • Node 22 or later, to install archgram from npm and to run the skill.
  • macOS, Linux or Windows, on x64 or arm64. archgram is one native binary, and npm installs the one for your machine.