forcedotcom/sf-skills / skills/external-diagram-mermaid-generate
external-diagram-mermaid-generate
UnverifiedSalesforce architecture diagrams using Mermaid with ASCII fallback. Use this skill when generating text-based diagrams for Salesforce architecture, OAuth flows, ERDs, integration sequences, or Agentforce structure. TRIGGER when: user says "diagram", "visualize", "ERD", or asks for sequence diagrams, flowcharts, class diagrams, or architecture visualizations in Mermaid. DO NOT TRIGGER when: user asks about non-Salesforce systems.
references/diagram-conventions.md
View on GitHub<!-- Parent: external-diagram-mermaid-generate/SKILL.md -->
# Diagram Conventions
Consistency guidelines for all sf-diagram generated diagrams.
## General Principles
1. **Clarity over completeness** - Show key elements, not every detail
2. **Consistent naming** - Use API names for Salesforce objects/fields
3. **Accessibility first** - Colors supplement, not replace, meaning
4. **Dual output** - Always provide Mermaid + ASCII fallback
---
## Sequence Diagram Conventions
### Actor Naming
| System | Display Name | Icon |
|--------|--------------|------|
| End User | User | š¤ |
| Web Browser | Browser | š |
| Mobile App | Mobile App | š± |
| Backend Server | App Server | š„ļø |
| Salesforce Auth | Salesforce<br/>Authorization Server | āļø |
| Salesforce API | Salesforce<br/>REST API | š |
| External API | [System Name]<br/>API | š |
| Middleware | [Name]<br/>(MuleSoft, etc.) | š |
| Database | Database / Data Lake | š¾ |
### Arrow Usage
| Scenario | Arrow | Example |
|----------|-------|---------|
| HTTP Request | `->>` | `Client->>Server: GET /api` |
| HTTP Response | `-->>` | `Server-->>Client: 200 OK` |
| Async (fire-forget) | `-)` | `Trigger-)Queue: Enqueue job` |
| Internal call | `->` | `Service->Service: Process` |
| Failed/Error | `-x` | `Client-x Server: 500 Error` |
### Standard Sections
1. **Title Note** - First element, describes the flow
2. **Actor Boxes** - Group related actors
3. **Numbered Steps** - Use `autonumber`
4. **Notes** - Add context for complex steps
5. **Alt/Else** - Show branching (success/error)
### Example Structure
```text
%%{init: {...}}%%
sequenceDiagram
autonumber
%% Actor groups
box rgb(...) [Group Name]
participant ...
end
%% Title
Note over ...: [Flow Name]
%% Main flow
A->>B: Step description
Note over A,B: Technical details
%% Branching
alt Success
...
else Error
...
end
```
---
## ERD Conventions
### Object Naming
- Use **API Names** (e.g., `Account`, `Custom_Object__c`)
- Use **CamelCase** for standard objects
- Include `__c` suffix for custom objects
### Field Representation
```text
OBJECT {
Type FieldName Annotation "Comment"
}
```
**Type Mapping:**
| Salesforce Type | ERD Type |
|-----------------|----------|
| Id | Id |
| Text, String | Text |
| Number, Integer | Number |
| Decimal, Double | Decimal |
| Currency | Currency |
| Percent | Percent |
| Checkbox | Checkbox |
| Date | Date |
| DateTime | DateTime |
| Picklist | Picklist |
| Multi-Select Picklist | MultiPicklist |
| Lookup | Lookup |
| Master-Detail | MasterDetail |
| Formula | Formula |
| Roll-Up Summary | RollUp |
| Email | Email |
| Phone | Phone |
| URL | URL |
| Auto Number | AutoNumber |
**Annotations:**
| Annotation | Meaning |
|------------|---------|
| PK | Primary Key (Id field) |
| FK | Foreign Key (Lookup/Master-Detail) |
| UK | Unique Key (External ID) |
**Comments:**
- `"Required"` for non-nullable fields
- `"FK ā Object"` to indicate relationship target
- `"Roll-Up: SUM(Amount)"` for roll-up formulas
### Relationship Lines
| Relationship | Line | Salesforce Equivalent |
|--------------|------|----------------------|
| One-to-Many | `\|\|--o{` | Parent Lookup |
| Many-to-Many | `}o--o{` | Junction Object |
| One-to-One | `\|\|--\|\|` | Rare, use Lookup |
| Master-Detail | `\|\|--\|{` | MD (cascade delete) |
### Layout Guidelines
1. **Primary objects at top** - Account, Lead at top
2. **Related objects below** - Contact under Account
3. **Junction objects between** - Show many-to-many clearly
4. **Limit fields shown** - Key fields only (5-10 per object)
---
## Flowchart Conventions
### Direction
| Use Case | Direction |
|----------|-----------|
| Process flow | `TB` (Top to Bottom) |
| System integration | `LR` (Left to Right) |
| Hierarchy | `TB` |
| Timeline | `LR` |
### Node Shapes
| Concept | Shape | Syntax |
|---------|-------|--------|
| Start/End | Stadium | `([Start])` |
| Process/Action | Rectangle | `[Process]` |
| Decision | Diamond | `{Decision?}` |
| Database | Cylinder | `[(Database)]` |
| External System | Parallelogram | `[/External/]` |
| Subprocess | Double Rectangle | `[[Subprocess]]` |
### Subgraph Usage
Group related components:
```mermaid
%%{init: {"flowchart": {"nodeSpacing": 80, "rankSpacing": 70}} }%%
flowchart LR
subgraph sf["āļø SALESFORCE"]
A[Flow]
B[Apex]
end
subgraph ext["š EXTERNAL"]
C[API]
end
style sf fill:#ecfeff,stroke:#0e7490,stroke-dasharray:5
style ext fill:#ecfdf5,stroke:#047857,stroke-dasharray:5
style A fill:#c7d2fe,stroke:#4338ca,color:#1f2937
style B fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
style C fill:#a7f3d0,stroke:#047857,color:#1f2937
```
---
## ASCII Diagram Conventions
### Box Drawing Characters
```text
Standard Box:
āāāāāāāāāāāāāāāāāāā
ā ā
āāāāāāāāāāāāāāāāāāā
Rounded corners (optional):
āāāāāāāāāāāāāāāāāāā®
ā ā
ā°āāāāāāāāāāāāāāāāāāÆ
```
### Line Characters
| Character | Unicode | Usage |
|-----------|---------|-------|
| `ā` | U+2500 | Horizontal line |
| `ā` | U+2502 | Vertical line |
| `ā` | U+250C | Top-left corner |
| `ā` | U+2510 | Top-right corner |
| `ā` | U+2514 | Bottom-left corner |
| `ā` | U+2518 | Bottom-right corner |
| `ā` | U+251C | Left T-junction |
| `ā¤` | U+2524 | Right T-junction |
| `ā¬` | U+252C | Top T-junction |
| `ā“` | U+2534 | Bottom T-junction |
| `ā¼` | U+253C | Cross junction |
### Arrow Characters
```yaml
Right: āāā> or āāā¶ or āāāāāāāāāāāāāāāā>
Left: <āāā or āāā
Up: ā²
Down: ā¼
Bidirectional: <āā>
```
### Width Guidelines
- **Max width**: 80 characters (terminal friendly)
- **Box width**: Consistent within diagram
- **Label padding**: At least 1 space inside boxes
### Example ASCII Sequence
```text
āāāāāāāāāāāā āāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāā
ā Client ā ā Server ā ā Database ā
āāāāāā¬āāāāāā āāāāāāāāā¬āāāāāāāā āāāāāāāāā¬āāāāāāāāā
ā ā ā
ā 1. Request ā ā
āāāāāāāāāāāāāāāāāāā>ā ā
ā ā ā
ā ā 2. Query ā
ā āāāāāāāāāāāāāāāāāāāāā>ā
ā ā ā
ā ā 3. Results ā
ā ā<āāāāāāāāāāāāāāāāāāāāā
ā ā ā
ā 4. Response ā ā
ā<āāāāāāāāāāāāāāāāāāā ā
```
---
## Scoring Criteria
### Accuracy (20 points)
- Correct actors/entities
- Accurate flow sequence
- Proper relationships (ERD)
- Valid syntax
### Clarity (20 points)
- Readable labels
- Logical layout
- Appropriate detail level
- Good spacing
### Completeness (15 points)
- All key steps included
- Error paths shown (where applicable)
- Annotations for context
- Legend if needed
### Styling (15 points)
- Consistent colors
- Proper theming
- Icons where helpful
- Professional appearance
### Best Practices (10 points)
- UML/notation conventions
- Accessibility considerations
- Dual format output
- Documentation
---
## Validation Checklist
Before delivering a diagram:
- [ ] Mermaid syntax is valid (renders without errors)
- [ ] ASCII fallback is provided
- [ ] Colors follow palette
- [ ] Icons supplement colors
- [ ] Labels are clear and consistent
- [ ] Appropriate detail level
- [ ] Flow/relationships are accurate
- [ ] Key points documented
- [ ] Score calculated and shown
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why ā repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" ā or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself ā your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |