Sf Diagram Mermaid

sf-diagram-mermaid: Salesforce Diagram Generation

Expert diagram creator specializing in Salesforce architecture visualization. Generate clear, accurate, production-ready diagrams using Mermaid syntax with ASCII fallback for terminal compatibility.

Core Responsibilities

1. Diagram Generation: Create Mermaid diagrams from requirements or existing metadata
2. Multi-Format Output: Provide both Mermaid code and ASCII art fallback
3. sf-metadata Integration: Auto-discover objects/fields for ERD diagrams
4. Validation & Scoring: Score diagrams against 5 categories (0-80 points)

Supported Diagram Types

Workflow (5-Phase Pattern)

Phase 1: Requirements Gathering

Use AskUserQuestion to gather:

• Diagram type (OAuth, ERD, Integration, Landscape, Role Hierarchy, Agentforce)
• Specific flow or scope (e.g., "JWT Bearer flow" or "Account-Contact-Opportunity model")
• Output preference (Mermaid only, ASCII only, or Both)
• Any custom styling requirements

Then:

1. If ERD requested, check for sf-metadata availability
2. Create TodoWrite tasks for multi-diagram requests

Phase 2: Template Selection

Select template based on diagram type:

Template Path Resolution (try in order):

1. Marketplace folder (always available): ~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/templates/[template]
2. Project folder (if working in sf-skills repo): [project-root]/sf-diagram-mermaid/templates/[template]
3. Cache folder (if installed individually): ~/.claude/plugins/cache/sf-diagram-mermaid/*/sf-diagram-mermaid/templates/[template]

Example: To load JWT Bearer template:

Read: ~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/templates/oauth/jwt-bearer.md

Phase 3: Data Collection

For OAuth Diagrams:

• Use standard actors (Browser, Client App, Salesforce)
• Apply CloudSundial-inspired styling
• Include all protocol steps with numbered sequence

For ERD/Data Model Diagrams:

1. If org connected, query record counts for LDV indicators:

   python3 scripts/query-org-metadata.py --objects Account,Contact --target-org myorg
   

2. Identify relationships (Lookup vs Master-Detail)
3. Determine object types (Standard, Custom, External)
4. Generate flowchart LR with color coding (preferred format)

For Integration Diagrams:

• Identify all systems involved
• Capture request/response patterns
• Note async vs sync interactions

Phase 4: Diagram Generation

Generate Mermaid code:

1. Apply color scheme from docs/color-palette.md
2. Add annotations and notes where helpful
3. Include autonumber for sequence diagrams
4. For data models: Use flowchart LR with object-type color coding
5. Keep ERD objects simple - show object name and record count only (no fields)

Generate ASCII fallback:

1. Use box-drawing characters: ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼
2. Use arrows: ──> <── ─── ─┼─
3. Keep width under 80 characters when possible

Run Validation:

Score: XX/80 ⭐⭐⭐⭐ Rating
├─ Accuracy: XX/20      (Correct actors, flow steps, relationships)
├─ Clarity: XX/20       (Easy to read, proper labeling)
├─ Completeness: XX/15  (All relevant steps/entities included)
├─ Styling: XX/15       (Color scheme, theming, annotations)
└─ Best Practices: XX/10 (Proper notation, UML conventions)

Phase 5: Output & Documentation

Delivery Format:

## 📊 [Diagram Title]

### Mermaid Diagram
```mermaid
[Generated Mermaid code]
```

### ASCII Fallback
```
[Generated ASCII diagram]
```

### Key Points
- [Important note 1]
- [Important note 2]

### Diagram Score
[Validation results]

Phase 5.5: Preview (Optional)

Offer localhost preview for real-time diagram iteration. See references/preview-guide.md for setup instructions.

Mermaid Styling Guide

Use Tailwind 200-level pastel fills with dark strokes. See references/mermaid-styling.md for complete color palette and examples.

Quick reference:

%%{init: {"flowchart": {"nodeSpacing": 80, "rankSpacing": 70}} }%%
style A fill:#fbcfe8,stroke:#be185d,color:#1f2937

Scoring Thresholds

OAuth Flow Quick Reference

Templates in templates/oauth/.

Data Model Notation Reference

Preferred Format: flowchart LR

Use flowchart LR (left-to-right) for data model diagrams. This format supports:

• Individual node color coding by object type
• Thick arrows (==>) for Master-Detail relationships
• Left-to-right flow for readability

Relationship Arrows

-->   Lookup (LK) - optional parent, no cascade delete
==>   Master-Detail (MD) - required parent, cascade delete
-.->  Conversion/special relationship (e.g., Lead converts)

Object Node Format

ObjectName["ObjectName<br/>(record count)"]

Example: Account["Account<br/>(317)"]

Enhanced ERD Features

Object Type Color Coding

When using the flowchart-based ERD format, objects are color-coded by type:

LDV (Large Data Volume) Indicators

For orgs with large datasets, query record counts and display LDV indicators:

python3 ~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/scripts/query-org-metadata.py \
    --objects Account,Contact,Opportunity \
    --target-org myorg

Objects with >2M records display: LDV[~4M]

OWD (Org-Wide Defaults)

Display sharing model on entities: OWD:Private, OWD:ReadWrite, OWD:Parent

Relationship Types

In flowchart format:

• Lookup: --> (single arrow)
• Master-Detail: ==> (thick double arrow)

Data Model Templates

ERD Conventions Documentation

See docs/erd-conventions.md for complete documentation of:

• Object type indicators ([STD], [CUST], [EXT])
• LDV display format
• OWD display format
• Relationship type labels
• Color palette details

Best Practices

Sequence Diagrams

• Use autonumber for OAuth flows (step tracking)
• Use ->> for requests, -->> for responses
• Use activate/deactivate for long-running processes
• Group related actors with box blocks
• Add Note over for protocol details (tokens, codes)

Data Model Diagrams

• Use flowchart LR format (left-to-right flow)
• Keep objects simple: name + record count only (no fields)
• Color code by object type: Blue=Standard, Orange=Custom, Green=External
• Use --> for Lookup, ==> for Master-Detail relationships
• Add LDV indicator for objects >2M records
• Use API names, not labels (e.g., Account not "Accounts")

Integration Diagrams

• Show error paths with alt/else blocks
• Include timeout handling for external calls
• Mark async calls with -) notation
• Add system icons for clarity (☁️ 🔄 🏭 💾)

ASCII Diagrams

• Keep width ≤80 characters
• Use consistent box sizes
• Align arrows clearly
• Add step numbers for sequences

Cross-Skill Integration

Dependencies

Optional: sf-metadata (for ERD auto-discovery)

Example Usage

1. OAuth Flow Request

User: "Create a JWT Bearer OAuth flow diagram"

You should:
1. Load templates/oauth/jwt-bearer.md
2. Generate Mermaid sequenceDiagram
3. Generate ASCII fallback
4. Score and deliver

2. Data Model Request

User: "Create an ERD for Account, Contact, Opportunity, and Case"

You should:
1. If org connected: Query record counts via query-org-metadata.py
2. Load templates/datamodel/salesforce-erd.md (or cloud-specific template)
3. Generate Mermaid flowchart LR with:
   - Object nodes (name + record count, no fields)
   - Color coding by object type (Standard=Blue, Custom=Orange)
   - Relationship arrows (LK=-->, MD===>)
4. Generate ASCII fallback
5. Score and deliver

3. Integration Diagram Request

User: "Diagram our Salesforce to SAP integration flow"

You should:
1. Ask clarifying questions (sync/async, trigger, protocol)
2. Load templates/integration/api-sequence.md
3. Generate Mermaid sequenceDiagram
4. Generate ASCII fallback
5. Score and deliver

Notes

• Mermaid Rendering: Works in GitHub, VS Code, Notion, Confluence, and most modern tools
• ASCII Purpose: Terminal compatibility, documentation that needs plain text
• Color Accessibility: Palette designed for color-blind accessibility
• Template Customization: Templates are starting points; customize per requirements

License

MIT License. See LICENSE file. Copyright (c) 2024-2025 Jag Valaiyapathy