Architecture (or architectural – both are used) diagrams are primarily about making it easier to communicate and collaborate with all stakeholders in a project. An architecture diagram will show the concepts involved in the architecture, including key principles, elements, and components. They are high-level diagrams that aim to represent the big picture and make it clearly understandable.
An architecture diagram is not really intended to be a design document. It does not explore the minute details of how to build something, but rather what is to be built. Starting the project with an architecture diagram serves as a guide to development and helps all the stakeholders contribute, regardless of their level of technical expertise. Most importantly, an architecture diagram should help the project to meet the needs of all the stakeholders, which is why it’s important that it can be understood by everyone involved.
Architectural diagrams consist of shapes and lines. The shapes represent concepts, systems, processes, or entities, while the lines show the flow of data or relationship between them. You can use arrows to specify the direction of the flow of data, but not every architecture diagram needs that level of detail. The same goes for the borders of the shapes. You can use solid, dotted, or dashed borders to represent properties of the element depicted. You can also use colors to differentiate areas or types of element, as long as you use color consistently and for a particular purpose – and don’t go overboard with your palette.
A system architecture diagram will focus on the structure of the system to be created, along with the technologies used, external services, user requirements and components such as databases and servers.
Layers are often at the heart of the software architecture diagram. The software to be designed is divided into layers that represent different functionalities, such as the business layer, service layer, and data layer. This grouping helps show the interaction between users, systems, and services, both internal and external.
This is the most useful type of architecture diagram for management of the organizational and business model of a project. Roles, teams, interaction, management tools, security policies, business plans, and workflow can be shown.
It’s really easy to create an architecture diagram in Gleek, especially if you prefer to just type out your diagram and not waste time dragging and aligning shapes. Let’s say you want to create an e-commerce architecture diagram, which is somewhat analogous to a software architecture diagram, but is highly suitable for large-scale projects and designed to be used at the enterprise level.
Here’s one we prepared earlier 😉
In fact, this diagram is one of several templates already available in Gleek.
To use Gleek templates, go to app.gleek.io, right-click in the code field and choose Templates. Then select one of our pre-coded templates. Gleek will automatically fill out the code and draw a diagram. You can then edit or change the diagram whatever way you want. This is great for learning how to use Gleek, as you get a shortcut to a finished diagram and its code.
Try it out in Gleek now, and keep the following six tips in mind as you create your architecture diagrams.
1. Document what you draw
Your diagram needs to explain itself. You can’t rely on always being around to tell someone what they’re looking at. If you intend a box or shape to mean something, record that meaning on the diagram itself. This is also true of the borders or the shapes and the arrows used to indicate data flow or relationships. The best way to make sure that your diagram is understood correctly is to include a legend or key where you can list examples of the different elements.
2. Be consistent
Not only do you need to explain your design choices in the diagram, you also have to remain consistent in how you use them. Your shapes, arrows, and colors should do the same job throughout a single diagram and across related diagrams.
3. Don’t make assumptions
Assumptions are dangerous when designing any diagram. Not only can you not assume that you’ll be able to explain any vagueness, you also can’t assume that, for instance, your final reader will understand acronyms, internal references, or external information relevant to how the diagram works. It’s often a good idea to include a glossary as well as a legend.
4. Avoid conflicts
Each diagram should aim to use the same level of abstraction for all elements. Even if you could, don’t dive too deep into one area and leave a different part of the diagram unexplored. If you find yourself at conflicting levels of granularity in your diagram, you need to work out how to balance it out. If you end up with two diagrams that represent slightly different aspects of the same system, consider merging them.
5. Minimize clutter
It’s just as dangerous to add too much to a single diagram. An excess of information is often interpreted by the final reader as clutter. If you find your diagram growing so big that it can’t easily be explained, you might need to split it into two or more diagrams. If you have a lot of stakeholders in the project, you can find that you need to use a lot of diagrams. And don’t forget tip no.2 – be consistent in your design choices across all diagrams!
6. Keep your diagrams up to date
The project will change as it is planned and implemented. Unless you maintain your initial architecture diagrams, updating them as needed to reflect development, your stakeholders and developers will lose confidence in and start to ignore them. And you can end up with potentially irrelevant and harmful descriptions of the system.