Integrating Architecture Decision Records into CALM

[LeighFinegold]

Feature Request

Description of Problem:

CALM provides a robust framework for documenting system architectures, capturing nodes, relationships, controls, and patterns. However, it currently lacks a mechanism for integrating Architecture Decision Records (ADRs) directly into these specifications. ADRs are critical for capturing the context and rationale behind architectural decisions, which can significantly impact the structure and behaviour of a system.

In complex architectures, the absence of clear links between ADRs and architectural components can lead to misunderstandings, rework, and difficulties in decision-making. This challenge is compounded when systems evolve, making it essential to have a straightforward way to trace decisions back to the relevant nodes, relationships, flows, and patterns.

Potential Solutions:

1. Link Architectural Records to Nodes, Relationships, Flows, and Patterns: Amend nodes, relationships, flows, and pattern definitions that allow for references to ADRs i.e. similar how control requirements were added.

2. Separate ADR Construct: Alternatively, we could create a separate construct for ADRs that points back to the document containing nodes, relationships, and patterns. This construct would not be part of the core document but would allow users to reference and maintain ADRs independently while still associating them with relevant architectural elements.

By implementing one of these solutions, we would enhance CALM's capability to serve as a comprehensive source of truth for both architectural structures and the decisions that shape them.

[rocketstack-matt]

I think we would probably want both of these in target state. We should start with 1 because it's simple, but someone using CALM and the related tooling who doesn't already have an existing solution for ADRs would likely want it integrated.

[jpgough-ms]

I am supportive of having ADRs in CALM. I would be interested to hear opinions where ADRs might apply beyond Nodes and Architectures (including patterns) for my own understanding.

• From a flow perspective, given that these are business types of consideration/decisions (from the examples I have seen), is that an ADR?
• From a relationship perspective, i.e. this relationships uses mTLS feels more like an attribute of a larger ADR. Though I could see that a Firmware consideration might be in play - though could that be a control?

My opinion for this could be to have:

• ADRs added as an optional property to the top level and nodes (as a starting point)
• ADRs live within Calm Hub Initial Prototype #543 as a feature beyond the prototype
• Links are created from nodes, patterns, and architectures to the ADRs stored in the hub. To cover @rocketstack-matt's point, this could be a URL, covering other types of ADR store

Tagging @yt-ms as we briefly discussed this today