finos / finos/architecture-as-code

ADR (Architecture Decision Record) Links

Open
#2,187 1 comment 0 reactions 0 assignees View on GitHub
calm-hub-ui
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

## 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.

Contributor guide

Open the contributing guide

Research direction

Start by reading AdrRenderer.tsx and CustomNode.tsx, then trace the architecture transformation and sidebar entry points mentioned in the proposal. Confirm how CalmAdrMeta and ADR references are represented before planning extraction, indicators, navigation, tests, and documentation; done means the linked graph and sidebar behavior works with passing unit, component, and integration tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.