Generate comprehensive infrastructure and architecture diagrams using D2
Generates comprehensive infrastructure and architecture diagrams with D2 from codebase analysis
/plugin marketplace add heathdutton/claude-d2-diagrams/plugin install heathdutton-d2@heathdutton/claude-d2-diagrams[--incremental] [--infrastructure-only] [--architecture-only] [--scope=<path>] [--force]Generate comprehensive infrastructure and architecture diagrams using D2 (terrastruct/d2).
| Argument | Description |
|---|---|
--incremental | Only regenerate changed components |
--infrastructure-only | Generate only infrastructure diagram |
--architecture-only | Generate only architecture diagram |
--scope=<path> | Limit analysis to specific directory |
--force | Regenerate all, ignore cache |
This command orchestrates multiple specialized agents to analyze a codebase and produce visual diagrams:
Agents Used:
Output:
./diagrams/infrastructure.md - Detailed infrastructure documentation./diagrams/infrastructure-simplified.md - High-level infrastructure overview./diagrams/architecture.md - Detailed architecture documentation./diagrams/architecture-simplified.md - High-level architecture overview./diagrams/*.d2 - D2 source files (4 types)./diagrams/*-light.svg + *-dark.svg - Themed SVG diagrams (8 total)./diagrams/README.md - All diagrams (simple + detailed)The command uses two directories:
./diagrams/ - Committed output and configuration:
./diagrams/
├── README.md # Landing page with all diagrams
├── rules.md # Project-specific customization (optional)
├── infrastructure.md # Detailed infrastructure
├── infrastructure.d2
├── infrastructure-*.svg
├── infrastructure-simplified.md # High-level infrastructure
├── infrastructure-simplified.d2
├── infrastructure-simplified-*.svg
├── architecture.md # Detailed architecture
├── architecture.d2
├── architecture-*.svg
├── architecture-simplified.md # High-level architecture
├── architecture-simplified.d2
└── architecture-simplified-*.svg
.diagram/ - Ephemeral runtime state (gitignored):
.diagram/
├── state.json # Progress checkpoints for resume
└── cache/ # Incremental mode cache
├── iac-hash.txt
└── scan-results.json
Note: The .diagram/ folder is automatically added to .gitignore if one exists. This folder can be safely deleted at any time - it only enables resume and incremental features.
{
"phase": "documenter",
"completed": ["scanner"],
"total": 6,
"timestamp": "ISO8601",
"args": {
"incremental": false,
"scope": null
},
"checkpoints": {
"scanner": {"timestamp": "...", "result": "success"},
"documenter": null
}
}
IMPORTANT: Before any work, initialize state tracking and ensure proper gitignore setup.
STEP 1 - Create directories FIRST (use Bash tool, not Write):
mkdir -p ./diagrams .diagram/cache
STEP 2 - Add to .gitignore (use Bash tool):
if [ -f ".gitignore" ] && ! grep -q "^\.diagram" .gitignore 2>/dev/null; then
echo -e "\n# Diagram plugin ephemeral state\n.diagram/" >> .gitignore
fi
STEP 3 - Note on icons:
Icons are added directly to nodes using the icon: property. No need to copy icons.d2 to the project.
The class: property provides styling (stroke color, shape) while icon: provides the visual.
Example:
database: MySQL Config {
class: mysql
icon: https://icons.terrastruct.com/dev%2Fmysql.svg
}
See the Technology → Icon URL mapping in Phase 7 for all available icons.
STEP 4 - Initialize state file (use Bash tool, NOT Write tool):
echo '{"phase":"initialization","completed":[],"total":11}' > .diagram/state.json
WHY BASH: The Write tool will fail if the directory doesn't exist. Always use mkdir -p via Bash first, then write files.
Check for project rules (OPTIONAL - only if file exists):
# rules.md is OPTIONAL - do NOT error if missing
if [ -f "./diagrams/rules.md" ]; then
echo "Project rules found - will apply customizations"
# Read and incorporate rules into subsequent phases
else
echo "No custom rules (./diagrams/rules.md not found - this is normal)"
fi
IMPORTANT: The rules.md file is user-created and optional. Do NOT attempt to read it unless you first confirm it exists with Glob or the bash check above.
Model hint: Use haiku for fast parallel discovery.
Delegate to Scanner agent with prompt:
TASK: Rapid codebase scan for infrastructure and architecture artifacts.
NOTE: Existing documentation (docs/, diagrams/, *.md) are collected for REFERENCE ONLY.
They may be outdated. The code (IaC, source files) is the source of truth.
EXECUTE IN PARALLEL (spawn multiple Glob/Grep calls simultaneously):
Batch 1 - Infrastructure-as-Code:
- Glob: **/*.tf, **/*.tfvars
- Glob: **/Pulumi.yaml, **/Pulumi.yml
- Glob: **/*.template.yaml, **/*.template.json, **/cdk.json
- Glob: **/serverless.yml, **/serverless.yaml
Batch 2 - Container/Orchestration:
- Glob: **/Dockerfile*, **/docker-compose*.yml
- Glob: **/*.yaml then Grep for "apiVersion:" (Kubernetes)
- Glob: **/helmfile.yaml, **/Chart.yaml
Batch 3 - Documentation:
- Glob: **/README.md, **/ARCHITECTURE.md, **/INFRASTRUCTURE.md
- Glob: **/docs/**/*.md, **/diagrams/**/*
Batch 4 - Application Structure:
- Glob: **/package.json, **/go.mod, **/Cargo.toml, **/requirements.txt
- Glob: **/main.*, **/index.*, **/app.*
CONSTRAINTS:
- READ-ONLY: Do NOT modify any files
- SPEED: Prioritize breadth over depth
- DEDUP: Report each file only once
OUTPUT FORMAT (JSON):
{
"iac": {"terraform": [], "kubernetes": [], "docker": [], "other": []},
"docs": {"readme": [], "architecture": [], "other": []},
"app": {"entrypoints": [], "configs": [], "dependencies": []},
"stats": {"total_files": N, "scan_duration_ms": N}
}
Update state after completion:
{
"phase": "gate-check",
"completed": ["scanner"],
"checkpoints": {
"scanner": {"timestamp": "...", "result": "success", "iac_count": N}
}
}
Verify prerequisites before proceeding:
D2 Installation
which d2 && d2 --version
If missing, attempt installation:
# macOS
brew install d2
# Linux
curl -fsSL https://d2lang.com/install.sh | sh -s --
# Go
go install oss.terrastruct.com/d2@latest
CRITICAL: If D2 cannot be installed, ABORT with clear instructions.
Discovery Results
Incremental Check (if --incremental)
# Compare current IaC hash with cached
find . -name "*.tf" -o -name "Dockerfile*" -o -name "*.yaml" | \
xargs sha256sum | sha256sum > /tmp/current-hash.txt
if diff -q .diagram/cache/iac-hash.txt /tmp/current-hash.txt; then
echo "No changes detected - using cached scan"
fi
Update state:
{
"phase": "documenter",
"completed": ["scanner", "gate-check"]
}
IMPORTANT: Run these two documentation tasks IN PARALLEL using two simultaneous Task tool calls.
Both phases depend only on Scanner results - they do NOT depend on each other. Spawn both agents in a single message to maximize parallelization.
Model hint: Use opus for deep analysis. Run in parallel with Phase 4.
Delegate to Documenter agent with prompt:
ULTRATHINK: Perform deep, systematic analysis of infrastructure before documenting.
SOURCE OF TRUTH HIERARCHY (CRITICAL):
1. **CODE IS KING** - IaC files (*.tf, Dockerfile, k8s manifests) are the authoritative source
2. **Existing docs are HINTS ONLY** - Any existing diagrams/, docs/, or *.md files may be OUTDATED
3. **When code contradicts docs, CODE WINS** - Always trust what the code actually defines
4. **Verify everything** - Don't copy from old docs; re-derive from code
REASONING PROCESS (follow these steps mentally before writing):
Step 1 - Inventory: Read EVERY IaC file from scanner results. For each file:
- What resources does it define?
- What are the explicit dependencies?
- What are the implicit dependencies (naming conventions, references)?
Step 2 - Categorize: Group all discovered resources:
- Compute: EC2, ECS, EKS, Lambda, containers, pods, VMs
- Data: RDS, DynamoDB, Redis, Elasticsearch, S3, queues (SQS, Kafka)
- Network: VPC, subnets, ALB/NLB, API Gateway, CloudFront, Route53
- Security: IAM roles/policies, security groups, secrets, KMS
- External: Third-party APIs, SaaS integrations, webhooks
Step 3 - Map Relationships: For EVERY resource, identify:
- What does it connect TO? (outbound)
- What connects to IT? (inbound)
- Is this sync or async communication?
- What data flows through this connection?
Step 4 - Verify Completeness: Cross-reference with application code:
- Are there SDK calls to services not in IaC? (managed services, external APIs)
- Are there environment variables referencing infrastructure?
- Are there hardcoded endpoints or connection strings?
CONSTRAINTS:
- Do NOT guess or assume - if uncertain, note it as "UNVERIFIED: [reason]"
- Do NOT omit resources because they seem minor
- Do NOT skip resources in modules/includes - trace them
- EVERY claim must be traceable to a specific file:line
OUTPUT: Create ./diagrams/infrastructure.md with this structure:
# Infrastructure Documentation
## Overview
[2-3 sentence summary of the infrastructure]
## Components
### Compute
[For each: name, type, purpose, configuration highlights, file:line reference]
### Data Stores
[For each: name, type, purpose, configuration highlights, file:line reference]
### Networking
[For each: name, type, purpose, configuration highlights, file:line reference]
### Security
[For each: name, type, purpose, configuration highlights, file:line reference]
### External Services
[For each: name, type, purpose, how integrated, file:line reference]
## Relationships
[Mermaid-style relationship list or table showing all connections]
## Environment Differences
[If multiple environments detected: dev/staging/prod differences]
## Unverified Items
[List anything uncertain with reasoning]
SELF-CHECK before completing:
- [ ] Every IaC resource is documented
- [ ] Every relationship is bidirectional (A->B means B<-A documented)
- [ ] No guessing - uncertainties are flagged
- [ ] Word count exceeds 200
Apply project rules (OPTIONAL - only if ./diagrams/rules.md exists):
test -f ./diagrams/rules.md before attempting to readUpdate state:
{
"phase": "architecture-documenter",
"completed": ["scanner", "gate-check", "infrastructure-documenter"]
}
Model hint: Use opus for deep analysis. Run in parallel with Phase 3. Both detailed documentation phases run together.
Delegate to Documenter agent with prompt:
ULTRATHINK: Perform deep, systematic analysis of software architecture.
SOURCE OF TRUTH HIERARCHY (CRITICAL):
1. **CODE IS KING** - Source files, imports, configs are the authoritative source
2. **Existing docs are HINTS ONLY** - Any existing ARCHITECTURE.md, diagrams/, README may be OUTDATED
3. **When code contradicts docs, CODE WINS** - Old diagrams may show deleted services or wrong dependencies
4. **Verify everything** - Trace actual imports/calls; don't trust old documentation
5. **Old D2 files are suggestions** - Existing *.d2 files may be stale; regenerate from code analysis
REASONING PROCESS (follow these steps mentally before writing):
Step 1 - Identify Boundaries: Find all distinct services/modules:
- Separate deployable units (microservices, lambdas, workers)
- Logical modules within monoliths (packages, namespaces)
- Shared libraries and utilities
- For each: What is its single responsibility?
Step 2 - Trace Entry Points: For each service/module:
- Where does execution begin? (main, index, handler, app)
- What triggers it? (HTTP, event, schedule, queue)
- What are the public interfaces? (APIs, exports, events emitted)
Step 3 - Map Dependencies: Build the dependency graph:
- Internal: Which modules depend on which?
- External: What third-party libraries are critical?
- Runtime: What services must be running for this to work?
- Draw arrows: caller -> callee
Step 4 - Understand Data Flow: Trace data through the system:
- Where does data enter? (APIs, webhooks, uploads)
- How is it transformed? (validation, enrichment, aggregation)
- Where is it stored? (databases, caches, files)
- Where does it exit? (responses, events, exports)
Step 5 - Identify Patterns: Recognize architectural patterns:
- Layered? (presentation -> business -> data)
- Event-driven? (pub/sub, event sourcing)
- Microservices? (service mesh, API gateway)
- Monolith? (modular or big ball of mud?)
CONSTRAINTS:
- Do NOT guess module purposes - read the code
- Do NOT assume standard patterns - verify them
- Do NOT skip "utility" or "common" modules - they often hide coupling
- EVERY module must have a clear, documented purpose
OUTPUT: Create ./diagrams/architecture.md with this structure:
# Software Architecture Documentation
## Overview
[2-3 sentence architecture summary - what pattern, how many services, key tech]
## System Context
[What external systems/users interact with this system?]
## Layers / Services
### [Layer/Service Name]
- **Purpose**: [Single sentence]
- **Technology**: [Language, framework, key libraries]
- **Entry Points**: [How is it invoked?]
- **Dependencies**: [What does it require?]
- **Interfaces**: [What does it expose?]
- **Location**: [file paths]
[Repeat for each layer/service]
## Data Flow
### [Flow Name, e.g., "User Registration"]
1. [Step 1: where data enters]
2. [Step 2: first transformation]
...
N. [Step N: final destination]
[Document 2-3 critical flows]
## API Contracts
[Key APIs with method, path, purpose - or reference to OpenAPI spec]
## Deployment Mapping
[How architecture maps to infrastructure from Phase 3]
## Technical Debt / Concerns
[Any architectural issues noticed - tight coupling, circular deps, etc.]
SELF-CHECK before completing:
- [ ] Every service/module has documented purpose
- [ ] Dependency directions are clear (who calls whom)
- [ ] At least 2 data flows documented
- [ ] Infrastructure mapping present
- [ ] Word count exceeds 200
Update state:
{
"phase": "simplified-docs",
"completed": ["scanner", "gate-check", "infrastructure-documenter", "architecture-documenter"]
}
IMPORTANT: Run both simplified documentation phases IN PARALLEL using two simultaneous Task tool calls.
Both phases depend only on their respective detailed docs - they do NOT depend on each other. Spawn both agents in a single message to maximize parallelization.
Model hint: Use sonnet for efficient high-level synthesis. Run in parallel with Phase 6. Uses ./diagrams/infrastructure.md as input.
Delegate to Documenter agent with prompt:
TASK: Create a simplified, high-level infrastructure diagram for stakeholders and quick onboarding.
SOURCE MATERIAL:
Read ./diagrams/infrastructure.md (detailed infrastructure) first.
GOAL: Distill the detailed infrastructure into 3-8 major components that capture the essence of the system.
This is for:
- New team member onboarding
- Executive/stakeholder presentations
- Main README.md hero diagram
- Quick mental model of "what runs where"
SIMPLIFICATION RULES:
1. **Aggregate Similar Resources**: Combine related infrastructure into logical groups
- Multiple EC2 instances → "Application Servers"
- Multiple RDS instances → "Database Cluster" (or separate if architecturally different)
- Multiple Lambda functions → "Serverless Functions"
- Multiple subnets → hide (unless public/private distinction matters)
2. **Hide Implementation Details**:
- No instance types, sizes, or counts
- No availability zones or regions (unless multi-region is key)
- No security groups or IAM roles
- No monitoring/logging infrastructure
3. **Focus on Major Boundaries**:
- VPC as a container (if relevant)
- External vs Internal
- Data tier vs Application tier vs Edge
- What talks to what at the highest level
4. **Include Technology Names**: Use clear labels with technology in parentheses
- "Database (Aurora MySQL)" not just "Database"
- "Cache (Redis)" not just "Cache"
- "Message Queue (Kafka)" not just "Queue"
- "State Store (DynamoDB)" not just "State"
- This helps readers quickly understand what's actually running
5. **Target Components**: 3-8 boxes total
- If you have more than 15, you're not simplifying enough
- If you have fewer than 8, you might be hiding important distinctions
OUTPUT: Create ./diagrams/infrastructure-simplified.md with:
# Infrastructure Overview (Simplified)
## System Summary
[1-2 sentences: where does this run? cloud provider? key characteristics?]
## Major Components
### [Component Name]
**Purpose**: [One sentence - what infrastructure function]
**Contains**: [Brief list of what's aggregated here, if applicable]
[Repeat for 3-8 components]
## Data Flow
[Simple description: how traffic flows through the infrastructure]
1. External request hits...
2. ...routes to...
3. ...which accesses...
## Key Boundaries
| Boundary | Inside | Outside |
|----------|--------|---------|
| VPC | App servers, databases | Internet, users |
| ... | ... | ... |
SELF-CHECK:
- [ ] Component count is 3-8
- [ ] Labels include technology names in parentheses
- [ ] A technical person can understand what's running
- [ ] No unnecessary implementation details (instance sizes, versions)
- [ ] Major infrastructure tiers are represented
Update state:
{
"phase": "architecture-simplified",
"completed": ["scanner", "gate-check", "infrastructure-documenter", "architecture-documenter", "infrastructure-simplified"]
}
Model hint: Use sonnet for efficient high-level synthesis. Run in parallel with Phase 5. Uses ./diagrams/architecture.md as input.
Delegate to Documenter agent with prompt:
TASK: Create a simplified, high-level architecture diagram for stakeholders and quick onboarding.
SOURCE MATERIAL:
Read ./diagrams/architecture.md (detailed architecture) first.
GOAL: Distill the detailed architecture into 3-8 major components that capture the essence of the system.
This is for:
- New team member onboarding
- Executive/stakeholder presentations
- README overview
- Quick mental model building
SIMPLIFICATION RULES:
1. **Aggregate Services**: Combine related microservices into logical groups
- Multiple API endpoints → "API Gateway"
- Multiple workers/processors → "Background Processing"
- Multiple databases → keep separate if different technologies (e.g., "Database (MySQL)" vs "Cache (Redis)")
2. **Hide Internal Details**:
- No internal module structure
- No utility/helper services
- No monitoring/logging infrastructure (unless core to product)
- No CI/CD or deployment details
3. **Focus on Data Flow**:
- Where does data come FROM? (Users, APIs, Events)
- Where does data go TO? (Storage, External Systems, Users)
- What are the 2-3 major data transformation steps?
4. **Include Technology Names**: Use clear labels with technology in parentheses
- "Database (PostgreSQL)" not just "Database"
- "Message Queue (RabbitMQ)" not just "Queue"
- "Cache (Redis)" not just "Cache"
- "Event Stream (Kafka)" not just "Events"
- This helps readers quickly understand what's actually running
5. **Target Components**: 3-8 boxes total
- If you have more than 15, you're not simplifying enough
- If you have fewer than 8, you might be hiding important distinctions
OUTPUT: Create ./diagrams/architecture-simplified.md with:
# Architecture Overview (Simplified)
## System Summary
[1-2 sentences: what does this system do? who uses it?]
## Major Components
### [Component Name]
**Purpose**: [One sentence - what business function]
**Contains**: [Brief list of what's aggregated here, if applicable]
[Repeat for 3-8 components]
## Data Flow
[Simple numbered list: how data flows through the system]
1. User/External System sends request to...
2. ...processes and stores in...
3. ...which triggers...
4. ...returning response to...
## Key Interactions
| From | To | What |
|------|-----|------|
| Users | API | HTTP requests |
| API | Database | Read/Write |
| ... | ... | ... |
SELF-CHECK:
- [ ] Component count is 3-8
- [ ] Labels include technology names in parentheses
- [ ] A technical person can understand what's running
- [ ] No unnecessary implementation details (versions, configs)
- [ ] Major business capabilities are represented
Update state:
{
"phase": "renderer",
"completed": ["scanner", "gate-check", "infrastructure-documenter", "architecture-documenter", "infrastructure-simplified", "architecture-simplified"]
}
Model hint: Use opus for reliable diagram generation with thorough icon handling.
Delegate to Renderer agent with prompt:
TASK: Generate accurate D2 diagrams from documentation. Think carefully about D2 syntax.
STEP 1 - Review Documentation:
Read all 4 documentation files thoroughly:
- ./diagrams/infrastructure.md (detailed)
- ./diagrams/infrastructure-simplified.md (high-level)
- ./diagrams/architecture.md (detailed)
- ./diagrams/architecture-simplified.md (high-level)
Extract: all components, all relationships, groupings.
STEP 2 - Plan Diagram Structure:
Before writing D2, mentally plan:
- What are the top-level containers/groups?
- What nodes go in each group?
- What are ALL the connections?
- What labels clarify the connections?
STEP 3 - Write D2 with Correct Syntax:
**TECHNOLOGY → ICON MAPPING:**
For icons to appear in bundled SVGs, add BOTH `class:` (for styling) and `icon:` (for the image):
| Technology | Class | Icon URL |
|------------|-------|----------|
| MySQL | `mysql` | `https://icons.terrastruct.com/dev%2Fmysql.svg` |
| PostgreSQL | `postgresql` | `https://icons.terrastruct.com/dev%2Fpostgresql.svg` |
| Redis | `redis` | `https://icons.terrastruct.com/dev%2Fredis.svg` |
| MongoDB | `mongodb` | `https://icons.terrastruct.com/dev%2Fmongodb.svg` |
| Elasticsearch | `elasticsearch` | `https://icons.terrastruct.com/dev%2Felasticsearch.svg` |
| DynamoDB | `aws-dynamodb` | `https://icons.terrastruct.com/aws%2FDatabase%2FAmazon-DynamoDB.svg` |
| S3 | `aws-s3` | `https://icons.terrastruct.com/aws%2FStorage%2FAmazon-Simple-Storage-Service-S3.svg` |
| RDS/Aurora | `aws-rds` | `https://icons.terrastruct.com/aws%2FDatabase%2FAmazon-RDS.svg` |
| ElastiCache | `aws-elasticache` | `https://icons.terrastruct.com/aws%2FDatabase%2FAmazon-ElastiCache.svg` |
| Docker | `container` | `https://icons.terrastruct.com/dev%2Fdocker.svg` |
| Kubernetes | `kubernetes` | `https://icons.terrastruct.com/dev%2Fkubernetes.svg` |
| Go | `golang` | `https://icons.terrastruct.com/dev%2Fgo.svg` |
| Python | `python` | `https://icons.terrastruct.com/dev%2Fpython.svg` |
| Node.js | `nodejs` | `https://icons.terrastruct.com/dev%2Fnodejs.svg` |
| Users | `users` | `https://icons.terrastruct.com/essentials%2F359-users.svg` |
| Server | `server` | `https://icons.terrastruct.com/tech%2F022-server.svg` |
| Grafana | `grafana` | `https://icons.terrastruct.com/dev%2Fgrafana.svg` |
| Prometheus | `prometheus` | `https://icons.terrastruct.com/dev%2Fprometheus.svg` |
For classes without working icon URLs (Kafka, Datadog, etc.), use `class:` only for shape/styling.
**LABEL BEST PRACTICES:**
- Use SINGLE-LINE labels to avoid icon/text overlap
- Good: `config: MySQL Config`
- Bad: `config: Configuration (MySQL)\nFlows, steps`
**D2 SYNTAX EXAMPLE:**
```d2
direction: down
# Nodes with icons (class for style, icon for visual)
sources: Lead Sources {
class: users
icon: https://icons.terrastruct.com/essentials%2F359-users.svg
}
database: MySQL Config {
class: mysql
icon: https://icons.terrastruct.com/dev%2Fmysql.svg
}
# Nodes without icons (class provides shape/color only)
external: DataDog APM {class: cloud}
broker: Kafka Broker {class: queue}
vpc: AWS VPC { subnet-a: Subnet A { instance-1: EC2 } }
web-server -> postgres: "reads/writes" api -> cache: "gets" {style.stroke-dash: 5}
queue -> worker: "processes" { style: { stroke-dash: 5 stroke: "#666" } }
COMMON D2 ERRORS TO AVOID:
MINIMIZING CONNECTION BENDS:
direction: down or direction: right at diagram startSTEP 4 - Create Infrastructure Diagram (Detailed): Create ./diagrams/infrastructure.d2:
class: (styling) and icon: (URL) propertiesSTEP 5 - Create Infrastructure Diagram (Simplified): Create ./diagrams/infrastructure-simplified.d2:
class: and icon: propertiesSTEP 6 - Create Architecture Diagram (Detailed): Create ./diagrams/architecture.d2:
class: and icon: propertiesSTEP 7 - Create Architecture Diagram (Simplified): Create ./diagrams/architecture-simplified.d2:
class: and icon: propertiesSTEP 8 - Validate Before Rendering: Mental check for each diagram:
icon: property with a URL (CRITICAL)STEP 9 - Render SVGs (RUN ALL 8 IN PARALLEL): Execute these 8 commands simultaneously using parallel Bash tool calls:
d2 --bundle ./diagrams/infrastructure.d2 ./diagrams/infrastructure-light.svg --theme 0 --layout elk --animate-interval=1200 d2 --bundle ./diagrams/infrastructure.d2 ./diagrams/infrastructure-dark.svg --theme 200 --layout elk --animate-interval=1200
d2 --bundle ./diagrams/infrastructure-simplified.d2 ./diagrams/infrastructure-simplified-light.svg --theme 0 --layout elk --animate-interval=1200 d2 --bundle ./diagrams/infrastructure-simplified.d2 ./diagrams/infrastructure-simplified-dark.svg --theme 200 --layout elk --animate-interval=1200
d2 --bundle ./diagrams/architecture.d2 ./diagrams/architecture-light.svg --theme 0 --layout elk --animate-interval=1200 d2 --bundle ./diagrams/architecture.d2 ./diagrams/architecture-dark.svg --theme 200 --layout elk --animate-interval=1200
d2 --bundle ./diagrams/architecture-simplified.d2 ./diagrams/architecture-simplified-light.svg --theme 0 --layout elk --animate-interval=1200 d2 --bundle ./diagrams/architecture-simplified.d2 ./diagrams/architecture-simplified-dark.svg --theme 200 --layout elk --animate-interval=1200
These are independent operations - run them all in one message with 8 Bash tool calls.
ERROR RECOVERY:
**Update state:**
```json
{
"phase": "enhancer",
"completed": ["scanner", "gate-check", "infrastructure-documenter", "architecture-documenter", "infrastructure-simplified", "architecture-simplified", "renderer"]
}
Model hint: Use sonnet for reliable SVG processing.
Step 1 - Inline SVG icons for GitHub compatibility:
${CLAUDE_PLUGIN_ROOT}/scripts/inline-svg-icons.sh --all ./diagrams/
GitHub strips <image> tags for security. This converts them to inline <svg> elements which GitHub allows.
Step 2 - Add CSS animations:
${CLAUDE_PLUGIN_ROOT}/scripts/enhance-svg.sh --all ./diagrams/
IMPORTANT: Always use the plugin's built-in scripts. Do NOT write scripts to the target repository.
The enhance script:
./diagrams/animations.css<svg> tagCSS Design Principles:
path[marker-end])Alternative - Delegate to Enhancer agent if script fails:
Enhance the generated SVG diagrams with CSS animations.
DESIGN RULES:
1. Use `path[marker-end]` selector for connections
2. Do NOT use filter effects (can bleed into text)
3. Do NOT override colors - D2 handles themes
4. Always include text protection rules
Files to enhance (all 8):
- ./diagrams/infrastructure-light.svg
- ./diagrams/infrastructure-dark.svg
- ./diagrams/infrastructure-simplified-light.svg
- ./diagrams/infrastructure-simplified-dark.svg
- ./diagrams/architecture-light.svg
- ./diagrams/architecture-dark.svg
- ./diagrams/architecture-simplified-light.svg
- ./diagrams/architecture-simplified-dark.svg
CSS source: ./diagrams/animations.css
Verify after enhancement:
Animation types applied:
| Element Type | Animation | CSS Selector |
|---|---|---|
| Connection arrows | Moving dashes (1s) | path[marker-end] |
| Async connections | Slower dashes (2s) | path[marker-end][stroke-dasharray] |
| Cylinder shapes | Subtle opacity pulse | .shape-cylinder > path:first-of-type |
| Queue shapes | Subtle opacity pulse | .shape-queue > path:first-of-type |
Update state:
{
"phase": "readme-integration",
"completed": ["scanner", "gate-check", "infrastructure-documenter", "architecture-documenter", "infrastructure-simplified", "architecture-simplified", "renderer", "enhancer"]
}
This phase updates TWO readme files:
Check if a README.md exists at repo root:
test -f README.md && echo "exists" || echo "none"
If README.md exists, find a suitable location (after description, before detailed sections) and add:
## System Overview
### Infrastructure
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./diagrams/infrastructure-simplified-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./diagrams/infrastructure-simplified-light.svg">
<img alt="Infrastructure Overview" src="./diagrams/infrastructure-simplified-light.svg">
</picture>
### Architecture
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./diagrams/architecture-simplified-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./diagrams/architecture-simplified-light.svg">
<img alt="Architecture Overview" src="./diagrams/architecture-simplified-light.svg">
</picture>
[More diagrams →](./diagrams/README.md)
Placement rules:
If README.md doesn't exist, skip this step.
Create the diagrams landing page with ALL diagrams:
# System Diagrams
Auto-generated diagrams for this project. View the [main README](../README.md) for project overview.
---
## Infrastructure
### Overview (Simplified)
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./infrastructure-simplified-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./infrastructure-simplified-light.svg">
<img alt="Infrastructure Overview" src="./infrastructure-simplified-light.svg">
</picture>
[View simplified documentation](./infrastructure-simplified.md)
### Detailed
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./infrastructure-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./infrastructure-light.svg">
<img alt="Infrastructure Diagram" src="./infrastructure-light.svg">
</picture>
[View detailed documentation](./infrastructure.md)
---
## Architecture
### Overview (Simplified)
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./architecture-simplified-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./architecture-simplified-light.svg">
<img alt="Architecture Overview" src="./architecture-simplified-light.svg">
</picture>
[View simplified documentation](./architecture-simplified.md)
### Detailed
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./architecture-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./architecture-light.svg">
<img alt="Architecture Diagram" src="./architecture-light.svg">
</picture>
[View detailed documentation](./architecture.md)
---
## Documentation
| Document | Description |
|----------|-------------|
| [infrastructure-simplified.md](./infrastructure-simplified.md) | High-level infrastructure overview |
| [infrastructure.md](./infrastructure.md) | Detailed infrastructure components |
| [architecture-simplified.md](./architecture-simplified.md) | High-level architecture overview |
| [architecture.md](./architecture.md) | Detailed software architecture |
## Regenerating
\`\`\`
/d2:diagram # Full regeneration
/d2:diagram --incremental # Only changed components
\`\`\`
Update state:
{
"phase": "verification",
"completed": ["scanner", "gate-check", "infrastructure-documenter", "architecture-documenter", "infrastructure-simplified", "architecture-simplified", "renderer", "enhancer", "readme-integration"]
}
Model hint: Use haiku for fast verification.
Delegate to Verifier agent with prompt:
TASK: Verify all outputs meet quality standards. Be thorough but fast.
CHECKLIST (check each, report pass/fail):
1. FILE EXISTENCE (16 diagram files + 1 README):
[ ] ./diagrams/README.md exists
[ ] ./diagrams/infrastructure.md exists
[ ] ./diagrams/infrastructure.d2 exists
[ ] ./diagrams/infrastructure-light.svg exists
[ ] ./diagrams/infrastructure-dark.svg exists
[ ] ./diagrams/infrastructure-simplified.md exists
[ ] ./diagrams/infrastructure-simplified.d2 exists
[ ] ./diagrams/infrastructure-simplified-light.svg exists
[ ] ./diagrams/infrastructure-simplified-dark.svg exists
[ ] ./diagrams/architecture.md exists
[ ] ./diagrams/architecture.d2 exists
[ ] ./diagrams/architecture-light.svg exists
[ ] ./diagrams/architecture-dark.svg exists
[ ] ./diagrams/architecture-simplified.md exists
[ ] ./diagrams/architecture-simplified.d2 exists
[ ] ./diagrams/architecture-simplified-light.svg exists
[ ] ./diagrams/architecture-simplified-dark.svg exists
2. DOCUMENTATION QUALITY:
[ ] infrastructure.md has Overview section
[ ] infrastructure.md has Components section
[ ] infrastructure.md word count > 150
[ ] infrastructure-simplified.md has System Summary section
[ ] infrastructure-simplified.md has Major Components section
[ ] infrastructure-simplified.md documents 3-8 components with technology names
[ ] architecture.md has Overview section
[ ] architecture.md has Layers/Services section
[ ] architecture.md word count > 150
[ ] architecture-simplified.md has System Summary section
[ ] architecture-simplified.md has Major Components section
[ ] architecture-simplified.md documents 3-8 components with technology names
3. D2 SYNTAX (run these commands for all 4 D2 files):
[ ] d2 fmt ./diagrams/infrastructure.d2 --check (exit 0)
[ ] d2 fmt ./diagrams/infrastructure-simplified.d2 --check (exit 0)
[ ] d2 fmt ./diagrams/architecture.d2 --check (exit 0)
[ ] d2 fmt ./diagrams/architecture-simplified.d2 --check (exit 0)
[ ] infrastructure.d2 has >= 3 nodes
[ ] infrastructure.d2 has >= 2 connections (->)
[ ] infrastructure-simplified.d2 has 3-8 nodes with technology names in labels
[ ] infrastructure-simplified.d2 has >= 2 connections (->)
[ ] architecture.d2 has >= 3 nodes
[ ] architecture.d2 has >= 2 connections (->)
[ ] architecture-simplified.d2 has 3-8 nodes with technology names in labels
[ ] architecture-simplified.d2 has >= 2 connections (->)
4. SVG QUALITY (all 8 SVG files):
[ ] All SVG files > 1KB
[ ] All SVGs contain <svg tag
[ ] All SVGs contain "traffic-flow" (animation CSS)
[ ] All SVGs contain "prefers-reduced-motion" (accessibility)
[ ] No SVG contains "error" or "Error"
5. README INTEGRATION:
[ ] ./diagrams/README.md exists
[ ] Contains <picture> elements for all 4 diagram types
[ ] Contains both simplified and detailed sections
[ ] Contains prefers-color-scheme media queries
[ ] Contains links to all 4 documentation files (.md)
[ ] All srcset paths are valid relative paths
6. MAIN README (if exists):
[ ] Contains simplified diagrams (infrastructure-simplified, architecture-simplified)
[ ] Contains "More diagrams" link to ./diagrams/README.md
[ ] Uses correct relative paths (./diagrams/*.svg)
OUTPUT FORMAT (JSON):
{
"status": "PASS" | "FAIL",
"checks": {
"file_existence": {"pass": N, "fail": N, "issues": []},
"documentation": {"pass": N, "fail": N, "issues": []},
"d2_syntax": {"pass": N, "fail": N, "issues": []},
"svg_quality": {"pass": N, "fail": N, "issues": []},
"readme": {"pass": N, "fail": N, "issues": []}
},
"summary": "X/Y checks passed",
"action": "cleanup" | "remediate"
}
ON SUCCESS (all checks pass):
- Remove .diagram/state.json
- Report completion summary
ON FAILURE (any check fails):
- Keep .diagram/state.json
- List specific failures with remediation steps
- Do NOT clean up state
Users can create ./diagrams/rules.md to customize behavior (this file is committed with your diagrams):
# Diagram Generation Rules
## Naming Conventions
- Use "API Gateway" not "APIGW"
- Use full service names, not abbreviations
## Excluded Paths
- Ignore test/ directory
- Ignore examples/
## Additional Components
Include these even if not in IaC:
- Cloudflare (external CDN)
- Datadog (monitoring)
## Style Overrides
- Use blue tones for our brand
- Group by team ownership
## Icons
- Disable icons (removes icon requirement and validation warnings)
- OR: Custom icon mapping:
- MySQL → https://example.com/custom-mysql-icon.svg
- Redis → https://example.com/custom-redis-icon.svg
## Documentation Sections
Add these custom sections:
- Team Ownership
- SLA Requirements
By default, icons are required on all technology nodes. To customize:
Disable icons entirely:
## Icons
- Disable icons
Use custom icon URLs:
## Icons
- MySQL → https://example.com/mysql.svg
- PostgreSQL → https://example.com/postgres.svg
When icons are disabled:
icon: property is not added to nodesshape: and class: for visual distinction| Error | Recovery |
|---|---|
| D2 not installable | Abort with manual install instructions |
| No IaC found | Offer code-only analysis or abort |
| D2 syntax error | Auto-fix and retry (3 attempts) |
| Render failure | Fall back to dagre layout |
| Context limit | Use --incremental or --scope |
| Large codebase | Split into focused diagrams |
When complete, report:
Diagram Generation Complete
===========================
Files created:
README.md (updated with simplified diagrams)
./diagrams/README.md (landing page with all diagrams)
Infrastructure (detailed):
./diagrams/infrastructure.md (2,500 words)
./diagrams/infrastructure.d2
./diagrams/infrastructure-light.svg
./diagrams/infrastructure-dark.svg
Infrastructure (simplified):
./diagrams/infrastructure-simplified.md (350 words)
./diagrams/infrastructure-simplified.d2
./diagrams/infrastructure-simplified-light.svg
./diagrams/infrastructure-simplified-dark.svg
Architecture (detailed):
./diagrams/architecture.md (3,000 words)
./diagrams/architecture.d2
./diagrams/architecture-light.svg
./diagrams/architecture-dark.svg
Architecture (simplified):
./diagrams/architecture-simplified.md (450 words)
./diagrams/architecture-simplified.d2
./diagrams/architecture-simplified-light.svg
./diagrams/architecture-simplified-dark.svg
Components documented:
Compute: 8 resources
Data stores: 4 resources
Networking: 6 resources
Services: 12 modules
Verification: PASSED (all checks)
Main README: Updated with simplified diagrams
All diagrams: ./diagrams/README.md