Skip to content

Article CMS Persistence Workflow

Purpose

This document defines the cleanup rule that locally persisted article-domain artifacts must be persisted into the CMS system through the BFF.

This applies to:

  • article markdown artifacts under docs/articles/*.md
  • collection YAML artifacts under docs/articles/collections/*.yaml

Authority Model

During cleanup, local files may continue to exist for:

  • editorial drafting
  • review
  • normalization
  • migration support

But the intended operational authority is:

  • BFF as the mutation and retrieval gateway
  • CMS as the underlying persistence layer

Required Persistence Rule

An article-domain cleanup is not complete until the affected object is persisted through BFF into CMS.

That means:

  • cleaning a local article file is not enough
  • creating a local collection YAML is not enough
  • the resulting object must be represented in the BFF-backed system

Persistence Workflow

Article Object

  1. prepare or revise the local article artifact
  2. validate it against the article contract
  3. determine whether the object should be created or updated
  4. call:
  5. createArticle
  6. or updateArticle
  7. re-read via BFF and confirm persisted state

Article Collection

  1. prepare or revise the local collection artifact
  2. validate membership and collection metadata
  3. determine whether the collection should be created or updated
  4. call:
  5. createArticleCollection
  6. or updateArticleCollection
  7. apply membership mutations as needed:
  8. addArticlesToCollection
  9. removeArticlesFromCollection
  10. replaceArticlesInCollection
  11. re-read via BFF and confirm persisted state

Assistant Obligation

When an article-related cleanup or restructuring task is performed, the assistant should:

  1. identify which local artifacts changed
  2. determine whether those changes imply required BFF persistence
  3. perform safe validation before mutation
  4. persist the resulting objects through BFF when the needed mutation path exists
  5. report any gap where a required persistence path is still missing

Transitional Reality

Current scaffolding may still consume local article artifacts in some app flows.

That is acceptable as an interim compatibility measure.

But the direction of cleanup is:

  • local file as staging
  • BFF/CMS as authority
  • site scaffolding progressively shifting to BFF-backed retrieval