Update diagrams and description

shopware · Jan 17, 2024 · db9ece6 · db9ece6
1 parent 0525108
commit db9ece6
Show file tree

Hide file tree

Showing 17 changed files with 116 additions and 434 deletions.
diff --git a/concepts/commerce/catalog/products.md b/concepts/commerce/catalog/products.md
@@ -11,59 +11,75 @@ Products are sellable entities (physical and digital products) within your shop.
 
 Depending on your setup, Shopware can easily handle thousands of products. However, an upsurge in the product quantity (in millions) needs some tweaks for robust running of the environment as it depends on factors like the number of [categories](../../../../docs/concepts/commerce/catalog/categories), [sales channels](../../../../docs/concepts/commerce/catalog/sales-channels), [product properties](../../../../docs/concepts/commerce/catalog/products#property-groups--options), etc. Every product added to your shop can be made available on one or more [sales channels](../../../../docs/concepts/commerce/catalog/sales-channels).
 
-Let us start understanding about product more in detail:
+Let's delve into a more detailed understanding of products using the example of garments:
 
-* **Product details**: General information about a Product - for example, title, manufacturer, prices, media, etc.
-* **Product properties**: Product properties encapsulates property groups and options.
-* **Product variant**: A sellable good. Product Variants are generally mapped to products. Inventory is modeled per variant.
-* **Category**: Products in Shopware are organised in categories. It is a grouping of products based on characteristics, marketing or search concerns. Categories are represented as a hierarchical tree to form a navigation menu. A product can be contained in multiple categories.
+* **Product details**: General information about a Product.
+
+| Title | Product Id| Manufacturer | Prices | more.... |
+|-------|-----------|--------------|--------|----------|
+|levis Ocean Hoodie| SW1001 | CA | 40 | ... |
+
+* **Product properties**: Product properties encapsulates property groups and options. They can be displayed in a table on your product detail pages, in listings, or even be used for filtering.A product can have arbitrarily many property group options.
+
+|Property Group| Property Group options|
+|--------------|-----------------------|
+|Size          |  *S*, *M*, *L*, *XL*, etc |
+|Color         | *Red*, *Blue*, *Green*, *Black* |
+|Material      | *Leather*, *Cotton*, *Jeans* |
+
+* **Category**: Products in Shopware are organized in categories. It is a grouping of products based on characteristics, marketing or search concerns. Categories are represented as a hierarchical tree to form a navigation menu. A product can be contained in multiple categories.
 
 Look at the below condensed overview of the product data model:
 
 ```mermaid
 erDiagram
-    Product}|--|{ Category : has
+    Product||--|{ ProductCategory : "m:1"
+    ProductCategory}|--|| Category : "1:m"
     Product {
-        Example Levis_Ocean_Hoodie
+        uuid product_id
+    }
+    ProductCategory {
+        uuid product_id 
+        uuid category_id 
     }
     Category {
-        Example Hoodies
+        uuid category_id
+    }
+    Product ||--|{ ProductOption : "1:m"
+    ProductOption{
+        uuid product_id
+        uuid property_group_option_id
     }
-    Product ||--|{ Product-Group-Option : has
-    Product-Group-Option{
-        Example Leather
+    ProductOption }|--|| PropertyGroupOption : "m:1"
+    PropertyGroupOption{
+        uuid property_group_option_id
+        uuid property_group_id
     }
-    Product-Group-Option ||--|| Product-Group : belongs
-    Product-Group{
-        Example Material
+        PropertyGroupOption }|--|| PropertyGroup : "m:1"
+    PropertyGroup{
+        uuid property_group_id
     }
 ```
 
 Besides their relation to categories, products can also link to a set of *property group options*.
 
-## Property groups and options
-
-Product properties can be modeled using property groups and -options. They can be displayed in a table on your product detail pages, in listings, or even be used for filtering.
-
-Examples of property group garments are *Size*, *Color* or *Material*. The corresponding values of each group are referred to as *property group options*. A product can have arbitrarily many property group options.
-
-## Product variants
-
-Different variations of a product can be modeled using *product variants*. Products are a self-referencing entity, which is interpreted as a parent-child relationship. This mechanism is also used to model variants. This also provides inheritance between field values from parent products to child products.
+* **Product variant**: A sellable product. Products are a self-referencing entity, which is interpreted as a parent-child relationship. Similarly, product variants are also generally mapped to products. This mechanism is used to model variants. This also provides inheritance between field values from parent products to child products.
 
 ```mermaid
 erDiagram
-    Product||--|| Product : is
+    Product||--|| Product : "uuid=variant"
     Product {
-        Example Levis_Ocean_Hoodie
+        uuid product_id
+        uuid parent_id
     }
-    Product ||--|{ Product-Group-Option : has
-    Product-Group-Option{
-        Example Leather
+    Product ||--|{ PropertyGroupOption : "1:m"
+    PropertyGroupOption{
+        uuid property_group_option_id
+        uuid property_group_id
     }
-    Product-Group-Option ||--|| Product-Group : belongs
-    Product-Group{
-        Example Material
+    PropertyGroupOption }|--|| PropertyGroup : "m:1"
+    PropertyGroup{
+        uuid property_group_id
     }
 ```
 
@@ -83,7 +99,12 @@ Opposed to that **options** are considered variant defining, as they are the fac
 
 It is important to understand the difference between those two because both provide a relation between the product and the property group option entity. However only one constitutes to product variants.
 
-### Configurator
+| Variant | Product | Category | Product group | Product group option |
+|---------|---------|----------|---------------|----------------------|
+|Variant 1| Levis Ocean Hoodie | Hoodie & Sweaters | Color | Red |
+|Variant 2| Levis Ocean Hoodie | Hoodie & Sweaters | Color | Black |
+
+## Configurator
 
 When a variant product is loaded for a [Store API](../../api/store-api)-scoped request, Shopware assembles a configurator object which includes all different property groups and the corresponding variants. This way client applications, such as the [Storefront](../../../guides/plugins/plugins/storefront/) or the [PWA](../../../products/pwa) can display the different variant options of the product.
 

diff --git a/concepts/commerce/checkout-concept/cart.md b/concepts/commerce/checkout-concept/cart.md
@@ -31,36 +31,7 @@ The cart has very few hard dependencies on other core entities in Shopware 6. En
 
 An instance of this class represents one single cart. As shown in the diagram below, relations to central Entities of the system are omitted. This allows Shopware 6 to manage multiple carts per user, per sales channel, or across all sales channels. The only identification is a token hash.
 
-```mermaid
-classDiagram
-    Cart .. Price
-    Cart .. Error
-    Cart .. Transaction
-    Cart .. Delivery
-    Cart .. LineItem3
-    Cart .. LineItem1
-    Cart .. LineItem2
-    LineItem3 .. Promotion
-    LineItem1 .. Product1
-    LineItem2 .. Product2
-    namespace CART {
-        class Error
-        class Price
-        class Transaction
-        class Delivery
-        class LineItem1
-        class LineItem2
-        class LineItem3
-        class Promotion
-        class Cart {
-        Central_in_memory_representation_of_a_single_cart's_state
-    }
-}
-    namespace CONTENT {
-    class Product1
-    class Product2
-    }
-```
+![Representation of the cart struct](../../../assets/cart-struct.png)
 
 This highly mutable data structure is acted upon from requests and calculated and validated through services. It contains:
 
@@ -103,30 +74,19 @@ title: Cart State
 ---
 stateDiagram-v2
     [*] --> Empty
-    note left of Empty
-            An empty cart
-            > default shipping
-            > default payment
-        end note
     Empty --> Dirty : add line item
-    note left of Dirty
-        A modified cart but
-        > invalid prices
-        > raw line items
-        > unknown delivery validity
-
-        calculation required
-    end note
     Dirty --> Calculated : calculate
-    note left of Calculated
-    This cart can either be ordered or has errors that must be resolved
-
-    end note
     Calculated --> Dirty : modify line item/shipping/payment
     Calculated --> Calculated : order invalid
     Calculated --> [*] : order
 ```
 
+|Cart state | Description|
+|------|------------|
+|Empty | A cart with no items will have default shipping and payment settings. |
+|Dirty | On adding a new line item, the cart undergoes modifications with invalid prices, raw line items, and uncertain delivery validity. Consequently, calculations are necessary.|
+|Calculated | After accurate calculations, the cart can be either submitted as an order or may contain errors that need to be addressed. |
+
 ## Calculation
 
 Calculating a cart is one of the more costly operations an ecommerce system must support. Therefore the interfaces of the cart are designed as precise and as quick as possible. The calculation is a multi-stage process that revolves around the mutation of the data structure of the cart struct shown in the diagram below:
@@ -137,28 +97,20 @@ title: Cart Calculation
 ---
 stateDiagram-v2
     [*] --> Enrich
-    note left of Enrich
-            Process line items
-            > add images and descriptions
-            > determine prices
-        end note
     Enrich --> Process
-    note left of Process
-        Update price, shipping and payment
-    end note
-    Process --> Validate : calculate
-    note left of Validate
-    Validate through the rule system and 
-    check plausibility change in cart accordingly
-    end note
+    Process --> Validate
     Validate --> Validate : repeat until no changes occur
     Validate --> Persist
-    note left of Persist
-    Update storage
-    end note
     Persist --> [*]
 ```
 
+|Cart calculation state | Description|
+|------|------------|
+|Enrich | The calculation process in the "enrich" state for line items involves adding images, its descriptions and determining prices|
+|Process | During the process state, price updates occur, adjustments to shipping and payment are made|
+|Validate | In the validate state, validation is performed using the rule system and cart changes based on plausibility checks. |
+|Persist | The persist state is responsible for updating the storage. |
+
 ### Cart enrichment
 
 Enrichment secures the *Independence_ and _Adaptability* of Shopware 6. As shown in the below code snippet, the cart can create and contain line items that are initially empty and will only be loaded \(enriched\) during the calculation.
@@ -196,22 +148,18 @@ sequenceDiagram
 Enrichment->>Enrichment : 
 box
     participant Enrichment
-    participant ProductCollector
-    participant PromotionCollector
-    participant DiscountCollector
+    participant ProductCartProcessor
+    participant CartPromotionsCollector
+    participant CartDiscountCollector
     end
-    Note over Enrichment,DiscountCollector: Preparation
-    Enrichment->>ProductCollector: prepare
-    Enrichment->>PromotionCollector: prepare
-    Enrichment->>DiscountCollector: prepare
-    Note over Enrichment,DiscountCollector: Collect
-    Enrichment->>ProductCollector: collect
-    Enrichment->>PromotionCollector: collect
-    Enrichment->>DiscountCollector: collect
-    Note over Enrichment,DiscountCollector: Enrichment
-    Enrichment->>ProductCollector: enrich
-    Enrichment->>PromotionCollector: enrich
-    Enrichment->>DiscountCollector: enrich
+    Note over Enrichment,CartDiscountCollector: Collect
+    Enrichment->>ProductCartProcessor: collect
+    Enrichment->>CartPromotionsCollector: collect
+    Enrichment->>CartDiscountCollector: collect
+    Note over Enrichment,CartDiscountCollector: Enrichment
+    Enrichment->>ProductCartProcessor: enrich
+    Enrichment->>CartPromotionsCollector: enrich
+    Enrichment->>CartDiscountCollector: enrich
     Enrichment->>Enrichment : 
 ```
 
@@ -235,7 +183,7 @@ After the cart has been processed, it is validated against the rules, which can
 ```mermaid
 stateDiagram-v2
     [*] --> Empty_cart : checkout started
-    Empty_cart --> Cart_with_lineitem(car) : User orders a car
+    Empty_cart --> Enrichment : User orders a car
         state Enrichment {
     Cart_with_lineitem(car) --> Cart_with_lineitem(car+sunglasses) : Iteration 1 - Cart automatically adds sunglasses
     Cart_with_lineitem(car+sunglasses) --> Cart_with_lineitem(car+sunglasses+2%discount) : Iteration 2 - Cart automatically adds discount

diff --git a/concepts/commerce/content/shopping-experiences-cms.md b/concepts/commerce/content/shopping-experiences-cms.md
@@ -143,15 +143,7 @@ Whereas the structure of a CMS page remains somewhat static, its content can be
 
 The following diagram illustrates how that works using the example of a category:
 
-```mermaid
-flowchart TD
-    A["`Load category **A**`"] --> B["`Load CMS layout associated with category **A**`"]
-    B --> C["`Build **resolver context** containing context information of category **A**`"]
-    C --> D["`For every element in the CMS layout`"]
-    D --> E["`**Element resolver** - Assembles criteria to fetch data based on the resolver context`"]
-    E --> F["`Fetch **dynamic configuration** and use it to override existing slot configuration`"]
-    F --> G["`Respond with dynamically hyderated CMS page`"]
-```
+![Flow of resolving CMS page content](../../../assets/concept-commerce-shoppingExperiences-resolvingCmsPage.png).
 
 Let's go through the steps one by one.
 

diff --git a/concepts/extensions/index.md b/concepts/extensions/index.md
@@ -11,27 +11,13 @@ In order to provide users \(i.e., developers\) with a clear abstraction, Shopwar
 
 ## Apps
 
-```mermaid
-flowchart LR
-    subgraph Shopware PHP Process 
-    A(Core)
-    end
-    A(Core) -->|Notification webhook| B(App)
-    B(App) --> | REST API| A(Core)
-```
+![](../../assets/app-extension-model.png)
 
 Starting with Shopware 6.4.0.0, we introduced a new way to extend Shopware using the newly created app system. Apps are not executed within the process of the Shopware Core but are notified about events via webhooks, which they can register. They can modify and interact with Shopware resources through the [Admin REST API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide).
 
 ## Plugins
 
-```mermaid
-flowchart-elk LR
-subgraph Shopware PHP Process
-    A(Core)--PHP API-->B(Plugins)
-end
-    A-->C[Database]
-    B-->C
-```
+![](../../assets/plugin-extension-model.png)
 
 Plugins are executed within the Shopware Core process and can react to events, execute custom code or extend services. They have direct access to the database and guidelines are in place to ensure update-compatibility, such as a service facade or database migrations.
 

diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md
@@ -99,37 +99,7 @@ Once we have set all the necessary information to our page \(`AccountOrderPage`\
 
 To summarize the composition of a page, have a look at this diagram:
 
-```mermaid
-flowchart TD
-    A["`**Account Order Controlled**
-    _Storefront Controller_`"]
-    B["`**Account Order Page Loader**
-    _Page Loader_`"]
-    A --> |calls|B
-    B--> |receives Page & throws LoadedEvent|A
-    C["`**Account Order Page**
-    _Page_`"]
-    B-->|creates|C
-    C-->|receives|B
-    D["`**OrderRoute**
-    _store-api/v(version)/order_`"]
-    C-->|calls|D
-    D-->|receives|C
-    E["`**Twig Template**
-    _render Storefront_`"]
-    A-->|sends Page|E
-    F["`**Generic Page Loader**
-    _Generic Page_`"]
-    G["`**Header, Footer, etc**
-    _Pagelets_`"]
-    C-->|calls|F
-    F-->|receives|C
-    G-->|receives|F
-    H["`**Ordinary repository**
-    _Entity Repository_`"]
-    D-->|calls|H
-    H-->|receives|D
-```
+![Composition of a Storefront page](../../../assets/concepts-storefront-composite-data-loading.png)
 
 ## Translations