More common mistakes to avoid when creating system architecture diagrams

Recorded: March 22, 2026, 10 p.m.

Original

Summarized

7 More Common Mistakes in Architecture Diagrams | Ilograph Blog

Blog

Get Ilograph
^

Ilograph for Web
- Use Ilograph in the browser

Ilograph for Desktop
- Use Ilograph as an offline desktop app

Ilograph for Confluence
- Use Ilograph in your Confluence Cloud instance

Features
Pricing
Docs
Architecture Center
Blog

Home
Ilograph for Web
Ilograph for Desktop
Ilograph for Confluence
Features
Pricing
Docs
Architecture Center
Blog

7 More Common Mistakes in Architecture Diagrams

Billy Pilger ·

calendar

Mar 12, 2026
· 6 min read · Article

·

Share on:

facebook

copy

System architecture diagrams are essential tools for documenting complex systems. However, common mistakes in these diagrams can lead to confusion, misinterpretation, and frustration for viewers. Here’s a rundown of seven (more!) common mistakes to avoid.

This is a follow-up to the original 7 Common Mistakes in Architecture Diagrams.

Mistake #1: Not including resource names
Poorly labeled resources (the entities between the lines) is a common problem in system diagramming. Consider the labels under the icons in this AWS diagram:

The resources in this diagram are labeled by type instead of by name. Source: amazon.com.
Each resource in the diagram has an icon labeled with its type but not its name. While the resource type is certainly valuable, one is not a substitute for the other:

Types describe what kind of thing a resource is. Types can include concrete items such as database tables or VM instances, or abstract items such as services. Types can be written out or represented as an icon.

Names disambiguate resources from other resources of the same type. Descriptive names can also reveal the resource’s role or purpose.

When space allows, viewers are best off knowing both the name and type of a resource. This can be as simple as adding a type suffix to a resource name (e.g. Orders Table, Results Bucket). Diagram icons/shapes typically indicate the type (as they do in the diagram above), so labeling a resource by name is especially preferable when an icon is present.
#2 Unconnected resources
Here is a simple one: resources in a diagram should always be somehow connected to the other resources. Including resources that are disconnected from all others is a mistake.

Amazon Route 53, on the right, is disconnected from every other resource. Source: amazon.com.
In the diagram above from this article, Amazon Route 53 (on the right) is unconnected to the other resources. Its role in the system is completely unclear. Diagrams like this exist to show relations between resources, so omitting those relations defeats the purpose of the diagram to begin with.
This issue arises when diagram authors know a resource is part of a system but can’t find a clean way to express it. It is often the result of trying to include too much information in a single diagram (usually a “master” diagram, see next item).
#3 Making a “master” diagram
“Master” diagrams attempt to show an entire system at once. They stem from a misguided desire to “see it all” in a single diagram. They are almost always a mistake.

Ilograph's serverless back-end architecture (click to enlarge).
The above diagram is a “master” diagram of Ilograph’s back-end system architecture. It combines run-time dependencies, DNS configuration, CDN configuration, source code, and deployment-time dependencies, all in a single diagram. As it hopefully illustrates, including this much information in a single diagram will overwhelm the viewer.
The solution is to break up such a diagram into multiple perspectives (points of view):

The "master" diagram can be split up into multiple perspectives.
Most systems are complex enough to warrant breaking up their diagrams like this. Each perspective tells a cohesive story without interfering with the others.
If using model-based diagramming, perspectives can explicitly share resources among them to maintain their connections. For more details, see Breaking Up the Master Diagram.
#4 Conveyor belt syndrome
So far, the example diagrams in this article have all been relational diagrams, which show relations between resources. There is another class of system diagrams called behavioral diagrams, which aim to show specific interactions between resources rather than relations.
Because behavioral diagrams show specific interactions, they tend to be more detailed than relational diagrams. Diagram authors sometimes simplify these diagrams for space or time reasons; what I call conveyor belt syndrome occurs when they over-simplify them by omitting the realities of round-trips and orchestrations in the actual system. The result is a diagram that seriously misleads the viewer on the nature of the system.

This diagram depicts the system as a conveyor belt. Source: amazon.com.
The diagram above (from this solution) depicts the system as an assembly line: data flows neatly from one resource to the next. It’s as if each resource takes input from its predecessor, augments that input, and then passes it along to the following resource.
Now, it’s true that sometimes this is what is happening in the system. But as a rule, this isn’t accurate; there is a lot more back-and-forth among these resources (and others not shown). Experienced developers may intuitively understand that there is more to the diagram than it shows, but the inexperienced will be severely misled.
The solution is to use a different kind of diagram entirely: sequence diagrams. Sequence diagrams (first specified in UML) are tailor-made to show detailed back-and-forth interactions between resources, like in the revised diagram below:

Depicting a portion of the same system as a sequence diagram.
Reformatting the diagram like this yields both greater detail and greater fidelity to the system it depicts. See this article for more information.
#5 Meaningless animations
This is an issue that is almost certainly witnessed much more often than it is committed. Diagrams with meaningless, distracting, and at times obnoxious animations have proliferated on social networks such as LinkedIn over the years. Here is a typical example:

The animations add no actual information to the diagram. Source: cloudairy.com.
Diagrams like these exist exclusively for marketing purposes, almost needless to say. They’re great at attracting attention, but offer little to no value as technical resources. In addition to being a distraction, the animated arrows in the diagram above are completely redundant. They indicate nothing more than the direction that the arrow already goes in. Almost needless to say (again), unless you are creating a diagram primarily for marketing, avoid unnecessary animations like these.
#6 Fan traps
Fan traps in system diagramming occur when relation information between resources is lost in intermediate resources. For example, in an event-based system diagram, the specific communications between edge resources are lost if they are collapsed in a shared message broker:

In system architecture diagramming, a fan-trap occurs when relations collapse onto a single resource.
Fan traps can be fixed by adding more specific resources (in this example, topics) inside the intermediate resources and re-routing the relations through these new resources. This restores the communication paths between the edge nodes:

The individual relations are now visible.
There are other ways to resolve fan traps when adding intermediate resources isn’t possible; see this article for examples.
#7 Assuming AI can create quality diagrams from source code
Artificial Intelligence can be useful when diagramming. When “whiteboarding”, that is, interactively specifying a system, AI can assist a human as they make iterative improvements and try out ideas. If an AI could automatically diagram a system directly from source code, that would be even better. Unfortunately, while AIs certainly can attempt this, the diagrams they generate are often vague, contain hallucinations, and exhibit many of the issues discussed above.
These problems stem from the challenges AIs face when creating diagrams of real-world systems from source code. These including an almost complete lack of training data, difficulties analyzing dense source code, and a general inability to strategically choose what to include and omit. As AIs improve this could change in the future; but for now, detailed system diagramming is still primarily a human endeavour.
Questions or comments? Please reach out to me on LinkedIn or by email at billy@ilograph.com.
Share this article on LinkedIn
Share this article on Facebook

Recent Posts

New in Ilograph: Sub-sequences

New in Ilograph: Embedded Perspectives

New in Ilograph: Via Relations

New in Ilograph: Scale Overrides

Diagrams AI Can, and Cannot, Generate

How to Generate AWS Diagrams with Resource Explorer and Ilograph

Why Ilograph Added Contexts

Better AWS Architecture Diagrams: Distributed Load Testing

to-top

## 7 Common Mistakes in Architecture Diagrams – A Detailed Analysis

Billy Pilger, March 12, 2026

System architecture diagrams are critical tools for documenting complex systems, yet frequent missteps can lead to confusion, misinterpretation, and ultimately, frustration for stakeholders. This article, a follow-up to the original “7 Common Mistakes in Architecture Diagrams,” delves into seven key areas where common errors occur, offering detailed guidance for creating effective and informative diagrams. This analysis targets a college graduate audience requiring a thorough and nuanced understanding of architectural diagramming best practices.

**1. Neglecting Resource Naming & Labeling:** A fundamental problem stems from inadequate labeling of resources within the diagram. Instead of simply identifying resources by their *type* (e.g., “Database Table”), it’s crucial to include descriptive *names* that communicate their purpose and role within the system. As illustrated with the AWS example, relying solely on type labels offers limited context. Ideally, resource names should incorporate their type for clarity (e.g., “Orders Table,” “Results Bucket”). Proper naming enhances understanding and reduces ambiguity, allowing viewers to quickly grasp the system’s architecture and function.

**2. Disconnected Resources & Lack of Relationships:** The core function of an architecture diagram is to represent the *relationships* between system components. A critical mistake involves including resources that are completely isolated, lacking any connections to other elements within the diagram. This illustrates a fundamental misunderstanding of the diagram's intent. The Amazon Route 53 example highlights this issue: a disconnected instance contributes nothing to the overall system understanding. A successful diagram must consistently demonstrate how elements interact, illustrating dependencies and data flows.

**3. The Pitfalls of “Master” Diagrams:** The temptation to create a single “master” diagram that attempts to visualize an entire system is a pervasive trap. These overly comprehensive diagrams, like Ilograph's serverless back-end architecture, quickly become overwhelming, presenting an unmanageable amount of information. The solution lies in breaking down complex systems into multiple, targeted perspectives—each conveying a coherent story while respecting the limitations of visual representation. Utilizing alternative perspectives enables focused understanding without sacrificing necessary detail, which is reinforced by the strategy used for Ilograph.

**4. Conveyor Belt Syndrome & Oversimplified Interactions:** Another common oversight arises in behavioral diagrams, which represent specific interactions between resources. Diagram creators sometimes fall into the "conveyor belt syndrome," creating overly simplistic representations that mask the complexities of actual back-and-forth communication. This is exemplified by the Amazon example, depicting the system as a linear assembly line. While a conceptual simplification, it can mislead viewers regarding the true nature of the system. Sequence diagrams provide a higher fidelity representation by explicitly illustrating the dynamic interactions between steps, avoiding the oversimplified visual representations.

**5. Meaningless Animations & Distractions:** The proliferation of animated diagrams in marketing materials raises a crucial point. Animations, when unnecessary and purely decorative, introduce distractions without contributing substantive information. The cloudairy example demonstrates how decorative animations add no value to the diagram's technical understanding. Diagrams should prioritize clarity and information density, not superficial visual effects.

**6. Fan Traps & Loss of Relation Detail:** “Fan traps” occur when relations collapse onto a single resource, obscuring the intended communication paths. For example, in an event-based system, a shared message broker can hide the specific interactions between edge resources. To mitigate this, intermediates resources (e.g., topics) should be introduced to restore visibility into the complex data flows. A clear understanding of these traps is vital for creating diagrams that accurately represent system interactions.

**7. Over-Reliance on AI for Diagram Generation:** While AI tools can assist in diagramming processes, particularly in model-based diagramming, a critical limitation remains. Current AI systems struggle to generate truly insightful diagrams from source code due to a lack of training data, difficulties in code analysis, and an inability for strategic inclusion/exclusion decisions. The emphasis should remain on human expertise and strategic diagraming, leveraging AI effectively as a supportive tool, rather than relying on AI to autonomously generate accurate system representations.

This article provides a detailed examination of common mistakes in architecture diagrams, emphasizing the importance of clear labeling, accurate representations, and strategic diagram organization. By avoiding these pitfalls, stakeholders can create diagrams that enhance understanding, facilitate communication, and ultimately, contribute to successful system design and implementation.