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.

[LeighFinegold]

Based on the intro of calmhub concept and playing around with it attaching some more detail design thoughts for a discussion in office hours.

In general architecture-as-code will have a docify module which the cli will leverage to perform the docify command. I think calm-docify will need to have an online mode - calling off to a calmhub or an offline mode - looking at local file system.

I could see offline mode working based on what previously bundled when one was online. I could also see a solution where the internal references in documents are kept as network addressable urls, but the cli docify command is passed a url -> file location mapping.

In relation to process steps - I see as the below.

I believe in order to allow for document extensions, we might need to create an intermediary model to allow the calm spec to evolve at a difference pace to the calm specifications.

Design Assumptions

• We have to accept that in order to work in offline mode, the CLI has to perform its own validation even though calmhub itself will validate documents before insertion.
• To create a zipped bundle most likely want to structure folders based on schema type e.g. flows, architecture, pattern etc
• The cli will need to be configured with various different implementations that allows connectivity to a calmhub.