feat(impl):[#395] Add more detailed diagrams

docs/src/docs/arc42/cross-cutting/discovery-DTR--multiple-EDCs-with-multiple-DTRs--detailed.puml

@@ -0,0 +1,84 @@
+@startuml
+
+
+box IRS
+    participant DecentralDigitalTwinRegistryService as DTRS
+    participant EdcSubmodelClientImpl as EdcClient
+end box
+
+
+participant DiscoveryService
+participant "EDC Provider 1" as EDCProvider1
+participant "EDC Provider 2" as EDCProvider2
+participant "EDC Provider 3" as EDCProvider3
+participant "DTR" as DTR
+
+' DigitalTwinDelegate.process
+' DecentralDigitalTwinRegistryService.fetchShells
+' ConnectorEndpointsService.fetchConnectorEndpoints(String bpn) -- cacheable
+DTRS -> DiscoveryService: Get EDCs for BPN
+' discoveryFinderClient.findDiscoveryEndpoints(DiscoveryFinderRequest request)
+DiscoveryService -> DTRS: Return list of 3 EDCs
+
+' Turned into futures to get the EDR tokens by
+' EndpointDataForConnectorsService.createFindEndpointDataForConnectorsFutures(List<String> edcUrls)
+
+par
+    group CatalogRequestEDC1
+
+        == EDC Control Plane ==
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider1: Query for DTR contract offer
+        EDCProvider1 -> EdcClient: No offer
+        EdcClient -> DTRS: No token
+    end
+
+    else
+
+    group CatalogRequestEDC2
+
+        == EDC Control Plane ==
+
+        ' this happens in DecentralDigitalTwinRegistryService.fetchShellDescriptorsForConnectorEndpoints
+        ' when each of List<CompletableFuture<EndpointDataReference>> is composed
+        ' with fetchShellDescriptorsForKey
+        DTRS -> EdcClient: Get EDR Token for asset
+        ' EdcSubmodelFacade.getEndpointReferenceForAsset
+        ' EdcSubmodelClientImpl.getEndpointReferenceForAsset
+        EdcClient -> EDCProvider2: Query for DTR contract offer
+        EDCProvider2 -> EdcClient: DTR contract offer
+        ' EdcSubmodelClientImpl.negotiateContract
+        EdcClient -> EDCProvider2: Negotiate contract
+        EDCProvider2 -> EdcClient: EDR Token callback
+        EdcClient -> DTRS: EDR token
+
+
+        == EDC Data Plane ==
+
+        ' DecentralDigitalTwinRegistryService
+        '      .fetchShellDescriptor(EndpointDataReference, DigitalTwinRegistryKey)
+        DTRS -> DTR: Query for DT
+        DTR -> DTRS: DT
+        ' result is AssetAdministrationShellDescriptor which is the actual data
+    end
+
+    else
+
+    group CatalogRequestEDC3
+
+        == EDC Control Plane ==
+
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider3: Query for DTR contract offer
+        EDCProvider3 -> EdcClient: DTR contract offer
+        EdcClient -> EDCProvider3: Negotiate contract
+        EDCProvider3 -> EdcClient: EDR Token callback
+        EdcClient -> DTRS: EDR token
+
+        == EDC Data Plane ==
+
+        DTRS -> DTR: Query for DT
+        DTR -> DTRS: No DT
+    end
+end
+@enduml

docs/src/docs/arc42/cross-cutting/discovery-DTR--multiple-EDCs-with-no-DTRs--detailed.puml

@@ -0,0 +1,58 @@
+@startuml
+
+box IRS
+    participant DecentralDigitalTwinRegistryService as DTRS
+    participant EdcSubmodelClientImpl as EdcClient
+end box
+
+participant "Discovery Service" as DiscoveryService
+
+participant "EDC 1" as EDCProvider1
+participant "EDC 2" as EDCProvider2
+participant "EDC 3" as EDCProvider3
+
+
+' ConnectorEndpointsService.fetchConnectorEndpoints(String bpn) -- cacheable
+DTRS -> DiscoveryService: Get EDCs for BPN
+' discoveryFinderClient.findDiscoveryEndpoints(DiscoveryFinderRequest request)
+DiscoveryService -> DTRS: Return list of 3 EDCs
+
+par
+    group Catalog Request to EDC 1
+
+        == EDC Control Plane ==
+
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider1: Query for DTR contract offer
+        EDCProvider1 -> EdcClient: No offer
+        EdcClient -> DTRS: No token
+    end
+
+    else
+
+    group Catalog Request to EDC 2
+
+        == EDC Control Plane ==
+
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider2: Query for DTR contract offer
+        EDCProvider2 -> EdcClient: No offer
+        EdcClient -> DTRS: No token
+    end
+
+    else
+
+    group Catalog Request to EDC 3
+
+        == EDC Control Plane ==
+
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider3: Query for DTR contract offer
+        EDCProvider3 -> EdcClient: No offer
+        EdcClient -> DTRS: No token
+    end
+end
+
+DTRS -> DTRS: Tombstone
+
+@enduml

docs/src/docs/arc42/cross-cutting/discovery-DTR--multiple-EDCs-with-one-DTR--detailed.puml

@@ -0,0 +1,61 @@
+@startuml
+
+box IRS
+    participant DecentralDigitalTwinRegistryService as DTRS
+    participant EdcSubmodelClientImpl as EdcClient
+end box
+
+participant DiscoveryService
+participant "EDC Provider 1" as EDCProvider1
+participant "EDC Provider 2" as EDCProvider2
+participant "EDC Provider 3" as EDCProvider3
+participant DTR
+
+' ConnectorEndpointsService.fetchConnectorEndpoints(String bpn) -- cacheable
+DTRS -> DiscoveryService: Get EDCs for BPN
+' discoveryFinderClient.findDiscoveryEndpoints(DiscoveryFinderRequest request)
+DiscoveryService -> DTRS: Return list of 3 EDCs
+
+par
+    group CatalogRequestEDC1
+
+        == EDC Control Plane ==
+
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider1: Query for DTR contract offer
+        EDCProvider1 -> EdcClient: No offer
+        EdcClient -> DTRS: No token
+    end
+
+    else
+
+    group CatalogRequestEDC2
+
+        == EDC Control Plane ==
+
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider2: Query for DTR contract offer
+        EDCProvider2 -> EdcClient: No offer
+        EdcClient -> DTRS: No token
+    end
+
+    else
+
+    group CatalogRequestEDC3
+
+        == EDC Control Plane ==
+
+        DTRS -> EdcClient: Get EDR Token for asset
+        EdcClient -> EDCProvider3: Query for DTR contract offer
+        EDCProvider3 -> EdcClient: DTR contract offer
+        EdcClient -> EDCProvider3: Negotiate contract
+        EDCProvider3 -> EdcClient: EDR Token callback
+        EdcClient -> DTRS: EDR token
+
+        == EDC Data Plane ==
+
+        DTRS -> DTR: Query for DT
+        DTR -> DTRS: DT
+    end
+end
+@enduml

docs/src/docs/arc42/cross-cutting/discovery-DTR--one-EDC-with-multiple-DTRs--detailed.puml

@@ -0,0 +1,49 @@
+@startuml
+
+box IRS
+    participant DecentralDigitalTwinRegistryService as DTRS
+    participant EdcSubmodelClientImpl as EdcClient
+end box
+
+participant DiscoveryService
+participant "EDC Provider" as EDCProvider
+participant "DTR 1" as DTR1
+participant "DTR 2" as DTR2
+
+' ConnectorEndpointsService.fetchConnectorEndpoints(String bpn) -- cacheable
+DTRS -> DiscoveryService: Get EDCs for BPN
+' discoveryFinderClient.findDiscoveryEndpoints(DiscoveryFinderRequest request)
+DiscoveryService -> DTRS: Return list of 1 EDC
+
+==  EDC Control Plane ==
+
+DTRS -> EdcClient: Get EDR Token for asset
+EdcClient ->> EDCProvider: Query for DTR contract offer
+EDCProvider -> EdcClient: 2 DTR contract offers
+
+par
+    group Query DTR 1
+        EdcClient -> EDCProvider: Negotiate contract
+        EDCProvider -> EdcClient: EDR Token callback
+        EdcClient -> DTRS: EDR token
+
+        ==  EDC Data Plane ==
+
+        DTRS -> DTR1: Query for DT
+        DTR1 -> DTRS: no DT
+    end
+
+    else
+
+    group Query DTR 2
+        EdcClient -> EDCProvider: Negotiate contract
+        EDCProvider -> EdcClient: EDR Token callback
+        EdcClient -> DTRS: EDR token
+
+        ==  EDC Data Plane ==
+
+        DTRS -> DTR2: Query for DT
+        DTR2 -> DTRS: DT
+    end
+end
+@enduml

docs/src/docs/arc42/cross-cutting/discovery-DTR--one-EDC-with-one-DTR--detailed.puml

@@ -0,0 +1,41 @@
+@startuml
+
+box IRS
+    participant DecentralDigitalTwinRegistryService as DTRS
+    participant EdcSubmodelClientImpl as EdcClient
+end box
+
+participant DiscoveryService
+participant "EDC Provider 3" as EDCProvider3
+participant DTR
+
+' DigitalTwinDelegate.process
+' ConnectorEndpointsService.fetchConnectorEndpoints(String bpn) -- cacheable
+DTRS -> DiscoveryService: Get EDCs for BPN
+' discoveryFinderClient.findDiscoveryEndpoints(DiscoveryFinderRequest request)
+DiscoveryService -> DTRS: Return list of 1 EDC
+
+==  EDC Control Plane ==
+
+' see EdcSubmodelFacade.getEndpointReferenceForAsset,
+' EdcSubmodelClient.getEndpointReferencesForAsset,
+' EdcSubmodelClientImpl.getEndpointReferencesForAsset
+DTRS -> EdcClient: Get EDR Token for asset
+EdcClient -> EDCProvider3: Query for DTR contract offer
+EDCProvider3 -> EdcClient: DTR contract offer
+' Contract offer = CatalogItem
+EdcClient -> EDCProvider3: Negotiate contract
+
+EDCProvider3 -> EdcClient: EDR Token callback
+' EDR Token callback (this is the answer from pollingService)
+EdcClient -> DTRS: EDR Token
+' EDR Token = EndpointDataReference
+
+==  EDC Data Plane ==
+
+' mapToShellId
+' DecentralDigitalTwinRegistryClient.getAssetAdministrationShellDescriptor
+DTRS -> DTR: Query for DT
+DTR -> DTRS: DT
+
+@enduml

docs/src/docs/arc42/cross-cutting/discovery-process-dtr.adoc

@@ -1,8 +1,6 @@
 The Dataspace Discovery Service handles multiple EDC-Urls received for BPN.
 This applies to the following scenarios.
 
-__Please note that the expression "the first result" in the subsequent sections means the first successful answer.__
-
 ==== Scenario 1: EDC with multiple DTRs
 
 IRS queries all DTRs for the globalAssetId and will take the first result it gets.
@@ -13,6 +11,15 @@ If none of the DTRs return a result, IRS will create a tombstone.
 include::discovery-DTR--one-EDC-with-multiple-DTRs.puml[]
 ....
 
+
+Same diagram with a little more detail on IRS side:
+
+[plantuml,target=discovery-DTR--one-EDC-with-multiple-DTRs--detailed,format=svg]
+....
+include::discovery-DTR--one-EDC-with-multiple-DTRs--detailed.puml[]
+....
+
+
 ==== Scenario 2: Multiple EDCs with one DTR
 
 IRS starts a contract negotiation for all registry contract offers in parallel and queries the DTRs for all successful negotiations.
@@ -23,6 +30,16 @@ The first registry which responds with a DT will be the one used by IRS.
 include::discovery-DTR--multiple-EDCs-with-one-DTR.puml[]
 ....
 
+
+Same diagram with a little more detail on IRS side:
+
+[plantuml,target=discovery-DTR--multiple-EDCs-with-one-DTR--detailed,format=svg]
+....
+include::discovery-DTR--multiple-EDCs-with-one-DTR--detailed.puml[]
+....
+
+
+
 ==== Scenario 3: One EDC with one DTR
 
 Only one EDC found for BPN and the catalog only contains one offer for the DTR.
@@ -33,6 +50,14 @@ IRS will use this registry and will create a tombstone if no DT could be found f
 include::discovery-DTR--one-EDC-with-one-DTR.puml[]
 ....
 
+Same diagram with a little more detail on IRS side:
+
+[plantuml,target=discovery-DTR--one-EDC-with-one-DTR--detailed,format=svg]
+....
+include::discovery-DTR--one-EDC-with-one-DTR--detailed.puml[]
+....
+
+
 ==== Scenario 4: Multiple EDCs with multiple DTRs
 
 IRS starts a contract negotiation for all the registry offers.
@@ -42,6 +67,15 @@ IRS starts a contract negotiation for all the registry offers.
 include::discovery-DTR--multiple-EDCs-with-multiple-DTRs.puml[]
 ....
 
+Same diagram with a little more detail on IRS side:
+
+[plantuml,target=discovery-DTR--multiple-EDCs-with-multiple-DTRs--detailed,format=svg]
+....
+include::discovery-DTR--multiple-EDCs-with-multiple-DTRs--detailed.puml[]
+....
+
+
+
 ==== Scenario 5: Multiple EDCs with no DTRs
 
 IRS starts a contract negotiation for all the registry offers and creates a tombstone since no DTR could be discovered.
@@ -51,6 +85,13 @@ IRS starts a contract negotiation for all the registry offers and creates a tomb
 include::discovery-DTR--multiple-EDCs-with-no-DTRs.puml[]
 ....
 
+Same diagram with a little more detail on IRS side:
+
+[plantuml,target=discovery-DTR--multiple-EDCs-with-no-DTRs--detailed,format=svg]
+....
+include::discovery-DTR--multiple-EDCs-with-no-DTRs--detailed.puml[]
+....
+
 ==== Special Scenario: Same DT in multiple DTRs
 
 IRS will use all registries to query for the globalAssetId and takes the first result which is returned.