Note: This article, along with Architecture Records: Purpose, Scope, and Rationale, is being published in advance of the publication of the Solution assets, which will follow later in 2024.

This metamodel supports the recording of different types of Architecture Record in Ardoq. It introduces a framework with which a family of component types can be adopted.

We call the collective family “Architecture Records,” although each member will have its own name that reflects the type of Architecture Record it represents.
​
This guide introduces the recommended metamodel for five popular and valued members of this family:

You may choose to extend this family with members of your own design, selecting from the “raw ingredients” introduced in Architecture Records: Purpose, Scope, and Rationale.

The five types of record listed above are all forms of documented decision. The basic facts of a decision: the decision itself, what it applies to, over what period, who approved it, and when, may be sufficient to provide evidence of a decision to interested parties, such as an audit.

However, it is also valuable to record why a decision has been made. An architecture is the sum of its design decisions, and it will probably have a life span that will see owners, architects, developers and users come and go. Enabling future stakeholders to understand why an architecture is how it is is a key reason to document decisions. To support a rich description of an Architecture Record, the content has been broken down into a collection of fields that can be included in each type of Architecture Record.

Below is the metamodel of the “type family” Architecture Record. It is a “prototypical” Architecture Record and covers the superset of fields and references available for inclusion in a component type that belongs to the family. Five example family members are described in detail in later sections of this document.

The following table lists the set of fields from which a selection can be made to populate a particular “architecture record” component type.

The fields Decision YesNo and Decision Text are alternatives. In some circumstances, the component represents a record that has a clear binary decision, such as a compliance assessment considering this question: Does this component fall within the scope of a given policy? So a Compliance Assessment can use Decision YesNo. For a more general Decision Record, the text paragraph as provided with Decision Text is more suitable.

The following reference types are available for use with Architecture Records:

The reference fields do not all need to be used, and should be chosen where they are useful to connect a record component to other components in the knowledge graph. For example, for some organizations, recording the people who have approved a decision in the graph will be valuable; for others the value might come from connections to assets rather than people.

To illustrate how the fields and references come together to form a template that can be populated with real decisions, the example below shows a Decision Record component viewed in Ardoq Discover. It is the same example given in Architecture Records: Purpose, Scope, and Rationale to illustrate the Y-Statement format of ADRs.

A number of the provided reports and viewpoints refer to “Live” records. A “Live” record is one whose Decision Status is “Approved”, and whose Decision Live Start Date is today or earlier, and whose Decision Live End Date is today or later. “Live” is therefore shorthand for “Current Approved”.

Below, we describe five members of the Architecture Records family that are included with the Solution. The family can be extended with new members, or amended to suit a different record template.

A hierarchy of Category components can optionally be used to organize records within the same Workspace. For example, a single Patterns Workspace can be used to contain different collections of architectural design patterns covering distinct topics organized with a hierarchy of Category components.

This is a documented record of an architectural decision. The decision itself is recorded in free-form text, enabling a wide range of decisions to be captured. The decision should be accompanied by information about the decision context, rationale, assumptions, and consequences, enabling a design decision to be well understood by those who were not involved in decision-making. ADRs might originate in projects that are developing new assets, teams responsible for maintaining and updating assets, or in meetings of formal bodies, such as the Architecture Review Board.

[ ] = Component Field

{Owns} = Reference from the Person who owns the decision

{Has Subject} = Reference(s) to the component(s) that are the subject of the decision (e.g. an Application component)

{Refers To} = Reference(s) to component(s) that influenced the decision (e.g. Requirement components that represent Quality Characteristics)

{Approved By} = Reference(s) to Person components that have approved this decision

This Architecture Record is used to document an architecture pattern, a collection of which can form a Pattern Library within the parent Category. Each record can be searched and found in Ardoq Discover.

[ ] = Component Field

{Refers To} = Reference(s) to other Pattern components

{Is Realized By} = Reference(s) to components that realize this pattern. Each realization of the pattern should be represented with just one reference to primary component associated with the implementation (e.g. an Application component)

This captures the results of an assessment that has determined whether a particular subject component complies with a particular requirement. The requirement might, for example, be a policy or regulatory requirement, such as DORA or GDPR compliance, or a collection of requirements that collectively describe a framework, such as an organization’s architecture guiding principles. If they are modeled in Ardoq, they may be associated with the Assessment component with the Refers To reference. It differs from other Architecture Records in that it has a YesNo decision - the conclusion is definitive - either the subject does, or does not comply.

[ ] = Component Field

{Has Subject} = Reference(s) to the component(s) that are the subject of the Compliance Assessment (e.g. a Process component being assessed for compliance with GDPR)

{Refers To} = Reference(s) to component(s) that influenced the decision (e.g. Control components that have been deployed to the Subject, or the Policy components that the subject is being evaluated against)

{Approved By} = Reference(s) to Person components that have approved this assessment outcome

This Architecture Record documents a decision to approve one or more Technology Product (which collectively form the Technology Catalog) as a standard for use within an organization. The Live date range is used to indicate its currency, and can be used to trigger processes to renew the standard or find a replacement.

[ ] = Component Field

{Has Subject} = Reference(s) to the component(s) that represent the approved standard (e.g. Technology Product component(s) in the Technology Catalog)

{Approved By} = Reference(s) to Person components that have approved this standard

In some organizations, architecture standards and principles are expected to be strictly complied with, and exceptions to these need to be requested and approved by an authority. Requesting and granting such an exception is a form of decision, and this type of Architecture Record can be used to manage the process of requesting and approving (or rejecting) such requests. The Live end date can be used to trigger a process to confirm that the exception is no longer required.

[ ] = Component Field

{Has Subject} = Reference(s) to the component(s) that are the subject of the Exception Request (e.g. an Application component that is unable to adopt an approved standard)

{Refers To} = Reference(s) to component(s) from which the exception is being sought (e.g. an Architecture Standard component)

{Approved By} = Reference(s) to Person components that have approved this assessment outcome