aibot88 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 describeor 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
- Identify the diagram type and audience; pick logical vs physical, executive vs developer.
- Generate the base shape from metadata if possible (
sf org describe, schema introspection). - Write diagram source in Mermaid or PlantUML; store in
docs/diagrams/alongside metadata. - Render locally with the relevant CLI; iterate on layout.
- Commit with the metadata PR that introduced any schema changes.
- Add a README pointer so future reviewers find the diagram.
- 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
- Polymorphic relationships break simple ERD syntax.
WhatIdon Task points to many objects; show as a composite edge with a note, not a single arrow. - Implicit junction objects are easy to miss.
AccountContactRelation,OpportunityContactRoledon't appear in Object Manager's top view but belong in the diagram. - 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 usageintegration/integration-pattern-selection— integration diagram subjectdevops/metadata-api-fundamentals— diagram source material