SfSkills Domains Docs GitHub

Home / architect / salesforce-erd-and-diagramming

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.

Open the skill folder on GitHub

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

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

SituationRecommended ApproachReason
ERD for a single cloudMermaid ER from metadataRenders in GitHub, regenerates
Integration architecturePlantUML deployment or C4Richer syntax for systems
Executive viewLucid / draw.io with simplified labelsEditable by non-engineers
OAuth flowMermaid sequenceDiagramUniversal, renders anywhere
Ad hoc whiteboardExcalidraw or draw.ioQuick, not versioned
  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

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

ArtifactDescription
Mermaid ERD sourceVersioned, regeneratable ER diagram
OAuth sequence diagramFor SSO and connected app patterns
Integration topologySystems, credentials, protocols
Diagram generation scriptMetadata → diagram source automation

Package files