Create an Architecture Documentation Website from CALM

[LeighFinegold]

Feature Request

Description of Problem:

As of 2024-10, CALM provides a highly flexible framework for capturing detailed technical architectures through nodes, relationships, flows and associated control requirements. This has enabled us to effectively map and apply constraints onto system architectures and reusable patterns. We have already demonstrated the ability to transition from these architectural constraints to infrastructure as code, specifically in k8s environments.

However, as we scale to larger and more complex system architectures, especially when incorporating additional stakeholders and cross-functional teams, there is a growing need for a more dynamic and accessible format for architecture documentation. The current CALM specification, while robust, primarily exists as a static artifact that lacks interactivity and user-friendly navigation, which is essential for cross-team collaboration, onboarding, and maintaining long-term architectural knowledge.

This is particularly critical as developers, architects, and operations teams require more intuitive access to architecture details, business logic, and relationships between systems. Without a centralized, interactive view, it can be challenging to effectively communicate architectural changes, technical flows, and associated control requirements to both new and existing team members.

Potential Solutions:

Proposing introducing a feature to generate a document based website (using library like https://docusaurus.io/) from the CALM specification. This solution would allow teams to automatically generate a navigable, interactive site that documents the system architecture in an accessible format, making it easier to understand, explore, and communicate complex architectures across various teams and stakeholders.

The website should capture the following key aspects of the CALM specification:

• High-Level Business Flows: Clear documentation and visualization of business processes supported by the system, including how different flows interact with the architecture. This enables stakeholders to easily understand the relationship between business goals and the technical infrastructure.

• Architecture Decision Records (ADRs): A section that showcases key architectural decisions and their impact on the system. This allows users to track the rationale behind decisions and view how they affect nodes, relationships, flows, and patterns.

• Node Focus: The ability to drill down into individual nodes within a business flow or system. This would provide details about how a specific node functions, its role in the flow, and how it interacts with surrounding components.

• System Views: Comprehensive views of the entire system architecture, including nodes, relationships, and control requirements, allowing users to zoom in and out of technical details based on their needs.

• Interactive Visualization: Allowing users to explore business flows and system components dynamically, toggling between high-level and detailed views.

• Data Dictionary: With Add a useful and interoperable Data representation to CALM #462 be able to clearly show the data assets linke to the high-level/detailed views.

Proposed Solution

calm docify calm.json

This would automatically generate the architecture site as a part of CALM’s output, with a configuration option to define the website’s structure and content organization.

[jpgough-ms]

I think the #449 idea is a pre-requisite to make this work well. The idea behind bundle is that will pull assets from external references together, which would make the documentation richer.

[rocketstack-matt]

I think both the bundle and artefact store we've discussed would be relevant here (I've realised we haven't accurately captured the artefact repository idea, this is the seed of it #69

I'll get that written up, but I would see it as a central store that would enable us to publish:

• Patterns
• Instantiations
• Control Requirements
• Control Configurations
• Evidence

I could see this being valuable for sharing reusable artefacts (controls as well as patterns) and also enable the detailed-architecture links to be referenced so that a documentation tool (and future visualiser) to be able to navigate interrelated architectures.