Why Marrow
How Marrow differs from drawing tools, DSL-to-image generators, and hosted diagram SaaS.
Network diagrams tend to rot. The usual reasons: the source of truth is a drawing rather than data, the interactive version is trapped inside a vendor's platform, and updating the picture means an afternoon of dragging boxes.
Marrow attacks all three, and pays a real price for each. This page is about both halves.
The landscape
| How you specify it | What you get | Who owns the result | |
|---|---|---|---|
| draw.io, Lucidchart | Drag boxes by hand | Editable canvas | Their file format |
Graphviz, Mermaid, diagrams | A DSL, positions inferred | A static image | You |
| Hosted network-mapping SaaS | Discovery + their UI | Interactive, behind a login | Them |
| Marrow | Declared structure in YAML | Interactive HTML | You — it's a file |
Two axes matter.
You declare structure, not layout. With drawing tools, position is the
document — move a box and you've edited the source. With DSL tools you write
edges and a generic graph engine guesses the rest. Marrow sits between: you
state what each device is (tier, zone, ha_pair_with), and the engine
picks one of six archetypes and computes a layout that suits it. A core switch
lands above the access layer because you said it is core, not because you
dragged it there.
The output is interactive and yours. Mermaid and Graphviz give you a PNG or an SVG — no inspection, no search, no path tracing. Hosted tools give you all of that but keep it on their domain behind their auth. Marrow gives you an HTML file. Drop it in a wiki, a docs site, an S3 bucket, or an email attachment. It works offline and nobody needs an account to read it.
What it costs you
Being honest about the trade-offs is more useful than a feature table.
You cannot nudge anything. There is no layout: key, no drag handle, and
pin: is a deliberate escape hatch rather than a workflow. If the arrangement
isn't what you pictured, the fix is to declare different structure. Some people
find this liberating; some find it maddening. If you need pixel control over one
bespoke diagram, use a drawing tool — Marrow is for the fifty diagrams you have
to keep current.
It is not a discovery tool. Marrow does not scan your network. It compiles a
description you (or an agent, or a script, or your IaC) provide. marrow import
brings legacy v1 YAML forward, and discovery output can be shaped into the
schema, but the scanning itself is someone else's job.
Vendor icon packs need one fetch. AWS, Azure, GCP, and Cisco artwork is not redistributable, so it isn't in the repo. One command installs it per clone. See ADR-0005.
Very large topologies change shape. Past ~150 devices or 5 zones the build emits a multi-page site rather than one file. That's better for readers and for renderers, but it is a directory, not an attachment. See Output shapes.
When Marrow is the wrong tool
- You want a freeform architecture sketch with arbitrary shapes and annotations → drawing tool.
- You want one diagram, once, never to be updated → drawing tool.
- You want a graph embedded in a Markdown file with no build step → Mermaid.
- You want live, polled device status → Marrow renders a declared
status:, not a feed. A generator that rewrites the YAML from your monitoring system, on a schedule, gets you most of the way.
If you're evaluating: the fastest honest test is to describe your messiest real site and see whether the schema can express it. Start with Authoring topologies.