# Unclear Level of Abstraction Antipattern

**In short:** An architecture diagram that mixes high-level and low-level elements confuses readers. The fix is to keep each diagram at one abstraction level and draw separate diagrams when both views are needed.

## Explanation

A diagram has an abstraction level: how much detail its elements show. A whole system sits at a high level. A single part sits at a low level.

The antipattern appears when one diagram mixes high-level and low-level resources. Readers then cannot tell which level the picture describes.

**Remedy**

Pick one abstraction level per diagram. If you want both a high-level and a low-level view, split them into two separate diagrams. If a diagram is busy, split it so each part covers one or two concerns.

**Zoom levels in C4 and arc42**

The C4 model (see C4 Model) gives every element a clear type. A software system contains containers, which are applications and data stores. Each C4 diagram stays at one of these levels.

The arc42 building block view works the same way. Level 1 shows the overall system as a white box, meaning you see inside it. Level 2 zooms into some level 1 building blocks. Each level stays a separate abstraction. arc42 advises always describing level 1.

**Review and related mistakes**

The C4 review checklist asks whether you understand the type of every element, which is its abstraction level. The same checklist also covers related diagram problems: a missing title, an unclear diagram type and a missing legend.

## Example

Imagine one overview picture that shows a web shop as a whole, next to a single barcode scanner and a network router. Readers cannot tell whether it shows the system, the hardware or the setup.

The fix is to draw two diagrams. The first shows the shop as one box. The second zooms into the shop and shows its applications and data stores. Within each diagram, all elements sit at the same level.

## Trade-offs

Splitting diagrams gives you more diagrams to draw and keep up to date. Readers may also need to move between several pictures. In return, each picture has one clear level and one clear purpose.



## Checks

- Every element in each diagram belongs to the same abstraction level.
- High-level and low-level views are drawn as separate diagrams, not combined in one.
- Busy diagrams are split so each one focuses on one or two concerns.
- A reader can tell the element type of every element, such as software system or container.
- Each diagram has a title, a clear diagram type and a legend.

## Related

- [Architectural Overview Antipattern](https://arc.fuet.ch/concepts/documentation/architectural-overview-antipatterns.md)
- [Architectural Overview Diagram](https://arc.fuet.ch/concepts/documentation/architectural-overview-diagram.md)
- [C4 Model](https://arc.fuet.ch/concepts/documentation/c4-model.md)
- [Architecture Level](https://arc.fuet.ch/concepts/fundamentals/architecture-levels.md)
- [Component View Refinement Levels](https://arc.fuet.ch/concepts/documentation/component-view-refinement-levels.md)
- [ISO/IEC/IEEE 42010 Architecture Description Standard](https://arc.fuet.ch/concepts/documentation/iso-iec-ieee-42010-architecture-description-standard.md)
- [Distribution View Antipatterns](https://arc.fuet.ch/concepts/documentation/distribution-view-antipatterns.md)
- [Self-Invented Notation Drawback](https://arc.fuet.ch/concepts/documentation/self-invented-notation-drawback.md)

## Sources

- [7 Common Mistakes in Architecture Diagrams | Ilograph Blog](https://www.ilograph.com/blog/posts/diagram-mistakes/) — ilograph.com, accessed 2026-11-09
- [Review checklist | C4 model](https://c4model.com/diagrams/checklist) — c4model.com, accessed 2026-11-09
- [Abstractions | C4 model](https://c4model.com/abstractions) — c4model.com, accessed 2026-11-09
- [5 - Building block view | arc42 Documentation](https://docs.arc42.org/section-5/) — docs.arc42.org, accessed 2026-11-09