finos / finos/architecture-as-code
Drilling Down into Detailed Architecture
- 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
Assessment
This issue has not been assessed yet.