Published on 2026-02-22

D2 Architecture Diagrams Guide

A modern, highly productive declarative language for generating beautiful architecture diagrams directly from text.

D2 (Declarative Diagramming) is a relatively new language built specifically for modern software architecture. Unlike Mermaid, which has separate syntax for flowcharts, sequence diagrams, and class diagrams, D2 utilizes a unified, object-oriented syntax.

To use D2, wrap your code in a d2 fenced code block.

The D2 Philosophy

D2 is designed to be highly readable. You declare objects and the relationships between them. The layout engine (which incorporates elements of the ELK layout) automatically places them intelligently.

Basic Syntax

syntax

backend: {
  api_server
  database
}

frontend

frontend -> backend.api_server: Request
backend.api_server -> backend.database: Query

Shapes and Styling

Unlike older text-to-diagram tools, D2 treats styling and shapes as properties of the objects, not separate commands.

syntax

# Declare a node named "Cache" and give it properties
Cache: {
  shape: cylinder
  style: {
    fill: "#BF0603"
    stroke: white
    shadow: true
    border-radius: 5
  }
}

# The default shape is a rectangle
# You can also change the shape inline
API Server: { shape: hexagon }

API Server <-> Cache: Read / Write

Classes and Reusability

D2 supports the concept of “classes” to apply consistent styling across many nodes without repeating yourself.

syntax

classes: {
    service: {
        shape: oval
        style.fill: lightblue
    }
    db: {
        shape: cylinder
        style.fill: lightgreen
    }
}

User Service: { class: service }
Order Service: { class: service }

User Database: { class: db }
Order Database: { class: db }

User Service -> User Database
Order Service -> Order Database

Advanced Features: Icons and Markdown

D2 supports rendering simple Markdown inside nodes, and it has built-in support for fetching popular icons.

syntax

AWS Lambda: {
  icon: aws-lambda
  # You can embed markdown within the label
  label: |md
    # Serverless Function
    This executes our *business logic*.
  |
}

DynamoDB: { icon: aws-dynamodb }

AWS Lambda -> DynamoDB

Why D2?

If you are designing high-level cloud architectures or microservices topologies, D2 is vastly superior in its ease-of-use and aesthetic output compared to older tools. Its clean syntax and powerful auto-layout make it ideal for modern documentation.