UML diagrams (#1255)

* update data structure diagram * Update diagrams and description * add diagram code to rules and audit * update cardinality * update corrections * update cardinality * remove old images and update multi-inventory
shopware · Jan 30, 2024 · 6b75a56 · 6b75a56
1 parent adea36f
commit 6b75a56
Show file tree

Hide file tree

Showing 20 changed files with 281 additions and 42 deletions.
diff --git a/assets/auditlog-structure.svg b/assets/auditlog-structure.svg
diff --git a/assets/cart-calculation-steps.png b/assets/cart-calculation-steps.png
diff --git a/assets/cart-enrichtment-steps.png b/assets/cart-enrichtment-steps.png
diff --git a/assets/cart-state.png b/assets/cart-state.png
diff --git a/assets/cart-validation.png b/assets/cart-validation.png
diff --git a/assets/concept-catalog-products-datamodel.png b/assets/concept-catalog-products-datamodel.png
diff --git a/assets/concept-catalog-products-variantModel.png b/assets/concept-catalog-products-variantModel.png
diff --git a/assets/flow-concept-1.png b/assets/flow-concept-1.png
diff --git a/assets/flow-concept-2.png b/assets/flow-concept-2.png
diff --git a/assets/multi-inventory-data-structure.png b/assets/multi-inventory-data-structure.png
diff --git a/assets/rule-objects.png b/assets/rule-objects.png
diff --git a/assets/rule-sequence.png b/assets/rule-sequence.png
diff --git a/concepts/commerce/catalog/products.md b/concepts/commerce/catalog/products.md
@@ -11,32 +11,77 @@ 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](../../../concepts/commerce/catalog/categories), [sales channels](../../../concepts/commerce/catalog/sales-channels), [product properties](../../../concepts/commerce/catalog/products#property-groups--options), etc. Every product added to your shop can be made available on one or more [sales channels](../../../concepts/commerce/catalog/sales-channels).
 
-Let us start understanding about product more in detail:
-
-* **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.
-
-Look at the below condensed overview of the product data model:
-
-![Condensed overview of the product data model](../../../assets/concept-catalog-products-datamodel.png)
-
-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.
-
-![Variant model](../../../assets/concept-catalog-products-variantModel.png)
-
-However, it is also useful to attach some additional properties to differentiate product variants next to the field inheritance. For that reason, it is critical to understand the difference between *properties* and *options*:
+Let's delve into a more detailed understanding of products using the example of garments:
+
+* **Product details**: General information about a Product.
+
+| Title | Product Id | Manufacturer | Prices | .... |
+|-------|-----------|--------------|--------|----------|
+| Levis Ocean Hoodie | SW1001 | CA | 40 | ... |
+
+* **Product properties**: Product properties encapsulates property groups and options. They are displayed in a table on product details page, 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 relationships between entities - products, categories, options, and property groups are interconnected in the database schema.
+
+```mermaid
+erDiagram
+    Product||--|{ ProductCategory : "M:1"
+    ProductCategory}|--|| Category : "1:M"
+    Product {
+        uuid product_id
+    }
+    ProductCategory {
+        uuid product_id 
+        uuid category_id 
+    }
+    Category {
+        uuid category_id
+    }
+    Product ||--|{ ProductOption : "1:M"
+    ProductOption{
+        uuid product_id
+        uuid property_group_option_id
+    }
+    ProductOption }|--|| PropertyGroupOption : "M:1"
+    PropertyGroupOption{
+        uuid property_group_option_id
+        uuid property_group_id
+    }
+        PropertyGroupOption }|--|| PropertyGroup : "M:1"
+    PropertyGroup{
+        uuid property_group_id
+    }
+```
+
+* **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 : "uuid=variant"
+    Product {
+        uuid product_id
+        uuid parent_id
+    }
+    Product ||--|{ PropertyGroupOption : "1:M"
+    PropertyGroupOption{
+        uuid property_group_option_id
+        uuid property_group_id
+    }
+    PropertyGroupOption }|--|| PropertyGroup : "M:1"
+    PropertyGroup{
+        uuid property_group_id
+    }
+```
+
+It is also useful to attach some additional properties to differentiate product variants next to the field inheritance. For that reason, it is critical to understand the difference between *properties* and *options*:
 
 **Properties** are used to model facts about a product, but usually, different product variants share these facts. We can refer to properties as *non variant defining*. They could be useful to represent the following information:
 
@@ -50,9 +95,14 @@ Opposed to that **options** are considered variant defining, as they are the fac
 * Color
 * Container volume
 
-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.
+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*.
+
+| 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
+## 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.