Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Getting diagrams in and out

Take a diagram out as an image on any plan; on Pro and Premium, import from Mermaid or a file, or export as Mermaid or JSON.

  • On every plan: images. Copy the diagram to your clipboard, or download a PNG or an SVG (watermarked on Free).
  • On Pro and Premium: the SVG without the watermark, Print/PDF, Mermaid and RodGrid JSON export, and every import: a Mermaid flowchart, Mermaid-C4 (C4Context, C4Container…), RodGrid JSON, Excalidraw, draw.io and Structurizr.

The plan that decides which of these you can use is your own, not the Grid owner's, so a Free guest on a Premium owner's Grid gets the first list. All of this lives in the editor's top bar.

Which way out

  • To be read: an image, from the Export menu. It carries the picture, not the Grid, so it cannot be imported back. The PNG comes as Entire diagram or Current view, which crops to exactly what you can see, so a subsystem off screen is silently gone from the file. Ctrl/⌘+Shift+C copies the image.
  • To be edited as text next to a document: Export Mermaid, in the same menu. The .mmd file has the labels and connections, not which component each node was or where it sat, so importing it back matches the labels against the catalog and lays out the nodes again.
  • To be kept or moved: Export JSON, a button of its own. The file carries nodes, edges, groups, custom components, walkthroughs, comments and activity, but not scenarios. It is a copy outside the product, so whoever receives it can read those comments too.

To give someone an address to open rather than a file, see Publishing a Grid: public pages and embeds.

Two ways in

Import Mermaid opens a box for pasting a Mermaid flowchart or C4 diagram, the kind ChatGPT or Claude produces. Ask for a flowchart by name: the box understands only flowcharts and C4, and a sequence diagram pasted there does not arrive as one.

Import diagram opens a file picker for RodGrid JSON, Excalidraw, draw.io and Structurizr files up to 2 MB. A compressed draw.io file is refused with instructions for exporting uncompressed XML. To start from something already built rather than from a file, see Starting from a template.

Watch outAn import replaces everything on the Grid, including comments and walkthroughs, and it needs edit access. If the Grid has content you are asked first (Replace this Grid's contents?), and undo can bring the old content back until you reload the page or open another Grid. Unless replacing is the point, import into a new Grid.

What happens to each label

An importer does not copy shapes; it resolves them. Labels are matched to real catalog components wherever one fits, among those available on that Grid. A box labelled "Redis" arrives as the Redis component, with its icon, category and semantic role, so the Grid can be simulated and evaluated afterwards. Your exact label is kept as the node's title.

This flowchart, pasted, lands without a review step: flowchart LR, then A[Load Balancer] -->|routes| B[App Service], then B -->|reads| C[Session Cache].

What a pasted three-line flowchart becomes

Labels the resolver cannot settle are not guessed. Review imported components opens before anything lands, and you choose for each one. "Shorten API" gets Several matches are plausible and a list of suggestions, which are approximate. "Click Counter" gets No reliable catalog match, which leaves Custom Component. Anything unrecognised therefore arrives as a custom component, never a bare rectangle: it keeps its label and connections, and uses a generic simulation and cost profile that may change the estimates.

A RodGrid JSON file skips this, because it already names its components. It is refused whole if it uses components the Grid's plan lacks, or carries comments, walkthroughs or governance details into a Grid without collaboration.

What does not make the trip

Outside RodGrid JSON, colours and hand-drawn flourishes stay behind in every format, while dashed or heavy edges and arrowheads survive where the source has them. If the visual detail was the point, keep the original file. Containers flatten: Mermaid subgraphs, C4 boundaries, Structurizr nesting, and draw.io groups and swimlanes lose the box and keep the contents. Mermaid, C4 and Structurizr get a generated layout; Excalidraw and draw.io keep theirs, spread out as needed, and Working faster: shortcuts, search and tidy covers Tidy for what lands badly. From Excalidraw, only rectangles, ellipses, diamonds and loose text become nodes, so freehand strokes, images and frames are skipped, along with any arrow not attached to a shape at both ends.

Correct a URL shortener someone else drew

A resolved node can still be wrong for your design, and the fix is not a rename: renaming changes the title, and the component underneath stays. Place the right component, drag the edge ends onto it (Connecting & styling edges shows how), and delete the wrong node.

On Pro or Premium, open a new Grid, ask an LLM for a Mermaid flowchart of a URL shortener, and paste it in. Settle the review, delete what does not belong, replace what resolved wrongly, and rename what is left by what it does. Then build the same design by hand in the URL Shortener Challenge, which has no import.

Practice this