Everything you need to know about architectural diagrams (and how to draw one)

Everything you need to know about architectural diagrams (and how to draw one)

This post was originally published on October 9, 2019, and updated most recently on August 2, 2020.

Sometimes it’s helpful to get a big-picture view of something for context — and an architectural diagram does just that. In a nutshell, it shows how elements within a system interact with each other in a wider process.

There are many different kinds of architectural diagrams, all of which vary depending on what it is you’re trying to accomplish. They’re used in construction, engineering, security, IT, sales — basically any process that involves stages and stakeholders.

For this walkthrough, we’ll focus on software architectural diagrams, which break structures down into layers that show how specific systems interact with users and systems.

Design vs. architecture diagram

Many people confuse the two, but they’re completely different things. An architecture diagram describes what you’re building, how stakeholders interact with it, and where constraints lie. A design diagram explains how to build it.

To use an example: Say you’re building a football stadium. An architecture diagram will tell you what the architect wants, plus details about the investors, the building contractors, and local laws. It may include a summary of the building, plumbing, and electrics — but its main goal is to show you how to meet all these groups’ needs. Some parts show the concept from everyone’s point of view; others address individual needs. A design diagram, on the other hand, simply goes into detail about how to build the stadium, stage by stage.

Two ways architectural diagrams can help you

1. They help with comprehension

A picture is worth a thousand words, or so the saying goes. Similarly, architectural diagrams help convey complex information in a single image.

  • Architectural diagrams show systems. Displaying information visually allows the viewer to see everything at a glance, including how things interact. This is especially useful when making changes: You’ll be able to see the downstream effects of a given change more clearly.
  • Architectural diagrams also break down complex systems and processes into layers. So rather than trying to comprehend everything at once, you can zoom in and focus on smaller sub-processes or systems.

2. They improve communication and collaboration

One of the main issues software engineers face is consistency. When you’re working on anything that involves multiple people, there’s always a risk of miscommunication and discrepancies between project teams and developers. It is crucial to standardize information, which is where an architectural diagram comes in handy.

That said, it’s essential to bear in mind architectural diagrams can be inconsistent too — which is why they must be standardized, accurate, and detailed. They communicate the application’s elements, relationships, and properties over time to a range of different stakeholders, so they need to be consistent.

How to draw an architectural diagram

Architectural diagrams should be self-explanatory. If they’re not, then they’re failing. To make sure yours is easy to understand, make sure you keep variable elements consistent — and explain everything in the legend, key, or glossary. Here are some key rules to help you.

1. Document your shapes

The meanings of shapes vary from diagram to diagram, so to avoid confusion or misinterpretation, make sure you document the ones you’re using — even if it’s just a simple box. And be consistent throughout.

2. And the edges

The same goes for edges. Whether you use a dotted, dashed, or straight edge, make sure you properly label it in the diagram legend when using multiple border types.

3. Keep your arrows consistent

Arrows denote data flows and dependencies, but that same line could represent different things within those two categories. For example, a line could depict a relationship, but that relationship could represent a dependency or an implementation, for example. Minimize the risk of ambiguity by adding the relevant information to all arrows.

4. Use colors sparingly

When it comes to colors: less is more. You should only really use them to emphasize certain parts of the diagram. If you add color — like shapes, borders, and arrows — every choice needs to follow the same logic and be consistent and properly labeled. Otherwise, people will be asking why certain things are the way they are, which negates the point (and effectiveness) of the diagram.

5. Use multiple diagrams, if necessary

If you have multiple stakeholders, you may need to include a large amount of data. If this is the case, rather than creating an unintelligible spaghetti beast, create several diagrams for the different viewpoints. And whether you have one diagram or ten, remember to keep everything (boxes, shapes, borders, and colors) consistent throughout.

6. Merge incomplete diagrams

If two diagrams both represent one process or system, but they’re incomplete, consider merging them.

7. Include legends/keys/glossaries

This helps everyone understand your diagram. Remember, just because your team knows a certain acronym, it doesn’t mean a stakeholder will.

8. Use diagramming software

Using a dedicated cloud-based diagramming tool allows you to track changes in real-time and revert to previous versions if necessary (without the need for manually tracking versions on the server). This helps with traceability, minimizes the risk of someone working on the wrong document, and cuts down on admin.

Things to watch out for

  • Missing elements, broken relationships, or isolated entities: These could point to a wrong or incomplete diagram.
  • Unexplained acronyms: Aways write the expanded acronym first, then use the abbreviation. It’s also a good idea to put all acronyms in a glossary for reference.
  • Vague or generic terms: Avoid anything that could be interpreted in different ways.
  • Unexplained technologies, frameworks, or scripting languages: These shouldn’t feature in the diagram, but you should include a rationale as to why you’ve chosen certain things.
  • Assumptions: Alluding to further explanations or diagrams, such as “I will explain this later.” Over time, your diagram will pass through various groups and stakeholders, and they may not have access to this additional information. Make it self-contained.
  • Too much information — or too little: A good architectural diagram isn’t cluttered, but it instead self-contained and includes all relevant information. To strike this fine balance, revise and improve upon your first draft. Remember: It’s all in the edit.

Final thoughts

Many software projects lack proper documentation because people see it as time-consuming or confusing. But not having the right diagram for the job is like trying to drive somewhere without planning your route: The time spent getting lost and backtracking dwarfs any up-front time you would have spent mapping your journey.

It’s the same with architecture diagrams: Setting out this information helps you and your stakeholders navigate the project and brings clarity across the board. Using cloud-based diagramming software to create a diagram everyone can access is another way to maintain consistency because changes are tracked in real-time. This means you won’t have to send out version updates or worry about people working on or viewing an outdated diagram: Everyone is on the same page.

Cacoo’s software allows you to insert and edit your infrastructure directly into the cloud-based diagramming tool. Try it today!

Georgina Guthrie Georgina is a displaced Brit currently working in France as a freelance copywriter. Before moving to sunnier climates, she worked as a B2B agency writer in Bristol, England, which is also where she was born. In her spare time, she enjoys old films and cooking (badly).