Diagram Architect Helper

Your agent for creating technical diagrams in multiple formats — ASCII art, Mermaid, PlantUML, and Draw.io — to visualize code architecture, data flows, state machines, and system designs.

When to Use This Agent

Choose Diagram Architect Helper when:

• Creating architecture diagrams (system design, component interactions, deployment layouts)
• Generating sequence diagrams for API flows and service interactions
• Building data flow diagrams, ERD schemas, or state machine visualizations
• Converting whiteboard sketches or verbal descriptions into formal diagrams
• Producing diagrams that can live alongside code (Mermaid in Markdown, ASCII in comments)

Consider alternatives when:

• You need actual infrastructure provisioning — use a cloud or Terraform agent
• You need code architecture refactoring — use a refactoring agent
• You need polished presentation graphics — use a dedicated design tool

Quick Start

Copy
# .claude/agents/diagram-architect.yml
name: Diagram Architect Helper
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Technical diagram agent supporting ASCII, Mermaid, PlantUML, and Draw.io formats

Example invocation:

claude "Create a Mermaid sequence diagram showing the OAuth 2.0 authorization code flow between the browser, our app server, and the identity provider"

Core Concepts

Diagram Format Comparison

Format	Best For	Where It Renders
Mermaid	Sequence, flowcharts, ER diagrams	GitHub, GitLab, Notion, docs sites
PlantUML	Class diagrams, complex sequences	IntelliJ, VS Code, CI pipelines
ASCII	Inline docs, code comments, terminals	Everywhere (plain text)
Draw.io	Complex architecture, presentations	Draw.io app, Confluence, VS Code

Mermaid Example

Copy
sequenceDiagram
    participant B as Browser
    participant S as App Server
    participant IDP as Identity Provider

    B->>S: GET /login
    S->>B: Redirect to IDP /authorize
    B->>IDP: Authorization request
    IDP->>B: Authorization code
    B->>S: Callback with code
    S->>IDP: Exchange code for tokens
    IDP->>S: Access + refresh tokens
    S->>B: Set session cookie

Configuration

Parameter	Description	Default
output_format	Diagram format (mermaid, plantuml, ascii, drawio)	mermaid
diagram_type	Type (sequence, flowchart, class, er, state, gantt)	auto-detect
theme	Visual theme (default, dark, forest, neutral)	default
direction	Flow direction (TB, BT, LR, RL)	TB
detail_level	Detail granularity (high-level, detailed, exhaustive)	detailed

Best Practices

1. Choose the format based on where the diagram will live. Mermaid for GitHub READMEs and docs sites, PlantUML for IDE-integrated documentation, ASCII for code comments and terminal output, Draw.io for presentations and Confluence. The best diagram is the one people actually see.

2. Keep diagrams focused on one concept. A single diagram showing everything becomes unreadable. Create separate diagrams for system overview, data flow, sequence interactions, and deployment topology. Link them together in documentation.

3. Use consistent naming across diagrams. If "UserService" appears in your architecture diagram, use "UserService" (not "User Module" or "Users") in sequence diagrams too. Consistent naming helps readers connect concepts across different views.

4. Version diagrams alongside code. Store diagram source files (Mermaid markdown, PlantUML text) in the repository near the code they describe. This makes diagrams discoverable, reviewable in PRs, and updatable when code changes.

5. Start with the happy path, then add error flows. Draw the main success scenario first to establish the overall structure. Add error handling, retries, and edge cases as separate diagrams or clearly labeled branches to avoid cluttering the primary flow.

Common Issues

Mermaid diagrams break with special characters in labels. Characters like parentheses, brackets, and quotes in node labels cause parse errors. Wrap labels in quotes (["My Label (v2)"]) and escape special characters. Test diagrams in the Mermaid live editor before committing.

Complex diagrams become unreadable spaghetti. When a diagram has more than 15-20 nodes or 30+ connections, it's too complex for a single view. Break it into subgraphs, use hierarchical layouts, or split into multiple diagrams at different abstraction levels.

Diagram source and actual architecture drift apart. Without a process to update diagrams, they become misleading within weeks. Add diagram review to your PR checklist for architecture changes, or generate diagrams from code using tools like Structurizr or ts-morph that extract architecture from source.