# 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 writing the field inventory or data dictionary — use admin/data-model-documentation. NOT for deciding lookup vs master-detail or the model itself — use data/data-model-design-patterns.

- Skill: `pranavnagrecha/salesforce-erd-and-diagramming` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds add pranavnagrecha/salesforce-erd-and-diagramming`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pranavnagrecha/salesforce-erd-and-diagramming/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: PranavNagrecha (https://skillmd.com/u/pranavnagrecha)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/pranavnagrecha/salesforce-erd-and-diagramming

---


# 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 material