Pattern-to-Architecture Conformance Overlay

[YoofiTT96]

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.

[aamanrebello]

I agree with a side-by-side comparison, maybe we could have an error bar explicitly describing instances of non-conformation ("why don't they conform?"). I also agree with using existing code, hopefully it is not usable only in backend projects and can be used in browsers too.

Rather than this though "Add a "Compare" mode to the Drawer that accepts both a pattern and an architecture", I would propose one of the following:

• when a user has a pattern open in CalmHub, there is a button "Validate Architecture Against This Pattern", which you can click on to select an architecture (in the same namespace?)
• when a user has an architecture open in CalmHub, there is a button "Validate Against Pattern", which you can click on to select a pattern (in the same namespace?)
• both of the above?

These approaches would work better with deeplinks in my opinion. That's what I have to say anyway :)