Basics & architecture of Strapi - WEBSALE Dokumentation

This page explains the basic concepts and architecture of Strapi. The goal is to provide an understanding of how Strapi is built as a headless CMS, what role the API-first approach plays, and how content from Strapi is delivered to the WEBSALE shop. This page thus serves as a basis for understanding and confidently applying the other areas of the documentation (in particular content types, components, and content maintenance).

Basics of Strapi

Understanding the Strapi architecture

In Strapi there are two main areas responsible for managing and structuring content: the Content Manager and the Content-Type Builder. These areas complement each other and together provide a powerful toolset for content management and design.

Content-Type Builder & Content Manager

Content-Type Builder: defining structures and components

This area is used to define the structures in which content will later be entered. Here you define which fields and data types the content should have, and you create the components that will then be filled in the Content Manager.

Define structures: The Content-Type Builder is used to create and edit the schemas for collections and single entries. These schemas determine which data fields and data types are available and what the input masks in the Content Manager look like.
Design components: Another important function of the Content-Type Builder is to create reusable components. These components can be used in different parts of the project, thereby promoting consistency and reusability in development.

Content Manager: managing content

Here the content created and maintained in a Strapi project is managed directly. This is where users actually add content such as texts, images, and other media that are displayed on the storefront.

Manage content: In the Content Manager, all content such as texts, images, videos, and other media that are visible directly on the storefront is managed. Users can create new content here, edit existing content, or delete content that is no longer needed.
Organize data: The Content Manager enables systematic organization of content in collections and single entries. This structure helps make content easier to find and manage and supports a clear hierarchy and order within the system.

Interaction of Content Manager and Content-Type Builder

The Content Manager and the Content-Type Builder work hand in hand:

From the builder to the manager: Structures and components created in the Content-Type Builder serve as the basis for content management in the Content Manager. This ensures coherent data handling and efficient content management.
Adaptability and dynamics: Due to the flexible structure of the Content-Type Builder, adjustments can be made that are then reflected in the Content Manager without content being lost or having to be cumbersomely recreated.

Collections, single entries, and components

Collections

Collections in Strapi are structures that serve to manage several similar pieces of data under one roof. They are well suited for organizing content pages, multiple job listings, or even blog articles. A collection thus acts as a central point under which similar content or elements can be subordinated. Collections are available both under the Content Manager and the Content-Type Builder. More information about collections is available here.

Single entries

Single entries are specific content elements that are not necessarily part of a repeatable collection. They can be used for special pages or specific content blocks, such as a banner or a product slider on the home page. Single entries are available both under the Content Manager and the Content-Type Builder. More information about single entries is available here.

Content types for creating new collections & single entries

Content types are the building blocks for structuring content within Strapi. They define how data is organized in collections and single entries. New content types and thus new content under collections and single entries are created in the Content-Type Builder.

To create new content types, support from a WEBSALE employee from system administration is required. They have to enter the new content types in the configuration of the Strapi connector.

Components

Components in Strapi are reusable building blocks that can be used in different parts of the project to design content consistently and efficiently. More information about components is available here.

SEO meta data for CMS pages (meta info plugin)

For CMS pages, the meta info plugin is available by default. It is present on every CMS page and provides fixed, predefined fields there for the SEO details: SEO URL, meta title, meta description, and robots. These fields do not have to be created by you. They are not part of the freely designable content types but are managed by the plugin. As a result, they are present identically on every page and cannot be accidentally changed or deleted while editing content types. This ensures that every page created in Strapi reliably has an SEO URL and can be accessed via it. The values entered are passed on to the shop. The shop sets the meta title and meta description via the same internal mechanism as for category and product pages. They are therefore available in the template as usual via the functions $wsViews.metaTitle() and $wsViews.metaDescription(). In the template, all robots details appear collected under $wsViews.current.robotOptions.

The shop sets these details, it does not output them in the HTML on its own. For the meta title and meta description, the base template usually takes care of this. The robots details and the alternate languages (hreflang), however, are not rendered by the base template as delivered. If you need them, you have to output them yourself in the CMS page template, see Template theme.The configuration node seoMetaData, and in particular viewSchemes within it, concerns the SEO texts of static views. It is not evaluated for CMS pages. Their SEO details come exclusively from the meta info plugin.

Further information:

The meaning of the individual SEO fields is described under Components & collections in Strapi in the section “Meta information”.
Maintaining the meta information per page is illustrated with examples under Editing content in Strapi.
How the shop turns these details into an accessible page is described in the next section.

Delivery of CMS pages to the shop

Static content pages (for example terms and conditions, legal notice, payment methods, “About us”) are maintained in Strapi and transferred to the shop as JSON documents. The shop registers its own SEO URLs for them and renders all these pages with one template.

Strapi (editorial)
   │   content types + meta info plugin (SEO fields)
   ▼
websale-sync  ──►  file group "system"
                     json/<subshopId>/index-mapping.json   ← page directory
                     json/<subshopId>/<…>/<document>.json  ← one document per page
   │
   ├─►  SEO URL generator   registers the SEO URLs (view controller "CmsPage")
   │
   └─►  shop           call of the SEO URL → loads the document → renders cms_tpl.htm
                       The document is available in the template as $wsCmsPage

For a page to appear, two things have to match: the SEO URL must be registered (the SEO URL generator does this based on the page directory) and the page document must be in the object storage. If either of the two is missing, the shop returns a 404 error.

The SEO URL generator

SEO URLs are not created when a page is called, but in a separate process. The SEO URL generator (program seogenerator) iterates over the resources of a subshop and writes an SEO URL for each of them into the shop’s URL inventory. It is not CMS-specific. The same mechanism also registers the URLs of products and categories. Each subshop is processed separately.

Storage in the file group `system`

The paths are hard-wired and not configurable. It is the same file group that templates reach via the load option source: "system" (see $wsExternalData).

File	Path within the file group `system`
Page directory	`json/<subshopId>/index-mapping.json`
Page document	`json/<subshopId>/<file>`

<subshopId> is the ID of the subshop, for example deutsch, english, francais. Each subshop has its own folder and reads exclusively its own page directory.
The name of the directory file is configurable via cmsTemplates.mappingFile (default index-mapping.json). The folder json/ is not.
The folder structure below json/<subshopId>/ is arbitrary. The Strapi structure is common, for example collections/contentpage/jyllb6ubw0dj62vndr0lh7z1.json.

The file name has no meaning. It has no influence on the URL of the page. That is defined exclusively in the field url in the page directory or in meta.url of the document.

Which URL belongs to which file

The page directory answers this question:

{
  "mappings": [
    {
      "url": "Zahlungsarten",
      "file": "collections/contentpage/jyllb6ubw0dj62vndr0lh7z1.json",
      "subshop": "deutsch",
      "stage": "live"
    },
    {
      "url": "AGB",
      "file": "collections/contentpage/agb1.json"
    }
  ]
}

Field	Required	Meaning
`url`	yes	The accessible URL of the page, without a leading slash. If it is empty or `null`, the entry is ignored.
`file`	yes	Path of the document relative to `json/<subshopId>/`. If it is empty, the entry is ignored.
`subshop`	no	Subshop the page belongs to. Empty or missing = applies to every subshop. If a subshop other than the reading one is specified here, the entry is skipped.
`stage`	no	`live` or empty/missing = is published. Any other value (for example `draft` or `preview`) is skipped.

On each run of the SEO URL generator, the URLs of all matching entries are re-registered, and all already registered CMS URLs that are no longer in the directory are removed. As a result, a page that has been deleted or set to stage:draft disappears by itself the next time the SEO URLs are generated.

The cleanup only takes place in a full run. If a single page is re-registered via POST seo/urls/reset, no URLs are removed. If the page directory cannot be read, the run aborts early and neither are new URLs registered nor old ones removed.Not to be confused with the option “delete URLs that are no longer used” (deleteOld) when triggering the run: the removal of vanished CMS pages happens independently of it.

Notes on the URL

The value from url is taken over as the final path. The shop merely adds a slash in front and, if necessary, appends the trailing slash. This has several consequences:

No leading slash. The shop adds it itself. A value like "/AGB" leads to a double separator (//AGB) and thus to an unreachable page.
The trailing slash is added automatically according to the shop configuration (urls.urls.alwaysEndWithSlash).
No character set check and no normalization. Uppercase letters are explicitly common (AGB, Zahlungsarten).
The shop’s URL processing does not apply here. Of the settings under urls.urls, only active and alwaysEndWithSlash (plus suffixSeparator in the event of a collision) affect CMS URLs. lowercase, wordSeparator, and the character mappings for umlauts are not applied – unlike for category and product URLs. So even with lowercase: true, AGB becomes the path /AGB.
The URL is compared exactly when called, that is, including upper and lower case. /agb does not find a page registered as AGB.
Special characters and spaces must already be encoded. The value is treated as an already encoded path and is decoded. It is cleaner to avoid them in Strapi.
URLs already set manually in the Admin Interface win. If a manually set URL exists for a page, the value from the page directory is silently ignored, without a log message. A changed url then has no effect.
In the event of a path collision, the shop appends suffixSeparator plus a number instead of aborting the registration. The page is then reachable under an unexpected URL, and there is no log message about it. Older paths of the same page are redirected to the current path via 301.

Because the shop does not normalize anything, the URL must already be maintained in Strapi exactly as it should appear in the browser. This is intentional: page names like AGB should not be altered by automatic lowercasing.

The page document

Every document has the same outer structure, the so-called “envelope”: contentType, meta, and fields. It is the same envelope as in the schema format of the sync middleware, which is described in detail under Migration of the Strapi data structure (version 5).

{
  "contentType": "api::contentpage.contentpage",
  "meta": {
    "id": 92,
    "documentId": "jyllb6ubw0dj62vndr0lh7z1",
    "locale": "de",
    "createdAt": "2026-06-26T08:00:00.000Z",
    "updatedAt": "2026-07-16T09:00:00.000Z",
    "publishedAt": "2026-07-16T09:03:00.000Z",
    "url": "Zahlungsarten",
    "metaTitle": "Zahlungsarten",
    "metaDescription": "Beschreibung zu Zahlungsarten",
    "robots": ["noindex", "nofollow"],
    "hreflang": [
      {
        "language": "fr-fr",
        "url": "myshop.fr/paiement",
        "subshopId": "francais",
        "default": false
      }
    ]
  },
  "fields": [
    { "name": "Markup", "type": "richtext", "value": "AGB Content" },
    {
      "name": "content",
      "type": "dynamiczone",
      "value": [
        {
          "component": "elemente.ws-markup",
          "id": 96,
          "fields": [
            { "name": "FullWidth", "type": "boolean", "value": false }
          ]
        }
      ]
    }
  ]
}

Level	Content	How the shop handles it
`contentType`	Content type of the page	read, but not evaluated
`meta`	Strapi administrative data plus SEO block	partially evaluated, see below
`fields`	The editorial content, structure freely defined by the customer’s modeling	passed through unchanged. The shop does not interpret anything here.

The principle here is: the envelope is fixed, the content is free.
The shop only guarantees the evaluation of the SEO block. What fields looks like is determined solely by the modeling of the content types in Strapi. How it is displayed is determined solely by the template.

There are no content block types predefined by the shop. The shop does not know any fixed building blocks like “heading” or “image” with a guaranteed meaning. Which field names and components exist results from the Strapi modeling of the respective shop, and their display is entirely the template’s responsibility.

The SEO block in `meta`

The shop evaluates these fields:

Field	Type	Required	Effect
`url`	text	yes for `seo/urls/reset`	The URL of the page, without a leading slash. In the full run, the value from the page directory counts; when resetting a single URL via `POST seo/urls/reset`, however, this value counts. If it is missing there, no SEO URL is created. Both values should match.
`metaTitle`	text	recommended	Is set as the meta title of the page (browser tab, search result).
`metaDescription`	text	optional	Is set as the meta description.
`robots`	list of texts	optional	Each entry is added to the robots details of the page, for example `["noindex", "nofollow"]`. Entries that are not text are silently skipped.
`publishedAt`	timestamp or `null`	yes, for public visibility	Controls draft/published, see below.

All other meta fields (id, documentId, locale, createdAt, updatedAt) are Strapi administrative data. They are not evaluated but are available to the template. meta.hreflang is part of the envelope and is available in the template, but it is not automatically included in the shop’s hreflang details. $wsViews.current.getHreflangAutomatic() returns nothing for CMS pages. If you want to output alternate languages, you have to render them yourself in the template, see Template theme.

Draft and publication

There are two switches that are independent of each other:

stage in the page directory decides whether the URL is created at all. live or empty → the URL is registered. Anything else → no entry, the page is not addressable.
meta.publishedAt in the document decides whether the page is delivered.

`publishedAt`	Public call	With an active test mode session
Timestamp set	Page is delivered	Page is delivered
`null` or missing	404	Page is delivered (preview)

Drafts can therefore be previewed in the shop by enabling test mode, just like other preview content. See Enabling and disabling shop test modes.

Only the presence of a value is checked, not whether the point in time is in the past. A publishedAt in the future publishes the page immediately. Scheduled publication via the shop is therefore not possible. It has to take place on the Strapi side, since Strapi only sets the publishedAt field when publishing.

Configuration

The configuration node cmsTemplates is located in the content area:

{
  "cmsTemplates": {
    "template": "cms_tpl.htm",
    "mappingFile": "index-mapping.json"
  }
}

Parameter	Default	Meaning
`template`	`cms_tpl.htm`	Template used to render CMS pages. Path relative to `templates/views/`.
`mappingFile`	`index-mapping.json`	Name of the directory file in `json/<subshopId>/`

The node is a singleton and can be overridden per subshop. All details under content.cmsTemplates.

If a CMS page does not appear

Symptom	Likely cause	Check
The page returns 404	The SEO URL is not registered.	Is the page listed in the page directory with `url` and `file`? Does `subshop` match the subshop being called? Is `stage` set to `live` or empty? Are SEO URLs active at all (`urls.urls.active`)? Did the SEO URL generator run since the last change?
Not a single CMS page is reachable	`cmsPage` is missing in `urls.urls.generate`, or no run has taken place yet.	The SEO URL generator
The page returns 404 although the URL is registered	The document is missing, empty, or not readable, or it is a draft.	Is the file located under `json/<subshopId>/<file>`? Is `meta.publishedAt` set? Is the file valid JSON (log code `cmsTemplates.jsonParseError`)?
The page is reachable under `//AGB` or not at all	`url` contains a leading slash.	Remove the leading slash from `url`.
The page is reachable under a URL with an appended number	The path collides with an already registered URL.	Resolve the colliding URL in the Admin Interface or in the page directory.
A changed `url` has no effect; the page remains under the old address	A URL has been set manually for the page in the Admin Interface. It is not overwritten, and there is no log message about it.	Check the manual URL of the resource in the Admin Interface, see API reference SEO URLs.
A deleted page is still reachable	No full run took place, or the run aborted at the page directory.	Check the log for `cmsTemplates.generateNoMapping` and `cmsTemplates.generateMappingParseError`.
The page appears, but without content from `fields`	A field name or component name in the template does not match the Strapi modeling.	Template theme

The messages of the SEO URL generator and of the page call can be found in the LogManager via these codes:

Log code	Meaning
`cmsTemplates.generateNoMapping`	The page directory could not be read. The run aborts.
`cmsTemplates.generateMappingParseError`	The page directory is not valid JSON.
`cmsTemplates.generateSkippedMapping`	An entry was skipped. The message states `url`, `stage`, and `subshop`.
`cmsTemplates.generateSingleReadError`	For `seo/urls/reset`, the document was not readable.
`cmsTemplates.generateSingleParseError`	For `seo/urls/reset`, the document was not valid JSON.
`cmsTemplates.generateSingleNoUrl`	For `seo/urls/reset`, `meta.url` was missing in the document.
`cmsTemplates.jsonParseError`	When the page was called, the document was not valid JSON. The shop returns 404.

Media library

Strapi has an integrated media library that enables central management of media such as images, PDFs, and other files. All uploaded images and files are stored in the media library and can be managed from there. This includes deleting, replacing, or reusing media in different parts of the Strapi project.

Uploading media

Media can either be uploaded directly to the media library or added during content maintenance. When media is needed while editing content, the media library can be used. Here you have the option to select already uploaded files or to add new files.

Automatic image conversion

Strapi has a built-in converter that automatically compresses uploaded images to improve loading times and optimize storage requirements. In addition, the WEBSALE image converter is used, which converts images into the SourceFormat and the WebP format. These formats offer improved compression rates and are optimized for web use.

Template integration

The template manager defines within the template which image is used in which format. New images and media elements added to the media library must therefore be placed and configured in the template according to the template manager’s specifications. More information for template managers is available here.

Extending Strapi for subshops

Create a new language

Settings → Internationalization
“Add new language”
Select language.
Do not change the display name.
Note / copy the locale ID. For example, “French (fr)” - fr would be the locale ID here.
Save.

Assign a language to a subshop

Content Manager → Configuration
Choose ”+ Add entry” or edit an existing one.
Under “WEBSALE Subshop ID”, a comma-separated list of subshop IDs can now be entered.
Under “Strapi locale ID”, the “locale ID” copied in the previous step must be inserted.
Save afterwards.

The WEBSALE Strapi connector now automatically considers the new language.
Content maintained in the Content Manager for this language is placed on the shop server in the directories for subshops. Each value (comma-separated) represents a subshop folder.

​Basics of Strapi

​Understanding the Strapi architecture

​Content-Type Builder & Content Manager

​Content-Type Builder: defining structures and components

​Content Manager: managing content

​Interaction of Content Manager and Content-Type Builder

​Collections, single entries, and components

​Collections

​Single entries

​Content types for creating new collections & single entries

​Components

​SEO meta data for CMS pages (meta info plugin)

​Delivery of CMS pages to the shop

​The SEO URL generator

​Storage in the file group system

​Which URL belongs to which file

​Notes on the URL

​The page document

​The SEO block in meta

​Draft and publication

​Configuration

​If a CMS page does not appear

​Media library

​Uploading media

​Automatic image conversion

​Template integration

​Extending Strapi for subshops

​Create a new language

​Assign a language to a subshop

Basics of Strapi

Understanding the Strapi architecture

Content-Type Builder & Content Manager

Content-Type Builder: defining structures and components

Content Manager: managing content

Interaction of Content Manager and Content-Type Builder

Collections, single entries, and components

Collections

Single entries

Content types for creating new collections & single entries

Components

SEO meta data for CMS pages (meta info plugin)

Delivery of CMS pages to the shop

The SEO URL generator

Storage in the file group `system`

Which URL belongs to which file

Notes on the URL

The page document

The SEO block in `meta`

Draft and publication

Configuration

If a CMS page does not appear

Media library

Uploading media

Automatic image conversion

Template integration

Extending Strapi for subshops

Create a new language

Assign a language to a subshop