Practical and consistent conventions from my experience

Architecture is a discipline. It is also a device that assists in thinking and communication. As the latter, architecture deals with the static and dynamic structure of an overall system through models constructed of defined components, their external features and relationships.

Drawings are one of the oldest and most straightforward ways we represent things, real or imaginary. Naturally, they are the heart of architectural thinking and modelling. They define and transmit the model. Diagramming well is a critical ability for an architect.

Most architects prefer just to draw some closed shapes and connect them with arrows to express their structures. While this is natural, if it is not done well, it has wide and long-lasting downsides for the entire solution, the people and organisations involved. The quality should not vary drastically by who is drawing the picture.

In this article, I will put down conventions to produce clear, compelling and consistent architecture diagrams. There exist ISO, DIN, ANSI and other standards for process flow diagrams, IEEE for electrical diagrams, etc. The UML (Unified Modelling Language) standard is available for software application architecture modelling and many architects use it, but in my view, it is non-intuitive, confusing, dry, and limited.

For the dynamic aspect of the architecture, I find Sequence Diagrams to be adequate, as long as they use the same objects that are in the static model.

I will only deal with static diagrams here as they are usually where the architect begins modelling. Plus, static diagrams typically attempt to convey a lot more information than Sequence Diagrams and therefore have a greater need for conventions.

The Conventions for diagramming will be explained below in ten sections.

1. Information conveyed

A picture can speak a thousand words. Or more. Some of the information that static diagrams try to convey are:

• Functional units
• Relationships
• Scope of responsibility
• Scope of work
• Completeness of work
• The extent of the impact on a functional unit or relationship due to an enhancement
• The technology of a functional unit
• Vendor of a functional unit
• Criticality, business or technical
• Layers of the static aspect
• Zones by user type
• Zones by security type
• Human actors
• Things of the world other than computers and software

An architecture diagram can very quickly get very complicated.

There are two dimensions to static diagrams: the combination of audience and detail; and the artefacts used in them.

We can call the former the level of the drawing and define conventions for using the latter.

2. Levels

We describe the following levels and diagram names:

• Level 0 — Business Capabilities Diagram: The key audience is business executives and non-technical stakeholders.
• Level 1 — Technology Capabilities Diagram: The key audience is CIOs, CTOs, CISOs and Strategy & Planning managers.
• Level 2 — Architecture Diagram: The key audience is Designers and Project Managers.
• Level 3 — Design Diagram: The key audience is coders, testers and architects.

Diagrams with more details than the above are left to the Application Designers. They can be reviewed by architects but are not core deliverables for them. Level 1, 2 and 3 diagrams can be drawn either to show the functional or the operational (hardware, software) information.

This article will focus on the conventions for functional architecture diagrams.

3. Getting maximum impact

We read drawings through the eye-brain combination. Human eyes and the parts of our brains that process visual data have evolved to convert data into information that maximises safety and the ability to use objects in the world. There are two categories of capabilities — natural and nurtured. The former is genetic and innate, the latter learned in life. Understanding this makes it easier for us to create impactful drawings.

Here is how the eye-brain combination probably processes information, in order of informational utility and ease:

1. Motion is acutely detected as it can indicate a dangerous animal or water.
2. Size is absorbed rapidly as a larger animal or object can be more dangerous or useful.
3. Location is mapped quickly as something near or directly in front can be more hazardous or easy to grasp.
4. Colours are noticed after size as it can help to identify foe or food by standing out from the background.
5. Contrast is detected for differentiation after colours.
6. Shapes are recognised as familiar or new to classify or look closer.
7. Details within the mass of the animal or object are observed last.

Here are some skills that we likely learn with experience:

1. Gravity causes things to fall downwards.
2. Vertical stacks make structures.
3. Most things move horizontally.
4. Most languages are written left to right and we begin seeing any picture from the left side.
5. We focus on the centre of images for the longest time before exiting them.
6. Clusters indicate multiples instances of a single type.
7. Things that rise or go upwards indicate life, energy and positivity.

So, think of your drawing as the surroundings of a person walking in a forest or savanna.

How will you catch her or his attention? As we are only using static 2-dimensional drawings, motion is not at our disposal. So, we can create a semblance of it with prominent lines and arrowheads. We need to use size, position, colour, contrast, shape and text for maximum impact.

Here are the resulting guidelines:

1. Make essential things larger and centre them.
2. Start the story from the left, let it lead to the focal point in the centre and leave from the right side.
3. Create a strong mainstream of flow through the drawing by using positioning and arrows.
4. Use colour well for impact.
5. Put similar or related things together in loose clusters.
6. Use simple shapes for ease of understanding.
7. Verbalise the detail with text in moderation for a richer experience.
8. Position the secondary and tertiary information in sidestreams through which the eye can detour and return to the mainstream.

4. Guidelines by level

Level 0 — Business Capabilities Diagram

The Business Architect or Business Analyst typically draws this diagram. An Enterprise Architect who has sufficient knowledge of the business domain can also draw it. It shows all the essential capabilities required to carry out the business:

• It should not connect the business components with lines as they do not add any practical information.
• It should not have technology elements in it.
• There should ideally be one Business Architecture Diagram for the entire business landscape and separate architecture diagrams for each business domain, if required.

Level 1 — Technology Capabilities Diagram

The Enterprise Architect typically draws this diagram. It shows all the essential technical capabilities required to deliver the business capabilities.

• It should show systems and sub-systems that map to the business capabilities.
• It can connect the systems or sub-systems to indicate critical relationships, although it is not a must.
• It should not show the individual applications and interfaces of the technology systems.
• The systems and sub-systems of a Level 0 diagram can be referenced in a Level 1 diagram if it is covering the same (or a large enough) scope.

There should ideally be one Enterprise Architecture Diagram for the entire solution landscape and separate architecture diagrams for each technology domain, if required.

Level 2 — Architecture Diagram

The Level 2 diagram is usually the most essential and standard architecture diagram. The conventions of this article are most applicable to it.

Depending on the scope of the drawing, it can be drawn by different people:

1. Overall enterprise landscape — Enterprise Architect or Integration Architect
2. Integration Architecture — Integration Architect
3. Information Architecture — Information Architect
4. Application Architecture — Application Architect
5. Infrastructure (aka hardware) Architecture — Infrastructure Architect

Regardless of who owns the diagram, the following need to be considered:

• It should show all the components and integrations that are in the scope of the drawing.
• A component is a precisely defined term in IT architecture and represents a cohesive set of technical functions. Components are loosely coupled to other components. Defining proper components is a necessary precursor to the drawing of a Level 2 diagram.
• The systems and sub-systems of a Level 1 diagram can be referenced in a Level 2 diagram if it is covering the same (or a large enough) scope.
• Don’t mix up functional and infrastructure Level 2 drawings. Make one for each. There should ideally be one Enterprise or Integration Architecture Diagram for the entire solution landscape and separate architecture diagrams for each technology domain, if required.

Level 3 — Design Diagram

A Level 3 diagram falls into the domain of detailed design rather than architecture. It is defined here for the sake of completeness. An application designer draws it.

• It should show the sub-components, objects or classes that comprise a Level 2 architectural component, and their relationships or interfaces.
• UML notation can be used for Level 3 diagrams effectively.
• Each diagram should represent a module or sub-module of software.

5. Legend

Unless a drawing is using only one type of closed shape and line, and they all have the same attributes (type, colour, weight, etc.), you must have a legend for the diagram.

1. Legends should be in the corner of the layout, ideally at the bottom right.
2. They should be enclosed in a box and titled ‘Legend’.
3. They should have an example of each artefact they are differentiating by attribute and include descriptive text next to it.
4. The legend should not miss anything that needs to be differentiated.
5. The legend should be easily visible and readable but not distract from the diagram.

6. Artefacts and their attributes

Now, this is where things get a bit involved. So, pay attention, please.

There are several artefacts that we can use in a diagram along with their attributes to represent the items of the real world. The most important artefacts, with their most important attributes, are:

• Closed shapes, defined by the type of shape (rectangular, circular, oval, etc), outline type (solid, dashed), fill colour, and position in the drawing.
• Lines, defined by the type of line (solid, dashed, etc), the shape of the line (straights, curved, etc.), the colour of the line, and the direction of arrowhead.
• Text, defined by the case (upper, lower), the weight and size, and the colour.
• Special shapes, such as cylinders to represent a data store, etc.
• Icons, which may have the text caption attached (e.g. mobile user, automobile, satellite, etc.).

7. Artefact to use for each information type

Depending on the type of information you want to convey, you will need to select the appropriate artefacts for your diagram. The table below gives guidance on artefact application and what to pay attention to when depicting various information aspects.

8. General do’s

1. Name your functional units with nouns that indicate their action (e.g. Data Analyser, Report Generator). Alternatively, use nouns that indicate their function & form (e.g. Data Analysis Engine, Reporting Module).
2. Spread out the closed shapes evenly across the drawing, unless there is a reason to create clusters.
3. Use colours for impact.
4. Be consistent in the attributes of all artefacts of the same level or type (e.g. shape outline thickness and colour; line thickness, colour, arrowheads; text size, font and colour, etc.
5. Ensure all lines begin and end at an artefact or an external link icon.
6. Ensure all lines end at the boundary of artefacts and do not stop short or overshoot it.
7. Spell-check your drawing.
8. Expand any acronyms or mnemonics in a footnote or the legend.
9. Make sure the drawing looks nice.
10. Put a legend.
11. Put yourself in the shoes of the reader and check if everything is self-explanatory and your drawing is telling the story you want it to tell.

9. General don’ts

1. Don’t mix up the levels of your drawing. Create multiple drawings if required.
2. Don’t clutter up your drawing with information overload. Create multiple drawings if needed.
3. Don’t use flashy colours for any artefacts. Pastels and standard colours such as Red, Amber and Green are best. Use grey shades for less critical objects.
4. Don’t forget the legend! It is the most common omission. Especially, if you’ve used colours abundantly don’t leave the viewer wondering if they mean something.
5. Don’t make the viewer strain to understand anything on the diagram.

10. Examples of architecture diagrams

The following four pictures are examples of each level of architectural drawing. Please note they do not follow all the conventions laid down here. The reader can take it as an exercise to see where they observe and deviate from it.

The PowerPoint document accompanying this article has an example or template for a Level 2 Diagram as it is drawn most often and serves the widest purpose.

Final notes

The conventions laid down are not exhaustive. But, once you start thinking in this way, about how to communicate clearly and consistently through drawings, you will naturally fill in the gaps and extend the system yourself.

It is the system I use and have propagated in my circle of architects, but you may follow something somewhat different. That is okay, as long as you disseminate it through your area of influence and use it consistently. If I have forgotten something significant and routine, please send in your comments, and I will update this article to make it more complete and useful.

Also, there are dimensions I have not used, such as 3D representations, hyperlinks, cardinality, etc. as they can overload an architecture diagram and slow down their creation. If a situation warrants their use, please feel free to apply them. But still, pause to think of a consistent convention for their use. Trust me that it will pay off for architectural quality and its communication to others.

Draw well, architect!

---

Document versions of the conventions and examples are available for download below.

Please feel free to apply it and share your practitioner feedback. We will make it better together. If you have any questions or need some more samples, I am only a line away on LinkedIn or at quality-thinking.com. Always glad to help!

---

Conventions for Effective InfoTech Architecture Diagrams.pdf

IT Architecture Diagram L2 Convention – Template.pptx

Diagram Template – Conventions for Effective Architecture Diagrams.vsd Visio File

Diagram Template – Conventions for Effective Architecture Diagrams.vdx XML file

Connect with me: