Diagram Pattern Comparison
SVG, Mermaid, draw.io, D2, Excalidraw — Which approach to choose
There are broadly 3 approaches to drawing architecture diagrams. Code-based (Mermaid, D2) enables Git diff and CI/CD automation, GUI-based (draw.io, Excalidraw) is accessible to non-developers, and direct rendering (SVG/HTML+CSS) offers full control at higher authoring cost.
Architecture Diagram
| Tool | Method | Git Diff | Layout Control | Non-dev | CI/CD Automation |
|---|---|---|---|---|---|
| Mermaid.js | Text | ✓ | Weak | Medium | ✓ |
| D2 | Text | ✓ | Strong | Medium | ✓ |
| PlantUML | Text | ✓ | Medium | Hard | ✓ |
| draw.io | GUI (XML) | XML | Full | ✓ | Limited |
| Excalidraw | GUI (JSON) | JSON | Full | ✓ | ✗ |
| SVG Direct | Code | ✓ | Full | N/A | Manual |
| HTML+CSS | Code | ✓ | Full | N/A | Manual |
graph LR
A[Client] -->|HTTP| B[Load Balancer]
B --> C[App Server 1]
B --> D[App Server 2]
C --> E[(Database)]
D --> Eclient: Client {shape: rectangle}
lb: Load Balancer {shape: hexagon}
app1: App Server 1
app2: App Server 2
db: Database {shape: cylinder}
client -> lb: HTTP
lb -> app1
lb -> app2
app1 -> db
app2 -> dbHow It Works
Direct SVG: Code shapes, lines, and text with <svg> tags. Full pixel control, but highest authoring cost
HTML+CSS (app56 approach): Compose diagrams with Tailwind boxes + flexbox/grid. Responsive, same stack as code
Mermaid.js: Declare as text in markdown code blocks → auto-rendered. Displays directly in GitHub/GitLab READMEs
D2: Declarative diagram language. Superior layout control over Mermaid with powerful theming/styling
draw.io (diagrams.net): GUI editor with drag & drop. Saved as XML for Git management. VS Code extension available
Excalidraw: Hand-drawn style whiteboard. Great for brainstorming and initial design. JSON storage for Git management
Pros
- ✓ Code-based: Git diff enabled, changes visible in PR reviews
- ✓ Code-based: Auto-rendering in CI/CD (mermaid-cli, d2)
- ✓ GUI-based: Editable by non-developers
- ✓ draw.io: XML storage enables Git management + VS Code extension
- ✓ Excalidraw: Hand-drawn style feels "unfinished" — ideal for early discussions
- ✓ AI era: ChatGPT/Claude can generate Mermaid/D2 code on the fly
Cons
- ✗ Code-based: Hard to control complex layouts (relies on auto-layout)
- ✗ Mermaid: Readability drops in large diagrams
- ✗ GUI-based: Binary files cannot be Git diffed (Lucidchart, Figma, etc.)
- ✗ Direct SVG: High authoring cost and hard to maintain
- ✗ draw.io XML: Fragile when manually edited
- ✗ Excalidraw: Too casual for official documentation