Revealing Architecture Diagrams at TrailheaDX 2021
Introducing Salesforce Diagrams
Salesforce unveiled its architecture diagram framework in “Introduction to Salesforce Diagrams” at the TrailheaDX 2021 developer conference.
Salesforce diagrams show how Salesforce solutions fit an organization's strategy and system landscape at the highest level. They drill down through several levels to technical details such as process flows and data models.
Salesforce Certified Technical Architect Carl Brundage outlines the need for diagrams to:
Provide a high-level solution overview, including external systems
“Quickly and clearly articulate a point of view” of solution design
“Derive a shared understanding” of the solution
Diagrams enable stakeholders to find and fix design flaws before development starts, costing far less money and heartache than reworking a finished solution.
Diagram Chaos
Marc Braga, Salesforce’s Principal Architect Evangelist, writes in Introducing Salesforce Diagrams that solution architects create diagrams “to align stakeholders on their vision and help delivery teams understand the details of an implementation.” He notes that solution architects abandoned diagramming languages like the Unified Modeling Language (UML) in favor of agility (or perhaps expediency).
Marc goes on to say:
A quick search for “salesforce architecture diagrams” produces hundreds of ad-hoc, outdated diagrams, and static images requiring architects to start from scratch every time. Without a framework to approach the creation and communication of Salesforce diagrams, they often become overly complex and packed with details that overwhelm the viewer.
The salesforce architect team took a deep dive into the diagram chaos. They collected feedback from architects and others summarized here:
Architectures had inconsistent levels of detail & appearance
There are no Salesforce-provided symbols, icons, or templates for the common diagrams architects create
The landscape is fractured and siloed
There was no single destination for reliable, up-to-date resources
Bringing Order with Style
The salesforce architects team started by creating a diagram framework. As Marc Braga writes in Introducing Salesforce Diagrams:
We built our approach from the feedback we heard from practitioners across the Salesforce ecosystem, as well as our internal stakeholders. We saw that diagrams are used for a wide variety of conversations with a wide variety of motivations. We adopted the idea of diagram styles because we decided it was important to start by being clear and prescriptive about the purpose of diagrams. We also saw that the purpose was often lost on the viewer because folks tended to overload diagrams with very different kinds of details. We adopted the concept of levels based on the C4 model as an “abstraction-first” approach to make this all easy to learn and use.
The diagram framework introduced at TrailheaDX organizes diagrams by style and level. The diagram styles are:
Marketing, Strategy & Sales for business stakeholders to
Show the vision for a solution
Understand solution concepts and high-level processes
Recognize solution benefits for buy-in
Documentation & Implementation for technical stakeholders to
Show detailed requirements
Document the solution
Align delivery teams
A diagram’s style reflects its purpose and audience.
The framework defines four levels to manage a diagram’s scope and level of detail:
Level 1: The Big Picture
Solution overview or system landscape
Level 2: Piece of the Whole
A subset of a solution overview or system landscape
Level 3: Process or Interaction View
Limited view of products or technologies in a solution
Focuses on showing more complex details
Level 4: The Double Click
The “most narrow view,” focusing on showing fine-grained details
As the levels increase, they show more detail within a tighter scope. Some diagrams, such as business process maps, require more than four levels. A diagram should have as many levels as necessary to remove ambiguity.
For more information about how business process maps fit into the Salesforce diagram framework, see Drawing Salesforce Diagrams using Elements.cloud.
The salesforce architects website contains the document How to Build Salesforce Diagrams, describing styles and levels in more detail. It includes informative tables showing the scope, audience, elements, and examples at each level within each style.
Templates, for Example
Once the salesforce architects team created the framework, they started populating it with content. The salesforce architects site has two documents containing sample diagrams:
Marketing, Strategy, and Sales Templates contains business diagram templates.
Documentation and Implementation Templates has technical diagram templates.
Both documents base their templates on an online retail commerce solution. The table below shows the templates organized by style and level:
| Level | Marketing, Strategy, and Sales Templates | Documentation and Implementation Templates |
|---|---|---|
| 1: The Big Picture | Retail marketecture | B2C solution system landscape |
| 2: Piece of the Whole | "Order on Behalf" solution piece | B2C solution integration layer (part of system landscape) |
| 3: Process or Interaction View | "Order on Behalf" process flow | A user provisioning and de-provisioning flow |
| 4: The Double Click | "Order on Behalf" via a chat-based channel process flow | Part of the B2C solution data model |
Levels 1 and 2 show the relationship between concepts or components suitable for business stakeholders. Levels 3 and 4 show process flows and technical details intended for technical stakeholders and delivery teams.
Design to the Rescue
The architects team engaged the Lightning Design Team to “reimagine Salesforce product data models and ERDs (entity-relationship diagrams).” The team applied the same core design principles to diagrams that work successfully with Lightning:
Clarity
Efficiency
Consistency
Beauty
The designers emphasized a diagram’s purpose: clearly communicating a solution’s vision, concepts, landscape, technologies, and lower-level details efficiently with visual consistency.
The design team delivered the Diagram Kit of Parts, introduced in the TrailheaDX session. The kit contains reusable graphic components for building and customizing diagrams. Architects can now create diagrams using templates as patterns with the kit to give their diagrams a professional look with well-designed components.
The “Introducing Salesforce Diagrams” session concluded with a roadmap to make diagramming easier for architects:
A library of shapes and icons for Lucidchart “coming soon”
Redesigned Salesforce data models using the new framework
New resources for the Reference Architecture Gallery, a collection of pre-built diagrams.
Blazing a Trail with Style
Kudos to the salesforce architects team for listening to their constituents, reaching out to the design team, and introducing a diagram framework:
Enabling architects to create consistent diagrams organized by style and level
Including sample templates showing how diagrams work
Providing a kit of professionally designed components
Having a single destination for diagram resources on the salesforce architects website
The salesforce architects team has blazed a trail for continuously improving architect diagrams with templates and components organized in a simple framework.