finos / finos/architecture-as-code

CALM-Hub Decorator Registry and Views

Open
#2,792 2 comments 0 reactions 0 assignees View on GitHub
Roadmap Group: Proof of Concepts
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 6h
Merged PRs (30d)
38

Description

## Feature Proposal

### Target Project:

calm-hub, calm-hub-ui

### Description of Feature:

Decorator standards are intentionally kept outside the CALM schema release cycle; they evolve independently, and that's a reasonable design choice. But there's a gap: CALM Hub has no mechanism to discover decorator standards, and its UI hardcodes knowledge of specific decorator types.

Today, the deployment decorator exists as:
- A worked schema in the documentation
- Draft standards in `calm/draft/2026-03/standards/deployment/`
- Hardcoded TypeScript types in `calm-hub-ui` (`DeploymentDecorator`, `DeploymentDecoratorData`)
- A dedicated UI panel with deployment-specific rendering logic (`DeploymentPanel.tsx`, `DeploymentDetail.tsx`, `SummarySection.tsx`)
- A hardcoded tab in `DiagramSection.tsx`: `type DiagramTabType = 'diagram' | 'json' | 'deployments'`

Because decorator standards live outside the schema release, CALM Hub needs its own mechanism to discover, register, and render decorator standards. Without this, each decorator type ends up hardcoded into the UI, requiring a code change, new React components, and a release for every new decorator type. This contradicts the open-ended `type: string` design of decorators, where the whole point is that teams can define new types independently.

If a team publishes a threat-model decorator, a business-taxonomy decorator, or any other type today, CALM Hub has no way to render them.

### User Stories:

- As a **CALM adopter**, I want to register my custom decorator type with CALM Hub and have it rendered meaningfully, without waiting for a UI code change.
- As a **security team**, I want to publish threat-model decorators and have CALM Hub show them alongside deployment decorators, without the CALM Hub team hardcoding support.
- As a **CALM contributor**, I want to add a new decorator standard without having to also write bespoke React components and TypeScript types for CALM Hub UI.
- As a **CALM Hub operator**, I want to configure which decorator types my installation supports and how they're validated.

### Current Limitations:

- `decorators.json` defines the base envelope but no standard decorator types are registered or discoverable
- Deployment standard exists only in draft (`calm/draft/2026-03/standards/deployment/`)
- `calm validate` is decorator-blind; nothing catches malformed decorators or validates them against type-specific schemas (#2552)
- `DiagramSection.tsx` defines `type DiagramTabType = 'diagram' | 'json' | 'deployments'`, a closed set
- Deployment tab is architectures-only: `isArchitecture && viewModeRow('deployments', ...)`
- `MetadataPanel` has hardcoded tabs for flows, controls, deployment, and ADRs
- New decorator types require code changes in both backend and frontend

### Proposed Implementation:

CALM Hub should support a decorator standard registry that serves two purposes: knowing what decorator types are available (with their schemas), and driving how they're rendered in the UI.

**Registry mechanism** (how CALM Hub knows about decorator types):

Possible approaches include:
- **API-based registration**: decorator standards registered via REST API and stored in CALM Hub
- **Configuration-based**: decorator standard schemas loaded from a config directory at startup
- **Convention-based**: CALM Hub scans for schemas following a naming pattern

Each registered standard provides its JSON schema (using the existing `allOf` extension of `decorators.json`) so that CALM Hub can validate incoming decorators against their declared type.

**View rendering** (how CALM Hub displays registered decorator types):

Possible approaches include:
- **Schema-driven rendering**: the registered schema includes hints about how to render its data (field labels, layout, formatting). CALM Hub generates a generic view. Declarative but may be too rigid for complex views.
- **View registry**: administrators register view definitions alongside schemas, describing rendering contracts. More flexible.
- **Generic fallback**: at minimum, any decorator type without a specific view gets a generic JSON/table renderer. Nothing should be invisible just because it lacks a bespoke component.

The deployment panel could become the first "registered" view rather than a hardcoded one, proving the pattern.

### Alternatives Considered:

- **Bundle decorator standards into CALM schema releases**: rejected because keeping them independent is a deliberate design choice that allows faster evolution
- **Continue hardcoding**: add new React components for each decorator type. Doesn't scale and creates a release bottleneck
- **JSON-only view for non-deployment decorators**: functional but loses the value of structured rendering

### Additional Context:

This issue is part of a series exploring CALM's decorator and document model. Consider reading the related issues for broader context:

- finos/architecture-as-code#2791 Documents vs Decorators
- finos/architecture-as-code#2793 Decorator Association Scalability Concerns
- finos/architecture-as-code#2552 Decorator mechanism: close meta-schema and CLI gaps
- finos/architecture-as-code#2690 RFC: shared CALM semantics layer to align calm-hub-ui and calm-studio
- finos/calm-schema#20 Contains the decorator definitional debate (intent vs evidence, ownership-based)

Contributor guide

Open the contributing guide

Research direction

Start by reading decorators.json, the draft deployment standards under calm/draft/2026-03/standards/deployment/, and the existing UI entry points DiagramSection.tsx, MetadataPanel, DeploymentPanel.tsx, and DeploymentDetail.tsx. Compare the hardcoded deployment paths with the proposed registry approaches; done should include discoverable decorator schemas and a fallback rendering path without requiring bespoke support for every new type.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
full-stack
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.