@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-mermaid-diagrams/references/diagram-conventions.md

@@ -0,0 +1,313 @@
+<!-- Parent: generating-mermaid-diagrams/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
+
+```
+%%{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
+
+```
+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
+
+```
+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
+
+```
+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
+
+```
+┌──────────┐     ┌───────────────┐     ┌────────────────┐
+│  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

package/skills/generating-mermaid-diagrams/references/erd-conventions.md

@@ -0,0 +1,320 @@
+<!-- Parent: generating-mermaid-diagrams/SKILL.md -->
+# ERD Conventions for sf-diagram
+
+Standardized conventions for Salesforce data model diagrams with object type indicators, LDV markers, OWD annotations, and relationship type labels.
+
+## Object Type Indicators
+
+| Indicator | Object Type | Color (Flowchart) | Fill | Stroke | API Suffix |
+|-----------|-------------|-------------------|------|--------|------------|
+| `[STD]` | Standard Object | Sky Blue | `#bae6fd` | `#0369a1` | None |
+| `[CUST]` | Custom Object | Orange | `#fed7aa` | `#c2410c` | `__c` |
+| `[EXT]` | External Object | Green | `#a7f3d0` | `#047857` | `__x` |
+
+### Examples
+
+```
+Account [STD]         → Standard Salesforce object
+Invoice__c [CUST]     → Custom object
+SAP_Product__x [EXT]  → External object via Salesforce Connect
+```
+
+---
+
+## LDV (Large Data Volume) Indicator
+
+Objects with **>2M records** should display an LDV indicator to highlight potential performance considerations.
+
+| Record Count | Display Format | Example |
+|--------------|----------------|---------|
+| < 2,000,000 | (none) | Account |
+| 2M - 10M | `LDV[~XM]` | `LDV[~4M]` |
+| 10M - 100M | `LDV[~XXM]` | `LDV[~15M]` |
+| > 100M | `LDV[~XXXM]` | `LDV[~250M]` |
+
+### Query Record Count
+
+```bash
+sf data query --query "SELECT COUNT() FROM Account" --target-org myorg --json
+```
+
+### In Diagram
+
+**erDiagram format** (in entity description):
+```mermaid
+Account {
+    Id Id PK "[STD] LDV[~4M]"
+    Text Name "Required"
+}
+```
+
+**Flowchart format** (in node label):
+```mermaid
+Account["Account<br/>LDV[~4M]"]
+```
+
+---
+
+## OWD (Org-Wide Default) Display
+
+Display sharing model on entities to show default record access levels.
+
+| OWD Setting | Display | Meaning |
+|-------------|---------|---------|
+| Private | `OWD:Private` | Owner + role hierarchy only |
+| PublicRead | `OWD:Read` | All users can view |
+| PublicReadWrite | `OWD:ReadWrite` | All users can view and edit |
+| PublicReadWriteTransfer | `OWD:Full` | All users have full access |
+| ControlledByParent | `OWD:Parent` | Inherits from master object |
+| FullAccess | `OWD:Full` | Full access to all |
+
+### Query OWD
+
+```bash
+sf sobject describe --sobject Account --target-org myorg --json | jq '.result.sharingModel'
+```
+
+### Common OWD Patterns
+
+| Object | Typical OWD | Notes |
+|--------|-------------|-------|
+| Account | Private | Most orgs restrict account access |
+| Contact | ControlledByParent | Usually follows Account OWD |
+| Opportunity | Private | Sales data is sensitive |
+| Case | Private or Public Read | Depends on support model |
+| Lead | Public Read/Write | Often shared across sales |
+
+---
+
+## Relationship Type Labels
+
+Distinguish between Lookup and Master-Detail relationships for understanding data dependencies.
+
+| Label | Relationship | Cascade Delete | Roll-Up | Required Parent |
+|-------|--------------|----------------|---------|-----------------|
+| `LK` | Lookup | No | No | No |
+| `MD` | Master-Detail | Yes | Yes | Yes |
+
+### In erDiagram Syntax
+
+```mermaid
+erDiagram
+    Account ||--o{ Contact : "LK - has many"
+    Account ||--o{ Invoice__c : "MD - owns"
+```
+
+### In Flowchart Syntax
+
+| Type | Arrow | Visual |
+|------|-------|--------|
+| Lookup | `-->` | Single arrow |
+| Master-Detail | `==>` | Thick double arrow |
+
+```mermaid
+flowchart TB
+    Account -->|"LK"| Contact
+    Account ==>|"MD"| Invoice
+```
+
+---
+
+## Cardinality Notation (Crow's Foot)
+
+Standard ERD cardinality symbols:
+
+| Symbol | Meaning | Description |
+|--------|---------|-------------|
+| `\|\|` | Exactly one | One and only one |
+| `\|o` | Zero or one | Optional, at most one |
+| `o{` | Zero or many | Optional, any number |
+| `\|{` | One or many | Required, at least one |
+
+### Common Salesforce Patterns
+
+```mermaid
+erDiagram
+    %% One Account has many Contacts (optional)
+    Account ||--o{ Contact : "has many"
+
+    %% One Opportunity has many Line Items (optional)
+    Opportunity ||--o{ OpportunityLineItem : "contains"
+
+    %% Contact required for OpportunityContactRole
+    Contact ||--|{ OpportunityContactRole : "plays role"
+
+    %% Self-referential (Account hierarchy)
+    Account ||--o{ Account : "parent of"
+```
+
+---
+
+## Entity Metadata Row Pattern
+
+Add a special metadata row in erDiagram entities to consolidate annotations:
+
+```mermaid
+erDiagram
+    Account {
+        Id Id PK "[STD]"
+        Text Name "Required"
+        Lookup ParentId FK "Account (Self)"
+        Text __metadata__ "LDV[~4M] | OWD:Private"
+    }
+```
+
+**Note**: The `__metadata__` row is a convention for displaying object-level info within the erDiagram entity block.
+
+---
+
+## Color Palette for ERD
+
+### Entity Colors (for Flowchart ERD)
+
+| Object Type | Fill | Stroke | Text |
+|-------------|------|--------|------|
+| Standard | `#bae6fd` | `#0369a1` | `#1f2937` |
+| Custom | `#fed7aa` | `#c2410c` | `#1f2937` |
+| External | `#a7f3d0` | `#047857` | `#1f2937` |
+
+### Subgraph Colors (for Grouping)
+
+| Category | Fill | Stroke | Style |
+|----------|------|--------|-------|
+| Standard Group | `#f0f9ff` | `#0369a1` | dashed |
+| Custom Group | `#fff7ed` | `#c2410c` | dashed |
+| External Group | `#ecfdf5` | `#047857` | dashed |
+| Legend | `#f8fafc` | `#334155` | dashed |
+
+### Style Declarations
+
+```mermaid
+%% Standard Object - Sky Blue
+style Account fill:#bae6fd,stroke:#0369a1,color:#1f2937
+
+%% Custom Object - Orange
+style Invoice fill:#fed7aa,stroke:#c2410c,color:#1f2937
+
+%% External Object - Green
+style SAP_Product fill:#a7f3d0,stroke:#047857,color:#1f2937
+
+%% Subgraph - Standard group
+style std fill:#f0f9ff,stroke:#0369a1,stroke-dasharray:5
+```
+
+---
+
+## Query Commands Reference
+
+### Batch Query Script
+
+Use the provided Python script for efficient metadata queries:
+
+```bash
+python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+    --objects Account,Contact,Lead,Opportunity,Case \
+    --target-org myorg \
+    --output table
+```
+
+### Manual Queries
+
+**Record Count (LDV)**:
+```bash
+sf data query --query "SELECT COUNT() FROM Account" --target-org myorg --json
+```
+
+**OWD Setting**:
+```bash
+sf sobject describe --sobject Account --target-org myorg --json | jq '.result.sharingModel'
+```
+
+**Object Type Check**:
+```bash
+sf sobject describe --sobject Invoice__c --target-org myorg --json | jq '.result.custom'
+```
+
+---
+
+## Complete Example
+
+### Flowchart ERD with All Conventions
+
+```mermaid
+%%{init: {"flowchart": {"nodeSpacing": 60, "rankSpacing": 50}} }%%
+flowchart TB
+    subgraph legend["LEGEND"]
+        direction LR
+        L_STD["Standard [STD]"]
+        L_CUST["Custom [CUST]"]
+        L_EXT["External [EXT]"]
+        L_LK["─── LK (Lookup)"]
+        L_MD["═══ MD (Master-Detail)"]
+
+        style L_STD fill:#bae6fd,stroke:#0369a1,color:#1f2937
+        style L_CUST fill:#fed7aa,stroke:#c2410c,color:#1f2937
+        style L_EXT fill:#a7f3d0,stroke:#047857,color:#1f2937
+        style L_LK fill:#f8fafc,stroke:#334155,color:#1f2937
+        style L_MD fill:#f8fafc,stroke:#334155,color:#1f2937
+    end
+
+    subgraph std["STANDARD OBJECTS"]
+        Account["Account<br/>LDV[~4M] | OWD:Private"]
+        Contact["Contact<br/>OWD:Parent"]
+        Opportunity["Opportunity<br/>LDV[~2M] | OWD:Private"]
+    end
+
+    subgraph cust["CUSTOM OBJECTS"]
+        Invoice["Invoice__c<br/>OWD:Private"]
+        InvoiceLine["Invoice_Line__c"]
+    end
+
+    subgraph ext["EXTERNAL OBJECTS"]
+        SAP["SAP_Product__x"]
+    end
+
+    %% Relationships
+    Account -->|"LK"| Contact
+    Account -->|"LK"| Opportunity
+    Account ==>|"MD"| Invoice
+    Invoice ==>|"MD"| InvoiceLine
+    InvoiceLine -->|"LK"| SAP
+
+    %% Standard Objects - Sky Blue
+    style Account fill:#bae6fd,stroke:#0369a1,color:#1f2937
+    style Contact fill:#bae6fd,stroke:#0369a1,color:#1f2937
+    style Opportunity fill:#bae6fd,stroke:#0369a1,color:#1f2937
+
+    %% Custom Objects - Orange
+    style Invoice fill:#fed7aa,stroke:#c2410c,color:#1f2937
+    style InvoiceLine fill:#fed7aa,stroke:#c2410c,color:#1f2937
+
+    %% External Objects - Green
+    style SAP fill:#a7f3d0,stroke:#047857,color:#1f2937
+
+    %% Subgraph styling
+    style legend fill:#f8fafc,stroke:#334155,stroke-dasharray:5
+    style std fill:#f0f9ff,stroke:#0369a1,stroke-dasharray:5
+    style cust fill:#fff7ed,stroke:#c2410c,stroke-dasharray:5
+    style ext fill:#ecfdf5,stroke:#047857,stroke-dasharray:5
+```
+
+---
+
+## Best Practices
+
+1. **Always include a legend** in flowchart diagrams for color/arrow meaning
+2. **Query live org data** for accurate LDV and OWD values
+3. **Use consistent naming** - API names, not labels
+4. **Group related objects** using subgraphs
+5. **Limit fields shown** to key relationships (5-10 per entity max)
+6. **Show relationship direction** - parent on left, child on right
+7. **Mark required relationships** with appropriate cardinality
+
+---
+
+## References
+
+- [Salesforce Data Model Notation](https://developer.salesforce.com/docs/platform/data-models/guide/salesforce-data-model-notation.html)
+- [Mermaid ERD Syntax](https://mermaid.js.org/syntax/entityRelationshipDiagram.html)
+- [Mermaid Flowchart Syntax](https://mermaid.js.org/syntax/flowchart.html)
+- [sf-diagram Color Palette](color-palette.md)