From 964db6b68917ed42c864db6824df319340de8f2e Mon Sep 17 00:00:00 2001 From: Tunahan Cicek Date: Wed, 13 Nov 2024 15:26:08 +0100 Subject: [PATCH] Move arc42 doc to /architecure --- CHANGELOG.md | 5 ++ docs/README.md | 26 ++++++ .../1-introduction-and-goals.md | 6 +- .../2-architecture-constraints.md | 0 .../3-system-scope-and-context.md | 0 docs/{ => architecture}/4-runtime-view.md | 0 docs/{ => architecture}/5-deployment-view.md | 7 +- .../6-crosscutting-concepts.md} | 44 +++++++++- .../{ => architecture}/7-quality-scenarios.md | 0 docs/{ => architecture}/glossary.md | 0 .../media/OverallConcept.png | Bin docs/documentation.md | 82 ------------------ 12 files changed, 78 insertions(+), 92 deletions(-) create mode 100644 docs/README.md rename docs/{ => architecture}/1-introduction-and-goals.md (75%) rename docs/{ => architecture}/2-architecture-constraints.md (100%) rename docs/{ => architecture}/3-system-scope-and-context.md (100%) rename docs/{ => architecture}/4-runtime-view.md (100%) rename docs/{ => architecture}/5-deployment-view.md (70%) rename docs/{6-concepts.md => architecture/6-crosscutting-concepts.md} (70%) rename docs/{ => architecture}/7-quality-scenarios.md (100%) rename docs/{ => architecture}/glossary.md (100%) rename docs/{ => architecture}/media/OverallConcept.png (100%) delete mode 100644 docs/documentation.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 67af0b7..e9765c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 0.5.2 +### Added +### fixed +- Change documentation folder structure + ## 0.5.1 ### Added ### fixed diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..25e157a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ + + +# Introduction +Following documentation is available: + +| Documentation | Purpose | +|-------------------------------------------------|------------------------------------------------------| +| [Arc42](architecture/) | Architecture documentation for the discovery finder. | \ No newline at end of file diff --git a/docs/1-introduction-and-goals.md b/docs/architecture/1-introduction-and-goals.md similarity index 75% rename from docs/1-introduction-and-goals.md rename to docs/architecture/1-introduction-and-goals.md index 83f1c59..d163c7c 100644 --- a/docs/1-introduction-and-goals.md +++ b/docs/architecture/1-introduction-and-goals.md @@ -28,10 +28,10 @@ The Discovery Finder is used to find an endpoint to a BPD Discovery for a certai | 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 | +| Data Consumer | The data consumer uses the Discovery Finder to search for endpoints for BPN Discoveries for a specific type. | wants to find an Endpoint for a BPN Discovery to find a BPN | +| Data Provider | The data provider adds or deletes his endpoint at the Discovery Finder | 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 | - +| Keycloak | Keycloak is used for token validation | | ### NOTICE diff --git a/docs/2-architecture-constraints.md b/docs/architecture/2-architecture-constraints.md similarity index 100% rename from docs/2-architecture-constraints.md rename to docs/architecture/2-architecture-constraints.md diff --git a/docs/3-system-scope-and-context.md b/docs/architecture/3-system-scope-and-context.md similarity index 100% rename from docs/3-system-scope-and-context.md rename to docs/architecture/3-system-scope-and-context.md diff --git a/docs/4-runtime-view.md b/docs/architecture/4-runtime-view.md similarity index 100% rename from docs/4-runtime-view.md rename to docs/architecture/4-runtime-view.md diff --git a/docs/5-deployment-view.md b/docs/architecture/5-deployment-view.md similarity index 70% rename from docs/5-deployment-view.md rename to docs/architecture/5-deployment-view.md index 679263a..31ecb83 100644 --- a/docs/5-deployment-view.md +++ b/docs/architecture/5-deployment-view.md @@ -6,11 +6,8 @@ For Deployment needed: - 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). +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](../../README.md) and the [INSTALL.md](../../INSTALL.md). ### NOTICE diff --git a/docs/6-concepts.md b/docs/architecture/6-crosscutting-concepts.md similarity index 70% rename from docs/6-concepts.md rename to docs/architecture/6-crosscutting-concepts.md index 21b02b4..c74531b 100644 --- a/docs/6-concepts.md +++ b/docs/architecture/6-crosscutting-concepts.md @@ -1,4 +1,4 @@ -## 6 Concept +## 6 Crosscutting Concept ### Overall Concept @@ -118,8 +118,48 @@ 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. -### NOTICE +### 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 | + + +### Security Assessment +#### Data Flow Diagram + +```mermaid +%%{init: {"flowchart": {"curve": "linear"} }}%% +flowchart + DC(Data Consumer \n e.g. IR) + DP(Data Provider) + K(Keycloak) + subgraph Discovery Finder + DF(Discovery Finder Backend) + DFDB[(Discovery Finder postgres)] + end + subgraph BPN Discovery + BD(BPN Discovery Backend) + BDDB[(BPN Discovery postgres \n N instances per data \n asset type and usage)] + end + + DC <-->|Token request| K + DP <-->|Token request| K + DF <-->|Request endpoint for given type| DC + DF <--> DFDB + K -.->|Provide public key for token validation| DF + BD <--> BDDB + DC <-->|Request BPN for specific type| BD + DP -->|Register BPN type key| BD + BD -->|Success/error message for registration| DP + K -.->|Provide public key for token validation| BD +``` +### NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). - SPDX-License-Identifier: Apache-2.0 diff --git a/docs/7-quality-scenarios.md b/docs/architecture/7-quality-scenarios.md similarity index 100% rename from docs/7-quality-scenarios.md rename to docs/architecture/7-quality-scenarios.md diff --git a/docs/glossary.md b/docs/architecture/glossary.md similarity index 100% rename from docs/glossary.md rename to docs/architecture/glossary.md diff --git a/docs/media/OverallConcept.png b/docs/architecture/media/OverallConcept.png similarity index 100% rename from docs/media/OverallConcept.png rename to docs/architecture/media/OverallConcept.png diff --git a/docs/documentation.md b/docs/documentation.md deleted file mode 100644 index e3ca51f..0000000 --- a/docs/documentation.md +++ /dev/null @@ -1,82 +0,0 @@ -# Developer Documentation Tractus-X Discovery Finder - -This page provides an overview of the Discovery Finder. - -## 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 | | - - -## Discovery 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 - -## 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) and the [INSTALL.md](INSTALL.md). - -## Security Assessment - -### Data Flow Diagram - -```mermaid -%%{init: {"flowchart": {"curve": "linear"} }}%% -flowchart - DC(Data Consumer \n e.g. IR) - DP(Data Provider) - K(Keycloak) - subgraph Discovery Finder - DF(Discovery Finder Backend) - DFDB[(Discovery Finder postgres)] - end - subgraph BPN Discovery - BD(BPN Discovery Backend) - BDDB[(BPN Discovery postgres \n N instances per data \n asset type and usage)] - end - - DC <-->|Token request| K - DP <-->|Token request| K - DF <-->|Request endpoint for given type| DC - DF <--> DFDB - K -.->|Provide public key for token validation| DF - BD <--> BDDB - DC <-->|Request BPN for specific type| BD - DP -->|Register BPN type key| BD - BD -->|Success/error message for registration| DP - K -.->|Provide public key for token validation| BD -``` - -### NOTICE - -This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). - -- SPDX-License-Identifier: Apache-2.0 -- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH -- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/sldt-discovery-finder.git