finos / finos/architecture-as-code

Drilling Down into Detailed Architecture

Open
#2,616 2 comments 0 reactions 1 assignee Claimed by @lbulanti-ms View on GitHub
calm-hub-ui
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

# Feature: Drilling down into Detailed Architecture

## Summary

CALM nodes can already point to a more detailed architecture through the
`details` block. Today this relationship is expressed in the model but is not
navigable in the UI. This feature proposes a drill-down interaction: when a node
has a `details` block, the visualizer shows a `+` affordance on that node, and
activating it opens the referenced detailed architecture.

## Background

A node in the CALM schema has an optional `details` block that links it to a
lower level of abstraction:

- **`detailed-architecture`**: a reference (URL or file path) to the full CALM
architecture document that expands the node.
- **`required-pattern`** (optional): the pattern that the detailed architecture
must conform to.

For example:

```json
{
"unique-id": "service-123",
"node-type": "service",
"name": "Payment Service",
"description": "Handles all payment transactions",
"details": {
"detailed-architecture": "http://calm-hub/architecture-5",
"required-pattern": "http://calm-hub/pattern-2"
}
}
```

The model supports composition across levels of detail, but the visualizer
treats a node with `details` the same as any other node. There is no way to move
from the high-level view into the detailed view that the node represents.

## Proposed feature

Make the `details` relationship a first-class navigation in the UI.

1. When a node has a `details` block, render a `+` affordance on that node to
signal that a more detailed architecture exists behind it.
2. Nodes without a `details` block render unchanged, with no `+` affordance.
3. Activating the `+` resolves `details.detailed-architecture` and renders that
architecture in the visualizer, letting the user drill down into the detail.
4. Provide a way back up to the parent architecture, so a user can move between
levels rather than getting stuck in the detailed view.

## Behaviour and acceptance criteria

- [ ] A node containing a `details` block shows a clear `+` affordance.
- [ ] A node without a `details` block shows no `+` affordance and behaves as it
does today.
- [ ] Activating the `+` resolves the `details.detailed-architecture` reference
and renders the referenced architecture.
- [ ] The user can navigate back to the parent architecture from the detailed
view (for example via a breadcrumb).
- [ ] An unresolvable or missing `detailed-architecture` reference is handled
gracefully with a clear message rather than a broken view.

## Open questions

- **Navigation model**: does drilling down replace the current view, open a
nested view in place, or open the detail in a new context? A breadcrumb trail
feels natural if we replace the view.
- **Multi-level drill-down**: a detailed architecture may itself contain nodes
with their own `details` blocks. The interaction should compose so a user can
keep going deeper and then step back up cleanly.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.