Mermaid is great for infrastructure diagrams because the diagram can live as text.
The hard part is deciding the right level of detail.
If every subnet, security group, load balancer, service, and database is on the same level, the diagram becomes hard to read.

An infrastructure diagram builder can help you create a first draft before polishing the Mermaid syntax.

Start with the audience

Before drawing, decide who the diagram is for.
For a review, prioritize connections and data flow.
For handover documentation, prioritize the components people will operate.

flowchart LR
  User[User]
  ALB[ALB]
  App[ECS Service]
  DB[(RDS)]

  User --> ALB
  ALB --> App
  App --> DB

This rough version is often enough to start a conversation.
Details such as subnets and security groups can be added later or split into another diagram.

Common problems

  • Node names are too long
  • Arrow directions do not match the actual request flow
  • Cloud service names and internal team names are mixed
  • Network, application, and data layers are packed into one diagram
  • Mermaid syntax errors break the preview

The first diagram should explain the shape of the system.
If it tries to explain every detail, it usually becomes harder to maintain.

Keep it easy to update

Infrastructure diagrams age quickly.
Short node names, consistent grouping, and preview-friendly syntax make updates less painful.

The goal is not to create a perfect diagram once.
The goal is to create a diagram that teammates are willing to update.