Architecture Diagram Update Guide

Overview

This guide explains how to create and update architecture diagrams using D2.

D2 Basics

D2 is a declarative diagramming language. Diagrams are defined in .d2 files or inline in markdown.

Basic Syntax

File Locations

Type	Location
Architecture diagrams	docs/diagrams/architecture.d2
Sequence diagrams	docs/diagrams/sequence-*.d2
ERD diagrams	docs/diagrams/erd-*.d2
State machines	docs/diagrams/state-*.d2

Creating a New Diagram

1. Create a .d2 file in docs/diagrams/
2. Use TALA layout for complex diagrams
3. Test locally with d2 --layout=tala file.d2 output.svg
4. Reference in markdown via inline D2 block or include

Style Guide

Colors

• API/Services: #6366f1 (indigo)
• Databases: #3b82f6 (blue)
• Cache: #ef4444 (red)
• Success states: #10b981 (green)

Shapes

• Services: rectangle
• Databases: cylinder
• Users: person
• Decisions: diamond

CI/CD Rendering

Diagrams are rendered in GitLab CI using the D2 Docker image:

build-docs:
  image: ghcr.io/terrastruct/d2:latest
  script:
    - mkdocs build