eclipse-tractusx · tunacicek · May 24, 2023 · Apr 26, 2023 · Apr 27, 2023 · Apr 28, 2023
diff --git a/docs/1-introduction-and-goals.md b/docs/1-introduction-and-goals.md
@@ -0,0 +1,34 @@
+## 1 Introduction and goals
+
+The Digital Twins are no longer administrated in a central registry. The implementation of two services, "Discovery Finder" and "BPN
+Discovery", ensure that Eclipse Data Space Connectors (EDC) can be found in the decentralized
+environment.
+
+The Discovery Finder is responsible to find a matching BPN Discovery for a specific type.
+
+### High level requirement 
+
+The Discovery Finder is used to find an endpoint to a BPD Discovery for a certain type and at last to find an EDC.
+
+### Quality goals
+
+-   Ensure that EDCs can be found.
+
+-   Data sovereignty is given. The provider is responsible for his data.
+
+-   All users and services are secured and can only access when
+    authenticated and authorized.
+
+-   Discovery Finder and BPN Discovery are "central" services
+    (horizontal and vertical scalability included) and meant to help to
+    connect companies. So it is integrated into the
+    Catena-X network with all their services.
+
+### Stakeholders
+
+| Role             | Description                                        | Goal, Intention                                             |
+|------------------|----------------------------------------------------|-------------------------------------------------------------|
+| Consumer         | uses a Discovery Finder                            | wants to find an Endpoint for a BPN Discovery to find a BPN |
+| Data Provider    |                                                    | wants that his EDC / Digital Twin can be found              |
+| Catena-X network | provides the environment and operates the services | to enable the companies to connect and exchange data        |
+
diff --git a/docs/2-architecture-constraints.md b/docs/2-architecture-constraints.md
@@ -0,0 +1,41 @@
+## 2 Architecture and constraints
+
+### Overall Architecture
+
+A consumer sends a request to the Discovery Finder with a catalogue of a certain type e.g., "bpid", "oen". The Discovery Finder 
+responses with a list of endpoints of BPN Discoveries which provide BPNs for these kind of types.  
+Subsequently the consumer sends a request to the given BPN Discoveries. If the BPN Discovery finds matching entries he returns a List of BPNs. 
+With the given BPN the consumer can search for EDCs at the EDC Discovery according to this BPN.
+
+### Overall-View
+
+![Overall view](media/OverallConcept.png)
+
+### Architecture
+A consumer can send a request to the Discovery Finder with a catalogue of different types. The Discovery Finder then will send a list of endpoint of
+BPN Discoveries which are providing BPNs for the requested types. 
+
+
+### Constraints
+
+-   Every Provider handles its own EDC / Digital Twin Registry - this
+    is no central service.
+
+-   Consumer and Data Provider must have a technical user with correct user-roles
+
+-   The Discovery Finder is a central component and must be managed by
+    one instance.
+
+### Architecture Constraints
+
+-   Developed under an open-source license and all used frameworks and
+    libraries suites to this license.
+
+-   Must be compliant and fulfill the Catena-X Guidelines.
+
+-   The deployment is done in a Catena-X environment. So, the Discovery Finder must be able to run in a Kubernetes environment with Helm
+    Charts.
+
+-   The Discovery Finder must be managed centralized.
+
+-   Keycloak as an OAuth2 compliant authorization is needed to manage the identity and access of the user.
diff --git a/docs/3-system-scope-and-context.md b/docs/3-system-scope-and-context.md
@@ -0,0 +1,22 @@
+## 3 System scope and context
+
+### Business Context
+
+![](media/BusinessContext.PNG)
+
+| Neighbor      | Description                                          |
+|---------------|------------------------------------------------------|
+| Consumer App  | Searches for endpoints for a given type, e.g.  "oen" |
+| BPN Discovery | Registers himself at startup                         |
+| Keycloak      | Is used for token validation                         |
+
+
+### Technical Context
+
+![](media/TechnicalContext.PNG)
+
+| Neighbor      | Description                                                              |
+|---------------|--------------------------------------------------------------------------|
+| Consumer App  | Requests for a BPN Discovery for a certain type like "oen"               |
+| Keycloak      | Generates token for users and provides id management of user and service |
+| BPN Discovery | Registers itself at startup                                              |
diff --git a/docs/4-runtime-view.md b/docs/4-runtime-view.md
@@ -0,0 +1,52 @@
+## 4 Runtime-view
+
+### Search request
+
+![](media/SearchFlow.PNG)
+
+1.  The ConsumerApp sends a request of a certain type to
+    DiscoveryEndpointFinderApiDelegate.
+
+2.  DiscoveryEndpointFinderApiDelegate calls DiscoveryFinderService to
+    find DiscoveryEndpoints.
+
+3.  DiscoveryFinderService calls EndpointRepository to search in
+    database.
+
+4.  BPNDiscoveryService sends as a result an EndpointCollectionDto to
+    DiscoveryEndpointFinderApiDelegate.
+
+5.  DiscoveryEndpointFinderApiDelegate sends a response to the
+    ConsumerApp with the found results.
+
+### Add request
+
+![](media/AddFlow.PNG)
+
+1.  The Data Provider sends a request with a given endpoint to
+    DiscoveryEndpointFinderApiDelegate.
+
+2.  DiscoveryEndpointFinderApiDelegate calls DiscoveryFinderService to
+    save this entry. Within this call the DiscoveryFinderMapper maps the
+    request object to an Enpoint.
+
+3.  DiscoveryFinderService calls the EndpointRepository to save the new
+    entry in the database.
+
+### Delete request
+
+![](media/DeleteFlow.PNG)
+
+1.  The Data Provider sends a request to delete an entry to
+    DiscoveryEndpointFinderApiDelegate.
+
+2.  DiscoveryEndpointFinderApiDelegate calls the DiscoveryFinderService
+    to delete the Endpoint.
+
+3.  DiscoveryFinderService calls UuidUtils to validate the resourceId.
+
+4.  DiscoveryFinderService calls the EndpointRepository to find the
+    entry or throws an exception if the entry can't be found.
+
+5.  DiscoveryFinderService calls the EndpointRepository to delete
+    finally the entry from the database.
diff --git a/docs/5-deployment-view.md b/docs/5-deployment-view.md
@@ -0,0 +1,13 @@
+## 5 Deployment-view
+
+For Deployment needed:
+
+-   Webserver
+-   Kubernetes-Cluster
+-   Helm
+
+To deploy this system, you need to use the Helm Chart in a running
+Kubernetes cluster. The Helm Chart is located under
+"charts/discoveryfinder". In case you don't have a running cluster, you
+can set up one by yourself locally, using minikube. For further information
+checkout the [readme.md](https://github.com/eclipse-tractusx/sldt-discovery-finder/blob/main/README.md).
diff --git a/docs/6-concepts.md b/docs/6-concepts.md
@@ -0,0 +1,115 @@
+## 6 Concept
+
+### Overall Concept
+
+The overall concept can be found under **2 Architecture and
+constraints**.
+
+### Discovery Finder API
+
+The Discovery Finder is a central component in the environment. Every
+consumer and data provider can call this service via the given api
+endpoints.
+
+The api with its links can be found here: [Discovery Finder Api]( https://semantics.int.demo.catena-x.net/discoveryfinder/swagger-ui/index.html)
+
+#### POST [/api/administration/connectors/discovery]
+
+Define the endpoint to BPN discovery services and the EDC discovery
+service.
+
+**Request body:**
+
+```json
+{
+  "type": "oen",
+  "description": "Service to discover BPN to a particular OEN",
+  "endpointAddress": "http://...",
+  "documentation": "http://.../swagger/index.html"
+}
+```
+
+**Response:**
+
+```json
+{
+  "type": "oen",
+  "description": "Service to discover BPN to a particular OEN",
+  "endpointAddress": "http://...",
+  "documentation": "http://.../swagger/index.html",
+  "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67"
+}
+```
+
+This service is allowed to **administrators only**.
+
+
+#### POST [/api/administration/connectors/discovery/search]
+
+Find the endpoints to BPN discovery services and the EDC discovery
+service.
+
+**Request body:**
+
+```json
+{
+"types": 
+ [
+   "oen", 
+   "bpid"
+ ]
+}
+```
+
+**Response:**
+
+```json
+{"endpoints":
+ [
+  {
+    "type": "oen",
+    "description": "Service to discover BPN to a particular OEN",
+    "endpointAddress": "http://...",
+    "documentation": "http://.../swagger/index.html",
+    "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67"
+  },
+  {
+    "type": "bpid",
+    "description": "Service to discover BPN to a particular Battery Pass ID",
+    "endpointAddress": "http://...",
+    "documentation": "http://.../swagger/index.html",
+    "resourceId": "08702529-3714-4c4f-b022-346b9b4fbbe2"
+  }
+ ]
+}
+```
+
+#### DELETE [/api/administration/connectors/discovery/{resourceId}]
+
+Delete the endpoint to BPN discovery services and the EDC discovery service.
+This service is allowed to **administrators only**.
+
+Path variable {resourceId} is required
+Response: http Status Code 204 -> no response
+
+An OpenApi.yaml for this service can be found under:
+"backend/src/main/resources/static/discovery-finder-openapi.yaml" [Link](https://github.com/eclipse-tractusx/sldt-discovery-finder/blob/main/backend/src/main/resources/static/discovery-finder-openapi.yaml)
+
+
+### Security / Safety / Use of JWT Token
+
+The whole environment is secured with OAuth2. We used and recommend the usage of Keycloak. The Discovery Finder has
+a realm entry in Keycloak. Every user who wants to use Discovery Finder
+need the corresponding roles for his user.
+
+The roles are:
+
+1. [ ] *VIEW*( "view_discovery_endpoint" )
+2. [ ] *ADD*( "add_discovery_endpoint" )
+3. [ ] *DELETE*( "delete_discovery_endpoint" )
+
+These roles are sent within a JWT Token generated by Keycloak.
+
+With all three roles it is possible to add and delete entries from the
+Discovery Finder Database. For searching the view role is sufficient.
+The credentials are set with entries in Helm Charts.
diff --git a/docs/7-quality-scenarios.md b/docs/7-quality-scenarios.md
@@ -0,0 +1,9 @@
+## 7 Quality scenarios
+
+### Quality Requirements
+
+| Tool       | Description                                                                                                                                                                                                                                              |
+|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Veracode   | "Veracode enables you to quickly and cost-effectively scan software for flaws and get actionable source code analysis results."[Link](https://www.veracode.com)                                                                                          |
+| Trivy      | "Trivy is a simple and comprehensive vulnerability/misconfiguration/secret scanner for containers and other artifacts. Trivy detects vulnerabilities of OS packages and language-specific packages." [Link](https://aquasecurity.github.io/trivy/v0.34/) |
+| SonarCloud | "SonarCloud's static analysis detects Bugs and Code Smells in your repositories and provides the feedback you need to write better code." [Link](https://www.sonarsource.com/products/sonarcloud/)                                                       |
diff --git a/docs/documentation.md b/docs/documentation.md
@@ -2,4 +2,74 @@
 
 This page provides an overview of the Discovery Finder.
 
-## Architectural Overview
+## Architectural Overview
+The Digital Twins are no longer administrated in a central registry. The implementation of two services, "Discovery Finder" and "BPN
+Discovery", ensures that EDCs still can be found in the decentralized environment.
+The Discovery Finder hereby is responsible to send endpoints from BPN Discoveries for a specific type.
+
+![Overall view](media/OverallConcept.png)
+
+## Actors
+There are two actors who interact with the Discovery Finder
+
+| Actor         | Description                                                                                                  | Example                                               |
+|---------------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|
+| Data Consumer | The data consumer uses the Discovery Finder to search for endpoints for BPN Discoveries for a specific type. |                                                       |
+| Data Provider | The data provider adds or deletes his endpoint at the Discovery Finder                                       | A BPN Discovery registers its endpoint after startup. |
+| Keycloak      | Keycloak is used for token validation                                                                        |                                                       |
+
+
+## Disovery Finder Api
+
+The Discovery Finder provides a Swagger-Interface for all its endpoints:
+https://semantics.int.demo.catena-x.net/discoveryfinder/swagger-ui/index.html
+
+#### Search request
+![](media/search_DF.PNG)
+
+**Reqiest body**
+
+![](media/Request_Search_DF.PNG)
+
+**Response**
+
+![](media/Response_Search_DF.PNG)
+
+#### Add request
+![add endpoint](media/setDF_Endpoint.PNG)
+
+**Request body**
+
+![request body](media/Request_Set_DF_Endpoint.PNG)
+
+**Response**
+
+![response](media/Response_Set_DF_Endpoint.PNG)
+
+#### Delete request
+![delete endpoint](media/Delete_DF.PNG)
+
+ResourceID in path
+
+![ResourceID ](media/ResourceID_DF.PNG)
+
+**Response**
+
+![response](media/Response_Delete_DF.PNG)
+
+## Authentication & Authorization
+The service is secured by a OAuth2 compliant authorization. Every API call has to provide a
+valid Bearer Token. Authorization is provided by a role based access. These roles are possible:
+
+| Role                      | Description                            |
+|---------------------------|----------------------------------------|
+| view_discovery_endpoint   | can search for BPN Discovery endpoints |
+| add_discovery_endpoint    | can add BPN Discovery endpoints        |
+| delete_discovery_endpoint | can delete BPN Discovery endpoints     |
+
+## Deployment
+
+To deploy this system, you need to use the Helm Chart in a running
+Kubernetes cluster. The Helm Chart is located under
+"charts/discoveryfinder". For further information
+checkout the [readme.md](https://github.com/eclipse-tractusx/sldt-discovery-finder/blob/main/README.md). 
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -0,0 +1,8 @@
+## Glossary**
+
+| Term     | Description                                                                                                |
+|----------|------------------------------------------------------------------------------------------------------------|
+| Keycloak | Keycloack is an open-source Identity Management and Access management solution that allows Single Sign-On. |
+| Realm    | Manages a set of users, credentials, roles. Authenticates the users it controls.                           |
+| BPN      | Business Partner Number                                                                                    |
+| EDC      | Eclipse Data Space Connector                                                                               |
diff --git a/docs/media/AddFlow.PNG b/docs/media/AddFlow.PNG
diff --git a/docs/media/BusinessContext.PNG b/docs/media/BusinessContext.PNG
diff --git a/docs/media/DeleteFlow.PNG b/docs/media/DeleteFlow.PNG
diff --git a/docs/media/Delete_DF.PNG b/docs/media/Delete_DF.PNG
diff --git a/docs/media/OverallConcept.png b/docs/media/OverallConcept.png
diff --git a/docs/media/Request_Search_DF.PNG b/docs/media/Request_Search_DF.PNG
diff --git a/docs/media/Request_Set_DF_Endpoint.PNG b/docs/media/Request_Set_DF_Endpoint.PNG
diff --git a/docs/media/ResourceID_DF.PNG b/docs/media/ResourceID_DF.PNG
diff --git a/docs/media/Response_Delete_DF.PNG b/docs/media/Response_Delete_DF.PNG
diff --git a/docs/media/Response_Search_DF.PNG b/docs/media/Response_Search_DF.PNG
diff --git a/docs/media/Response_Set_DF_Endpoint.PNG b/docs/media/Response_Set_DF_Endpoint.PNG
diff --git a/docs/media/SearchFlow.PNG b/docs/media/SearchFlow.PNG
diff --git a/docs/media/TechnicalContext.PNG b/docs/media/TechnicalContext.PNG