Skip to content

Article Collection Intents

Purpose

This document defines intent for article collections managed through the marketing BFF and persisted into the CMS system behind it.

Article collections are reusable editorial assets. They are not owned by any one site, even if a site uses them heavily.

Role of Article Collections

Article collections support:

  • reusable editorial grouping
  • site/page article selection
  • collection-level media and copy
  • stable retrieval targets for apps and assistants

Use intent belongs in docs/sites/. Collection definition belongs in the article domain.

Transitional Local Rule

Local collection YAML files under docs/articles/collections/*.yaml are staging artifacts during cleanup.

They must be treated as preparation material for CMS persistence through BFF, not as the long-term authoritative collection store.

Retrieval Intent

The current BFF retrieval endpoints for article collections are:

  • getArticleCollection(collectionKey)
  • getArticleCollections(collectionKey?)

Mutation Intent

The current verified BFF article-collection mutations are:

  • createArticleCollection(input)
  • updateArticleCollection(collectionKey, input)
  • deleteArticleCollection(collectionKey)
  • addArticlesToCollection(collectionKey, articleIds)
  • removeArticlesFromCollection(collectionKey, articleIds)
  • replaceArticlesInCollection(collectionKey, articleIds)

Human Input Pattern

Collection intent should support requests such as:

  • show me the articles in omnivoltaic vision
  • add article X to collection Y
  • replace the members of collection Y
  • update the collection hero description
  • persist this collection to CMS

The assistant should resolve these as collection-level operations, then persist them through the BFF.

Collection Contract Direction

An article collection should be treated as a first-class object with:

  • collectionKey
  • name
  • description
  • optional scope metadata when useful
  • collection-level media
  • article membership

Collection storage should remain collection-first, not site-first.