Skip to content
Software Architecture Guide

Modeling Method

Explanation

Section titled “Explanation”

A modeling method records the choices a team makes so that everyone draws architecture the same way. Without it, each person invents their own style and diagrams become hard to compare.

Match detail to audience. Different readers need different levels of detail. The C4 Model (see its article) offers zoom levels for this purpose. Each level tells a different story to a different audience. Most teams only need context and container diagrams.

Keep the set of elements small. State the type of every element explicitly, for example person, system, container, or component. A short, fixed list of element types is easier to learn and to read.

Make each diagram explain itself.

  • Give every diagram a title that states its diagram type and scope.
  • Add a legend (a key) that explains the notation.
  • Label every relationship arrow with its intent.

Agree on colors. Colors can be chosen freely. They must be used the same way within a diagram and across diagrams.

Avoid diagram sprawl. Do not draw everything. The arc42 Architecture Documentation Template advises detailing only building blocks that are important, surprising, risky, complex, or volatile. It also uses abstraction levels. Each level zooms into the one before it, so readers get the idea without implementation detail.

Choose tooling with the method. Decide whether model data lives in git next to the source code or inside a tool or cloud service.

Example

Section titled “Example”

A small team agrees on a few rules. They draw only a context diagram and a container diagram. Every diagram has a title such as “Container diagram for the Order System”, a legend, and labeled arrows. Blue always means systems the team owns. Grey always means external systems. They keep the diagram files in git next to the source code.

Trade-offs

Section titled “Trade-offs”

Every rule costs effort to write down and to follow. Too many rules make the method heavy, and a small core of rules is easier to keep. Storing models in git keeps them next to the code. A separate tool or cloud service keeps them elsewhere. Weigh this when you pick tooling. Detailing only important building blocks keeps diagrams few, but some parts will have no diagram.

Checks

Section titled “Checks”
  • Every diagram has a title stating its diagram type and scope.
  • Every diagram carries a legend explaining its notation.
  • Every relationship arrow has a label stating its intent.
  • Color coding is consistent within and across diagrams.
  • The type of every element is stated explicitly.
Section titled “Related”

Sources

Section titled “Sources”