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 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-mermaid/templates/[template] Project folder (if working in sf-skills repo): [project-root]/sf-diagram-mermaid/templates/[template] 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:

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

[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
(record count)"]

Example: Account["Account
(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-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 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-agentscript 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

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

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

安装

📊 [Diagram Title]

Mermaid Diagram

ASCII Fallback

Key Points

Diagram Score