The short version: a system landscape diagram shows which systems exist, who owns them, and what moves between them — and nothing else. It survives review when every arrow is labelled with its payload and frequency, when Salesforce is one box rather than an exploded internal view, and when it fits on one page. The failure mode is always the same: too much detail, so the decision it was drawn to support gets lost.
What the diagram is for
It answers three questions for someone who does not work on the system daily:
- What are the moving parts?
- Which of them do we control?
- What depends on what, and how tightly?
Anything not serving one of those belongs elsewhere. Internal Salesforce structure, field-level mappings, sequence of calls within a transaction — all valuable, all a different diagram.
What goes on it
| Include | Leave out |
|---|---|
| Each system as one box | Components inside each system |
| Ownership — yours or third party | Team names and org structure |
| Direction of each integration | Field-level mapping |
| What moves, and how often | API versions and endpoints |
| Synchronous versus asynchronous | Retry and error-handling detail |
| Trust and network boundaries | Infrastructure topology |
| Human actors, where they initiate | Every user persona |
The first row is the one people resist. Salesforce is one box. The moment you draw objects, flows and Apex inside it, the diagram has become a Salesforce diagram and stopped being a landscape, and the reviewer who wanted to understand the estate cannot.
Drawing it
Put Salesforce where the traffic makes sense, not in the middle. Centring it is a habit from Salesforce-centric thinking and it often forces lines to cross unnecessarily. Arrange for readability.
Group by ownership. Systems you control on one side, third parties on the other, with a boundary between them. This makes the change-control story visible without a word of explanation.
Label every arrow with payload and frequency. “Customer master, hourly” or “Orders, real time”. An unlabelled arrow is an unreviewable claim and reviewers will, correctly, ask about every one.
Distinguish synchronous from asynchronous visually. Solid for synchronous, dashed for asynchronous. A reviewer scanning for risk is looking for solid lines to systems you do not control, because that is where an outage propagates into your users’ experience.
Show middleware as a box, not as a line. If an integration platform sits between two systems, it is a system with its own availability and its own failure modes. Drawing it as a line through which things pass hides that.
What makes reviewers reject it
Unlabelled arrows. The most common single finding.
No indication of direction. A line between two systems does not say who initiates, and who initiates determines who fails when the other is down.
Mixed levels of abstraction. One box is an entire ERP, another is a single Apex class. The reader cannot tell what granularity to expect anywhere else.
Missing the things that are not systems. A manual CSV upload somebody does every Monday is an integration. Leaving it off because it is not automated is how it stays invisible until the person doing it leaves.
No date or owner on the diagram itself. A landscape with no date is untrustworthy within six months, because nobody can tell whether it describes the present.
Keeping it true
A landscape diagram decays faster than any other document because the estate changes and the diagram does not. Two things help.
Put it where the work happens — in the repository, in the architecture documentation, wherever people already look. Rather than in a slide deck nobody reopens.
Make updating it part of adding an integration. A new integration that does not appear on the landscape is not done. That is a cheap rule to state and the only one I have seen work.
And put a date and an owner on the page. A diagram dated eighteen months ago is at least honest about what it is, which lets the reader calibrate.
A first pass, in order
- List every system, including manual processes and spreadsheets people depend on.
- Mark each as controlled by you or not.
- For each pair that exchanges data, write payload, direction and frequency as text first.
- Only then draw, placing boxes to minimise crossings.
- Show it to someone who does not work on it and ask what they think it says.
Step three as text first is the trick. Most of the thinking is in the list, and doing it in a drawing tool makes you optimise layout while you should still be deciding content.
Frequently asked
How many systems is too many for one page?
Past roughly fifteen boxes, readability drops sharply. Beyond that, split by domain and draw a simple index diagram showing how the domains relate.
Should I show data volumes?
Only where volume drives a decision. An integration moving millions of rows nightly is architecturally different from one moving a hundred. Otherwise it is noise.
Does this replace an integration specification?
No. The landscape shows that an integration exists and its shape. The specification says what the fields are and what happens on failure.
How do I show a planned system?
Draw it distinctly, a dashed outline is conventional, and label it with the expected date. Mixing current and planned state without distinguishing them is a reliable way to mislead people.
Who should own the diagram?
A named person, on the diagram. Shared ownership of a document means nobody updates it.
Reference: Salesforce Well-Architected and the Salesforce Architect diagramming resources, Salesforce; general architecture documentation practice.
