Merge pull request #64 from FraunhoferISST/docs/arc42

Docs: Added initial arc42

docs/arc42/01_introduction_and_goals.md

@@ -0,0 +1,47 @@
+# Introduction and Goals
+
+Supply networks are complex. Supply or demand shortages affect multiple partners along the
+supply network. In case a shortage occurs, partners need to collect and exchange manually
+while discussing the potential actions to take.
+
+PURIS FOSS tries to address this manual collection of data. The application tries to facilitate
+this information exchange by implementing the respective information exchange.
+
+PURIS FOSS tries to solve short-term information needs within a given business relationship.
+The information are production and supply chain related. The full-fledged vision is a dashboard
+allowing partners to make their situation transparent exchanging production-related demands,
+planned production quantities and stocks. This information is visualized and exchanged
+on a day granularity and shall be enhanced by delivery information.
+
+In case of material shortages, commonly manual work is done. This tool shall allow to exchange
+common information in those cases and allow status evaluation to not even run into shortages.
+
+Based on less manual work needed, if the system is integrated, users may exchange and collect
+information much faster so that the employees focus on the actual resolving.
+Additionally, PURIS FOSS in Catena-X follows International Data Spaces (IDS) and GAIA-X principles
+providing data sovereignty.
+
+## Requirements Overview
+
+The following requirements shall be fulfilled:
+- Exchange material flow related data (demand, production outputs, stocks and delivery information)
+- Visualize the exchanged information.
+
+## Quality Goals
+
+| Quality Goal              | Motivation and Description                                                                  |
+|---------------------------|---------------------------------------------------------------------------------------------|
+| Compatibility to Catena-X | PURIS FOSS follows similar patterns as use cases in resiliency topics and overall Catena-X. |
+| Fast usage                | PURIS FOSS allows partners to exchange data with as less onboarding effort as needed        |
+| Data sovereignty          | PURIS FOSS follows Catena-X and GAIA-X requirements for data sovereignty                    |
+
+## Stakeholders
+
+Key stakehoders for puris are:
+
+| Stakeholder            | Goal or Interest                            |
+|------------------------|---------------------------------------------|
+| Catena-X Ecosystem     | Integration of the Ecosystem concepts       |
+| Politics and Companies | more resilient supply networks              |
+| SME                    | less efforts for integration                |
+| Disposition            | Knowledge about supply and demand situation |

docs/arc42/02_architecture_constraints.md

@@ -0,0 +1,12 @@
+# Architecture Constraints
+
+PURIS FOSS follows the following constraints:
+
+| Constraint                                 | Background or motivation                                                                                                                                                                                                                                                                                                                                 |
+|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| IDS & GAIA-X Compliance                    | Data sharing, storing and processing must be in compliance to the standards provided by GAIA-X and IDS.                                                                                                                                                                                                                                                  |
+| Data Sharing between Companies             | Companies must use IDS compliant and certified connectors along with an approved Catena-X information model for communication. This guarantees interoperability between certified participants. The Eclipse Dataspace Connector is highly recommended for this purpose. The data should stay inside the connector if full data sovereignty is necessary. |
+| Data sovereignty                           | To ensure data sovereignty, data owners need to attach machine readable usage policies to their data before sharing. The data consumer has to accept the usage policies before processing the data. Connectors (+ the underlying/corresponding systems) must technically enforce those usage policy descriptions.                                        |
+| DAPS                                       | DAPS Registration Service is a central Catena-X Service, which allows registering connectors remotely in Catena-X DAPS service. This Service can be used by all operators of connectors (on-premise, managed)                                                                                                                                            |
+| Interoperability between Data Applications | Data exchange MUST follow standards so that different vendors applications may exchange data. This allows to reduce the risk of vendor-lock-ins.                                                                                                                                                                                                         |
+| Semantic Aspect Meta Model                 | Tooling used in Catena-X to semantically describe data.                                                                                                                                                                                                                                                                                                  |

docs/arc42/03_system_scope_and_context.md

@@ -0,0 +1,50 @@
+# System Scope and Context
+
+The first draft of this application only targets to provide a possibility to enter and exchange stock information 
+related to partners. This application scope follows the following information.
+
+## Business Context
+
+PURIS FOSS may be operated in any supply network, but currently will likely be operated in the
+automotive supply network.
+
+**\<Diagram or Table>**
+
+**Disposition**
+The disposition has a major information need to keep a material flow into and out of the production. The disposition steers the allocation of material within the production. PURIS supports the disposition to identify shortages by providing relevant information regarding the material flow.
+
+**Production (Process)**
+Production is the actually value-adding process of a manufacturer. It's demand is derived by outer factors such as orders. A lack of material in supply chains leads to shortages. The production process has to be seen as a consumer of data provided by PURIS (Catena-X data consumer) and as a provider of data to PURIS (Catena-X data provider). In that way PURIS is able to fulfill the disposition's information need.
+
+**Logistics**
+For a production process it is necessary to fulfill its logistics requirements. That means that the material in demand is given in the necessary quantity at the right time at the right place (see seven Rs above). PURIS targets to support the information flow to overview this problem task.
+
+**(Automotive) Supply Chain**
+Supply chains synchronize demands with the supply. They are networks and not linear, as each customer commonly has more than 1 supplier of services or physical goods. Supply chains are commonly supported by three flows: material flow, finance flow and information flow. For PURIS the information flow is the relevant one.
+
+- Customers send (demand) forecasts and purchase Orders to their suppliers or manufacturers.
+- Suppliers and manufacturers send shipment information to their customers.
+
+There are existing EDI formats describing this kind of information in a detailed way. Additionally, the VDA publishes recommendations on how to use the DELFOR (UN standard EDI message) in the automotive supply chain. While the VDA standards (delivery forecasts, delivery call-offs, orders, despatch advices, inventory reports, etc) only apply to the first tiers of the automotive supply chain, later tiers won't be following the VDA standards - either because of their size or because their operating their business in different domains. Those companies are likely to work with DELFOR message standards, too OR even don't do EDI.
+
+## Technical Context
+
+The Technical Context has been derived from the architecture constraints:
+
+**\<Diagram or Table>**
+
+**PURIS FOSS**
+
+The PURIS FOSS is a system consuming short-term supply information supporting identification and mitigating shortages.
+
+**SAMM**
+
+SAMM is a technology used to define submodel information for the Asset Administration Shell (AAS). SAMM is used to define the actual payload of the APIs used in PURIS FOSS.
+
+**Tractus-X Connector**
+
+The [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc) (abbreviated and simplified as EDC) is a Catena-X specific implementation of the [Eclipse Dataspace Components Connector (EDC)](https://github.com/eclipse-edc/Connector) is an open-source framework which can be used to participate within an International Data Space (IDS).
+
+*Sovereign data exchange*
+
+To ensure data sovereignty, access and usage policies (prohibitions, permissions, obligations) may be attached as a machine readable defintion by data owners before sharing their data. The data consumer has to accept the policies before processing the data (human readable, machine readable). Connectors (and the underlying/corresponding systems) must technically enforce usage policies while there is also legal governance. An access and usage contract can be negotiated beforehand along with access and usage policies to ensure parties agree upon. It is necessary that data apps are compliant to the usage policies, since the policies define data processing rules.

docs/arc42/04_solution_strategy.md

@@ -0,0 +1,19 @@
+# Solution Strategy
+
+**Organization**
+
+PURIS FOSS
+- follows the related standardization candidates or even published standards.
+- 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.
+- Demand and Production Output are measured "per day" e.g., today's demand and next thursday's demand.
+
+**Interoperable Data Exchange and Pattern**
+- Use SAMM aspect models to exchange PURIS data (see domain model).
+- Use the EDC to participate in Catena-X.
+  - Data Providers can offer their data or data providing API as a _Data Asset_.
+  - Data Consumers can consume a Data Provider's _Data Asset_.
+- Data is exchanged using an asynchronous pull and push mechanism.

docs/arc42/05_building_block_view.md

@@ -0,0 +1,36 @@
+# Building Block View
+
+The components or (sub-) systems do have the following capabilities. Please note that the authentication flows have 
+been omitted for readability.
+
+![Level 0 - Blackbox View](puml/05-level-0.svg)
+
+| Component / system                 | Descriptions                                                                                                                                                                                                                              |
+|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Data Provisioning & Transformation | The Data Provisioning & Transformation Building Block handles the upload of data from internal systems into PURIS and provides capabilities for data transformation. **This component is not part of this repository**.                   |
+| PURIS FOSS Backend                 | This system represents the PURIS FOSS application's logic. It handles the data exchange.                                                                                                                                                  |
+| 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. |
+
+## Level 1 White Boxes
+
+**PURIS FOSS Frontend**
+
+![Level 1 - Whitebox View - PURIS FOSS Frontend](puml/05-level-1-frontend.svg)
+
+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.     |
+
+**PURIS FOSS Backend**
+
+![Level 1 - Whitebox View - PURIS FOSS Backend](puml/05-level-1-backend.svg)
+
+| Component / system | Descriptions                                                                                                                                           |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| EDC                | The EDC component provides the EDC implementations to create assets, negotiate contracts and intialize transfers.                                      |
+| MAD                | Stores the partner and material related information. They may only be added via REST interfaces.                                                       |
+| Stock              | Stores and handles stock related data. It provides interfaces to create and read stock data. Also it allows to exchange stock information via the EDC. |

docs/arc42/06_runtime_view.md

@@ -0,0 +1,35 @@
+# Runtime View
+
+The runtime view mainly focuses on two separate scenarios. One can either interact with the data or pull it.
+
+## Scenario: Update partner-related data
+
+The information exchange in PURIS follows a response and request pattern. Requests are directly answered based on
+existing data as soon as they arrive. The diagram does not integrate the EDC to explain the overall flow.
+
+![Overview of request and response](puml/06-api-flow.svg)
+
+The request and response flow both implement a message header and a content section in the exchanged data.
+- the message header contains information about the message.
+- the content contains either the request (material numbers) or the response (respective SAMM model as json payload).
+
+The API implementations are provided and consumed via the EDC.
+1. A data asset is created on Startup by the `AssetCreatedCommandLineRunner`.
+1. To request new data
+    1. the partners' catalog is queried to search for the request api.
+    1. the contract is negotiated.
+    1. the transfer is initialized using the [dynamic http receiver EDC extension](https://github.com/eclipse-edc/Connector/tree/main/extensions/control-plane/transfer/transfer-pull-http-dynamic-receiver).
+    1. the "consumer pull" flow is used (see [sample](https://github.com/eclipse-edc/Samples/tree/main/transfer/transfer-06-consumer-pull-http))
+        1. Provider receives EDR token by `EndpointDataReferenceReceiver`.
+        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.
+
+## 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,
+then the frontend hands over the data to the backend to perform the action.
+
+The web-ui allows the following interactions:
+- create or update stocks for a partner.
+- select a specific stock to see the related partner stocks.
+- Trigger an update for all partner's data for a specific material (see previous Scenario).

docs/arc42/07_deployment_view.md

@@ -0,0 +1,19 @@
+# Deployment View
+
+## Local Deployment
+
+Overall the Deployment locally looks similar to the following graphic.
+
+![Local Deployment of two PURIS clients with MVD](puml/07-deployment.svg)
+
+**Docker**
+
+_to be merged_
+
+**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_

docs/arc42/08_concepts.md

@@ -0,0 +1,9 @@
+# Cross-cutting Concepts
+
+## Multi-Partner Information
+
+Within the supply network there may be materials / parts that are produced for multiple partners or customers that
+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.

docs/arc42/09_architecture_decisions.md

@@ -0,0 +1,3 @@
+# Architecture Decisions
+
+_None have been documented yet._

docs/arc42/10_quality_requirements.md

@@ -0,0 +1,3 @@
+# Quality Requirements
+
+PURIS FOSS is compliant to the [Tractus-X Release Guidelines](https://eclipse-tractusx.github.io/docs/release).

docs/arc42/11_technical_risks.md

@@ -0,0 +1,6 @@
+# Risks and Technical Debts
+
+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.