Technology

Architecture Diagrams as Code: Mermaid vs. Architecture as Code

Creating architecture diagrams using code has become increasingly popular among developers and architects. This approach enhances consistency, reproducibility, and version control, aligning well with Infrastructure as Code (IaC) principles. Two prominent tools in this space are Mermaid and Architecture as Code (powered by Graphviz). Let’s compare these tools and understand their strengths and limitations.

What is Mermaid?

Mermaid is an open-source JavaScript-based diagramming tool that allows users to create diagrams using a simple, Markdown-like syntax. It supports various types of diagrams, including:

  • Flowcharts
  • Sequence diagrams
  • Class diagrams
  • State diagrams
  • Entity-relationship diagrams (ERD)
  • Gantt charts

Mermaid integrates well with documentation tools like Markdown and can be embedded directly in platforms such as GitHub, GitLab, and Notion. The simplicity of its syntax makes it easy to learn and use for rapid diagram creation.
he

Example of a Flowchart in Mermaid

1
2
3
4
flowchart TD;
  A[Start] --> B{Decision};
  B -->|Yes| C[Proceed];
  B -->|No| D[Exit];

What is Architecture as Code?

Architecture as Code is another approach that leverages Graphviz for generating architecture diagrams. Graphviz is a powerful open-source graph visualization tool that renders structural information into network graphs.

The key benefits of using Architecture as Code with Graphviz include:

  • More precise control over diagram rendering
  • Better layout optimization for complex diagrams
  • Native support for directed graphs

Example of a Graphviz DOT File

1
2
3
4
digraph G {
  A -> B [label="Yes"];
  A -> C [label="No"];
}

Key Differences Between Mermaid and Architecture as Code

Feature Mermaid Architecture as Code (Graphviz)
Syntax Simplicity Easy-to-learn Markdown-like syntax Requires DOT language (more structured)
Diagram Types Supports multiple types like flowcharts, sequence diagrams, ERD, etc. Focuses on graph-based diagrams
Rendering Engine Uses JavaScript-based rendering Uses Graphviz for visualization
Integration Works well with GitHub, GitLab, and Notion Commonly used in software engineering and network diagrams
Customization Limited customization High level of customization with precise layout control

Which One Should You Choose?

  • If you need quick and simple diagrams that integrate well with Markdown and documentation tools, Mermaid is a great choice.
  • If you require highly detailed and customizable architecture diagrams with precise layout control, Architecture as Code (Graphviz) is the better option.

Both tools embrace the diagrams as code approach, allowing teams to store, version, and automate diagram generation within their workflows.