sf-diagram: Salesforce Diagram Generation Skill

sf-diagram: 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

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

Supported Diagram Types

| Type | Mermaid Syntax | Use Case | |------|---------------|----------| | OAuth Flows | sequenceDiagram | Authorization Code, JWT Bearer, PKCE, Device Flow | | Data Models | flowchart LR | Object relationships with color coding (preferred) | | Integration Sequences | sequenceDiagram | API callouts, event-driven flows | | System Landscapes | flowchart | High-level architecture, component diagrams | | Role Hierarchies | flowchart | User hierarchies, profile/permission structures | | Agentforce Flows | flowchart | Agent → Topic → Action flows |

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:

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

Phase 2: Template Selection

Select template based on diagram type:

| Diagram Type | Template File | |--------------|---------------| | Authorization Code Flow | oauth/authorization-code.md | | Authorization Code + PKCE | oauth/authorization-code-pkce.md | | JWT Bearer Flow | oauth/jwt-bearer.md | | Client Credentials Flow | oauth/client-credentials.md | | Device Authorization Flow | oauth/device-authorization.md | | Refresh Token Flow | oauth/refresh-token.md | | Data Model (ERD) | datamodel/salesforce-erd.md | | Integration Sequence | integration/api-sequence.md | | System Landscape | architecture/system-landscape.md | | Role Hierarchy | role-hierarchy/user-hierarchy.md | | Agentforce Flow | agentforce/agent-flow.md |

Template Path Resolution (try in order):

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

Example: To load JWT Bearer template:

Read: ~/.claude/plugins/marketplaces/sf-skills/sf-diagram/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:

If org connected, query record counts for LDV indicators:

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

Identify relationships (Lookup vs Master-Detail)
Determine object types (Standard, Custom, External)
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:

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

Generate ASCII fallback:

Use box-drawing characters: ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼
Use arrows: ──> <── ─── ─┼─
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

| Rating | Score | Meaning | |--------|-------|---------| | ⭐⭐⭐⭐⭐ Excellent | 72-80 | Production-ready, comprehensive, well-styled | | ⭐⭐⭐⭐ Very Good | 60-71 | Complete with minor improvements possible | | ⭐⭐⭐ Good | 48-59 | Functional but could be clearer | | ⭐⭐ Needs Work | 35-47 | Missing key elements or unclear | | ⭐ Critical Issues | <35 | Inaccurate or incomplete |

OAuth Flow Quick Reference

| Flow | Use Case | Key Detail | Template | |------|----------|------------|----------| | Authorization Code | Web apps with backend | User → Browser → App → SF | oauth/authorization-code.md | | Auth Code + PKCE | Mobile, SPAs, public clients | code_verifier + SHA256 challenge | oauth/authorization-code-pkce.md | | JWT Bearer | Server-to-server, CI/CD | Sign JWT with private key | oauth/jwt-bearer.md | | Client Credentials | Service accounts, background | No user context | oauth/client-credentials.md | | Device Authorization | CLI, IoT, Smart TVs | Poll for token after user auth | oauth/device-authorization.md | | Refresh Token | Extend access | Reuse existing tokens | oauth/refresh-token.md |

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:

| Object Type | Color | Fill | Stroke | |-------------|-------|------|--------| | Standard Objects | Sky Blue | #bae6fd | #0369a1 | | Custom Objects (__c) | Orange | #fed7aa | #c2410c | | External Objects (__x) | Green | #a7f3d0 | #047857 |

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/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

| Label | Type | Arrow Style | Behavior | |-------|------|-------------|----------| | LK | Lookup | --> | Optional parent, no cascade | | MD | Master-Detail | ==> | Required parent, cascade delete |

In flowchart format:

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

Data Model Templates

| Template | Objects | Path | |----------|---------|------| | Core | Account, Contact, Opportunity, Case | templates/datamodel/salesforce-erd.md | | Sales Cloud | Account, Contact, Lead, Opportunity, Product, Campaign | templates/datamodel/sales-cloud-erd.md | | Service Cloud | Case, Entitlement, Knowledge, ServiceContract | templates/datamodel/service-cloud-erd.md | | Campaigns | Campaign, CampaignMember, CampaignInfluence | templates/datamodel/campaigns-erd.md | | Territory Management | Territory2, Territory2Model, UserTerritory2Association | templates/datamodel/territory-management-erd.md | | Party Model | AccountContactRelation, ContactContactRelation | templates/datamodel/party-model-erd.md | | Quote & Order | Quote, QuoteLineItem, Order, OrderItem | templates/datamodel/quote-order-erd.md | | Forecasting | ForecastingItem, ForecastingQuota, OpportunitySplit | templates/datamodel/forecasting-erd.md | | Consent (GDPR) | Individual, ContactPointEmail, DataUsePurpose | templates/datamodel/consent-erd.md | | Files | ContentDocument, ContentVersion, ContentDocumentLink | templates/datamodel/files-erd.md | | Scheduler | ServiceAppointment, ServiceResource, ServiceTerritory | templates/datamodel/scheduler-erd.md | | Field Service | WorkOrder, ServiceAppointment, TimeSheet | templates/datamodel/fsl-erd.md | | B2B Commerce | WebStore, WebCart, BuyerGroup, BuyerAccount | templates/datamodel/b2b-commerce-erd.md | | Revenue Cloud | ProductCatalog, ProductSellingModel, PriceAdjustment | templates/datamodel/revenue-cloud-erd.md |

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

| Skill | When to Use | Example | |-------|-------------|---------| | sf-metadata | Get real object/field definitions for ERD | Skill(skill="sf-metadata") → "Describe Lead object" | | sf-connected-apps | Link OAuth flow to Connected App setup | "Generate JWT Bearer diagram for this Connected App" | | sf-ai-agentforce | Visualize Agentforce agent architecture | "Create flow diagram for FAQ Agent" | | sf-flow | Document Flow logic as flowchart | "Diagram the approval process flow" |

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

Agent Skills: sf-diagram: Salesforce Diagram Generation

Skill Files