finos / finos/architecture-as-code
Pattern-to-Architecture Conformance Overlay
- 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
Assessment
This issue has not been assessed yet.