Skip to content
Software Architecture Guide

Component View Antipattern: Lifting Code to Model Level

Explanation

Section titled “Explanation”

A building block view shows the parts of a system and how they relate. arc42 says this view should make the source code understandable through abstraction. It should not reproduce the code.

The antipattern appears when a team copies code structure into the model. Packages named Facade, Service, Dto or Converter become boxes in the diagram. The diagram is then a second copy of the code. It adds no new insight.

arc42 describes the view as levels of black boxes (outside only) and white boxes (inside shown). Level 3 zooms only into selected level 2 blocks. It is not a place to list every code package.

C4 (see the article C4 Model) points the same way. A component sits one abstraction level above code. It groups related functionality behind an interface. It is not a single package or class. In object-oriented languages, one or more classes implement a component.

Better alternatives

  • Form building blocks by cohesion. Group code that belongs together by responsibility.
  • Create component diagrams only when they add value. Automate their creation for long-lived documentation, so the model does not drift from the code.
  • Skip code-level diagrams in long-lived documentation. IDEs can generate them on demand. Keep this detail for the most important or complex components.

Example

Section titled “Example”

A team documents an order system. Its level 3 diagram shows boxes named OrderFacade, OrderService, OrderDto and OrderConverter, repeated for customers and payments. Every box matches a code package.

A better view shows three blocks: Ordering, Customer Management and Payment. Each groups code by responsibility. A developer who needs package detail generates it from the code with an IDE.

Trade-offs

Section titled “Trade-offs”

Code-level detail has a use. It is warranted only for the most important or complex components. Generating diagrams with tools costs setup effort. In return, they stay current with the code. Hand-drawn abstract views need judgment about what to select and what to hide.

Checks

Section titled “Checks”
  • Building blocks in the view are grouped by responsibility, not named after code packages such as Facade, Service or Dto.
  • Level 3 zooms only into selected level 2 blocks, not into every block.
  • Code-level detail appears only for the most important or complex components.
  • Code-level diagrams are generated by tooling rather than drawn by hand.
Section titled “Related”

Sources

Section titled “Sources”