docs: Update Lifecycle Manager docu (#1339)

* docs: Update Lifecycle Manager docu

* Upload the diagram

* Update architecture.md

* Apply Iwona's reveiw suggestions

* Apply Chris's suggestions from code review

docs/technical-reference/api/kyma-cr.md

@@ -1,12 +1,15 @@
 # Kyma Custom Resource
 
-The [Kyma custom resource (CR)](/api/v1beta2/kyma_types.go) contains 3 fields that are together used to declare the desired state of a cluster:
+The [Kyma custom resource (CR)](../../../api/v1beta2/kyma_types.go) is used to declare the desired state of a cluster. **.spec.channel**, **.spec.modules[].channel**, and **.spec.modules** are the basic fields that are used together to define the cluster state.
 
-1. **.spec.channel** and **.spec.modules[].channel**: The Release Channel that should be used by default for all modules that are to be installed in the cluster.
-2. **.spec.modules**: The modules that should be installed into the cluster. Each module contains a name serving as a link to the ModuleTemplate CR.
-Additionally, you can add a specific channel (if `.spec.channel`) should not be used.
-On top of that, you can specify a `controller`, which serves as a Multi-Tenant Enabler.
-It can be used to only listen to ModuleTemplate CRs provided under the same controller name. Last but not least, it includes a `customResourcePolicy` which can be used for specifying defaulting behavior when initializing modules in a cluster.
+- **.spec.channel** - defines a release channel that should be used by default for all modules that are to be installed in the cluster.
+- **.spec.modules[].channel** - defines a release channel other than the default channel (**.spec.channel**) for a given module that is to be installed in the cluster.
+- **.spec.modules** - specifies modules that should be added to the cluster. Each module contains a name serving as a link to the ModuleTemplate CR.
+Additionally, you can add a specific channel if **.spec.channel** should not be used.
+On top of that, you can specify a **controller**, which serves as a Multi-Tenant Enabler.
+It can be used to only listen to ModuleTemplate CRs provided under the same controller name. Last but not least, it includes a **customResourcePolicy** which can be used for specifying default behavior when initializing modules in a cluster.
+
+## Configuration
 
 ### **.spec.channel** and **.spec.modules[].channel**
 
@@ -22,7 +25,7 @@ spec:
   - name: serverless
 ```
 
-will attempt to look up the modules `keda` and `serverless` in the `alpha` release channel.
+attempts to look up the Keda and Serverless modules in the `alpha` release channel.
 
 However, if you specify channels using the **.spec.modules[].channel** attribute, the latter one is used instead.
 
@@ -35,11 +38,11 @@ spec:
   - name: serverless
 ```
 
-In this case, the relevant channel will be `regular` for `keda`, but not for `serverless`.
+In this case, `regular` is the relevant channel for Keda, but not for Serverless.
 
 ### **.spec.modules**
 
-The module list is used to define the desired set of all modules. This is mainly derived from the  **.spec.modules[].name** attribute which is resolved in one of 3 ways.
+The module list is used to define the desired set of all modules. This is mainly derived from the **.spec.modules[].name** attribute which is resolved in one of 3 ways.
 
 Let's take a look at this simplified ModuleTemplate CR:
 
@@ -61,7 +64,7 @@ spec:
 
 The module mentioned above can be referenced in one of the following ways:
 
-1. The label value of `operator.kyma-project.io/module-name`:
+- The label value of `operator.kyma-project.io/module-name`:
 
     ```yaml
     spec:
@@ -70,7 +73,7 @@ The module mentioned above can be referenced in one of the following ways:
       - name: module-name-from-label
     ```
 
-2. The Name or Namespace/Name of a ModuleTemplate CR:
+- The name or namespace/name of a ModuleTemplate CR:
 
     ```yaml
     spec:
@@ -88,7 +91,7 @@ The module mentioned above can be referenced in one of the following ways:
       - name: default/moduletemplate-sample
     ```
 
-3. The fully qualified name of the descriptor as located in **.spec.descriptor.component.name**:
+- The fully qualified name of the descriptor as located in **.spec.descriptor.component.name**:
 
     ```yaml
     spec:
@@ -100,26 +103,26 @@ The module mentioned above can be referenced in one of the following ways:
 ### **.spec.modules[].customResourcePolicy**
 
 In addition to this very flexible way of referencing modules, there is also another flag that can be important for users requiring more flexibility during module initialization. The `customResourcePolicy` flag is used to define one of `CreateAndDelete` and `Ignore`.
-While `CreateAndDelete` will cause the ModuleTemplate's **.spec.data** to be created and deleted to initialize a module with preconfigured defaults, `Ignore` can be used to only initialize the operator without initializing any default data.
+While `CreateAndDelete` causes the ModuleTemplate CR's **.spec.data** to be created and deleted to initialize a module with preconfigured defaults, `Ignore` can be used to only initialize the operator without initializing any default data.
 This allows users to be fully flexible in regard to when and how to initialize their module.
 
 ### **.status.state**
 
-The **state** attribute is a simple representation of the state of the entire Kyma CR installation. It is defined as an aggregated status that is either `Ready`, `Processing`, `Error`, or `Deleting`, based on the status of _all_ Manifest CRs on top of the validity/integrity of the synchronization to a remote cluster if enabled.
+The **state** attribute is a simple representation of the state of the entire Kyma CR installation. It is defined as an aggregated status that is either `Ready`, `Processing`, `Warning`, `Error`, or `Deleting`, based on the status of all Manifest CRs on top of the validity/integrity of the synchronization to a remote cluster if enabled.
 
-The **state** will always be reported based on the last reconciliation loop of the [Kyma controller](../../../internal/controller/kyma_controller.go). It will be set to `Ready` only if all installations were successfully executed and are consistent at the time of the reconciliation.
+The **state** is always reported based on the last reconciliation loop of the [Kyma controller](../../../internal/controller/kyma_controller.go). It will be set to `Ready` only if all installations were successfully executed and are consistent at the time of the reconciliation.
 
 ### **.status.conditions**
 
-The conditions represent individual elements of the reconciliation that can either be `true` or `false`, for example representing the readiness of all modules (Manifest CR). For more details on how conditions are aggregated and built, take a look at [KEP-1623: Standardize Conditions](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1623-standardize-conditions), which is our reference documentation for conditions.
+The conditions represent individual elements of the reconciliation that can either be `true` or `false`, for example, representing the readiness of all modules (Manifest CRs). For more details on how conditions are aggregated and built, take a look at [KEP-1623: Standardize Conditions](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1623-standardize-conditions), which is our reference documentation for conditions.
 
 Currently, we maintain conditions for:
 
 - Module (Manifest CR) synchronization
 - Module Catalog (ModuleTemplate CR) synchronization
 - Watcher Installation Consistency
 
-We also calculate **.status.state** readiness based on all the conditions available.
+We also calculate the **.status.state** readiness based on all the conditions available.
 
 ### **.status.modules**
 
@@ -160,9 +163,9 @@ The same is done for the ModuleTemplate CR. The actual one that is used as a tem
 
 To observe not only how the state of the `synchronization` but the entire reconciliation is working, as well as to check on latency and the last observed change, we also introduce the **lastOperation** field. This contains not only a timestamp of the last change (which allows you to view the time since the module was last reconciled by Lifecycle Manager), but also a message that either contains a process message or an error message in case of an `Error` state. Thus, to get more details of any potential issues, it is recommended to check **lastOperation**.
 
-In addition, we also regularly issue `Events` for important things happening at specific time intervals, e.g. critical errors that ease observability.
+In addition, we also regularly issue Events for important things happening at specific time intervals, e.g. critical errors that ease observability.
 
-### `operator.kyma-project.io` labels
+## `operator.kyma-project.io` labels
 
 Various overarching features can be enabled/disabled or provided as hints to the reconciler by providing a specific label key and value to the Kyma CR and its related resources. For better understanding, use the matching [API label reference](/api/shared/operator_labels.go).
 
@@ -173,7 +176,7 @@ The most important labels include, but are not limited to:
 - `operator.kyma-project.io/signature`: An identifier that can be set on a Secret to identify correct signature X.509 Secrets that contain a key called `key` which contains a X.509 PKIX PublicKey or an PKCS1 Public Key. Used in conjunction with the label-value for templates signed with a signature in the descriptor.
 - `operator.kyma-project.io/skip-reconciliation`: A label that can be used with the value `true` to completely disable reconciliation for a Kyma CR. Can also be used on the Manifest CR to disable a specific module. This will avoid all reconciliations for the entire Kyma or Manifest CRs. Note that even though reconciliation for the Kyma CR might be disabled, the Manifest CR in a Kyma can still get reconciled normally if not adjusted to have the label set as well.
 - `operator.kyma-project.io/managed-by`: A cache limitation label that must be set to `lifecycle-manager` to have the resources picked up by the cache. Hard-coded but will be made dynamic to allow for multi-tenant deployments that have non-conflicting caches
-- `operator.kyma-project.io/purpose`: Can be used to identify resources by their intended purpose inside Lifecycle Manager. Useful meta information for cluster managers.
+- `operator.kyma-project.io/purpose`: Can be used to identify resources by their intended purpose inside Lifecycle Manager. Useful meta-information for cluster managers.
 - `operator.kyma-project.io/sync`: A boolean value. If set to `false`, the Module Catalog synchronization is disabled for a given Kyma CR, and for the related remote cluster (Managed Kyma Runtime). The default value is `true`.
 - `operator.kyma-project.io/internal`: A boolean value. If set to `true`, the ModuleTemplate CRs labeled with the same label, so-called `internal` modules, are also synchronized with the remote cluster. The default value is `false`.
 - `operator.kyma-project.io/beta`: A boolean value. If set to `true`, the ModuleTemplate CRs labeled with the same label, so-called `beta` modules are also synchronized with the remote cluster. The default value is `false`.

docs/technical-reference/api/manifest-cr.md

@@ -1,12 +1,14 @@
 # Manifest Custom Resource
 
-The [Manifest](/api/v1beta1/manifest_types.go) is our internal representation of what results from the resolution of a `ModuleTemplate` in the context of a single cluster represented through `Kyma`. Thus, a lot of configuration elements are similar or entirely equivalent to the layer data found in the `ModuleTemplate` and it is currently being considered for specification rework.
+The [Manifest custom resource (CR)](../../../api/v1beta2/manifest_types.go) is our internal representation of what results from the resolution of a ModuleTemplate CR in the context of a single cluster represented by a Kyma CR. Thus, a lot of configuration elements are similar or entirely equivalent to the data layer found in a ModuleTemplate CR.
 
-### `.spec.remote`
+## Configuration
 
-This flag determines wether the given module should be installed in the remote cluster target or not. If it should, then it will attempt a lookup of the cluster by searching for a secret with a label `operator.kyma-project.io/kyma-name` having the same value as the `operator.kyma-project.io/kyma-name` label on the `Manifest`.
+### **.spec.remote**
 
-Thus a Manifest like
+This parameter determines whether or not the given module should be installed in a remote cluster. If it should, then in the KCP cluster, it attempts to search for a Secret having the same `operator.kyma-project.io/kyma-name` label and value as in the Manifest CR.
+
+Thus a Manifest CR like
 
 ```yaml
 apiVersion: operator.kyma-project.io/v1beta2
@@ -20,13 +22,13 @@ spec:
   remote: true
 ```
 
-will use the value `kyma-sample` to lookup a secret with the same value `kyma-sample`.
+looks for a Secret with the same `operator.kyma-project.io/kyma-name` label and value `kyma-sample`.
 
-### `.spec.config`
+### **.spec.config**
 
-The config reference uses an image layer reference that contains configuration data that can be used to further influence any potential rendering process while the resources are processed by the [declarative library](/internal/declarative/README.md#resource-rendering). It is resolved through a translation of the `ModuleTemplate` to the `Manifest` during the [resolution of the modules](/pkg/module/parse/template_to_module.go) in the `Kyma` control loop.
+The config reference uses an image layer reference that contains configuration data that can be used to further influence any potential rendering process while the resources are processed by the [declarative library](../../../internal/declarative/README.md#resource-rendering). It is resolved through a translation of the ModuleTemplate CR to the Manifest CR during the [resolution of the modules](../../../pkg/module/parse/template_to_module.go) in the Kyma CR control loop.
 
-There can be at most one config layer, and it is referenced by the name `config` with type `yaml` as `localOciBlob` or `OCIBlob`:
+There can be at most one config layer, and it is referenced by the **name** `config` with **type** `yaml` as `localOciBlob` or `OCIBlob`:
 
 ```yaml
 spec:
@@ -49,9 +51,9 @@ spec:
         version: 0.0.1-6cd5086
 ```
 
-### `.spec.install`
+### **.spec.install**
 
-The install layer contains the relevant data required to determine the resources for the [renderer during the manifest reconciliation](/internal/declarative/README.md#resource-rendering).
+The installation layer contains the relevant data required to determine the resources for the [renderer during the manifest reconciliation](../../../internal/declarative/README.md#resource-rendering).
 
 It is mapped from an access type layer in the descriptor:
 
@@ -77,17 +79,16 @@ install:
       type: oci-ref
 ```
 
-The [internal spec resolver](/internal/manifest/spec_resolver.go) will use this layer to resolve the correct specification style and renderer type from the layer data.
+The [internal spec resolver](../../../internal/manifest/spec_resolver.go) uses this layer to resolve the correct specification style and renderer type from the data layer.
 
-### `.spec.resource`
+### **.spec.resource**
 
-The resource is the default data that should be initialized for the module and is directly copied from `.spec.data` of the `ModuleTemplate` after normalizing it with the `namespace` for the synchronized module.
+The resource is the default data that should be initialized for the module and is directly copied from **.spec.data** of the ModuleTemplate CR after normalizing it with the **namespace** for the synchronized module.
 
-### `.status`
+### **.status**
 
-The Manifest status is an unmodified version of the [declarative status](/internal/declarative/README.md#resource-tracking), so the tracking process of the library applies. There is no custom API for this.
+The Manifest CR status is an unmodified version of the [declarative status](../../../internal/declarative/README.md#resource-tracking), so the tracking process of the library applies. There is no custom API for this.
 
-### `.metadata.labels`
+### **.metadata.labels**
 
 * `operator.kyma-project.io/skip-reconciliation`: A label that can be used with the value `true` to disable reconciliation for a module. This will avoid all reconciliations for the Manifest CR.
-

docs/technical-reference/api/moduleTemplate-cr.md

@@ -1,6 +1,8 @@
 # ModuleTemplate Custom Resource
 
-The core of our modular discovery, the [ModuleTemplate custom resource (CR)](/api/v1beta2/moduletemplate_types.go) contains 3 main parts that are used to initialize and resolve modules.
+The core of our modular discovery is the [ModuleTemplate custom resource (CR)](../../../api/v1beta2/moduletemplate_types.go). It is used to initialize and resolve modules.
+
+## Configuration
 
 ### **.spec.channel**
 
@@ -52,6 +54,7 @@ The `.spec.customStateCheck` field in Kyma Lifecycle Manager is primarily design
 Imagine a scenario where a module's health is indicated by `status.health` in its CR. In such cases, users can employ the customStateCheck configuration to map the health states to Lifecycle Manager states.
 
 Here's an example of YAML configuration:
+
 ```yaml
 spec:
   customStateCheck:
@@ -68,6 +71,7 @@ In this example, when the module's CR is in the green health state, the correspo
 The valid mappedState values are defined in the [Kyma CR API](https://github.com/kyma-project/lifecycle-manager/blob/main/api/v1beta2/kyma_types.go#L225-L245).
 
 Furthermore, this field supports complex mappings. For instance, if multiple states are needed to determine the `Ready` state, users can define the following customStateCheck:
+
 ```yaml
 spec:
   customStateCheck:
@@ -87,12 +91,12 @@ The core of any ModuleTemplate CR, the descriptor can be one of the schemas ment
 
 By default, it will most likely be easiest to use [Kyma CLI](https://github.com/kyma-project/cli/tree/main) and its `create module` command to create a template with a valid descriptor, but it can also be generated manually, for example using [OCM CLI](https://github.com/open-component-model/ocm/tree/main/cmds/ocm).
 
-### `.spec.mandatory`
+### **.spec.mandatory**
 
 The `mandatory` field indicates whether the module is installed in all runtime clusters without any interaction from the user.
 Mandatory modules do not appear in the Kyma CR `.status` and `.spec.modules`, furthermore they have the same configuration across all runtime clusters.
 
-### `operator.kyma-project.io` labels
+## `operator.kyma-project.io` labels
 
 These are the synchronization labels available on the ModuleTemplate CR: