# terrastruct/d2 architecture

> Architecture diagram of the GitHub repository terrastruct/d2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/terrastruct/d2
- Repository: https://github.com/terrastruct/d2

## Overview

D2 is a diagram scripting language: authors provide text, which the CLI or Go library turns into a graph, lays out, and renders or exports. The README documents multiple layout engines, themes, language tooling, and SVG, PNG, GIF, PDF, and PPTX output. The tree supports these subsystem paths, but most implementation excerpts are absent, so the diagram shows the documented workflow without asserting uncertain internal call details.

Main entry points: [`d2lib/d2.go`](https://github.com/terrastruct/d2/blob/master/d2lib/d2.go) (Go library), [`d2layouts/d2layouts.go`](https://github.com/terrastruct/d2/blob/master/d2layouts/d2layouts.go) (Layout selection), [`d2cli/main.go`](https://github.com/terrastruct/d2/blob/master/d2cli/main.go) (CLI), [`d2parser/parse.go`](https://github.com/terrastruct/d2/blob/master/d2parser/parse.go) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[main.go]"]
  node_library["Go library<br/>[d2.go]"]
end

subgraph group_language["Language processing"]
  node_parser["Parser<br/>[parse.go]"]
  node_ast["AST<br/>[d2ast.go]"]
  node_compiler["Compiler and IR<br/>[compile.go]"]
  node_graph["Diagram graph<br/>[d2graph.go]"]
end

subgraph group_layout["Graph layout"]
  node_layouts["Layout selection<br/>[d2layouts.go]"]
  node_dagre["Dagre engine<br/>[layout.go]"]
  node_elk["ELK engine<br/>[layout.go]"]
  node_tala["TALA engine<br/>[layout.go]"]
  node_sequence["Sequence and grid<br/>[layout.go]"]
end

subgraph group_render["Rendering and export"]
  node_scene["Scene builder<br/>[build.go]"]
  node_svg["SVG renderer<br/>[d2svg.go]"]
  node_export["File exporters<br/>[export.go]"]
end

subgraph group_tools["Language tooling"]
  node_format["Formatter<br/>[format.go]"]
  node_lsp["Language server<br/>[d2lsp.go]"]
end

node_author(("Diagram author"))
node_result["Diagram files"]

node_author -->|"provides source"| node_cli
node_author -->|"provides source"| node_library
node_cli -->|"invokes"| node_library
node_library -->|"parses source"| node_parser
node_parser -->|"produces AST"| node_ast
node_library -->|"compiles diagram"| node_compiler
node_compiler -->|"produces graph"| node_graph
node_library -->|"selects layout"| node_layouts
node_layouts -->|"dispatches"| node_dagre
node_layouts -->|"dispatches"| node_elk
node_layouts -.->|"dispatches"| node_tala
node_layouts -->|"supports specialized layouts"| node_sequence
node_library -->|"builds render scene"| node_scene
node_scene -->|"provides render data"| node_svg
node_library -->|"exports formats"| node_export
node_export -->|"writes SVG PNG GIF PDF PPTX"| node_result
node_author -->|"formats source"| node_format
node_author -->|"uses language tooling"| node_lsp

click node_cli "https://github.com/terrastruct/d2/blob/master/d2cli/main.go"
click node_library "https://github.com/terrastruct/d2/blob/master/d2lib/d2.go"
click node_parser "https://github.com/terrastruct/d2/blob/master/d2parser/parse.go"
click node_ast "https://github.com/terrastruct/d2/blob/master/d2ast/d2ast.go"
click node_compiler "https://github.com/terrastruct/d2/blob/master/d2compiler/compile.go"
click node_graph "https://github.com/terrastruct/d2/blob/master/d2graph/d2graph.go"
click node_layouts "https://github.com/terrastruct/d2/blob/master/d2layouts/d2layouts.go"
click node_dagre "https://github.com/terrastruct/d2/blob/master/d2layouts/d2dagrelayout/layout.go"
click node_elk "https://github.com/terrastruct/d2/blob/master/d2layouts/d2elklayout/layout.go"
click node_tala "https://github.com/terrastruct/d2/blob/master/d2layouts/d2talalayout/layout.go"
click node_sequence "https://github.com/terrastruct/d2/blob/master/d2layouts/d2sequence/layout.go"
click node_scene "https://github.com/terrastruct/d2/blob/master/d2renderers/d2scenebuild/build.go"
click node_svg "https://github.com/terrastruct/d2/blob/master/d2renderers/d2svg/d2svg.go"
click node_export "https://github.com/terrastruct/d2/blob/master/d2exporter/export.go"
click node_format "https://github.com/terrastruct/d2/blob/master/d2format/format.go"
click node_lsp "https://github.com/terrastruct/d2/blob/master/d2lsp/d2lsp.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_library toneBlue
class node_parser,node_ast,node_compiler,node_graph toneAmber
class node_layouts,node_dagre,node_elk,node_tala,node_sequence toneMint
class node_scene,node_svg,node_export toneRose
class node_format,node_lsp,node_author,node_result toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/terrastruct/d2/blob/master/d2cli/main.go): `d2cli/main.go`
- [Go library](https://github.com/terrastruct/d2/blob/master/d2lib/d2.go): `d2lib/d2.go`

### Language processing

- [Parser](https://github.com/terrastruct/d2/blob/master/d2parser/parse.go): `d2parser/parse.go`
- [AST](https://github.com/terrastruct/d2/blob/master/d2ast/d2ast.go): `d2ast/d2ast.go`
- [Compiler and IR](https://github.com/terrastruct/d2/blob/master/d2compiler/compile.go): `d2compiler/compile.go`
- [Diagram graph](https://github.com/terrastruct/d2/blob/master/d2graph/d2graph.go): `d2graph/d2graph.go`

### Graph layout

- [Layout selection](https://github.com/terrastruct/d2/blob/master/d2layouts/d2layouts.go): `d2layouts/d2layouts.go`
- [Dagre engine](https://github.com/terrastruct/d2/blob/master/d2layouts/d2dagrelayout/layout.go): `d2layouts/d2dagrelayout/layout.go`
- [ELK engine](https://github.com/terrastruct/d2/blob/master/d2layouts/d2elklayout/layout.go): `d2layouts/d2elklayout/layout.go`
- [TALA engine](https://github.com/terrastruct/d2/blob/master/d2layouts/d2talalayout/layout.go): `d2layouts/d2talalayout/layout.go`
- [Sequence and grid](https://github.com/terrastruct/d2/blob/master/d2layouts/d2sequence/layout.go): `d2layouts/d2sequence/layout.go`

### Rendering and export

- [Scene builder](https://github.com/terrastruct/d2/blob/master/d2renderers/d2scenebuild/build.go): `d2renderers/d2scenebuild/build.go`
- [SVG renderer](https://github.com/terrastruct/d2/blob/master/d2renderers/d2svg/d2svg.go): `d2renderers/d2svg/d2svg.go`
- [File exporters](https://github.com/terrastruct/d2/blob/master/d2exporter/export.go): `d2exporter/export.go`

### Language tooling

- [Formatter](https://github.com/terrastruct/d2/blob/master/d2format/format.go): `d2format/format.go`
- [Language server](https://github.com/terrastruct/d2/blob/master/d2lsp/d2lsp.go): `d2lsp/d2lsp.go`

### Other components

- **Diagram author**
- **Diagram files**

## Connections

- Diagram author → CLI: provides source
- Diagram author → Go library: provides source
- CLI → Go library: invokes
- Go library → Parser: parses source
- Parser → AST: produces AST
- Go library → Compiler and IR: compiles diagram
- Compiler and IR → Diagram graph: produces graph
- Go library → Layout selection: selects layout
- Layout selection → Dagre engine: dispatches
- Layout selection → ELK engine: dispatches
- Layout selection → TALA engine: dispatches
- Layout selection → Sequence and grid: supports specialized layouts
- Go library → Scene builder: builds render scene
- Scene builder → SVG renderer: provides render data
- Go library → File exporters: exports formats
- File exporters → Diagram files: writes SVG PNG GIF PDF PPTX
- Diagram author → Formatter: formats source
- Diagram author → Language server: uses language tooling