updated documentation

CHANGELOG.md

@@ -4,6 +4,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
+- Updated the documentation structure according to Arc42 template
+
 ## 0.5.1
 ### Added
 ## fixed

docs/architecture/1-introduction-and-goals.md

+## 1 Introduction and goals
+
+The Semantic Hub is a logical and architectural component of Tractus-X. It stores Semantic Model definitions and allows the generation of several artifacts.
+The source code under this folder contains reference implementations of the SLDT Semantic Hub
+
+
+### 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-semantic-hub.git
\ No newline at end of file

docs/architecture/2-architecture-constraints.md

+## 2 Architecture and constraints
+
+### Overall Architecture
+The SLDT Semantic Hub stores Semantic Model definitions and allows the generation of several artifacts. It restricts access to the models by authentication via a token and authorization via roles in the token claims. Therefore, the Hub interacts with a Keycloak instance. The models are created in the Hub during our governance process as depicted below.
+```mermaid
+graph LR
+    SemanticHub[Semantic hub] -- "read models" --> Data[Data Consumer/Provider]
+    Keycloak --"PUB Key for token validation" --> SemanticHub
+    Github[Github Models Repository] -- "synchronize models from the governance process" --> SemanticHub
+```
+
+
+### 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-semantic-hub.git
\ No newline at end of file

docs/architecture/3-system-scope-and-context.md

+## 3 System scope and context
+
+### Business Context
+
+```mermaid
+%%{init: {"flowchart": {"curve": "linear"} }}%%
+flowchart LR
+    DC(Data Consumer)
+    DP(Data Provider)
+    K(Keycloak)
+
+    subgraph Semantic Hub
+    SHB(Semantic Hub Backend)
+    SH[(Sematic Hub postgres)]
+    end
+    
+    SHB <-->|Find submodels / metadata| DC
+    SHB <-->|Submodel creation \n provide metadata| DP
+
+    SHB <--> SH
+
+    K -->|Public key for token validation| SHB
+
+    DC <-->|Token request| K
+    DP <-->|Token request| K
+```
+
+### 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-semantic-hub.git
\ No newline at end of file

docs/architecture/4-runtime-view.md

+## 4 Runtime-view
+
+### Upload of an aspect model
+```mermaid
+sequenceDiagram
+    actor ModelAdmin as Model Admin
+    participant SemanticHub as Semantic hub
+    participant TripleStore as TripleStore
+
+    ModelAdmin ->>+ SemanticHub: Upload aspect model file (.ttl)
+    loop validation
+    SemanticHub ->>+ SemanticHub: Check if aspect model is complaint with bamm/samm (using sdk)
+    SemanticHub ->>+ TripleStore: Check if aspect model already exists
+    Note over SemanticHub, TripleStore: If the aspect model exists and is in release status, <br> the upload will be rejected. <br>If the aspect model exists in draft status,<br> upload will be accepted.
+    SemanticHub ->>+ TripleStore: Check if external referenceses exists
+    Note over SemanticHub, TripleStore: If an external reference does not exists,<br> the upload will be rejected.<br>Should we allow to reference namespaces,<br> in DRAFT state?
+    TripleStore -->> SemanticHub: response ok
+    end
+    note over ModelAdmin, SemanticHub: The model admin provides the release status <br> (RELEASED/DRAFT) upon upload
+    SemanticHub ->>+ SemanticHub: Add the release status as triple to the model
+    SemanticHub ->>+ TripleStore: Write all triples to TripleStore
+    TripleStore -->> SemanticHub: response ok
+    SemanticHub -->> ModelAdmin: Response upload successful
+```
+| Validation | Description Value | 
+|---|---|
+| BAMM compliance  | Checks if the model is compliant with the BAMM. The BAMM SDK does provide the validation logic. |
+| Model Status check (RELEASE vs DRAFT)  | Uploads will always accepted when there are no existing namespace:version combination in the TripleStore. For a model in DRAFT state, uploads will always be accepted. For a model in RELEASE state, uploads will be denied. RELEASED models are immutable. |
+|  External reference check | It will be checked if all exernal references are available in the TripleStore. The BAMM SDK does provide a mechanisim where the resolving against the TripleStore can be integrated. |
+
+
+## Download of the documentation of an Aspect Model
+```mermaid
+sequenceDiagram
+    actor ModelAdmin as Model Admin
+    participant SemanticHub as Semantic hub
+    participant TripleStore as TripleStore
+
+    ModelAdmin ->>+ SemanticHub: Get documentation for aspect model com.catenax:0.0.1:Sample
+    SemanticHub ->>+ TripleStore: Resolve aspect model with all references based on provided urn com.catenax:0.0.1:Sample
+    TripleStore -->> SemanticHub: response 
+    SemanticHub ->>+ SemanticHub: generate documentation based on the response from TripleStore
+    SemanticHub -->> ModelAdmin: respond with generated documenation
+```
+```
+
+Example queries to resolve an aspect model with all references:
+Construct Query
+```
+@prefix ns: <urn:bamm:org.idtwin:1.0.0#DocumentationSimple>
+
+CONSTRUCT {
+?s ?p ?o .
+} WHERE {
+bind( ns: as ?aspect)
+?aspect (<>|!<>)* ?s . // resolves all references
+?s ?p ?o .
+}
+Search for Aspect Models
+The current search API can stay as is. Below is an example query for selecting bamm properties:
+Search Queries
+CONSTRUCT {
+?s ?p ?o .
+} WHERE {   
+FILTER ( $param == ?o )  // Custom filter can be added here.
+?s ?p ?o .
+}
+```
+
+### 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-semantic-hub.git
\ No newline at end of file

docs/architecture/5-deployment-view.md

+## 5 Deployment-view
+
+For Deployment needed:
+
+-   Webserver
+
+-   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/semantic-hub".
+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-semantic-hub/blob/main/README.md).
+
+
+### 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-bpn-discovery.git
\ No newline at end of file

docs/architecture/6-concepts.md

+## 6 Concept
+
+### Overall Concept
+
+#The overall concept can be found under **2 Architecture and
+constraints**.
+
+### Semantic Hub
+
+Example Aspect Model
+```
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix bamm: <urn:bamm:io.openmanufacturing:meta-model:1.0.0#> .
+@prefix : <urn:bamm:org.idtwin:1.0.0#> .
+
+
+:DocumentationSimple a bamm:Aspect;
+bamm:name "ManufacturerDocumentationSimple";
+bamm:preferredName "ManufacturerDocumentation"@en;
+bamm:description "The Submodel defines a simplified set of manufacturer documentation to bring about information from manufacturer to operator of industrial equipment."@en;
+
+:documents a bamm:Property;
+bamm:name "documents";
+bamm:preferredName "documents"@en;
+bamm:description "Set of documents"@en;
+```
+
+The Semantic Hub will add the release status as triple upon upload:
+Release Status
+```
+@prefix aux: <urn:bamm:io.openmanufacturing:aspect-model:aux#>
+
+<urn:bamm:org.idtwin:1.0.0#> aux:releaseStatus aux:DRAFT .
+```
+
+## Package
+| No | Rule                                                                                                              | Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+|----|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 1. | A package is defined by the urn prefix until "#".                                                                 | net.catenax.semantics.product:1.2.0#                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| 2. | A package can contain one or multiple aspects.                                                                    | Example 1: net.catenax.semantics.traceability:1.2.0#Traceability Example 2: net.catenax.semantics.product:1.2.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:1.2.0#ProductDetails                                                                                                                                                                                                                                                                                |
+| 3. | Multiple versions of a package can exists.                                                                        | Possible: net.catenax.semantics.product:1.2.0 net.catenax.semantics.product:4.2.0                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| 4. | The versioning applies to the package.  All aspects and model elements scoped to a package have the same version. | Possible: net.catenax.semantics.product:1.2.0#ProductDescription  net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:1.2.0#ProductDetails  Possible:net.catenax.semantics.product:4.3.0#ProductDescription  net.catenax.semantics.product:4.3.0#ProductUsage net.catenax.semantics.product:4.3.0#ProductDetails  Not Possible: net.catenax.semantics.product:1.3.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:3.2.0#ProductDetails |
+| 5. | All aspect models and model elements scoped to a package have the same status.                                    | Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → RELEASE net.catenax.semantics.product:1.2.0#ProductDetails → RELEASE Not Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → DRAFT                                                                                                                                                                          |
+
+
+### 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-semantic-hub.git
\ No newline at end of file

docs/architecture/7-quality-scenarios.md

+## 7 Quality scenarios
+
+### Quality Requirements
+
+| Tool       | Description                                                                                                                                                                                                                                              |
+|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Veracode   | "Veracode enables you to quickly and cost-effectively scan software for flaws and get actionable source code analysis results." [Link](https://www.veracode.com)                                                                                         |
+| Trivy      | "Trivy is a simple and comprehensive vulnerability/misconfiguration/secret scanner for containers and other artifacts. Trivy detects vulnerabilities of OS packages and language-specific packages." [Link](https://aquasecurity.github.io/trivy/v0.34/) |
+| SonarCloud | "SonarCloud's static analysis detects Bugs and Code Smells in your repositories and provides the feedback you need to write better code." [Link](https://www.sonarsource.com/products/sonarcloud/)                                                       |
+
+
+
+### 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-semantic-hub.git
\ No newline at end of file

docs/architecture/glossary.md

+## Glossary
+
+| Term     | Description                                                                                                |
+|----------|------------------------------------------------------------------------------------------------------------|
+| Keycloak | Keycloack is an open-source Identity Management and Access management solution that allows Single Sign-On. |
+| Realm    | Manages a set of users, credentials, roles. Authenticates the users it controls.                           |
+| SAMM     | Semantic Aspect Meta Model                         |
+### 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-semantic-hub.git
\ No newline at end of file