Chore/408 improve arc42 documentation

INSTALL.md

@@ -59,11 +59,105 @@ Create a new application in ArgoCD and point it to your repository / Helm chart
 A detailed instruction on how to configure the IRS and EDC can be found here: [Administration Guide](https://eclipse-tractusx.github.io/item-relationship-service/docs/administration/administration-guide.html)
 
 ## Local Installation
+
 IRS provides a local setup which can be deployed to kubernetes.
 This setup includes all third-party services which IRS uses and interacts with.
 
 Instructions can be found here [README](README.md).
 
 ## Sample Calls
 
-Sample calls can be found here [USAGE](USAGE.md).
+Sample calls can be found here [USAGE](USAGE.md).
+
+## Local Installation with Umbrella
+
+The eclipse-tractusx/umbrella chart provides a pre-configured Helm Chart with many Tractus-X Services. To integrate IRS
+with this Chart, run the following steps:
+
+For detailed instructions on how to set up the umbrella chart, see the chapters "Cluster setup" and "Network setup" in
+the umbrella [README.md](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/charts/umbrella/README.md).
+
+Clone the [Umbrella repo](https://github.com/eclipse-tractusx/tractus-x-umbrella) (only required once):
+
+```
+git clone https://github.com/eclipse-tractusx/tractus-x-umbrella.git
+```
+
+Check out
+the [IRS umbrella integration branch](https://github.com/eclipse-tractusx/tractus-x-umbrella/tree/chore/e2e-irs-preparation):
+
+```
+cd tractus-x-umbrella/
+git fetch origin
+git checkout -b chore/e2e-irs-preparation origin/chore/e2e-irs-preparation
+```
+
+Build the required images for IATP mock.
+
+```bash
+eval $(minikube docker-env)
+docker build iatp-mock/ -t tractusx/iatp-mock:testing --platform linux/amd64
+```
+
+Install the Umbrella chart
+
+```bash
+helm dependency update charts/tx-data-provider
+helm dependency update charts/umbrella
+helm install umbrella charts/umbrella -f charts/umbrella/values-adopter-irs.yaml -n e2e-testing --create-namespace --set iatpmock.image.repository=tractusx/iatp-mock --set iatpmock.image.tag=testing
+```
+
+(Optional) Build IRS Docker image from local
+
+```bash
+docker build . -t tractusx/irs-api:local
+```
+
+Install the IRS Helm Chart with the local Docker image
+
+```bash
+helm dependency update ./charts/item-relationship-service
+helm install irs ./charts/item-relationship-service --namespace e2e-testing -f ./charts/item-relationship-service/values-umbrella.yaml --set image.repository=tractusx/irs-api -- set image.tag=local
+```
+
+Or use the latest released version
+
+```bash
+helm repo add irs https://eclipse-tractusx.github.io/item-relationship-service 
+helm install irs irs/item-relationship-service --namespace e2e-testing -f ./charts/item-relationship-service/values-umbrella.yaml --set image.repository=tractusx/irs-api --set image.tag=latest
+```
+
+### upload testdata
+
+To upload testdata, first forward the dataprovider pods to your localhost:
+
+```bash
+kubectl port-forward svc/umbrella-dataprovider-dtr 4444:8080 --namespace e2e-testing &
+kubectl port-forward svc/umbrella-dataprovider-edc-controlplane 8888:8081 --namespace e2e-testing &
+kubectl port-forward svc/umbrella-dataprovider-submodelserver 9999:8080 --namespace e2e-testing
+```
+
+then use the testdata upload script to seed the dataprovider services with testdata:
+
+```bash
+./local/testing/testdata/upload-testdata.sh "TEST2" "BPNL00000003AYRE" "BPNL00000003AZQP" \
+  "http://umbrella-dataprovider-submodelserver:8080" "http://localhost:9999" \
+  "http://umbrella-dataprovider-dtr:8080/api/v3" "http://localhost:4444/api/v3" \
+  "http://umbrella-dataprovider-edc-controlplane:8084" "http://localhost:8888" \
+  "http://umbrella-dataprovider-edc-dataplane:8081"
+```
+
+Now forward the IRS service port to access the API:
+
+```bash
+kubectl port-forward svc/irs-item-relationship-service 8080:8080 --namespace e2e-testing
+```
+
+### Uninstall
+
+To uninstall the IRS and Umbrella chart
+
+```bash
+helm uninstall irs --namespace e2e-testing
+helm uninstall umbrella --namespace e2e-testing
+```

docs/src/docs/arc42/building-block-view/level-1.adoc

@@ -44,10 +44,11 @@ A job is processed in this order:
 6. Assembles the complete item graph.
 
 |*BlobStore*
-|The BlobStore is the database where the relationships and tombstones are stored for a requested item.
+|The BlobStore is the database where the intermediate relationships and tombstones are stored as BLOBs during job processing. When complete, the job will take these intermediate BLOBs and consolidate them in the job response.
+The BLOBs are single-use only and will not be re-used for future jobs.
 
 |*JobStore*
-|The JobStore is the database where the jobs with the information about the requested item are stored.
+|The JobStore is the database where the jobs with the information about the requested item are stored. Completed and failed jobs will be deleted from the JobStore after their configured time-to-live is reached.
 
 |*Digital Twin Client*
 |The Digital Twin Client is the interface to the Digital Twin Registry. It provides an interface for the Asset Administration Shells.

docs/src/docs/arc42/cross-cutting/testing.adoc

@@ -1,5 +1,19 @@
 = Testing concepts
 
+== How to test a feature
+
+Features in IRS are tested by unit, integration and end-to-end tests.
+We maintain a unit and integration tests coverage of at lease 80% which has to be kept up for new features.
+
+To test integration with the whole IRS flow, we provide https://github.com/eclipse-tractusx/item-relationship-service/blob/main/irs-api/src/test/java/org/eclipse/tractusx/irs/IrsWireMockIntegrationTest.java[Wiremock integration tests] where all third-party services are mocked.
+This test can be extended with your desired configuration to maintain full coverage.
+
+End-to-end tests are conducted via https://taverntesting.github.io/[Tavern] and https://cucumber.io/[Cucumber].
+
+Cucumber feature files are located in https://github.com/eclipse-tractusx/item-relationship-service/tree/main/irs-cucumber-tests/src/test/resources/org/eclipse/tractusx/irs/cucumber/features[irs-cucumber-tests/src/test/resources/org/eclipse/tractusx/irs/cucumber/features] and executed with a GitHub workflow https://github.com/eclipse-tractusx/item-relationship-service/blob/main/.github/workflows/cucumber-integration-test-UMBRELLA.yaml[cucumber-integration-test-UMBRELLA.yaml].
+
+Tavern Tests are located in https://github.com/eclipse-tractusx/item-relationship-service/tree/main/local/testing/api-tests[local/testing/api-tests] and executed with a GitHub workflow https://github.com/eclipse-tractusx/item-relationship-service/blob/main/.github/workflows/tavern-UMBRELLA.yml[tavern-UMBRELLA.yml].
+
 == Umbrella
 
 The https://github.com/eclipse-tractusx/tractus-x-umbrella[umbrella chart] provides a pre-configured catena-x network which includes all necessary components for the IRS to work.
@@ -34,4 +48,6 @@ Test results are automatically added to the workflow summary and in case of the
 
 Due to limitations in the IATP mock, the only way of using multiple BPNs in the test data is to spin up multiple EDC provider instances.
 However, the chart is used inside GitHub Workflows, so compute resources are limited.
-For this reason, the IRS test data was changed to include only data pointing to a single BPN.
+For this reason, the IRS test data was changed to include only data pointing to a single BPN.
+
+For instructions on how to use the Umbrella Chart locally, see https://github.com/eclipse-tractusx/item-relationship-service/blob/main/INSTALL.md#local-installation-with-umbrella[INSTALL.md]

docs/src/docs/arc42/glossary.adoc

@@ -5,6 +5,7 @@
 |Term |Abrv. | Description
 
 |Asset Administration Shell | AAS | see "Digital Twin"
+|Asset Administration Shell Registry | AAS Registry | see "Digital Twin Registry"
 |Aspect Servers (Submodel Endpoints) | | Companies participating in the interorganizational data exchange provides their data over aspect servers. The so called "submodel-descriptors" in the AAS shells are pointing to these AspectServers which provide the data-assets of the participating these companies in Catena-X.
 |Bill of Materials | BoM | A Bill of Materials is a comprehensive list of materials, components, sub-assemblies, and the quantities of each needed to manufacture or build a product. It serves as a structured document that provides information about the raw materials, parts, and components required for the production process.
 |Business Partner Number | BPN | A BPN is the unique identifier of a partner within Catena-X
@@ -15,7 +16,7 @@
 |Contract Offer| | A "Contract Offer" is a synonym for "CatalogItem" from EDC.
 |Data Space | | Data Spaces are the key concept for a large-scale, cross-border data economy. This is also the vision of the Gaia-X initiative for a data infrastructure in Europe. The International Data Space Association (IDSA) contributes significantly to this with the architectural model, interfaces, and standards.
 |Digital Twin | DT | The Digital Twin is the key technology of Industry 4.0 and connects the physical world with the digital world and acts as an enabler of the Catena-X network. It is based on a standardized programming interface of the Industrial https://industrialdigitaltwin.org/[Digital Twin Association (IDTA)] and its Asset Administration Shell.
-|Digital Twin Registry | DTR | The Digital Twin Registry is a registry which lists all digital twins and references their aspects including information about the underlying asset, asset manufacturer, and access options (e.g. aspect endpoints).
+|Digital Twin Registry | DTR | The Digital Twin Registry is a registry which lists all digital twins and references their aspects including information about the underlying asset, asset manufacturer, and access options (e.g. aspect endpoints). For further information, see https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Adoption%20View%20Digital%20Twin%20Kit[Digital Twin Kit]
 |Eclipse Dataspace Connector | EDC | The Eclipse Data Space Connector (EDC) is a standard and policy-compliant connector that can be used within the scope of Catena-X, but also more generally as a connector for Data Spaces. It is split up into Control-Plane and Data-Plane, whereas the Control-Plane functions as administration layer and has responsibility of resource management, contract negotiation and administer data transfer. The Data-Plane does the heavy lifting of transferring and receiving data streams. For more information see:
 https://github.com/eclipse-edc/Connector[EDC Connector] , https://github.com/eclipse-tractusx/tractusx-edc[Tractus-X EDC (Eclipse Dataspace Connector)]
 |Edge | | see Traversal Aspect

docs/src/docs/arc42/runtime-view/ess-top-down/irs-recursive.adoc

@@ -0,0 +1,5 @@
+The IRS recursive approach is a decentral approach of retrieving and aggregating data throughout the Catena-X network.
+
+The core functionality is based on notifications which are exchanged between multiple IRS instances. The notifications trigger an investigation on the next level down the supply chain and return aggregated data containing, e.g. simple information about whether a certain BPN is part of the supply chain or not.
+
+Investigations triggered on the next level down the supply chain can trigger further investigations themselves, hence the name _IRS recursive_.

docs/src/docs/arc42/runtime-view/full.adoc

@@ -5,16 +5,17 @@
 This section describes the iterative flow, the main processes of the IRS, and explains how data is transferred and processed when a job is executed.
 
 include::irs-iterative/irs-iterative.adoc[leveloffset=+1]
-include::irs-iterative/scenario-1.adoc[leveloffset=+1]
-include::irs-iterative/scenario-2.adoc[leveloffset=+1]
-include::irs-iterative/scenario-3.adoc[leveloffset=+1]
-include::irs-iterative/scenario-4.adoc[leveloffset=+1]
+include::irs-iterative/scenario-1.adoc[leveloffset=+2]
+include::irs-iterative/scenario-2.adoc[leveloffset=+2]
+include::irs-iterative/scenario-3.adoc[leveloffset=+2]
+include::irs-iterative/scenario-4.adoc[leveloffset=+2]
 
 == IRS Recursive
 
 This section covers the main processes of the IRS in a recursive scenario in a network.
 This recursive scenario is illustrated using the various use cases realized in the scenario.
 
+include::ess-top-down/irs-recursive.adoc[leveloffset=+1]
 include::ess-top-down/ess-top-down.adoc[leveloffset=+1]
-include::ess-top-down/ess-top-down-scenario-1.adoc[leveloffset=+1]
-include::ess-top-down/ess-top-down-scenario-2.adoc[leveloffset=+1]
+include::ess-top-down/ess-top-down-scenario-1.adoc[leveloffset=+2]
+include::ess-top-down/ess-top-down-scenario-2.adoc[leveloffset=+2]

docs/src/docs/arc42/runtime-view/index.adoc

@@ -15,6 +15,7 @@ This section describes the iterative flow, the main processes of the IRS, and ex
 This section covers the main processes of the IRS in a recursive scenario in a network.
 This recursive scenario is illustrated using the various use cases realized in the scenario.
 
+include::ess-top-down/irs-recursive.adoc[leveloffset=+1]
 - xref:ess-top-down/ess-top-down.adoc[Use Case: ESS (Environmental and Social Standards) Top-Down approach]
 - xref:ess-top-down/ess-top-down-scenario-1.adoc[Scenario 1: Register an Ess-Investigation-Order]
 - xref:ess-top-down/ess-top-down-scenario-2.adoc[Scenario 2: Register an Ess-Investigation-Job]

docs/src/docs/arc42/runtime-view/irs-iterative/irs-iterative.adoc

@@ -1,3 +1,9 @@
+IRS Iterative is the main IRS mode for retrieving data chains throughout the Catena-X network. The core functionality can be summed up in three steps:
+
+1. Start the process with a provided globalAssetId and BPN combination, and required submodels to request.
+2. Retrieve the EDC endpoint for the BPN, search the catalog for the Digital Twin Registry contract Offer and search the DTR for the provided BPN.
+3. Retrieve the relationship submodel for the requested lifecycle and direction and repeat step 1 with the globalAssetIds and BPNs from the relationship submodel linked data until the desired depth is reached or no more relationships could be found.
+
 [plantuml, target=overall, format=svg]
 ....
 include::../../../../uml-diagrams/runtime-view/api-call-asynchrous-sequence.puml[]

docs/src/docs/arc42/scope-context/business-context.adoc

@@ -11,4 +11,9 @@ The IRS API is being consumed by the dismantler dashboard and other parties whic
 == Catena-X network
 The IRS retrieves data from the Catena-X network (using the necessary infrastructure, see Technical Context), aggregates it and provides it back to the consumers. This connection is mandatory. If the Catena-X services are unavailable, the IRS cannot perform any work.
 
-As of now, the IRS uses its own IAM credentials to gather the required data. This might be changed to use the consumer credentials in the future.
+As of now, the IRS uses its own IAM credentials to gather the required data. This might be changed to use the consumer credentials in the future.
+
+== Submodels
+A Semantic Aspect Meta Model (SAMM) (see https://docs.bosch-semantic-stack.com/oss/samm-specification.html[samm-specification]), also known as semantic model ,aspect model or submodel, is a standardized specification to describe certain attributes of a physical part. Notable aspect models for the IRS use-case are BOMs (which parts are directly built into a part) and usages (in which parts is a part built into).
+
+Available aspect models in the catena-x context can be found in the https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main[sldt-semantic-models repository].

docs/src/docs/arc42/scope-context/technical-context.adoc

@@ -13,7 +13,7 @@ We provide a REST API that can be consumed by any system registered in the Caten
 In order to consume the Restful application IRS, the security aspect should be taken in consideration. IRS is a Spring Boot based application and is secured with the OpenID connector provider with OAuth2 protocol. This means for the consumers (users) that they need to authenticate themselves in order to be authorized to get access to the IRS. They generate a bearer token that they get from OAuth2 provider and attach it to the HTTP header parameter Authorization.
 
 === Registry API
-The IRS acts as a consumer of the component Asset Administration Shell Registry. The IRS contains a Restful client (REST template) that build a REST call to the mentioned Digital Twin Registry API based on its known URL (the AAS registry URL is configured in the IRS Restful API). The request contains the given "globalAssetId" by the consumer. Like described in the above section, the security aspect is required in order to achieve a REST call against the AAS Registry. As a response, the IRS gets the corresponding asset administration shell descriptor. The last one contains a list of submodel descriptors which can be filtered by the aspect type entered by the consumer. An aspect type like https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built[SingleLevelBomAsBuilt], https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part[SerialPart] etc. And as mentioned above, the transport protocol HTTP(S) is used for the REST call communication.
+The IRS acts as a consumer of the component Asset Administration Shell (AAS) Registry. The IRS contains a Restful client (REST template) that build a REST call to the mentioned Digital Twin Registry API based on its known URL (the AAS registry URL is configured in the IRS Restful API). The request contains the given "globalAssetId" by the consumer. Like described in the above section, the security aspect is required in order to achieve a REST call against the AAS Registry. As a response, the IRS gets the corresponding asset administration shell descriptor. The last one contains a list of submodel descriptors which can be filtered by the aspect type entered by the consumer. An aspect type like https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_built[SingleLevelBomAsBuilt], https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.serial_part[SerialPart] etc. And as mentioned above, the transport protocol HTTP(S) is used for the REST call communication.
 
 ==== Discovery Service
 In a decentralized system, the digital twin registry is moved behind an EDC. To access the registry of a data provider, a new set of central services was introduces. These discovery services consist of BPN Discovery, Discovery Finder and EDC Discovery.

docs/src/uml-diagrams/building-block-view/level-2-int-transfer-process-management.puml

@@ -10,9 +10,7 @@ skinparam defaultFontName "Architects daughter"
 component [**TransferProcessManagement**] <<Component>> as TransferProcessManagement {
     component [**AASTransferProcessManager**] <<Component>> as TransferProcessManager
     component [**DecentralDigitalTwinRegistryService**] <<Component>> as DTRService {
-        component [**DecentralDigitalTwinRegistryClient**] <<Component>> as DTRClient {
-            component [**EndpointDataForConnectorsService**] <<Component>> as EndpointDataForConnectorsService
-        }
+        component [**DecentralDigitalTwinRegistryClient**] <<Component>> as DTRClient
     }
     component [**EdcSubmodelFacade**] <<Component>> as SubmodelFacade {
         component [**EdcSubmodelClient**] <<Component>> as SubmodelClient {
@@ -51,7 +49,6 @@ SubmodelClient ----( SMSAPI
 interface "PolicyStoreAPI" as PolicyStoreAPI
 PolicyCheckerService --(  PolicyStoreAPI
 PolicyStoreAPI -- PolicyStoreService
-EndpointDataForConnectorsService -> SubmodelFacade
 
 database BlobStore
 TransferProcessManager -left-( BlobStoreInterface

docs/src/uml-diagrams/deployment-view/level-0-dev.puml

@@ -5,8 +5,6 @@ skinparam nodesep 100
 skinparam ranksep 20
 skinparam defaultFontName "Architects daughter"
 
-cloud OAuth2
-
 node "Kubernetes Cluster" as k8s {
 
     component IRS
@@ -28,6 +26,4 @@ node "Kubernetes Cluster" as k8s {
 
 }
 
-IRS --> OAuth2
-
 @enduml

docs/src/uml-diagrams/deployment-view/level-0-isolated.puml

@@ -41,7 +41,7 @@ node "Kubernetes Cluster" as k8s {
     provider -- dtr
 
     OAuth2 ---> ds
-    OAuth2 ---> IRS
+    OAuth2 <--- IRS
     OAuth2 ---> semHub
 
     IRS -> semHub