Merge pull request #172 from bci-oss/chore/arc42-structure

Move arc42 doc to architecture/ folder
eclipse-tractusx · Nov 18, 2024 · 2aabb93 · 2aabb93
2 parents 855f896 + 87157aa
commit 2aabb93
Show file tree

Hide file tree

Showing 12 changed files with 89 additions and 101 deletions.
diff --git 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
@@ -0,0 +1,26 @@
+<!--
+ * Copyright (c) 2024 Robert Bosch Manufacturing Solutions GmbH
+ * Copyright (c) 2024 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License, Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+-->
+
+# Introduction
+Following documentation is available:
+
+| Documentation                                   | Purpose                                           |
+|-------------------------------------------------|---------------------------------------------------|
+| [Arc42](architecture/)                  | Architecture documentation for the bpn discovery. |
diff --git a/docs/1-introduction-and-goals.md → .../architecture/1-introduction-and-goals.md b/docs/1-introduction-and-goals.md → .../architecture/1-introduction-and-goals.md
@@ -32,7 +32,6 @@ The BPN Discovery is used to find according BPNs for a given type / key combinat
 | Data Provider    | registers his keys of a specific type in a BPN Discovery | 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 |
 
-
 ### NOTICE
 
 This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

diff --git a/docs/2-architecture-constraints.md → ...rchitecture/2-architecture-constraints.md b/docs/2-architecture-constraints.md → ...rchitecture/2-architecture-constraints.md
@@ -1,7 +1,6 @@
 ## 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.

diff --git a/docs/3-system-scope-and-context.md → ...rchitecture/3-system-scope-and-context.md b/docs/3-system-scope-and-context.md → ...rchitecture/3-system-scope-and-context.md
@@ -11,12 +11,12 @@ graph LR
     Data_Provider[Data Provider] -- "register his types and keys" --> BPN_Discovery
 ```
 
-| Neighbor         | Description                                  |
-|------------------|----------------------------------------------|
-| Consumer App     | Searches a BPN                               |
-| Data Provider    | Registers his type and keys at BPN Discovery |
-| Discovery Finder | Provides the endpoints of BPN Discoveries    |
-| Keycloak         | Keycloak is used for token validation        |
+| Neighbor         | Description                                   | Example                                                       |
+|------------------|-----------------------------------------------|---------------------------------------------------------------|
+| Consumer App     | Searches a BPN of given typ / key combination | A consumer searches for a BPN for type "oen" / key "123-oen". |
+| Data Provider    | Registers his type and keys at BPN Discovery  | A provider add a type "oen" / key "123-oen" under his BPN.    |
+| Discovery Finder | Provides the endpoints of BPN Discoveries     |                                                               |
+| Keycloak         | Keycloak is used for token validation         |                                                               |
 
 
 ### Technical Context

diff --git a/docs/4-runtime-view.md → docs/architecture/4-runtime-view.md b/docs/4-runtime-view.md → docs/architecture/4-runtime-view.md
diff --git a/docs/5-deployment-view.md → docs/architecture/5-deployment-view.md b/docs/5-deployment-view.md → docs/architecture/5-deployment-view.md
@@ -8,10 +8,9 @@ For Deployment needed:
 
 -   Helm
 
-To deploy this system, you need to use the Helm Chart in a running
-Kubernetes cluster. The Helm Chart is located under "charts/bpndiscovery".
+To deploy this system, you need to use the Helm Chart in a running Kubernetes cluster. The Helm Chart is located under "charts/bpndiscovery".
 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-bpn-discovery/blob/main/README.md).
+locally, using minikube. For further information checkout the [readme.md](../../README.md). and [install.md](../../INSTALL.md).
 
 
 ### NOTICE

diff --git a/docs/6-concepts.md → docs/architecture/6-crosscutting-concepts.md b/docs/6-concepts.md → docs/architecture/6-crosscutting-concepts.md
@@ -1,9 +1,8 @@
-## 6 Concept
+## 6 Crosscutting Concept
 
 ### Overall Concept
 
-#The overall concept can be found under **2 Architecture and
-constraints**.
+The overall concept can be found under **2 Architecture and constraints**.
 
 ### BPN Discovery API
 
@@ -182,7 +181,7 @@ These roles and the BPN of the requester are send within a JWT Token
 generated by Keycloak.
 
 With all three roles it is possible to add and delete entries from the
-BPN Discovery Database. To ensure that a user only can delete its own entries the BPN of the database entry and the BPN 
+BPN Discovery Database. To ensure that a user only can delete its own entries the BPN of the database entry and the BPN
 from the Token are compared.
 This BPN is also used to add new entries to the BPN Discovery.
 If only search requests are made the view role is sufficient.
@@ -191,7 +190,52 @@ The BPN Discovery registers itself at the Discovery Finder service when
 it starts. Therefore, the BPN Discovery has a technical user for the
 Discovery Finder.
 
-
+### 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_bpn_discovery   | can search for BPN Discovery endpoints |
+| add_bpn_discovery    | can add BPN Discovery endpoints        |
+| delete_bpn_discovery | can delete BPN Discovery endpoints     |
+
+The Bearer Token also provide a claim with the BPN. This BPN is used to store entries.
+When an entry shall be deleted this BPN is used to verify that the requester is allowed to do so.
+
+### Security Assessment
+#### Data Flow Diagram
+
+```mermaid
+%%{init: {"flowchart": {"curve": "linear"} }}%%
+flowchart
+    DC(Data Consumer \n <i>e.g. IR</i>)
+    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 <i>N instances per data \n asset type and usage</i>)]
+    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
 

diff --git a/docs/7-quality-scenarios.md → docs/architecture/7-quality-scenarios.md b/docs/7-quality-scenarios.md → docs/architecture/7-quality-scenarios.md
diff --git a/docs/glossary.md → docs/architecture/glossary.md b/docs/glossary.md → docs/architecture/glossary.md
@@ -1,4 +1,4 @@
-## Glossary
+## 9 Glossary
 
 | Term     | Description                                                                                                |
 |----------|------------------------------------------------------------------------------------------------------------|

diff --git a/docs/media/OverallConcept.png → docs/architecture/media/OverallConcept.png b/docs/media/OverallConcept.png → docs/architecture/media/OverallConcept.png
diff --git a/docs/documentation.md b/docs/documentation.md