salesforce-erd-and-diagramming
Salesforce ERD and architecture diagram generation: Mermaid/PlantUML data-model diagrams for Sales, Service, FSL, Commerce, Revenue Cloud; OAuth flow diagrams; integration architecture diagrams; object-relationship visualization. NOT for data model design decisions (use data-model-design-patterns). NOT for UI wireframing (use lightning-experience-design).
Best use case
salesforce-erd-and-diagramming is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Salesforce ERD and architecture diagram generation: Mermaid/PlantUML data-model diagrams for Sales, Service, FSL, Commerce, Revenue Cloud; OAuth flow diagrams; integration architecture diagrams; object-relationship visualization. NOT for data model design decisions (use data-model-design-patterns). NOT for UI wireframing (use lightning-experience-design).
Teams using salesforce-erd-and-diagramming should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/salesforce-erd-and-diagramming/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How salesforce-erd-and-diagramming Compares
| Feature / Agent | salesforce-erd-and-diagramming | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Salesforce ERD and architecture diagram generation: Mermaid/PlantUML data-model diagrams for Sales, Service, FSL, Commerce, Revenue Cloud; OAuth flow diagrams; integration architecture diagrams; object-relationship visualization. NOT for data model design decisions (use data-model-design-patterns). NOT for UI wireframing (use lightning-experience-design).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Salesforce ERD and Diagramming
Activate when an architect needs to produce data-model or architecture diagrams for a Salesforce implementation: an ERD for a cloud's core objects, an integration flow, an OAuth sequence, or a Well-Architected review deliverable. The focus is on "diagram-as-code" approaches that live next to metadata and regenerate deterministically.
## Before Starting
- **Confirm the audience and level of detail.** A CIO-level architecture diagram elides fields; a developer-level ERD includes them. Diagrams in the wrong style waste the audience's time.
- **Choose diagram-as-code over drawing tools for anything version-controlled.** Mermaid and PlantUML render in PRs; Lucidchart and draw.io fit hand-maintained executive decks but rot out of sync with the org.
- **Identify the source of truth.** If the ERD can be generated from `sf org describe` or metadata XML, generate it; never hand-draw what automation can.
## Core Concepts
### Object graph is already in metadata
Every Salesforce object has a metadata file. Fields, lookups, and master-details are in the XML. A diagram is a projection of that graph. Tools like Schema Builder render the full graph in-org; external tools read metadata and emit Mermaid/PlantUML.
### Logical vs physical ERD
Logical ERD shows business entities and their meaningful relationships (Account, Contact, Opportunity). Physical ERD includes system objects (Task, Note, Attachment, ContentDocumentLink). Almost all stakeholder-facing ERDs are logical; physical is reserved for integration and data migration work.
### Standard object conventions in diagrams
Reusable shorthand: `ACC` for Account, `OPP` for Opportunity, `CON` for Contact, `CAS` for Case. Mark master-detail with a solid line + filled diamond on the parent; lookup with dashed + open diamond. This matches Salesforce Architect-published diagrams.
### Integration architecture diagrams
Diagram types: OAuth sequence, event flow, data flow, deployment topology. Each follows a distinct shape library. Mermaid's `sequenceDiagram`, PlantUML's `@startuml ... actor` blocks cover most needs.
## Common Patterns
### Pattern: Mermaid ERD from metadata
Script reads `objects/*/fields/*.field-meta.xml`, emits Mermaid ER syntax. Each lookup becomes `ACC ||--o{ OPP : has`. Committed to `docs/diagrams/erd-sales.md` with source. Regenerates on metadata change via CI.
### Pattern: OAuth flow sequence
Mermaid `sequenceDiagram` with actors: User, Browser, Salesforce, External App, Token Endpoint. Use for Experience Cloud SSO, Salesforce-to-X connected apps, JWT bearer flows.
### Pattern: Integration topology diagram
PlantUML deployment diagram shows systems, named credentials, protocols, payload formats. Reference for operations on-call.
## Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| ERD for a single cloud | Mermaid ER from metadata | Renders in GitHub, regenerates |
| Integration architecture | PlantUML deployment or C4 | Richer syntax for systems |
| Executive view | Lucid / draw.io with simplified labels | Editable by non-engineers |
| OAuth flow | Mermaid sequenceDiagram | Universal, renders anywhere |
| Ad hoc whiteboard | Excalidraw or draw.io | Quick, not versioned |
## Recommended Workflow
1. Identify the diagram type and audience; pick logical vs physical, executive vs developer.
2. Generate the base shape from metadata if possible (`sf org describe`, schema introspection).
3. Write diagram source in Mermaid or PlantUML; store in `docs/diagrams/` alongside metadata.
4. Render locally with the relevant CLI; iterate on layout.
5. Commit with the metadata PR that introduced any schema changes.
6. Add a README pointer so future reviewers find the diagram.
7. Add CI to regenerate diagrams on metadata change; fail the build if source drifts from diagram.
## Review Checklist
- [ ] Diagram matches current metadata (regenerate if in doubt)
- [ ] Logical vs physical choice matches audience
- [ ] Diagram source is version-controlled text
- [ ] Legend shows lookup vs master-detail convention
- [ ] Standard-object shorthand consistent with team style
- [ ] Sensitive detail (PII, field-level security) redacted where audience warrants
- [ ] Diagram file referenced from relevant README / ADR
## Salesforce-Specific Gotchas
1. **Polymorphic relationships break simple ERD syntax.** `WhatId` on Task points to many objects; show as a composite edge with a note, not a single arrow.
2. **Implicit junction objects are easy to miss.** `AccountContactRelation`, `OpportunityContactRole` don't appear in Object Manager's top view but belong in the diagram.
3. **Metadata-to-diagram scripts miss managed-package objects.** Either include the package XML in the source or annotate the diagram with "external: package-name".
## Output Artifacts
| Artifact | Description |
|---|---|
| Mermaid ERD source | Versioned, regeneratable ER diagram |
| OAuth sequence diagram | For SSO and connected app patterns |
| Integration topology | Systems, credentials, protocols |
| Diagram generation script | Metadata → diagram source automation |
## Related Skills
- `architect/well-architected-reviews` — review deliverable usage
- `integration/integration-pattern-selection` — integration diagram subject
- `devops/metadata-api-fundamentals` — diagram source materialRelated Skills
salesforce-shield-deployment
Roll out Shield (Platform Encryption + Event Monitoring + Field Audit Trail) end-to-end, sequencing feature enablement to avoid data lockout. NOT for Classic Encryption or general PE design.
ferpa-compliance-in-salesforce
Use this skill when implementing FERPA (Family Educational Rights and Privacy Act) compliance controls in Salesforce Education Cloud or Education Data Architecture (EDA): LearnerProfile FERPA boolean fields, directory information opt-out via FLS and Individual data privacy flags, ContactPointTypeConsent for parental and third-party disclosure, 45-day student records response window tracking, and consent workflow automation. Trigger keywords: FERPA, student records privacy, LearnerProfile, parental disclosure, directory information opt-out, education data privacy, student consent, education cloud compliance. NOT for GDPR/CCPA general data privacy (see gdpr-data-privacy skill), platform encryption at rest (see platform-encryption skill), or HIPAA health-data compliance.
industries-cpq-vs-salesforce-cpq
Use this skill when comparing Industries CPQ (formerly Vlocity CPQ) with Salesforce CPQ (Revenue Cloud managed package) — covering feature parity, decision criteria, migration paths, and coexistence patterns. Trigger keywords: Vlocity CPQ, Industries CPQ, Salesforce CPQ comparison, Revenue Cloud migration, CPQ selection, which CPQ to use. NOT for implementing, configuring, or debugging either CPQ product.
tableau-salesforce-connector
Tableau ↔ Salesforce integration patterns: Tableau Salesforce connector, Tableau for Salesforce, CRM Analytics alternative, Data Cloud + Tableau, embedded Tableau dashboards. Choose between connector modes (live, extract, direct-to-Data-Cloud). NOT for CRM Analytics Studio (use crm-analytics-foundation). NOT for generic Tableau Server setup.
slack-salesforce-integration-setup
Use this skill when setting up or troubleshooting the Salesforce for Slack managed app — including connecting a Salesforce org to a Slack workspace, configuring the three-party admin handshake, linking Slack channels to Salesforce records, enabling record preview sharing, and managing org-level limits. Triggers on: Salesforce for Slack app not connecting, Slack org connection setup, Salesforce record sharing in Slack, Slack workspace admin approval, connecting Salesforce to Slack. NOT for building custom Slack apps or Slack bots (separate development platform), not for Slack Workflow Builder Salesforce connector (use slack-workflow-builder skill), not for Flow-based Slack messaging (use flow-for-slack skill).
salesforce-to-salesforce-integration
Use this skill to implement Salesforce-to-Salesforce integration patterns — covering the native S2S feature, API-based cross-org sync, Platform Event bridging, and Salesforce Connect Cross-Org adapter. Trigger keywords: Salesforce to Salesforce integration, cross-org data sharing, S2S feature, cross-org Platform Events, Salesforce Connect cross-org. NOT for multi-org strategy or architecture decisions (use architect/multi-org-strategy), single-org data sharing, or external (non-Salesforce) system integration.
salesforce-maps-setup
Use when configuring Salesforce Maps (formerly MapAnything) — territory planning, route optimization, live tracking, geo-grid visualizations, and check-in/check-out workflows for Sales or Service field reps not on Field Service. Covers package installation order (Maps + Maps Advanced + Maps Routing/Live Tracking add-ons), the MapsTerritoryPlan / MapsAdvancedRoute / MapsLayer object family, base-data syncs (Geocoding and Routing services), and integration with Sales and Service Cloud records. Triggers: 'Salesforce Maps setup', 'MapAnything migration', 'territory planning by polygon', 'route optimization for sales reps', 'live tracking field reps', 'plot accounts on a map', 'check-in to the closest account'. NOT for Field Service Lightning territory and scheduling (use admin/fsl-scheduling-optimization-design and data/fsl-territory-data-setup) — Maps and FSL are different products. NOT for Consumer Goods Cloud retail visit planning (use admin/consumer-goods-cloud-setup) — RoutePlan/Visit objects are CG-specific. NOT for Tableau / CRM Analytics geo charts.
salesforce-functions-replacement
Salesforce Functions is retired (EOL Jan 2025). This skill maps Functions workloads to replacements: Heroku (with Hyperforce), external containers, Apex (where viable), Agentforce Actions, external compute via Named Credentials. NOT for Lambda / Azure Functions tutorials. NOT for Apex @future replacement (use async-selection tree).
salesforce-data-pipeline-etl
Export large Salesforce datasets to a lakehouse via Bulk API 2.0, CDC streams, or Salesforce Data Pipelines. NOT for ad-hoc exports.
salesforce-connect-external-objects
Use when deciding whether Salesforce Connect and External Objects are the right fit for external data access, or when reviewing OData, cross-org, and custom adapter patterns, query limitations, and latency tradeoffs. Triggers: 'Salesforce Connect', 'External Objects', '__x', 'OData adapter', 'custom adapter'. NOT for ordinary ETL or replicated-data designs where the data should live inside Salesforce.
outbound-webhook-from-salesforce
Use when Salesforce must POST a webhook to a third-party endpoint after a record change — with signed payloads, retries, dead-lettering, rate limits, and idempotency. Covers design choice between Outbound Message, Flow HTTP Callout, Apex Queueable callout, and Event Relay. Does NOT cover inbound webhooks into Salesforce (see inbound-webhook or apex-rest-webhook).
mulesoft-salesforce-connector
Designing and configuring MuleSoft Anypoint Salesforce Connector flows: API selection (SOAP/REST/Bulk/Streaming), OAuth 2.0 JWT Bearer auth, watermark-based incremental sync with Object Store, batch processing with record-level error isolation, and replay topic subscriptions. Use when building Mule 4 flows that read from or write to Salesforce, migrating from Mule 3 watermark to Mule 4 Object Store, or troubleshooting connector authentication and API limits. NOT for native Salesforce-to-Salesforce integration without MuleSoft (use platform-events-integration or change-data-capture-integration). NOT for generic REST callout patterns from Apex (use rest-api-patterns).