Architecture Diagram System

Salesforce architects draw diagrams constantly. Explaining a platform to an executive, walking an engineer through a provisioning flow, showing a customer how their systems will connect.

There was no design system for any of it. Every architect solved it alone, every time, which meant the same platform got drawn four different ways depending on who happened to be holding the pen.

This one came to me scoped. Somebody had already worked out that architects needed a system and I was handed the problem rather than finding it.

Every architect solving it alone meant three costs, and none of them were about how the diagrams looked.

Customers read the same architecture differently depending on who drew it, which turns into scope disputes and rework on deals that had already closed. Architects rebuilt the same explanation from scratch every time, which is a recurring cost in hours nobody had ever counted. And customer-facing material looked improvised, which is a strange thing for an enterprise platform selling reliability to be handing people.

The absence was not a design problem. It was three business problems wearing one.

The problem is not that architecture diagrams are hard to draw. It is that a diagram serves several audiences who need completely different amounts of it, and most diagrams try to serve all of them at once and serve none.

An executive needs to understand what the system is for. An engineer needs the process flow. A customer needs to see where their own systems plug in. Same architecture, three different questions.

So the system has four tiers, and the architect picks one based on the audience rather than starting from scratch and hoping. Four tiers, five artifacts, because level 2 doubles.

Level 1, platform architecture. The system in visual layers. Major modules, how they relate, where they integrate. The one you draw for somebody who will never open the platform.

Level 2, two optics at one altitude. Same height, different question. Conceptual model: what the system is for. Service provisioning: onboarding, configuration, dependencies, made legible to somebody who has to sell or support it.

Level 3, process. Delivery, release, testing. The layer that gets argued over, because it is where three teams’ versions of the same process meet.

Level 4, style guide. Colour, shape, line weight, naming.

The process level leaned hard on railroad and subway maps. Tracks, junctions, interchanges, stops.

The reason is that a subway map lies about geography on purpose. Nobody needs to know how far apart two stations actually are, they need to know the sequence and where the lines cross. Process flows have exactly that shape, and most of them get drawn as though accuracy about everything were the goal.

So level 3 and 4 became a kit of parts built on that grammar. Which had to do three things at once: produce diagrams that hang together across everyone using it, let each architect’s diagram still be its own thing rather than a template with the words swapped, and stay recognisably Salesforce in a room where a customer is looking at it next to three competitors.

Cohesive, unique, and branded. Any two of those are straightforward. All three is the actual design problem.

I always knew it would be four tiers. What I had to decide was which end to start from.

I started at the granular end and abstracted upward. Level 3 and the style guide first, then the conceptual layers on top of them.

Building the other direction is more common and it does not work. You cannot decide what to leave out of a top-level diagram until you know what is actually in the system, and an abstraction invented before the detail exists is a guess that everybody downstream has to live with. Working upward meant every simplification was a decision to omit something specific rather than a decision to not think about it yet.

The problem arrived scoped. The system did not. I built the multi-tiered kit of parts from research through discovery through finalising and testing every piece of it.