ADR (Architecture Decision Record) Links

[YoofiTT96]

Feature Proposal

Target Project:

calm-hub-ui — Visualizer and Hub modules

Description of Feature:

Surface ADR references from CALM metadata as clickable links on nodes and in the sidebar, connecting architecture components to their decision records. When a node or relationship references an ADR, display a visual indicator on the graph and provide navigation to the full ADR view.

User Stories:

• As an architect, I want to see which nodes have associated ADRs so that I can understand the rationale behind design decisions.
• As a new team member, I want to click an ADR link on a node so that I can read why a particular technology choice was made.
• As a reviewer, I want to see all ADR references across the architecture so that I can assess whether decisions are documented.

Current Limitations:

• ADR rendering exists (AdrRenderer.tsx) with full structured display (status badges, collapsible sections, markdown rendering), but it is only accessible through the CALM Hub tree navigation.
• There is no link between architecture visualization nodes and their associated ADRs.
• The sidebar displays raw JSON for selected nodes and does not extract or highlight ADR references from metadata or controls.

Proposed Implementation:

• Parse ADR references from node/relationship metadata and controls fields during architecture transformation
• Add an ADR icon indicator on CustomNode.tsx (similar to the existing detailed-architecture ZoomIn icon)
• In the sidebar, render ADR references as clickable links that navigate to the ADR view in CALM Hub
• Add an ADR count badge or indicator to the graph toolbar showing total ADR coverage
• Consider adding an "ADR Coverage" view that highlights nodes with/without ADR references

Alternatives Considered:

• ADR panel in the bottom metadata area alongside Flows and Controls: Could work but would duplicate navigation that already exists in the Hub tree.
• Tooltip-only ADR references: Too hidden — users need persistent visual indicators to know ADRs exist.

Testing Strategy:

• Unit tests for ADR reference extraction from metadata/controls
• Component tests for ADR icon rendering on CustomNode
• Integration tests verifying navigation from node ADR link to ADR view

Documentation Requirements:

• Document ADR metadata format expected in CALM architecture files
• Update sidebar documentation to describe ADR link behavior

Implementation Checklist:

• Design reviewed and approved
• Implementation completed
• Tests written and passing
• Documentation updated
• Relevant workflows updated (if needed)
• Performance impact assessed

Additional Context:

The ADR rendering infrastructure is mature — AdrRenderer.tsx handles status badges, collapsible sections, markdown, and revision selection. The main gap is linking from the architecture graph into the ADR views. The CalmAdrMeta type from @finos/calm-shared defines the ADR data model.