| name | salesforce-erd-and-diagramming |
| description | 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). |
| category | architect |
| salesforce-version | Spring '25+ |
| well-architected-pillars | ["Operational Excellence","Reliability"] |
| tags | ["erd","diagramming","mermaid","plantuml","architecture-diagrams","data-model","documentation"] |
| triggers | ["generate an erd for salesforce sales cloud","diagram the oauth flow for experience cloud","mermaid erd for service cloud objects","how do i document my salesforce data model","plantuml diagram of integration architecture","object relationship diagram as code"] |
| inputs | ["Scope (which cloud, which objects, which integrations)","Target diagram format (Mermaid, PlantUML, draw.io, Lucid)","Audience (architect peers, execs, developers, auditors)","Level of detail (logical vs physical, with fields vs object-only)"] |
| outputs | ["ERD in chosen format (Mermaid / PlantUML source)","Integration architecture diagram (OAuth, data flow, callouts)","Diagram stored in repo alongside code, regeneratable","README pointer to the diagram source"] |
| dependencies | [] |
| version | 1.0.0 |
| author | Pranav Nagrecha |
| updated | 2026-04-21T00:00:00.000Z |
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 with actors: User, Browser, Salesforce, External App, Token Endpoint. Use for Experience Cloud SSO, Salesforce-to-X connected apps, JWT bearer flows.
