Skip to content
Software Architecture Guide

Rules of Thumb for Modeling

Explanation

Section titled “Explanation”

The facts available here come from the C4 model (see the article “C4 Model”). They cover habits that help people read a diagram they did not draw.

Give every diagram a title. The title should state the diagram type and its scope. A reader then knows at once what they are looking at.

State the type of each element. Do not leave readers guessing whether a box is a person, a software system, a container or a component. Write the type on the box.

Label every relationship line. The label should fit the direction and the intent of the relationship. Make it specific. A vague single word such as “Uses” tells the reader very little.

Keep colors consistent. If you color-code elements, use the same codes within one diagram and across all diagrams. A color that means different things on different pages misleads readers.

Add a key or legend. Choose notation that explains itself where you can. Even so, put a key on every diagram so the notation is explicit.

The article “Self-Invented Notation Drawback” covers why unexplained custom notation is risky. A key reduces that risk.

Example

Section titled “Example”

A team draws a diagram of an online shop. The title reads “Container diagram for the Online Shop”. Each box names its type, for example “Web Application [Container]”. One arrow says “Sends order details to” instead of “Uses”. Every database is blue on every diagram. A small key in the corner explains the colors and shapes.

Trade-offs

Section titled “Trade-offs”

The available facts describe the habits but not their costs. Types, labels and a key take extra effort and space on every diagram. The C4 guidance still asks for them.

Checks

Section titled “Checks”
  • Every diagram has a title that states its type and scope.
  • Every diagram includes a key or legend that explains its notation.
  • Every relationship line has a label that matches its direction and intent.
  • Relationship labels are specific and avoid vague words like ‘Uses’.
  • Color coding is the same within each diagram and across diagrams, and each element states its type.
Section titled “Related”

Sources

Section titled “Sources”