Are You Maintaining Your Infrastructure Diagrams?

“Where is the latest version of the architecture diagram?”

Create Infrastructure Diagrams in Your Browser: Auto-Generate Diagrams from Code

When a new member joins your team and asks that question, how many development sites can confidently present a file? In many projects, draw.io or PowerPoint diagrams created during the initial design phase are left abandoned and outdated.

The reason is simple: “It’s a hassle to fix.”
Manually reconnecting lines, adjusting layouts, and exporting as an image in a browser—the cost is simply too high in modern development where infrastructure changes frequently.

Creating Diagrams “Like Writing Code”

If we can manage diagrams as text-based assets, just like we manage code with Git, the freshness of our documentation will improve dramatically. That’s why we should look to Mermaid.js.

You simply define the connections in text, and the browser automatically renders the diagram with an optimal layout. There’s no reason not to use this “magical” system.

graph TD
    Internet["Internet"] --> LB["Load Balancer"]
    LB --> WebServer["Web Server"]
    WebServer --> DB[("Database")]

A “Visual Editor” to Avoid Struggling with Tools

That said, memorizing and hand-writing all of Mermaid’s syntax is also quite a task. You want to focus on “thinking about the infrastructure configuration,” not getting stuck on “Mermaid syntax errors.”

DevToolKits’ Infrastructure Diagram Builder was designed to give you the best of both worlds.

Build Intuitively, Export Smartly

  1. Place Nodes: Add components like servers or databases from the UI.
  2. Connect Lines: Simply choose which node communicates with which.
  3. Copy Mermaid: The finished diagram can be copied directly as code.

Paste the output Mermaid code into a GitHub README or Notion, and it becomes your “always up-to-date diagram.” When a fix is needed, just change a line of code. This agility is how true “documentation” should be.

Tips for readable architecture diagrams

The more nodes and lines you add, the more complex a diagram gets. Keeping these points in mind makes a diagram that is easy to understand when you come back to it later.

  • Group by layer: use Mermaid’s subgraph to group by “network layer”, “application layer” and “data layer”, or by VPC and availability zone, so the boundaries of responsibility are easy to see.
  • Keep the direction of traffic consistent: flowing from top to bottom (or left to right), as in external → load balancer → app → DB, makes the flow of data intuitive to follow.
  • Add labels in place of a legend: putting specific names such as WebServer["Web Server (ECS)"] lets the diagram alone convey the architecture.
graph TD
    subgraph Public
        Internet["Internet"] --> LB["Load Balancer"]
    end
    subgraph Private
        LB --> App["App Server"]
        App --> DB[("RDS")]
    end

Rather than aiming for a perfect diagram from the start, drawing only the main traffic paths first and updating the code with each change keeps your diagram “always current” in the end.

Grouping and color coding for readability

In the Infrastructure Diagram Builder, each node has a type and a group.

  • Group: nodes given the same name are gathered into a Mermaid subgraph and drawn inside a frame (for example Private subnet or VPC). Nodes with no group come first, and the groups follow in the order you entered them. Connections are written outside the groups, so lines that cross groups work as they are.
  • Type: choose from user, gateway, server, database, storage, network and cloud.
  • Color by type: tick it and only the types in use get a color (default stays uncolored). For example server is blue, database green, user yellow and gateway purple. The diagram area keeps a light background even in dark mode, so the colors are a pale fill with dark text.
subgraph grp_1["Private subnet"]
    n3["App Server 1"]
    n5[("Database")]
end
classDef infra_server fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
class n3 infra_server

Conclusion

Infrastructure diagrams are not “Art” that you finish once. They are “Living things” that continue to change shape as your system grows.

Graduate from “point-and-click work” and move more lightly and accurately.
Visualize your designs with the power of text and keep your team’s common understanding updated constantly.

💡 A Handy Use Case: When submitting a Pull Request on GitHub, try updating the Mermaid code along with your infrastructure changes. This way, the configuration changes can be reviewed right along with the code, preventing documentation from becoming obsolete.

The rich SVG view: arrange it by hand, and pick up where you left off

Besides Mermaid code, you can view the diagram as a custom “rich SVG” (the default view; the Mermaid view and copying the code are still available).

  • Look: cards with a shadow and the node type as a small caption; groups are drawn as colored frames with a tab-style name. Solid, dotted, thick and arrow-less lines are drawn differently, and lines can carry labels
  • Interaction: hover over a node (or focus it with the keyboard) to keep only its connected lines, and click it to see what it connects to and from. Drag nodes (or focus one and use the arrow keys) to rearrange them, and use “Reset layout” to return to the automatic layout
  • Saving: the diagram can be fitted to the width, zoomed, and saved as SVG or PNG, with the layout you set
  • Export: besides Mermaid you can export Graphviz DOT, PlantUML, D2 and Mermaid architecture-beta

Your diagram and the positions of the nodes you moved are saved automatically in this browser, so you can pick up where you left off. You can also delete the saved data, or export and import it as JSON. Nothing is sent to a server.

Frequently Asked Questions

Where can I use the Mermaid diagrams?

Many services that support Mermaid—GitHub READMEs and issues/PRs, GitLab, Notion, and more—render it as a diagram when you paste it as a code block. Unlike images, it’s text you can manage in Git, so it lives in your diffs and keeps a change history.

What’s the advantage over draw.io or PowerPoint?

GUI tools let you fine-tune the look, but editing and re-exporting is a chore, so diagrams tend to go stale. Mermaid updates the diagram by changing a single line of text and can be version-controlled in Git, making it easy to keep in sync with configuration changes and “always current.”

Is the configuration I enter sent anywhere?

The Infrastructure Diagram Builder processes everything in your browser and never sends your configuration or Mermaid code to a server, so you can safely diagram sensitive details like internal system architecture.

How can I make a large, complex diagram easier to read?

Group by network, application and data layers or by VPC and zone with Mermaid’s subgraph, and keep the direction of traffic consistent from top to bottom (or left to right), so the boundaries of responsibility and the flow of data are easy to follow. Drawing only the main paths first and updating with each change keeps the diagram fresher than trying to draw everything at once.