From 38431f6862605d736069adae1006475ff0069800 Mon Sep 17 00:00:00 2001 From: --show-origin Date: Fri, 5 Jan 2024 08:12:22 -0800 Subject: [PATCH] docs: updated documentation for arc42, interface doc and user guide --- docs/README.md | 2 +- docs/adminGuide/Admin_Guide.md | 6 ++ docs/arc42/04_solution_strategy.md | 5 +- docs/arc42/05_building_block_view.md | 11 +-- docs/arc42/06_runtime_view.md | 7 ++ docs/arc42/07_deployment_view.md | 17 +++-- docs/arc42/08_concepts.md | 17 +++++ docs/arc42/11_technical_risks.md | 2 +- docs/arc42/puml/05-level-0.puml | 6 +- docs/arc42/puml/05-level-0.svg | 5 +- docs/arc42/puml/05-level-1-frontend.puml | 9 +++ docs/arc42/puml/05-level-1-frontend.svg | 5 +- docs/arc42/puml/06-api-flow-detailed.puml | 57 ++++++++++++++++ docs/arc42/puml/06-api-flow-detailed.svg | 4 ++ docs/arc42/puml/07- deployment.svg | 1 - docs/arc42/puml/07-deployment-argo.puml | 30 +++++++++ docs/arc42/puml/07-deployment-argo.svg | 4 ++ ...07- deployment.puml => 07-deployment.puml} | 4 ++ docs/arc42/puml/07-deployment.svg | 4 ++ docs/interfaceDoc/Interface_Doc.md | 3 +- docs/userGuide/User_Guide.md | 67 +++++++++++++++++++ 21 files changed, 245 insertions(+), 21 deletions(-) mode change 100755 => 100644 docs/arc42/puml/05-level-0.svg mode change 100755 => 100644 docs/arc42/puml/05-level-1-frontend.svg create mode 100644 docs/arc42/puml/06-api-flow-detailed.puml create mode 100644 docs/arc42/puml/06-api-flow-detailed.svg delete mode 100755 docs/arc42/puml/07- deployment.svg create mode 100644 docs/arc42/puml/07-deployment-argo.puml create mode 100644 docs/arc42/puml/07-deployment-argo.svg rename docs/arc42/puml/{07- deployment.puml => 07-deployment.puml} (84%) create mode 100644 docs/arc42/puml/07-deployment.svg create mode 100644 docs/userGuide/User_Guide.md diff --git a/docs/README.md b/docs/README.md index 0adf5b4d..3f107abd 100644 --- 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 index 619022e1..72be65b2 100644 --- 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 index 460a9e8a..b08a33ec 100644 --- 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 index bfca9155..4f2f9581 100644 --- 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 index 1436538d..e9b999c4 100644 --- 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 index 518331e7..d0f9cee6 100644 --- a/docs/arc42/07_deployment_view.md +++ b/docs/arc42/07_deployment_view.md @@ -2,13 +2,9 @@ ## 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** @@ -16,4 +12,11 @@ One can configure the two local helm environments using the product helm chart a ## 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 index 319a7b78..77754cd8 100644 --- 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 index c00ea5b5..9d099e1b 100644 --- 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 index f300a18e..3e53f252 100644 --- 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 "<> PURIS"{ [PURIS FOSS Backend] as puris_backend @@ -14,7 +15,8 @@ package "<> 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 } diff --git a/docs/arc42/puml/05-level-0.svg b/docs/arc42/puml/05-level-0.svg old mode 100755 new mode 100644 index f5b4a3bf..03fcdfc9 --- a/docs/arc42/puml/05-level-0.svg +++ b/docs/arc42/puml/05-level-0.svg @@ -1 +1,4 @@ -«system» PURISPURIS FOSS BackendPURIS FOSS FrontendData Provisioning & TransformationInterface internal systemsEclipse DataSpace Components ConnectorEDC APIsprovide and pull dataaccording to standards \ No newline at end of file + +«system» PURISPURIS FOSS BackendPURIS FOSS FrontendData Provisioning & TransformationEclipse DataSpace Components ConnectorPostgresql DBKeycloakInterface internal systemsEDC APIsprovide and pull dataaccording to standards diff --git a/docs/arc42/puml/05-level-1-frontend.puml b/docs/arc42/puml/05-level-1-frontend.puml index 266ecfd1..3ee5d357 100644 --- a/docs/arc42/puml/05-level-1-frontend.puml +++ b/docs/arc42/puml/05-level-1-frontend.puml @@ -5,8 +5,17 @@ package "<> PURIS FOSS Frontend"{ [Stock View] as stock_view [Dashboard] as dashboard + [Authentication Service] as auth_service + [Access Service] as access_service + + auth_service <-- access_service } + +[Keycloak] as idp + +idp - auth_service + stock_view --> "Stock Interface" stock_view --> "MAD interface" diff --git a/docs/arc42/puml/05-level-1-frontend.svg b/docs/arc42/puml/05-level-1-frontend.svg old mode 100755 new mode 100644 index c427d919..54e947c1 --- a/docs/arc42/puml/05-level-1-frontend.svg +++ b/docs/arc42/puml/05-level-1-frontend.svg @@ -1 +1,4 @@ -«system» PURIS FOSS FrontendStock ViewDashboardStock InterfaceMAD interface \ No newline at end of file + +«system» PURIS FOSS FrontendStock ViewDashboardAuthentication ServiceAccess ServiceKeycloakStock InterfaceMAD interface diff --git a/docs/arc42/puml/06-api-flow-detailed.puml b/docs/arc42/puml/06-api-flow-detailed.puml new file mode 100644 index 00000000..f804537b --- /dev/null +++ b/docs/arc42/puml/06-api-flow-detailed.puml @@ -0,0 +1,57 @@ +@startuml +autonumber +skinparam sequenceMessageAlign center + +box "Data Consumer" +participant "Business\nApplication" as app_cons +participant "EDC Consumer" as edc_cons +end box + +box "Data Provider" +participant "EDC Provider" as edc_prov +participant "Business\nApplication" as app_prov +end box + +app_cons -> edc_cons: search for request assets at partner +edc_cons <-> edc_prov: catalog communication +edc_cons --> app_cons: catalog + +app_cons -> app_cons: identify Information Object\nExchange Request asset + +app_cons -> edc_cons: negotiate contract for Information\n Object Exchange Request API +edc_cons <-> edc_prov: negotiation +edc_cons --> app_cons: contract agreement + +note left: Define Endpoint Data Reference Endpoint = \n Business Application +app_cons -> edc_cons: initialize transfer +edc_cons <-> edc_prov: initialize transfer +edc_prov --> app_cons: transfer completed, EDR sent + +app_cons -> app_cons: prepare request based on\nEDR endpoint and auth + +note right: Request against Endpoint via EDC +app_cons -> edc_prov: Request Information Object Exchange (via EDC) +edc_prov -> app_prov: proxy request +activate app_prov +app_prov --> edc_prov: Accepted +edc_prov --> app_cons: Accepted + +app_prov -> app_prov: Determine requested Information Object + +note right: simplified communication with EDC, same as above +app_prov -> edc_prov: EDC communication +edc_prov <-> edc_cons: EDC communication +edc_cons --> app_prov: transfer completed, EDR sent + +note right: Send requested Information Objectvia EDC +app_prov -> edc_cons: Response Information Object Exchange (via EDC) +edc_cons -> app_cons: proxy request +activate app_cons +app_cons --> edc_cons: Accepted +edc_cons --> app_prov: Accepted +deactivate app_prov + +app_cons -> app_cons: use data +deactivate app_cons + +@enduml diff --git a/docs/arc42/puml/06-api-flow-detailed.svg b/docs/arc42/puml/06-api-flow-detailed.svg new file mode 100644 index 00000000..a45b8bbd --- /dev/null +++ b/docs/arc42/puml/06-api-flow-detailed.svg @@ -0,0 +1,4 @@ + +Data ConsumerData ProviderBusinessApplicationBusinessApplicationEDC ConsumerEDC ConsumerEDC ProviderEDC ProviderBusinessApplicationBusinessApplication1search for request assets at partner2catalog communication3catalog4identify Information ObjectExchange Request asset5negotiate contract for InformationObject Exchange Request API6negotiation7contract agreementDefine Endpoint Data Reference Endpoint =Business Application8initialize transfer9initialize transfer10transfer completed, EDR sent11prepare request based onEDR endpoint and authRequest against Endpoint via EDC12Request Information Object Exchange (via EDC)13proxy request14Accepted15Accepted16Determine requested Information Objectsimplified communication with EDC, same as above17EDC communication18EDC communication19transfer completed, EDR sentSend requested Information Objectvia EDC20Response Information Object Exchange (via EDC)21proxy request22Accepted23Accepted24use data diff --git a/docs/arc42/puml/07- deployment.svg b/docs/arc42/puml/07- deployment.svg deleted file mode 100755 index 012cc043..00000000 --- a/docs/arc42/puml/07- deployment.svg +++ /dev/null @@ -1 +0,0 @@ -CustomerCXSupplierTractus-X Connector CustomerPURIS FOSS BackendPURIS FOSS FrontendInterface internal systems(Customer)KeycloakManaged Identity WalletTractus-X Connector SupplierPURIS FOSS BackendPURIS FOSS FrontendInterface internal systems(Supplier) \ No newline at end of file diff --git a/docs/arc42/puml/07-deployment-argo.puml b/docs/arc42/puml/07-deployment-argo.puml new file mode 100644 index 00000000..7deb8991 --- /dev/null +++ b/docs/arc42/puml/07-deployment-argo.puml @@ -0,0 +1,30 @@ +@startuml + + +package "PURIS"{ + + [Tractus-X Connector Customer] as edc + + [Postgresql DB] as postgres + [PURIS FOSS Backend] as puris_backend + [PURIS FOSS Frontend] as puris_frontend + + puris_backend - edc + postgres -- puris_backend + "Interface internal systems\n" - puris_backend + puris_backend -- puris_frontend + +} + +package "CX" { + + [Keycloak] as keycloak + [Managed Identity Wallet] as miw + +} + +edc -- keycloak +edc -- miw +puris_frontend -- keycloak + +@enduml diff --git a/docs/arc42/puml/07-deployment-argo.svg b/docs/arc42/puml/07-deployment-argo.svg new file mode 100644 index 00000000..69e778e5 --- /dev/null +++ b/docs/arc42/puml/07-deployment-argo.svg @@ -0,0 +1,4 @@ + +PURISCXTractus-X Connector CustomerPostgresql DBPURIS FOSS BackendPURIS FOSS FrontendInterface internal systems KeycloakManaged Identity Wallet diff --git a/docs/arc42/puml/07- deployment.puml b/docs/arc42/puml/07-deployment.puml similarity index 84% rename from docs/arc42/puml/07- deployment.puml rename to docs/arc42/puml/07-deployment.puml index 3faafac3..4957443b 100644 --- a/docs/arc42/puml/07- deployment.puml +++ b/docs/arc42/puml/07-deployment.puml @@ -5,10 +5,12 @@ package "Customer"{ [Tractus-X Connector Customer] as edc_cus + [Postgresql DB] as postgres_cus [PURIS FOSS Backend] as puris_backend_cus [PURIS FOSS Frontend] as puris_frontend_cus puris_backend_cus - edc_cus + postgres_cus -- puris_backend_cus "Interface internal systems\n(Customer)" - puris_backend_cus puris_backend_cus -- puris_frontend_cus @@ -26,10 +28,12 @@ package "Supplier"{ [Tractus-X Connector Supplier] as edc_sup + [Postgresql DB] as postgres_sup [PURIS FOSS Backend] as puris_backend_sup [PURIS FOSS Frontend] as puris_frontend_sup edc_sup - puris_backend_sup + postgres_sup -- puris_backend_sup puris_backend_sup - "Interface internal systems\n(Supplier)" puris_backend_sup -- puris_frontend_sup diff --git a/docs/arc42/puml/07-deployment.svg b/docs/arc42/puml/07-deployment.svg new file mode 100644 index 00000000..7648abe9 --- /dev/null +++ b/docs/arc42/puml/07-deployment.svg @@ -0,0 +1,4 @@ + +CustomerCXSupplierTractus-X Connector CustomerPostgresql DBPURIS FOSS BackendPURIS FOSS FrontendInterface internal systems(Customer)KeycloakManaged Identity WalletTractus-X Connector SupplierPostgresql DBPURIS FOSS BackendPURIS FOSS FrontendInterface internal systems(Supplier) diff --git a/docs/interfaceDoc/Interface_Doc.md b/docs/interfaceDoc/Interface_Doc.md index f51abeae..e894c2a0 100644 --- a/docs/interfaceDoc/Interface_Doc.md +++ b/docs/interfaceDoc/Interface_Doc.md @@ -29,4 +29,5 @@ _Note: The port and the path depend on the configuration of the spring backend ( ## Postman -TODO +There is a [postman collection](../../local/postman/puris-integration-test.postman_collection.json) containing +information on how to provide master data and some basic data to test the application. diff --git a/docs/userGuide/User_Guide.md b/docs/userGuide/User_Guide.md new file mode 100644 index 00000000..500182c9 --- /dev/null +++ b/docs/userGuide/User_Guide.md @@ -0,0 +1,67 @@ +# User Guide + +This guide explains the overall masks that may be used by different roles. +- A `PURIS_USER` may see use views "View and Manage Stocks" and "Supplier Dashboard". +- A `PURIS_ADMIN` may _additionally_ use the views "Catalog", "Negotiations" and "Transfers". + +In the following the views are explained. + +Note: A user may additionally log out or see license information of the application. + +## View and Manage Stocks + +This view allows a user to either create material or product stocks and allocate them to a partner. Stocks always need +to be allocated to a partner due to potential multi-sourcing scenarios. + +The view is divided horizontally into three parts: +1. Create or Update Material / Product Stocks +2. Material Stocks +3. Product Stocks + +### Create or update Material / Product Stocks + +The view allows a user to either add a material (user selected radio button 'Material') or a product +(user selected radio button 'Product'). The user then +1. Either selects a Material or Product. +2. Sets the partner who will receive (Product) or from whom one received (Material) the stock. +3. Sets a quantity that is on stock with a selected unit of measurement (UOM). +4. Whether the stock is blocked or not (e.g. quality assurance ongoing). +5. The stocks location based on a Site (BPNS) and a corresponding Address (BPNA). +6. Optionally adds a reference to order positions. + +The updated or created stocks can be seen in the related section after triggering button "Add or Update". + +### Material Stocks + +The table shows the relevant information regarding all material stocks that are at your sites. The user may select one +stock to see which of the selected material are already allocated on supplier side. Using the button "Update Partner +Stocks", the user may request an update of this data for all partners who supply the material. +Note: Stock information is updated asynchronously. The user may reload the page later to see the updated data. + +### Product Stocks + +The table shows the relevant information regarding all product stocks that are at your sites. The user may select one +stock to see which of the selected products have already arrived on customer side but not be used for production. Using +the button "Update Partner Stocks", the user may request an update of this data for all partners who buy the material. +Note: Stock information is updated asynchronously. The user may reload the page later to see the updated data. + +## Supplier Dashboard + +The Supplier Dashboard is a preview. It allows a partner to select a customer, material and location information to +get insights regarding the current status of a customers' supply situation. Using the button "Update Customer Data", the +respective information for the partner get updated. +Note: information is updated asynchronously. The user may reload the page later to see the updated data. + + +## Catalog + +An admin may use the page to query offers available at a partner to check if the partner set up the information exchange +for this partner. + +## Negotiations + +An admin may use the page to see all recent negotiations and their state. + +## Transfers + +An admin may use the page to see all recent transfers and their state.