Part 98: The Basics of Diagramming in Salesforce Architecture
Welcome back to the Salesforce series. In the previous post we introduced Topic 4: The Complete Guide to Salesforce Architecture, and talked about what it means to think like an architect. In this post, we are going to get practical and talk about the single most important communication skill an architect can develop — diagramming.
If you have ever sat in a meeting where someone tried to explain a multi-system integration using only words, you know the problem. People nod politely, but half the room is picturing something completely different. Diagrams fix that. They turn abstract concepts into shared understanding. They expose gaps in your thinking before those gaps become production incidents. And when you are presenting a solution to stakeholders who do not care about Apex triggers or governor limits, a clean diagram is worth more than a hundred pages of documentation.
This post covers the types of diagrams you will use most often as a Salesforce architect, the tools I recommend for creating them, and a hands-on project to tie it all together. Let us get started.
What Is Diagramming and Why Do We Do It?
Diagramming is the practice of creating visual representations of systems, processes, data models, and interactions. In the context of Salesforce architecture, it means drawing out how your org is structured, how data flows between objects, how users interact with the system, and how Salesforce connects to external platforms.
We diagram for several reasons:
- Clarity of thought. The act of drawing forces you to confront ambiguity. If you cannot diagram a process, you do not fully understand it yet.
- Communication. Different stakeholders need different views of the same system. A C-suite executive needs a high-level overview. A developer needs technical detail. Diagrams let you tailor the message without rewriting documentation.
- Documentation. Teams change. People leave. New developers and admins join. Diagrams provide a visual map that is far easier to parse than paragraphs of text when someone needs to understand a system quickly.
- Validation. When you present a diagram to a client or a development team, they can immediately spot errors, missing pieces, or misunderstandings. It is much cheaper to fix a diagram than to fix code in production.
- Planning. Before any build begins, diagrams serve as blueprints. They help you estimate effort, identify dependencies, and sequence work correctly.
As a Salesforce architect, you will create diagrams during discovery, during solution design, during build reviews, and during handoffs. They are not a one-time artifact — they evolve with the project.
My Suggested Diagramming Tools
There are plenty of diagramming tools available, but three stand out for Salesforce architecture work.
Lucidchart
Lucidchart is a web-based diagramming application that is widely used in the Salesforce ecosystem. It has built-in Salesforce-specific shape libraries, supports real-time collaboration, and integrates with Google Workspace and Microsoft Office. If your team already uses Lucidchart, it is a natural fit. The paid plans unlock features like shared team libraries and advanced export options, but the free tier is sufficient for personal use.
draw.io (diagrams.net)
draw.io is completely free and open source. It runs in the browser, integrates with Google Drive and GitHub, and supports a huge range of shape libraries. It does not have the polish of Lucidchart, but it has zero cost and no usage limits. For individuals, freelancers, and teams that do not want to manage another subscription, draw.io is an excellent choice. I personally recommend draw.io to anyone getting started because there is no barrier to entry.
Miro
Miro is more of a digital whiteboard than a traditional diagramming tool, but it excels at collaborative brainstorming sessions and early-stage architecture discussions. If you are running a workshop with a client and want to sketch out ideas together in real time, Miro is hard to beat. It is less precise than Lucidchart or draw.io for final documentation, but it is perfect for discovery.
My recommendation: Use draw.io for most of your architecture diagrams. Switch to Miro when you need a collaborative whiteboard. Use Lucidchart if your organization already has licenses and you want the Salesforce-specific shape libraries.
The System Architecture Diagram
The system architecture diagram is the most important diagram an architect creates. It provides a bird’s-eye view of the entire solution — which systems exist, how they connect, what data flows between them, and what technologies or protocols are used for integration.
When to Use It
Every Salesforce project should have a system architecture diagram. It is the first thing you create during solution design and the first thing you show to stakeholders. It answers the question: “What does the big picture look like?”
What to Include
- All systems involved. Salesforce orgs (production, sandboxes), external systems (ERP, marketing platforms, data warehouses), third-party tools (middleware, iPaaS), and user-facing applications.
- Integration paths. Show how systems communicate. Label each connection with the protocol (REST API, SOAP, Platform Events, MuleSoft, etc.) and the direction of data flow.
- Data flow direction. Use arrows to indicate whether data flows one way or bidirectionally.
- Users and access channels. Show how different user groups access the system — browser, mobile app, Experience Cloud portal, external website.
- Key services. If Salesforce is using specific clouds or features (Sales Cloud, Service Cloud, Marketing Cloud, Data Cloud), call them out.
Text-Based Example
[Sales Team] [Support Team] [Partners]
| | |
v v v
Salesforce Salesforce Experience
Sales Cloud Service Cloud Cloud Portal
| | |
+----------+-----------+--------------------+
|
[Salesforce Core Platform]
/ | \
REST API Platform Events SOAP API
/ | \
[ERP System] [Data Warehouse] [Marketing Cloud]
(SAP/Oracle) (Snowflake) (Email Campaigns)This simple layout tells anyone at a glance which systems are in play and how they connect. You would refine this in your actual diagramming tool with proper shapes, colors, and labels.
The Entity Relationship Diagram (ERD)
An Entity Relationship Diagram shows the data model — the objects in your Salesforce org and the relationships between them. It is the data architect’s best friend.
When to Use It
Use an ERD whenever you are designing a custom data model, reviewing an existing org’s structure, or explaining to a team how objects relate to each other. If a project involves more than three or four custom objects, you need an ERD.
What to Include
- Objects (entities). Both standard and custom objects.
- Fields (attributes). Focus on key fields — Name, record types, lookup/master-detail fields, and any fields critical to business logic.
- Relationships. Lookup, master-detail, and junction objects. Label the cardinality (one-to-many, many-to-many).
- Cardinality notation. Use crow’s foot notation or simple labels like 1:N and M:N.
Text-Based Example
+----------------+ 1:N +------------------+
| Account |<--------------->| Contact |
|----------------| |------------------|
| Name | | FirstName |
| Industry | | LastName |
| Annual Revenue | | Email |
+----------------+ | AccountId (FK) |
| +------------------+
| 1:N
v
+----------------+ M:N +------------------+
| Opportunity |<----+--------->| Product2 |
|----------------| | |------------------|
| Name | | | Name |
| StageName | | | ProductCode |
| Amount | | | IsActive |
| CloseDate | | +------------------+
| AccountId (FK) | |
+----------------+ |
|
+------------------+
| OpportunityLine |
| Item (Junction) |
|------------------|
| OpportunityId |
| Product2Id |
| Quantity |
| UnitPrice |
+------------------+Notice the junction object (OpportunityLineItem) that resolves the many-to-many relationship between Opportunity and Product. This is a pattern you will see frequently in Salesforce data models.
Sequence Diagrams
A sequence diagram shows how different components interact with each other over time. It focuses on the order of operations — who sends what message to whom, and in what sequence.
When to Use It
Sequence diagrams are essential when designing integrations, complex automation flows, or any scenario where timing and order matter. If a business process involves multiple systems or multiple Salesforce components firing in sequence (trigger, flow, callout, platform event), a sequence diagram makes the order explicit.
What to Include
- Actors and systems represented as vertical lifelines.
- Messages shown as horizontal arrows between lifelines, labeled with the action or API call.
- Return messages shown as dashed arrows.
- Activation bars to show when a component is actively processing.
Text-Based Example
User Salesforce Apex Trigger External ERP
| | | |
|--Create Opp----->| | |
| |--After Insert->| |
| | |--REST Callout-->|
| | |<--200 OK--------|
| | |--Update Opp---->|
| |<--Save---------| |
|<--Confirmation---| | |This diagram tells the story: a user creates an Opportunity, which fires an after-insert trigger, which makes a REST callout to an ERP system, receives a response, updates the Opportunity with ERP data, and the user sees a confirmation. Anyone reading this knows exactly what happens and in what order.
Activity Diagrams
Activity diagrams model the flow of a business process from start to finish. Think of them as enhanced flowcharts with support for parallel processing, decision points, and swim lanes.
When to Use It
Use activity diagrams when documenting business processes, designing approval workflows, or mapping out automation logic. They are particularly useful during discovery when you are capturing how a client’s team currently works before you design the Salesforce solution.
What to Include
- Start and end nodes. A filled circle for start, a circle with a border for end.
- Actions. Rounded rectangles representing steps in the process.
- Decision points. Diamond shapes where the flow branches based on a condition.
- Parallel bars. Horizontal bars indicating where activities happen simultaneously.
- Swim lanes. Vertical or horizontal lanes grouping actions by the actor or system responsible.
Text-Based Example
[Start]
|
v
(Sales Rep Creates Lead)
|
v
<Lead Score > 80?>----No--->(Assign to Nurture Queue)
| |
Yes v
| [Wait 30 Days]
v |
(Assign to Account Executive) v
| <Re-score Lead>----> [Loop back]
v
(Convert Lead to Opportunity)
|
v
[End]Activity diagrams are great for getting sign-off from business stakeholders because they map directly to how people think about their work.
Use Case Diagrams
Use case diagrams show what a system does from the perspective of its users. They identify the actors (people or systems that interact with Salesforce) and the use cases (the things those actors can do).
When to Use It
Use case diagrams are valuable during requirements gathering. They help you define scope — what the system will and will not do — and they make it easy to identify missing requirements by showing which actors have access to which features.
What to Include
- Actors. Stick figures or labeled boxes representing users or external systems.
- Use cases. Ovals representing actions or features.
- System boundary. A rectangle enclosing the use cases that belong to the system.
- Relationships. Lines connecting actors to their use cases.
Text-Based Example
+--------- Salesforce CRM ----------+
| |
| (Create Opportunity) |
| (Generate Quote) |
| (Submit for Approval) |
| (View Dashboard) |
| (Manage Cases) |
| (Run Reports) |
+------------------------------------+
Sales Rep ---- Create Opportunity
Sales Rep ---- Generate Quote
Sales Rep ---- Submit for Approval
Sales Manager - View Dashboard
Sales Manager - Run Reports
Support Agent -- Manage CasesThis quickly communicates who does what within the system.
Class Diagrams
Class diagrams show the structure of your Apex code — the classes, their attributes (variables), their methods, and the relationships between classes (inheritance, interfaces, composition).
When to Use It
Use class diagrams when designing complex Apex solutions, especially when the project involves multiple interrelated classes, service layers, or design patterns. They are also useful when onboarding new developers to an existing codebase.
What to Include
- Classes with their name, key fields, and methods.
- Visibility modifiers (public, private, global).
- Relationships such as inheritance (extends), interface implementation (implements), and associations.
Text-Based Example
+-----------------------------+
| <<interface>> |
| IDiscountStrategy |
|-----------------------------|
| + calculateDiscount( |
| Opportunity): Decimal |
+-----------------------------+
^ ^
| |
+----------------+ +--------------------+
| VolumeDiscount | | LoyaltyDiscount |
|----------------| |--------------------|
| - threshold | | - yearsAsCustomer |
| - percentage | | - tierMultiplier |
|----------------| |--------------------|
| + calculate | | + calculate |
| Discount() | | Discount() |
+----------------+ +--------------------+This shows a strategy pattern: an interface with two concrete implementations. A developer reading this immediately understands the architecture of the discount calculation feature.
Environment Diagrams
Environment diagrams show the Salesforce environments (orgs) in your release pipeline — how code and configuration move from development through testing to production.
When to Use It
Every Salesforce project with more than one sandbox should have an environment diagram. It is critical for release management and helps the entire team understand the deployment pipeline.
What to Include
- All environments. Production, full sandboxes, partial sandboxes, developer sandboxes, scratch orgs.
- Flow of deployments. Arrows showing the direction of deployments and data refreshes.
- Purpose of each environment. Label each org with its role (development, QA, UAT, staging, production).
- Tools used for deployment. Change sets, Salesforce CLI, CI/CD pipelines (GitHub Actions, Jenkins, Copado).
Text-Based Example
[Dev Sandbox 1]---+
| Deploy via CLI
[Dev Sandbox 2]---+---------> [QA Sandbox] -----> [UAT Full Sandbox]
| |
[Dev Sandbox 3]---+ |
Deploy via CI/CD
|
v
[Production]
|
Refresh (monthly)
|
v
[UAT Full Sandbox]Actors and Licenses Diagram
This diagram maps out the different types of users who access the Salesforce org, what license each user type holds, and what they can do.
When to Use It
During solution design and cost estimation. Salesforce licenses are expensive, and choosing the wrong license type can blow a budget. This diagram helps you match user groups to the most cost-effective license.
What to Include
- User groups/personas. Internal sales reps, support agents, partners, community users, integration users.
- License types. Salesforce License, Platform License, Experience Cloud License, API-only License.
- Access level. What each group can access — objects, apps, features.
- User counts. Estimated number of users per group, which feeds directly into licensing cost calculations.
Text-Based Example
Actor | License Type | Count | Access
--------------------|-------------------------|-------|---------------------------
Sales Reps | Salesforce License | 50 | Sales Cloud, Reports
Support Agents | Service Cloud License | 20 | Cases, Knowledge, Omni
Partners | Partner Community | 200 | Leads, Opportunities (limited)
Customers | Customer Community | 5000 | Cases, Knowledge (read)
Integration User | Salesforce Integration | 2 | API-only, no UI access
Marketing Team | Marketing Cloud License | 5 | Campaigns, JourneysRole Hierarchy Diagram
The role hierarchy diagram visualizes how data visibility cascades through your organization in Salesforce. Roles determine who can see whose records when the org-wide default is set to Private.
When to Use It
Whenever you are designing or documenting a Salesforce security model. If the client has more than one level of management or multiple business units, you need a role hierarchy diagram.
What to Include
- Roles arranged in a tree structure from top to bottom.
- Record access implications. Users in higher roles can see records owned by users in lower roles (roll-up visibility).
- Business unit groupings if the org serves multiple divisions.
Text-Based Example
[CEO]
/ \
[VP Sales] [VP Support]
/ \ |
[Regional Mgr [Regional Mgr [Support Mgr]
East] West] |
/ \ / \ [Support Agent]
[Sales [Sales [Sales [Sales
Rep 1] Rep 2] Rep 3] Rep 4]Each level can see the records of the levels below it. Sales Rep 1’s records are visible to Regional Manager East, VP Sales, and the CEO, but not to VP Support or the Support team.
Section Notes
A few practical tips for diagramming in the real world:
- Keep it simple. A diagram that tries to show everything ends up showing nothing. Create multiple diagrams at different levels of detail rather than one massive diagram that overwhelms the viewer.
- Use color intentionally. Color can group related elements, highlight problem areas, or distinguish Salesforce components from external systems. But do not use color as the only way to convey meaning — think about viewers who are colorblind or who print in grayscale.
- Version your diagrams. Treat diagrams like code. Store them in version control (draw.io files work great in Git repositories). Date them. Update them when the architecture changes.
- Label everything. Every arrow should have a label. Every box should have a name. If someone cannot understand the diagram without you standing next to it explaining, it needs more labels.
- Audience matters. A diagram for a technical review meeting is different from a diagram for an executive sponsor. Adjust the level of detail to match your audience.
- Establish a legend. If you use shapes, colors, or line styles to represent different things, include a legend on the diagram so viewers do not have to guess.
- Review with the team. Diagrams are communication tools. If you create them in isolation and never review them with others, you are missing half the value. Walk your team through the diagram. Invite feedback. Iterate.
PROJECT: Create a System Diagram Based on a Client’s Needs
Now it is time to put everything together. Below is a realistic client scenario. Your task is to read the requirements and create a system architecture diagram using the tool of your choice (I recommend draw.io).
The Scenario
Client: GreenLeaf Solar, a mid-sized solar panel installation company.
Current State:
- GreenLeaf’s sales team currently tracks leads and deals in spreadsheets.
- Their field technicians use a separate mobile app (FieldTrack) to manage installation schedules and job completions.
- Accounting runs on QuickBooks Online.
- Marketing sends email campaigns through Mailchimp.
- Customer support is handled through a shared Gmail inbox.
Desired State:
- GreenLeaf wants Salesforce as their central CRM.
- Sales Cloud for lead management, opportunity tracking, and quoting (CPQ).
- Service Cloud for customer support cases, with a self-service portal for customers to track installation progress.
- Integration with FieldTrack so that when a technician marks a job as complete, the Salesforce record updates automatically.
- Integration with QuickBooks Online for invoice syncing — when an Opportunity is marked Closed Won, an invoice should be generated in QuickBooks.
- Marketing Cloud Connect to sync leads and contacts with Mailchimp (eventually migrating to Marketing Cloud, but not in phase one).
- Nightly batch sync of all customer and financial data to a Snowflake data warehouse for executive reporting.
- Partners (independent solar installers) need portal access to submit leads and view their pipeline.
Your Task
Create a system architecture diagram that includes:
- All systems — Salesforce (Sales Cloud, Service Cloud, Experience Cloud), FieldTrack, QuickBooks Online, Mailchimp, Snowflake, and the customer self-service portal.
- All user groups — Sales reps, support agents, field technicians, partners, customers, and executives.
- Integration paths — Label each connection with the integration method (REST API, middleware, Platform Events, batch sync, etc.) and the direction of data flow.
- Key data flows — Lead capture, opportunity-to-invoice, job completion updates, marketing sync, and data warehouse loads.
Hints
- Think about which system is the system of record for each data type.
- Consider whether integrations are real-time or batch.
- FieldTrack is a third-party system with a REST API. QuickBooks Online has a well-documented REST API. Mailchimp has a REST API.
- For the Snowflake sync, consider whether you would use a middleware tool (like MuleSoft) or a direct connection.
- Partners accessing the portal means Experience Cloud with Partner Community licenses.
- Customers accessing the self-service portal means Experience Cloud with Customer Community licenses.
Once your diagram is complete, review it against the requirements and ask yourself: does every requirement map to something visible on the diagram? If not, you are missing something.
That wraps up the fundamentals of diagramming for Salesforce architecture. These diagram types form the visual vocabulary you will use throughout your career as an architect. In the next post, we will continue building on this foundation and explore how to translate business requirements into architectural decisions. See you there.