Design Discussion: Documents vs Decorators

[LeighFinegold]

Feature Discussion

Target Project:

CALM (cross-cutting: calm-hub, calm-hub-ui, CLI, calm-spec)

Description of Feature:

CALM tooling and workflows produce artefacts that sit alongside architectures but aren't architectures themselves. Solution Architecture Documents (SADs), user guides, operational runbooks, compliance narratives, API documentation, and similar prose or mixed-format deliverables.

These are documents in their own right with independent lifecycles, often authored by different teams, and needing version control.

Today, the only mechanism to associate these with an architecture in CALM Hub is to make them decorators. But a user guide isn't a "cross-cutting overlay that augments an existing CALM element." It's a standalone artefact. Treating it as a decorator:

1. Loses version history: decorators aren't versioned in CALM Hub (no version endpoints, no version timeline)
2. Dilutes the decorator concept: "decorator" becomes a catch-all for "anything that isn't core JSON," making it harder to reason about what decorators are actually for
3. Misrepresents the artefact: a SAD or user guide is a first-class deliverable, not supplementary metadata

For example, calm docify can generate documentation from architectures. Even if it were implemented, there's no place to publish the output.

User Stories:

• As an architect, I want to publish my Solution Architecture Document alongside my CALM architecture so that reviewers can see both the model and the narrative in one place.
• As a platform team lead, I want to version operational runbooks associated with my architecture so that I can track changes over time and roll back if needed.
• As a compliance officer, I want architecture-related compliance narratives to be versioned and traceable so that I can demonstrate audit history.
• As a developer, I want user guides linked to the architecture they describe so that I don't have to search Confluence/SharePoint for the right version.

Current Limitations:

• CALM Hub stores and versions 8 document types (architectures, patterns, flows, standards, interfaces, controls, ADRs, timelines), all JSON
• Decorators are stored but not versioned: no version endpoints, no version history, no timeline
• No mechanism exists to store non-JSON content (Markdown, HTML, PDF)
• calm docify SAD mode is unimplemented
• No CLI command to publish generated documentation to CALM Hub

Proposed Implementation:

This issue is primarily a design question: the implementation depends on the answer.

The core question: where should versioned, non-JSON artefacts that relate to CALM architectures live? Options include:

1. A new document type in CALM Hub: versioned, content-type-aware, associated with architectures but independently managed
2. External systems with references: documents live in Git/Confluence/SharePoint; CALM tracks references to them (e.g. via a URL field on architectures)
3. A hybrid: CALM Hub stores metadata and references; content lives elsewhere but is discoverable through CALM Hub
4. Make decorators versioned: add versioning support to decorators so they can serve as the store for these artefacts. This addresses the versioning gap but still raises the question of whether a user guide or SAD is conceptually a "decorator"

Each has trade-offs around traceability, tooling integration, and scope. The key assertion is that whatever the answer, these artefacts are not decorators and shouldn't be forced into the decorator model.

Additional Context:

This issue is part of a series exploring CALM's decorator and document model. Related issues that may provide useful context:

• Design Discussion: CALM-Hub Decorator Registry and Views #2792 CALM Hub decorator registry and views
• Design Discussion: Decorator Association Scalability Concerns #2793 Decorator Association Scalability Concerns
• [calm-spec] Decorator mechanism — close meta-schema and CLI gaps (core.json, sidecar wrapper, extension schemas, calm validate) #2552 Decorator mechanism: close meta-schema and CLI gaps
• Allow flows array to be a reference to a document referencing a flow #1876 Allow flows array to be a reference (contains the decorator definitional debate)
• Add a Guide Section to the Calm Schema #1633 Add a Guide Section to the CALM Schema

[markscott-ms]

Some thoughts of how I think about things:

A decorator attaches a post-fact evaluation or outcome of an architecture to the architecture, i.e. a decorator is typically a review of some kind about an architecture, or information generated as a result of that architecture.

• The statement "my architecture intends to conform to the a data management policy" => NOT a decorator.

• A review of an architecture against the data management policy => decorator

• My architecture is constructed with the intent that it mitigates these attack vectors => NOT a decorator

• A pen testing report => decorator.

• A deployment report (deploy logs etc) => decorator

• ARB minutes discussing an architecture => decorator

• SAD => not a decorator, it is a document about intent and context, not outcome.

On the topic of ADRs and SADs being in CALMHub:

• I do not believe that CALMHub should contain rendered output. No PNGs, no PDFs, no SVGs.
• Having these primarily textual documents shoe-horned into a JSON structure creates an upload and adoption challenge. Even Structured MADR only has YAML frontmatter with the cataloguing access points specified (literally like the front matter pages - title, colophon etc - in a book are there to aid the collection manager to catalogue the book into their library). The rest is "free text" in Markdown format. If ADRs and SADs are stored in CALMHub, then they should be separated into these two parts only - a structured frontmatter for cataloguing, and a free-form content. JSON is not nice for handling multiline strings. Should .md be supported? calm docify renders MD + architecture into a SAD.

[aamanrebello]

I feel like if flows and ADRs are already document types, would a SAD (or anything else) also not merit being a document type? I suppose it would become difficult to add new document types for each and every kind of document, so maybe there is a need for a more generic document type that can encompass different kinds of documents?

[markscott-ms]

The danger of generic is CalmHub ends up being a "SharePoint"-type thing.