> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/architecture.md).

# Architecture

A thin layer between an Emporix storefront and the @contenter/\* SDK, plus a component library.

## What the plugin is

A thin layer between an Emporix storefront and the `@contenter/*` SDK, plus a component library.

* **The SDK owns** page delivery, slot composition, the live-preview protocol, the draft/live model, the configuration from the environment, the Emporix token and the theme stylesheet.
* **The plugin owns** what is specific to an Emporix storefront:
  * the component library;
  * the category tree and product search behind the editor's pickers;
  * the theme-token manifest the theme editor offers;
  * the wiring, declared in `plugin.json` and generated by the storefront's `npm run generate`.
* **The storefront owns** its routes and any components of its own. It edits none of its files to install the plugin; its header and footer are replaced by the CMS layout while Contenter is the active CMS.

## Layers

```
src/app/…
    the storefront's own CMS routes (unchanged) + generated route files
   │
   ▼
extensions/medienwerft-cms-plugin

   components/        <CmsRoot>, getCmsBodyProps, default chrome,
                      CmsLayoutSlots, CmsProviders

   lib/               cms-server.ts (CmsPage, CmsLayout, resolvePage), theme
                      read, pickers

   route-handlers/    dispatch.ts → draft · page-index · component-registry ·
                      revalidate · categories/tree ·
                      theme/{site}/cms-theme.css

   pages/             createCmsEditorRoute

   library/           components/, definitions/, registry.ts, decorators/

   services/,         CmsAdapter:contenter, category tree (Emporix catalogue),
   integrations/      theme-token manifest

   │
   ▼
@contenter/* SDK (vendor/*.tgz)  →  cms-api (Emporix cloud function or hosted)
```

## The component library

Two halves, built from ONE definitions map so they cannot disagree:

| Half                                             | Module                                                     | Read by                                                         |
| ------------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------- |
| Definitions (server-readable, no `'use client'`) | `library/definitions` → `libraryDefinitions({ nestable })` | the component-registry route → the editor's palette             |
| Registry (`'use client'`)                        | `library/registry.ts` → `libraryRegistry(definitions)`     | the preview runtime → in-preview operations such as "move into" |

A storefront with no components of its own touches neither. `CmsProviders` defaults to `libraryRegistry()`, and the registry route publishes `libraryDefinitions()` when no `EmporixCMSComponentService` is bound.

A storefront that adds components composes both halves itself, binds `EmporixCMSComponentService`, and hands its registry to the plugin in `src/cms/storefront-components.ts`. Medienwerft's showcase storefront does this for its CMS-authored header, top bar and footer.

## Decoration

`cms-category-tile-row` needs category names and images the CMS does not store. A decorator adds them:

* **On the server**, in every read, through `libraryServerDecorators`.
* **In the browser**, after every editor push, through `libraryClientDecorators`. The editor pushes raw content, so both halves are needed.

A storefront binding its own `CMSComponentDecoratorService` replaces the server half and spreads the library's in.

## How the storefront reaches the plugin

All declared in `plugin.json` (see the storefront's `extensions/README.md`):

* `routes`: `api/cms/[...cms]` → `route-handlers/dispatch.ts`; `[site]/[locale]/cms-editor` → `pages/cms-editor-route.tsx`.
* **`CmsAdapter:contenter`**, selected with `NEXT_CMS_PROVIDER=contenter`. Its hooks:

  * `providesLayout` + `Layout` (`components/contenter-layout.tsx`): the CMS layout's slots around every page. The storefront's shop shell renders the `default` layout (`CMS_DEFAULT_LAYOUT_ID`) and its checkout shell the `reduced` one (`CMS_REDUCED_LAYOUT_ID`, default `checkout`); the storefront's own header and footer are not rendered.
  * `PageRenderer` (`components/contenter-page.tsx`): a CMS page's `main` slot. The storefront's `CmsPage` shell hands every page to it, so the home page and the catch-all are not edited.
  * `Root` and `getBodyProps`: `<CmsRoot>` and `getCmsBodyProps` in both root layouts. `Root` takes the storefront's own registry from `src/cms/storefront-components.ts` (`lib/storefront-components.ts`).

  Being adapter hooks rather than `plugin.json` fields, all of them apply only while Contenter is the active provider. `getPage` serves the catch-all's metadata. The adapter loads the plugin's server code lazily: it sits in the DI containers, and `lib/cms-server.ts` reads the SSR container while loading.
* `csrfExempt`, `alwaysInclude`, `env` and `dependencies`, as described in [chapter 3](https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/install-the-plugin.md).

## Configuration

`lib/cms-server.ts` reads the environment once with the SDK's `cmsConfigFromEnv()` and logs its problems as `[cms] …`. The base URL decides the mode:

* **Behind the Emporix gateway**, the client mints an Emporix token from `CMS_EMPORIX_CLIENT_ID` / `_SECRET`, or from the storefront's `NEXT_EMPORIX_CLIENT_*`.
* **Against a hosted cms-api**, the client reads with `CMS_API_KEY`.

`CMS_API_KEY` also gates the preview route and signs the preview token the draft route checks. It never leaves the server.

## Theme

`<CmsRoot>` links `/api/cms/theme/{site}/cms-theme.css?v=<hash of the theme's content>`, with `precedence` so it comes after the storefront's own theme.

* **Caching:** the URL changes with the content, so it is cached for good.
* **Editor:** the theme editor previews unsaved values in the browser. Its baseline measurement ignores this link by default.

## Extension points

| To change                          | Do                                                                                                                                                                                                                                                                                     |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The components offered             | compose `libraryDefinitions` / `libraryRegistry`, bind `EmporixCMSComponentService`, export the registry from `src/cms/storefront-components.ts` — [chapter 6](https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/your-own-components.md) |
| What a component's data includes   | bind `CMSComponentDecoratorService`; hand the browser half over as `decorators` in `src/cms/storefront-components.ts`                                                                                                                                                                  |
| The header and footer              | author them in the CMS layouts (`default`, `checkout`) with components of your own — [chapter 5](https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/site-layout.md)                                                                       |
| The theme tokens the editor offers | bind your own `CMSThemeTokenManifestService` and re-point the alias in `plugin.json`                                                                                                                                                                                                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/architecture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
