docs: updated documentation for arc42, interface doc and user guide

eclipse-tractusx · Jan 5, 2024 · 38431f6 · 38431f6
1 parent 5350252
commit 38431f6
Show file tree

Hide file tree

Showing 21 changed files with 245 additions and 21 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -11,4 +11,4 @@ The following table links you to the respective documentations.
 | [DEVELOPMENT.MD](./DEVELOPMENT.md)                         | Information relevant, if you contribute in PURIS development.   |
 | [Administration Guide](./adminGuide/Admin_Guide.md)        | Information relevant, if you want to use the PURIS application. |
 | [Interface Documentation](./interfaceDoc/Interface_Doc.md) | Information about the interfaces.                               |
-| User Manual                                                | TODO                                                            |
+| [User Manual](./userGuide/User_Guide.md)                   | Explanation of the views and how to use them.                   |
diff --git a/docs/adminGuide/Admin_Guide.md b/docs/adminGuide/Admin_Guide.md
@@ -229,3 +229,9 @@ overwrite the existing stocks.
 |----------------|----------------------------|---------------------------------------|
 | Product Stock  | /stockView/product-stocks  | Add stocks allocated to your customer |
 | Material Stock | /stockView/material-stocks | Add stocks allocated to your supplier |
+
+## Postgres
+
+The PURIS Backend uses a postgres Database. The helm installation already has a dependency that may be installed with 
+the chart. Optionally it may be disabled to use your own installation. Refer to the overall 
+[INSTALL.md](../../INSTALL.md) for further information.
diff --git a/docs/arc42/04_solution_strategy.md b/docs/arc42/04_solution_strategy.md
@@ -3,12 +3,13 @@
 **Organization**
 
 PURIS FOSS
-- follows the related standardization candidates or even published standards.
+- follows the related standardization candidates or even published standards (CX-0112).
 - is developed parallel to the consortial SAFe project.
 
 **Up-to-dateness / real-time**
 
-- Stock information has always the latest amount. E.g. at 6 a.m. there is a stock of 60 parts of material and at 8 a.m. there is a stock of 80 parts of material.
+- Stock information has always the latest amount. E.g. at 6 a.m. there is a stock of 60 parts of material and at 8 a.m.
+there is a stock of 80 parts of material.
 - Demand and Production Output are measured "per day" e.g., today's demand and next thursday's demand.
 
 **Interoperable Data Exchange and Pattern**

diff --git a/docs/arc42/05_building_block_view.md b/docs/arc42/05_building_block_view.md
@@ -12,6 +12,7 @@ been omitted for readability.
 | PURIS FOSS Frontend                | This system represents the PURIS FOSS user interface. It handles the data visualization.                                                                                                                                                  |                                                                                                                                                  
 | EDC                                | The Eclipse Dataspace Components Connector (EDC) is the component allowing PURIS FOSS to participate in the IDS. It is used to provide and consume data assets following policy information. Any data transfer is routed through the EDC. |
 | Keycloak                           | Keycloak is an identity provider that can manage multiple clients (applications). Catena-X allows the usage of a shared identity provider.                                                                                                |
+| Postgresql DB                      | Database used by Backend to persist data                                                                                                                                                                                                  |
 
 ## Level 1 White Boxes
 
@@ -21,10 +22,12 @@ been omitted for readability.
 
 The Frontend only handles visualization logic. The remaining logic is handled in the backend.
 
-| Component / system | Descriptions                                                                                                                                                 |
-|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Stock View         | Allows to manually add or update stock information that is allocated to partners. Also latest stock information for partners may be requested (via backend). |
-| Dashboard          | The dashboard allows to compare material-related demands, production outputs and stocks in a mocked way. Only Stock information is currently implements.     |
+| Component / system     | Descriptions                                                                                                                                                 |
+|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Stock View             | Allows to manually add or update stock information that is allocated to partners. Also latest stock information for partners may be requested (via backend). |
+| Dashboard              | The dashboard allows to compare material-related demands, production outputs and stocks in a mocked way. Only Stock information is currently implements.     |
+| Authentication Service | Encapsulates keycloak authentication and session management to be used by the main app.                                                                      |
+| Access Service         | Steers based on the roles (see [Admin Guide](../../adminGuide/Admin_Guide.md)) which views may be visited by the user.                                       |
 
 **PURIS FOSS Backend**
 

diff --git a/docs/arc42/06_runtime_view.md b/docs/arc42/06_runtime_view.md
@@ -24,6 +24,13 @@ The API implementations are provided and consumed via the EDC.
         1. Provider queries API for information of interest based on the standardized API description.
         1. Consumer receives request, determines data for response and starts with step 2 for the response interface.
 
+The workflow with simplified EDC communication may be seen in the following sequence diagram.
+EDC flow is the same to use the request and response api. Central Services, such as the Managed Identity Wallet are 
+ommitted.
+
+![Overview of request and response with EDC](puml/06-api-flow-detailed.svg)
+
+
 ## Scenario: Interact with data in web-ui
 
 When reloading the UI, the latest data is pulled from the backend. Whenever an update on the information is performed,

diff --git a/docs/arc42/07_deployment_view.md b/docs/arc42/07_deployment_view.md
@@ -2,18 +2,21 @@
 
 ## Local Deployment
 
-Overall the Deployment locally looks similar to the following graphic.
+Overall the Deployment locally using the [INSTALL.md in local](../../local/INSTALL.md) looks similar to the following graphic.
 
-![Local Deployment of two PURIS clients with MVD](puml/07-deployment.svg)
-
-**Docker**
-
-_to be merged_
+![Local Deployment of two PURIS clients with MVD](./puml/07-deployment.svg)
 
 **Helm / Kubernetes**
 
 One can configure the two local helm environments using the product helm chart and the [mxd tutorial](https://github.com/eclipse-tractusx/tutorial-resources/tree/main/mxd).
 
 ## ArgoCD Deployment (e.g. INT)
 
-_to be done_
+The very basic deployment for one PURIS FOSS looks as follows:
+
+![Argo CD Deployment of one PURIS client](./puml/07-deployment-argo.svg)
+
+The keycloak may be configured to be used. Also a decentral instance may be connected to the frontend. Refer to the 
+[helm docs](../../charts/puris/README.md) for further information.
+
+The chart allows also to either install the database as a dependency or bring your own.
diff --git a/docs/arc42/08_concepts.md b/docs/arc42/08_concepts.md
@@ -7,3 +7,20 @@ share the same material number.
 A partner asking for information may not receive any information that are not meant for him. Therefor the PURIS concept
 is, that exchanged information MUST be allocated to a partner to not leak any partner relationships in the vertical
 direction.
+
+## Material Numbers
+
+In the backend materials are commonly handled by the own material number. The partner material relationship then brings
+the respective material number of a partner leading to the following constellations:
+- puris user acts as customer: 
+  - own material number = material number customer
+  - material number partner = material number supplier
+- puris user acts as supplier: 
+    - own material number = material number supplier
+    - material number partner = material number customer
+
+
+## Security
+
+Backend APIs are secured by an API Key. The Frontend may be configured to be accessed based on keycloak authentication.
+Refer to the [Admin Guide](../adminGuide/Admin_Guide.md) for further information.
diff --git a/docs/arc42/11_technical_risks.md b/docs/arc42/11_technical_risks.md
@@ -3,4 +3,4 @@
 This application started as a demonstrator and is enhanced to become an application. This may lead to technical
 debts that need to be resolved later.
 
-Until now, no automatic tests (not even unit tests) have been implemented.
+Until now, automated test coverage is low to medium.
diff --git a/docs/arc42/puml/05-level-0.puml b/docs/arc42/puml/05-level-0.puml
@@ -1,11 +1,12 @@
 @startuml
 [Data Provisioning & Transformation] as data_prov
 [Eclipse DataSpace Components Connector] as edc
+[Postgresql DB] as postgres
 [Keycloak] as idp
 
 data_prov -( "Interface internal systems"
 edc -- "EDC APIs"
-
+e
 package "<<system>> PURIS"{
 
   [PURIS FOSS Backend] as puris_backend
@@ -14,7 +15,8 @@ package "<<system>> PURIS"{
   "EDC APIs" )-- "provide and pull data\naccording to standards" puris_backend
   "Interface internal systems" - puris_backend
   puris_backend <-- puris_frontend
-  idp <- puris_frontend
+  puris_frontend -- idp
+  puris_backend --> postgres
 
 }