Our Traceability Model

This page describes the traceability model that Antora Tracer uses to trace its own development artifacts. For the general concepts behind roles and relations, see The Traceability Model.

The diagram below is generated from the project’s configuration — examples/traceability.yml extending the built-in requirements-engineering preset. Each node is a role. Each arrow is a relation the configuration permits, labeled with its relation types. Only declared directions are drawn: the diagram does not add the inverse direction that the extension derives for traversal.

Traceability configuration graph

Roles

user_need

A user need is a specific, actionable requirement or desire that a user has when interacting with a system, product, or service. It represents the goal, problem, or task the user wants to accomplish, often framed from their perspective. User needs are the foundation for deriving use cases, which describe how the system should behave to fulfill those needs.

Key Characteristics:

  • User-Centric: Focuses on what the user wants to achieve, not how the system works.

  • Actionable: Clearly defines a task or outcome (e.g., "I want to reset my password").

  • Problem-Oriented: Addresses a pain point or a job to be done.

  • Non-Technical: Avoids implementation details (e.g., "The system should use OAuth 2.0" is not a user need).

Example 1. Example

"As a bank customer, I want to transfer money to another account so that I can pay my rent on time."

It follows the pattern <WHO> <WHAT> <WHY>

Use Case

Example 2. Example

Use Case Name

Transfer Funds

Primary Actor

Bank Customer

Description

Allows a customer to transfer money from their account to another account.

Preconditions

  • Customer is logged in.

  • Customer has sufficient funds in their account.

  • Recipient account is valid and active.

Main Success Scenario

  1. Customer selects "Transfer Money" from the dashboard.

  2. System prompts for recipient account details (account number, name).

  3. Customer enters the recipient details and the amount to transfer.

  4. System validates the recipient account and available balance.

  5. Customer confirms the transaction details.

  6. System processes the transfer.

  7. System sends a confirmation notification to the customer.

  8. System updates both the sender’s and recipient’s account balances.

Extensions

3a. Invalid recipient account: System displays an error message and prompts the customer to re-enter the details. 4a. Insufficient funds: System notifies the customer and aborts the transfer. 5a. Customer cancels: System returns to the dashboard without processing the transfer.

Postconditions

  • Recipient account balance is increased by the transferred amount.

  • Sender’s account balance is decreased by the transferred amount.

  • Transaction is recorded in both accounts' history.

  • Customer receives a confirmation receipt (email or in-app notification).

This project tracks eight roles.

requirement

A functional requirement the extension must fulfill (REQ-xxx). These are the "what the system must do" statements.

use_case

A user goal with actors, preconditions, a main flow, and postconditions (UC-xxx). Use cases lead to requirements.

process_requirement

A requirement on the delivery process itself — how the team builds and ships (PRQ-xxx).

constraint

A condition the system must not violate (CON-xxx), such as runtime or output-format limits. This role currently has no relations declared, so it renders as an isolated node until the model is completed.

design

An architectural or design element that addresses requirements (ARC-xxx, DES-xxx).

implementation

A code artifact that implements a design (IMP-xxx).

test

A verification or validation procedure (TST-xxx, TEST-xxx).

document

An external specification or standard the project references. This role is inherited from the preset and not yet populated by this project’s artifacts.

Relations

Relations are directional and typed: each states one fact per item, reading source → target. The sections below follow the source role, mirroring how the configuration declares them.

From Relation To Description

Requirement

refines

Requirement

The requirement narrows a broader requirement.

Requirement

depends on

Requirement

The requirement can only be satisfied after another requirement.

Requirement

conflicts with

Requirement

Two requirements cannot both be satisfied as stated.

design → requirement

addresses

The design responds to the requirement.

satisfies

The design fulfills the requirement.

design → design

depends_on

The design depends on another design element.

composed_of

The design is composed of smaller design elements.

refined_by

The design is refined by a more detailed design.

design → implementation, test, document

realized_by

The design is realized by an implementation.

validated_by

The design is validated by a test.

documented_by

The design is documented by a document.

implementation → requirement, design

satisfies

The implementation fulfills the requirement.

implements

The implementation implements the design.

implementation → implementation

depends_on

The implementation depends on another implementation.

uses

The implementation reuses another implementation.

implementation → test

tested_by

The implementation is tested by a test.

test → requirement

covers

The test covers the requirement.

verifies

The test verifies the requirement.

test → design, implementation

validates

The test validates the design.

tests

The test tests the implementation.

document → requirement, design

contains

The document contains the requirement.

describes

The document describes the design.

use_case ↔ requirement

leads_to

The use case leads to the requirement.

is_derived_from

The requirement is derived from the use case.

These two types form one logical pair and are both declared, so both arrows appear in the diagram.

process_requirement → requirement, design

validates

The process requirement validates that a product requirement is met by the delivery process.

considered_by

The process requirement is considered by a design or architectural decision.

Reading the diagram

Three self-loops appear: requirement, design, and implementation each declare relations back to their own role. These are intentional — intra-role refinement and dependency are part of the model.

The constraint role renders as an isolated node. This is a known gap: the role has items (CON-001 through CON-005) but no relations are declared for it yet.

Related