In one sentence: agree a fixed set of shapes before anybody draws anything, because most Salesforce diagrams fail review not from bad thinking but from every box looking the same. A workable kit is six shapes, three line types and two colours — small enough that people actually use it consistently, which is the only property that matters.
Why a kit, rather than good judgement per diagram
A reviewer reading a diagram spends their first minute working out the visual language. If the language changes between diagrams, or between halves of the same diagram, that minute becomes the whole review, and the questions are about the drawing rather than the design.
Consistency is worth more than expressiveness. A restricted kit used the same way every time is read faster than a rich one used loosely, even when the rich one is technically more precise.
The six shapes
| Shape | Means | Example |
|---|---|---|
| Rounded rectangle | A system that stores data | Salesforce, the ERP, the warehouse |
| Rectangle | A component inside a system | A service class, an integration job |
| Cylinder | A datastore, where it is the point | Data Cloud, an S3 bucket, a database |
| Stick figure or simple person | A human actor or persona | Sales rep, customer, support agent |
| Hexagon | A boundary you do not control | A third-party API, a partner system |
| Dashed container | A trust or network boundary | The org, a VPC, a region |
Six is chosen deliberately. People cannot reliably remember more, and a seventh shape nearly always turns out to be one of these six with a different label.
The three lines
- Solid arrow — a synchronous call. Direction is the direction of the request, not of the data.
- Dashed arrow — asynchronous or event-driven. The receiver may act later. The sender does not wait.
- Plain line, no arrowhead — a relationship without a call, such as a data model association.
The solid-versus-dashed distinction is the highest-value convention in the whole kit. A reviewer can see the synchronous coupling in a landscape at a glance, and synchronous coupling is where the operational risk lives.
Two colours, and what they are for
One neutral for everything you control. One accent for everything you do not — third parties, partner systems, anything outside your change control.
That is it. Colour is expensive: every additional colour needs a legend entry and a reader who remembers it. Using colour to encode a second dimension (environment, or team ownership) is where diagrams become unreadable in greyscale and unusable for anyone with a colour vision deficiency.
If you need another dimension, use a label, not a hue.
Labelling, which is where most diagrams lose
Label every arrow with what moves and how often. “Orders, nightly” beats an unlabelled line by an enormous margin. An unlabelled arrow between two boxes is an assertion that something happens, which nobody can review.
Name systems as people say them. If everyone calls it “the billing system”, label it that, with the formal product name in smaller text if it matters.
Put the protocol on the line only when it is a decision. REST versus a file drop is worth showing. The specific API version usually is not.
Include a legend, always, even when it seems obvious. It is obvious to you because you drew it.
Salesforce marks and the rule about them
Do not use Salesforce logo artwork, product badge graphics or the mascots in architecture diagrams you publish or hand to a client. Referring to Salesforce, Agentforce or Data Cloud by name in a labelled box is ordinary descriptive use and entirely fine. Reproducing the brand artwork is a different thing.
A plain labelled box is also better design. Logos vary in size and visual weight, which unbalances a diagram for reasons unrelated to the architecture.
What to leave out
The most common failure is including everything. A landscape diagram showing forty systems communicates less than one showing the eight that matter for the decision at hand.
Decide what the diagram is for before drawing, and omit anything that does not serve it. If something is important but off-topic, it belongs in a different diagram, which is why a landscape and a sequence diagram are separate artefacts rather than one crowded picture.
Frequently asked
Should I use a standard notation like ArchiMate or C4?
If your organisation already uses one, use it. Consistency with the house standard beats any kit invented locally. If there is no standard, a small kit like this is easier to adopt than a full notation nobody will learn.
What tool should I draw in?
Whichever one the next person can open and edit. A beautiful diagram in a tool nobody else has is a screenshot within a month.
Do I need different kits for different audiences?
Same kit, different level of detail. Changing the visual language between audiences means each group has to learn it separately.
How do I show environments?
Usually a separate diagram. Overlaying environments onto a landscape is the most common cause of an unreadable picture.
Should data models use this kit?
No. Entity relationship diagrams have their own well-established conventions and should follow them. This kit is for systems and integration, not for schema.
Reference: Salesforce Well-Architected and the Salesforce Architect diagramming resources, Salesforce; general architecture notation practice.
