Enable creation / editing of controls via Calm-Hub

[rocketstack-matt]

Feature Proposal

Target Project:

calm-hub-ui - The web interface for CALM architectural diagrams and processing

Description of Feature:

Add a user interface for creating and modifying controls directly in the calm-hub UI, eliminating the need for manual JSON editing. This feature will allow users to define control-requirements by adding fields and specifying property names, setting whether properties are variable or constant, and to create control-configurations by entering values through a structured form interface.

User Stories:

• As an architect, I want to create control requirements through a UI so that I don't have to write JSON schemas manually and can focus on defining the control properties.
• As a developer, I want to implement control configurations through a form interface so that I can ensure my configuration matches the requirements without parsing JSON schemas.
• As a compliance manager, I want to view and modify controls in a user-friendly interface so that I can ensure systems meet regulatory requirements without needing technical JSON knowledge.
• As a team lead, I want my team to be able to create consistent controls using guided UI forms so that we maintain standards across projects.
• As an enterprise architect, I want to extend existing control-requirements by referencing their IDs so that I can build upon established patterns while adding organization-specific requirements.

Current Limitations:

Currently, users must manually write JSON files for both control requirements and configurations. This process is error-prone, requires technical knowledge of JSON Schema, and creates a high barrier to entry for non-technical stakeholders. The existing process requires:

1. Creating separate JSON files for control requirements and configurations
2. Manually ensuring the configuration properly implements the requirement schema
3. Properly linking these files via URLs in the architecture definition
4. No visual feedback until after all JSON is written and validated

Proposed Implementation:

Technical Design:

1. Control Requirement Builder

   • Form interface to define control requirements
   • Field type selector (string, enum, boolean, number, etc.)
   • Option to mark fields as "const" (required with fixed value) or variable
   • Ability to extend existing control-requirements by referencing their ID
   • Support for inheritance from base control-requirements
   • JSON Schema preview/export functionality
   • Validation rules configuration

2. Control Configuration Form

   • Dynamically generated forms based on the selected control requirement
   • Auto-populated fields for const values
   • Input validation based on the requirement schema
   • Ability to save configurations as templates

3. Control Management Dashboard

   • List view of existing controls with filtering and search
   • Visualization of which controls are applied to which architecture components
   • Compliance status indicators

API Integration:

• Leverage existing control support in calm-hub backend
• No new API endpoints required as the backend already supports control management
• Connect UI components to existing backend functionality for retrieving and storing controls

Alternatives Considered:

1. JSON Editor with Validation - Rejected because it still requires JSON knowledge and doesn't provide enough guidance for control creation.
2. Fixed Template Controls Only - Rejected because it lacks the flexibility needed for different organizations' requirements.
3. External Control Management Tool - Rejected because integration with the main architecture view provides better context and usability.

Testing Strategy:

• Unit tests: Test form validation logic, control requirement generation, and configuration validation
• Integration tests: Test saving and loading controls from the backend
• End-to-end tests: Test complete workflows of creating requirements, configurations, and applying to architecture components
• Usability testing: Conduct sessions with users of different technical backgrounds to ensure the interface is intuitive

Documentation Requirements:

• User guide for creating control requirements
• User guide for implementing control configurations
• Examples of common control patterns
• API documentation for programmatic control management
• Update to the core concepts documentation to include the UI-based approach

Implementation Checklist:

• [ ] Design UI mockups for control creation interfaces
• [ ] Design reviewed and approved
• [ ] Implement Control Requirement Builder
• [ ] Implement Control Configuration Form
• [ ] Tests written and passing
• [ ] Documentation updated

Additional Context:

The UI should follow a wizard-like approach for creating new controls:

1. Define Basic Information

   • Control ID, name, description
   • Category/domain selection
   • Option to extend an existing control-requirement by entering its ID

2. Define Properties

   • Add properties one by one
   • For each property: name, type, description, constraints
   • Option to mark as required or optional
   • Option to set as const or variable

3. Review & Finalize

   • Preview of the generated schema
   • Option to export as JSON
   • Save to library

For configurations, the UI should provide immediate feedback on validity against the requirement schema, with clear error messages for any validation failures.

This feature would significantly reduce the barrier to entry for using controls in CALM, making it accessible to a broader audience and encouraging more comprehensive use of controls for governance and compliance purposes.

[aidanm3341]

waiting on the completion of #713 which introduces control endpoints to calmhub before continuing with this