Skip to content
Software Architecture Guide

Traceability

Explanation

Section titled “Explanation”

Traceability means you can follow a link from a requirement to the part of the architecture that deals with it. You can also follow it back, from a design choice to the requirement behind it.

arc42 (a template for documenting architecture, see the article arc42 Architecture Documentation Template) describes two forms.

Full-scale traceability. Every single requirement is referenced somewhere in the architecture or solution documentation. No requirement is left without a link.

Pragmatic traceability. You explain the important or fundamental decisions by naming the requirements behind them. This helps readers understand why the architecture looks the way it does.

The arc42 building block template supports linking too. Its blackbox template (a description of a building block that shows what it does, not how it works inside) has an optional field for the requirements that the block fulfills. That field connects requirements to the building blocks that implement them.

arc42 attaches a warning to this field. Add fulfilled requirements only if you really need traceability, because the effort is large.

Example

Section titled “Example”

A team builds an online shop. One requirement says customers can pay by invoice. In the description of the payment building block, the team fills the optional field with this requirement. The team also records the decision to use an external payment provider and names the requirement behind it. A new team member can now see why the provider exists. The team does not link minor requirements, such as button labels. This follows the pragmatic form.

Trade-offs

Section titled “Trade-offs”

Full-scale traceability gives complete coverage. arc42 calls it horribly expensive, slow and difficult, and advises avoiding it when you can. The pragmatic form costs less and still explains the key decisions, which helps understanding. The price is that some requirements have no recorded link to the architecture. Fill the optional requirements field only where you truly need the links.

Checks

Section titled “Checks”
  • The documentation states whether traceability is full-scale or pragmatic.
  • Important architecture decisions name the requirements behind them.
  • The fulfilled-requirements field of a building block is filled only where traceability is truly needed.
Section titled “Related”

Sources

Section titled “Sources”