"Data store architecture"

[eclarke1]

Feature Description

• Should explain googlesitekit-data usage requirement (central registry, similar to “wp.data”, including in production code it being available as “googlesitekit.data”)
• Should explain where data stores can be found in codebase (if core data store within “assets/js/googlesitekit”, if module data store within “assets/js/modules”)
• Should explain how data stores should be split into multiple “sub data stores” combined with combineStores(), as well as each “sub data store” should include all infrastructure needed for that store to work (i.e. actions, selectors, resolvers, controls, reducer in the same file rather than split by that, which is distinctly different from what Gutenberg does)
• Should explain that API-driven actions and selectors should be using createFetchStore()

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• The "Data store architecture" article should be written.
• It should holistically outlined the data store architecture, but specifically (as part of that) cover the bullet points in the issue description above.
• It should follow the contributor documentation best practices. Please re-read them before starting to write.
  • The article should have roughly between 500-2000 words - no hard limits though. Since this goes into some complex code, it should likely be one of the longer ones.
  • Also before writing, please review the list of all (eventual) articles in the TOC - if you refer to anything that is closely related to an article heading there, or if you refer to something that "undoubtedly" will be covered in a specific other article there, please includes links to such articles, even if they aren't written yet.
    • A more foundational article to link to e.g. in the introduction of this article would be the one written in #3454 (which is actually marked as a prerequisite here).
  • All links to other articles should be relative (i.e. work in the current branch you're in).
• This article specifically is quite engineering-heavy, so it should include a few basic code examples (e.g. registering a store, relying on createFetchStore to implement a "sub-store", ...). Preferably use fake examples for that code, as focused as possible on what you're trying to explain. If there's something more complicated that the article should simply point to, feel free to link to production code (remember to link to a specific tag or commit so that that link doesn't become outdated/invalid).
• The "(TODO)" annotation in the article itself and in the TOC should be removed.

Implementation Brief

Instead of a regular IB, please provide your proposed document outline (nested list of headings) for the article here. Use headings that the article could actually use, not just some brainstorm type of preliminary heading. Please assign to @felixarntz for IB review, specifically since this is one of the first articles in the epic.

Proposed document outline:

Introduction

• Introduce and summarize at a high level the Site Kit Data Store, the use of Redux under the hood, and the use and nuances of @wordpress/data.

Module structure

• Give an overview of the googlesitekit-data module.
• Provide related technical details e.g. exposing googlesitekit.data for production code with googlesitekit-data being defined as an external in Webpack.

Top-level stores

• Explain how store modules are organized in the codebase with core vs module stores.
• Describe how these top-level stores are separate Redux stores, accessible via a central registry.

Store composition

• Describe how stores are composed of "sub-stores" which are themselves discrete store definitions.
• Explain how sub-stores are structured with all of their infrastructure within the same file (as opposed to the Gutenberg approach).
• Mention the existence of "store creators" for pre-rolled sub-store creation, like createFetchStore,

Store creators

API access via createFetchStore

• Describe how the API is accessed by making use of the createFetchStore store creator.

More store creators

• Provide a brief summary of the other store creators.

Examples

• Walk through an example of constructing a simple store.
• Cover store composition via integration with createFetchStore.
• Depending on how it turns out, it might work out better to include examples in line with the rest of the document instead. Otherwise the individual sections can link to areas in this example.

QA Brief

Changelog entry

[eclarke1]

@felixarntz @aaemnnosttv @marrrmarrr this was one of the 4 articles voted highest priority by engineers so if possible to progress this through the workflow along with the others labelled 'Type: Docs' and have P1 assigned.

[eclarke1]

Removing @felixarntz from this one as I don't think it needs to be him that does the IBR cc @bethanylang

[techanvil]

@eclarke1, Felix did explicitly add this point to the IB himself, prior to me picking it up:

Please assign to @felixarntz for IB review, specifically since this is one of the first articles in the epic.

[eclarke1]

@techanvil ah my sincere apologies for missing that! @felixarntz apologies as well. I'll add you back then ;)

[techanvil]

No worries, easily done!