Infrastructure Diagram Code Syntax Guide for Architecture Tools

If you've ever struggled to keep your cloud infrastructure documentation up to date, you already know why infrastructure diagram code matters. Instead of dragging boxes around in a drawing tool, you define your servers, networks, databases, and connections using text-based code. When your environment changes, you update a few lines, regenerate the diagram, and you're done. No more outdated Visio files buried in someone's shared drive. This approach treats your infrastructure visuals the same way you treat application code version-controlled, reviewable, and reproducible.

What is infrastructure diagram code syntax?

Infrastructure diagram code syntax is a structured text format used to describe cloud or on-premises architecture components and their relationships. Tools like Mermaid, PlantUML, D2, and Diagrams (Python) each have their own syntax rules. You write declarations for resources such as EC2 instances, load balancers, or VPCs and then define how they connect. The tool parses the code and renders a visual diagram automatically.

This approach is sometimes called "diagrams as code" or "diagram-as-code." It falls under the broader Infrastructure as Code (IaC) philosophy where you prefer text files over manual configuration.

Why would someone use code instead of a drag-and-drop tool?

Drag-and-drop diagramming tools work fine for one-off presentations. But if you manage a complex environment with multiple teams, code-based diagrams offer clear advantages:

Version control. You can commit diagram files to Git, track changes over time, and review pull requests that modify architecture visuals.
Consistency. Syntax enforces structure. Two engineers writing about the same system will produce identical diagrams if they follow the same conventions.
Automation. CI/CD pipelines can regenerate diagrams whenever infrastructure code changes, keeping documentation in sync without manual effort.
Collaboration. Text files are easy to diff, merge, and comment on unlike binary image files or proprietary diagram formats.

For enterprise teams managing cloud environments, these benefits add up quickly. If you're evaluating tools for this, our guide on cloud architecture diagramming software for enterprise teams covers options designed for larger organizations.

How does the basic syntax work across common tools?

Each diagram-as-code tool has its own language, but the core concepts are similar: define nodes, define edges (connections), and optionally group components. Here's a quick comparison of how three popular tools handle the same simple architecture a web server connected to a database:

Mermaid syntax example

Mermaid uses a simple flowchart-style syntax. Nodes are declared with IDs and labels, and arrows show connections:

graph TD
  WebServer["Web Server (Nginx)"] --> Database[("PostgreSQL DB")]
  WebServer --> Cache["Redis Cache"]
  Cache --> Database

You write this inside a Markdown file or HTML page, and Mermaid's JavaScript library renders it in the browser. No image export step needed.

D2 syntax example

D2 takes a declarative approach with indentation-based nesting:

web-server: "Nginx" {
shape: rectangle
}
database: "PostgreSQL" {
shape: cylinder
}
web-server -> database: "queries"

D2 is newer but gaining traction because its syntax is readable and it produces clean output with minimal configuration.

Python Diagrams library example

The Diagrams Python library lets you write infrastructure diagrams using actual Python code. It maps to real cloud provider icons:

with Diagram("Web Architecture", show=False):
  web = EC2("Web Server")
  db = RDS("PostgreSQL")
  web >> db

This tool is especially useful if your team already writes Python and wants diagrams generated as part of a script. For more on how code-to-diagram generation works, see our guide on generating architecture diagrams from code.

What are the key syntax elements you need to know?

Regardless of which tool you pick, you'll work with these core building blocks:

Nodes (components). These represent resources servers, databases, queues, CDNs, users, or any infrastructure element. Each node has an ID and a display label.
Edges (connections). Lines or arrows between nodes that show data flow, network connections, or dependencies. You can usually add labels to edges to describe the relationship.
Groups (clusters/subgraphs). Logical containers that bundle related components. Think of a VPC containing multiple subnets, or a Kubernetes cluster containing pods.
Direction/layout hints. Most tools let you control whether the diagram flows top-to-bottom, left-to-right, or in some other arrangement.
Styling. Shape types, colors, and icons. Some tools like PlantUML and the Python Diagrams library include cloud-provider-specific icon sets out of the box.

What common mistakes do people make with diagram code syntax?

After working with diagram-as-code tools across multiple projects, these errors come up repeatedly:

Using inconsistent naming conventions. If your node IDs are webServer in one place and web_server in another, your diagrams become hard to maintain. Pick a convention and stick with it.
Overloading a single diagram. Trying to show your entire production environment in one diagram creates visual noise. Break systems into logical diagrams one per service, environment, or user flow.
Skipping edge labels. Unlabeled arrows leave readers guessing. Does that line mean "makes API calls to," "reads from," or "deploys to"? A short label removes the ambiguity.
Not versioning diagram files with infrastructure code. If your Terraform files live in one repo and your diagrams in another (or not in any repo), they'll drift apart fast.
Ignoring layout direction. Letting the tool auto-arrange nodes often produces messy results, especially with more than ten components. Set explicit directions for predictable output.
Choosing the wrong tool for the job. Mermaid works great for simple flowcharts embedded in docs. For detailed cloud architecture with provider-specific icons, the Python Diagrams library or dedicated diagram-as-code tools for microservices architecture may serve you better.

How do you pick the right syntax and tool?

Your choice depends on context. Consider these factors:

Audience. If non-technical stakeholders need to read or edit diagrams, Mermaid inside a Markdown doc is approachable. If only engineers interact with the files, Python Diagrams or D2 offer more power.
Integration needs. Mermaid renders natively in GitHub, GitLab, Notion, and many docs platforms. If your docs live in those tools, Mermaid avoids extra build steps.
Icon and styling requirements. Need AWS, Azure, or GCP icons in your output? The Python Diagrams library includes hundreds of provider-native shapes. Mermaid and D2 use generic shapes by default.
Team skills. A team comfortable with Python will onboard to the Diagrams library faster. A team that writes Markdown daily will prefer Mermaid or D2.

What does a practical workflow look like?

Here's a real-world workflow for keeping infrastructure diagrams current using code:

Store diagram source files (e.g., .mmd, .d2, .py) alongside your infrastructure-as-code repository.
Use a CI pipeline step to render diagrams on every merge to main. Tools like Diagrams and D2 both support CLI rendering.
Export rendered diagrams as SVG or PNG and push them to your documentation platform or static site.
Review diagram changes in pull requests the same way you review Terraform or CloudFormation changes.
Schedule periodic audits at least quarterly to confirm diagrams match what's actually deployed.

This workflow eliminates the "diagram is three months out of date" problem that plagues manually maintained documentation.

Quick syntax reference and tips

Keep these practical tips in mind as you write infrastructure diagram code:

Start with the highest-level view. Map your main services and their connections before adding details like individual database tables or specific ports.
Use meaningful node IDs. auth-service is better than box1 or component_a. Good IDs make your code self-documenting.
Comment complex sections. Most tools support comments. Use them to explain why a connection exists, not just that it exists.
Test rendering frequently. Don't write 200 lines of diagram code and render once at the end. Small, frequent renders catch syntax errors early.
Use subgraphs to manage complexity. Group your networking layer, application layer, and data layer into separate clusters. This keeps diagrams readable at any scale.
Pick SVG output when possible. SVG files scale cleanly and have smaller file sizes than high-resolution PNGs for most architecture diagrams.

What should you do next?

If you're ready to start writing infrastructure diagrams as code, here's a practical checklist to get moving:

Pick one tool based on your team's skills and your documentation platform. Start with Mermaid if you want the lowest barrier to entry.
Diagram one existing system. Choose a service you know well and describe it in your chosen syntax. Don't try to diagram everything at once.
Commit the source file to your repo. Put it next to the infrastructure code it describes.
Set up basic rendering. Even a local script that generates SVG on save is enough to start.
Share with your team and gather feedback. Ask if the diagram is clear, accurate, and useful. Iterate on conventions together before scaling the practice across projects.

Code-based infrastructure diagramming won't replace every whiteboard session or architecture review meeting. But it solves the documentation maintenance problem in a way that manual tools never could. Start small, build the habit, and let the syntax do the tedious work for you.