finos / finos/architecture-as-code

Pattern-to-Architecture Conformance Overlay

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

Description

## Feature Proposal

### Target Project:
`calm-hub-ui` — Visualizer module

### Description of Feature:
Load both a CALM pattern (JSON Schema) and an architecture instance side by side, with a color-coded overlay showing which pattern constraints the architecture satisfies or violates. This enables visual conformance checking directly in the browser.

### User Stories:
- As an architect, I want to load a pattern alongside an architecture so that I can see at a glance which constraints are met and which are violated.
- As a compliance reviewer, I want a color-coded overlay (green = satisfied, red = violated, yellow = partial) so that I can quickly assess conformance without reading raw validation output.
- As a team lead, I want to share a visual conformance report so that stakeholders can understand architecture compliance without reading JSON Schema errors.

### Current Limitations:
- The visualizer can display either a pattern or an architecture, but not both simultaneously.
- Conformance checking requires running `calm validate` on the CLI — there is no visual feedback in the UI.
- The `Drawer` component switches between pattern and architecture rendering modes; it does not support an overlay/comparison mode.

### Proposed Implementation:
- Add a "Compare" mode to the Drawer that accepts both a pattern and an architecture
- Reuse the existing `patternTransformer` to extract expected nodes/relationships from the pattern
- Match architecture nodes/relationships against pattern constraints by `unique-id`
- Color-code nodes: green (present and conformant), red (missing or violating), yellow (present but partially conformant)
- Color-code edges similarly based on relationship-type matching
- Show a summary panel with conformance statistics (e.g., "12/15 nodes conformant, 8/10 relationships conformant")
- Consider leveraging `calm-models` validation logic if available in the browser

### Alternatives Considered:
- **Side-by-side dual graphs**: Rejected because it doubles screen real estate usage and makes it harder to compare corresponding nodes.
- **CLI-only validation with JSON output rendered in UI**: Simpler but requires a backend round-trip and doesn't provide spatial visual feedback.

### Testing Strategy:
- Unit tests for conformance matching logic (node matching, relationship matching, constraint checking)
- Component tests for the overlay rendering with known conformant and non-conformant architectures
- Test with patterns containing `oneOf`/`anyOf` decision points to verify decision-aware conformance

### Documentation Requirements:
- User guide for loading pattern + architecture in compare mode
- Document color-coding legend and conformance status meanings

### 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 `calm validate` CLI command already performs schema-based conformance validation. The browser implementation could reuse or port the validation logic from `calm-models`. The existing `patternTransformer.ts` already extracts structured node/relationship data from patterns, which would serve as the basis for matching.

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.