docs(trg1): align docs directory structure (#71)

* docs: add README.md and adjust folder structure for arc42 Refactor docs to follow Sig#805. Closes: #58
eclipse-tractusx · Oct 24, 2024 · 8e7c78b · 8e7c78b
1 parent bc038cc
commit 8e7c78b
Show file tree

Hide file tree

Showing 27 changed files with 151 additions and 28 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -14,7 +14,7 @@ Link to Github issue.
 
 Please delete options that are not relevant.
 
-- [ ] I have followed the [contributing guidelines](https://github.com/eclipse-tractusx/ssi-authority-schema-registry/blob/main/docs/technical-documentation/dev-process/How%20to%20contribute.md)
+- [ ] I have followed the [contributing guidelines](https://github.com/eclipse-tractusx/ssi-authority-schema-registry/blob/main/docs/admin/dev-process/How%20to%20contribute.md)
 - [ ] I have performed [IP checks](https://eclipse-tractusx.github.io/docs/release/trg-7/trg-7-04#checking-libraries-using-the-eclipse-dash-license-tool) for added or updated 3rd party libraries
 - [ ] I have created and linked IP issues or requested their creation by a committer
 - [ ] I have performed a self-review of my own code

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 This repository contains the backend code for the SSI Authority & Schema Registry (SSI ASR) written in C#.
 
-For **information about the SSI Authority & Schema Registry**, please refer to the documentation, especially the context and scope section in the [architecture documentation](./docs/architecture).
+For **information about the SSI Authority & Schema Registry**, please refer to the documentation, especially the context and scope section in the [architecture documentation](./docs/architecture/Index.md).
 
 For **installation** details, please refer to the [README.md](./charts/ssi-asr/README.md) of the provided helm chart.
 
@@ -34,7 +34,7 @@ See Docker notice files for more information:
 
 ## Contributing
 
-See [Contribution details](/docs/technical-documentation/dev-process/How%20to%20contribute.md).
+See [Contribution details](/docs/admin/dev-process/How%20to%20contribute.md).
 
 ## License
 

diff --git a/charts/ssi-asr/README.md b/charts/ssi-asr/README.md
@@ -2,7 +2,7 @@
 
 This helm chart installs the SSI Authority & Schema Registry application.
 
-For further information please refer to [Technical Documentation](/docs/technical-documentation).
+For further information please refer to [Technical Documentation](/docs/admin).
 
 The referenced container images are for demonstration purposes only.
 

diff --git a/charts/ssi-asr/README.md.gotmpl b/charts/ssi-asr/README.md.gotmpl
@@ -2,7 +2,7 @@
 
 This helm chart installs the SSI Authority & Schema Registry application.
 
-For further information please refer to [Technical Documentation](/docs/technical-documentation).
+For further information please refer to [Technical Documentation](/docs/admin).
 
 The referenced container images are for demonstration purposes only.
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,20 @@
+# Introduction
+
+This repository provides the backend code for the SSI Authority & Schema Registry (SSI ASR).
+
+The following table links you to the respective documentations.
+
+| Documentation                                                    | Purpose                                                                                 |
+|------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| [Arc42](architecture/Index.md)                                   | Architecture Documentation for the SSI Authority & Schema Registry (SSI ASR).           |
+| [How to contribute](./admin/dev-process/How%20to%20contribute.md)| Information relevant, if you contribute in ssi authority schema registry development.   |
+| [Administration Guide](admin/Admin_Guide.md)                     | Information relevant, if you want to use the ssi authority schema registry application. |
+| [API Documentation](api/API_Doc.md)                              | Information about the endpoints.                                                        |
+
+## 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: 2024 Contributors to the Eclipse Foundation
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/admin/Admin_Guide.md b/docs/admin/Admin_Guide.md
@@ -0,0 +1,14 @@
+# Admin Guide
+
+## Getting started
+
+To start the application refer to the [Installation Guide](../../charts/ssi-asr/README.md).
+It provides information on deployment via helm.
+
+## 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: 2024 Contributors to the Eclipse Foundation
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/database/db-view.md → docs/admin/db-view.md b/docs/database/db-view.md → docs/admin/db-view.md
@@ -57,4 +57,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/...on/dev-process/Dev-flow_deploy-dev-env.md → ...in/dev-process/Dev-flow_deploy-dev-env.md b/...on/dev-process/Dev-flow_deploy-dev-env.md → ...in/dev-process/Dev-flow_deploy-dev-env.md
@@ -25,4 +25,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/...ation/dev-process/Dev-flow_git-diagram.md → ...admin/dev-process/Dev-flow_git-diagram.md b/...ation/dev-process/Dev-flow_git-diagram.md → ...admin/dev-process/Dev-flow_git-diagram.md
@@ -66,4 +66,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/...ation/dev-process/Enumeration Handling.md → ...admin/dev-process/Enumeration Handling.md b/...ation/dev-process/Enumeration Handling.md → ...admin/dev-process/Enumeration Handling.md
@@ -33,4 +33,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/...l-documentation/dev-process/FILEHEADER.md → docs/admin/dev-process/FILEHEADER.md b/...l-documentation/dev-process/FILEHEADER.md → docs/admin/dev-process/FILEHEADER.md
@@ -11,6 +11,7 @@ Install the extension and assign some [keyboard shortcut](https://code.visualstu
 Every time you create a new file or edit a file that you created and doesn't yet have a header, use the keyboard shortcut to insert the according header template in the file.
 
 Currently the following templates are available:
+
 * cx_header_default
 * cx_header_with_#
 
@@ -20,4 +21,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/...entation/dev-process/How to contribute.md → docs/admin/dev-process/How to contribute.md b/...entation/dev-process/How to contribute.md → docs/admin/dev-process/How to contribute.md
@@ -111,4 +111,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/...tation/release-process/Release Process.md → .../admin/release-process/Release Process.md b/...tation/release-process/Release Process.md → .../admin/release-process/Release Process.md
@@ -116,4 +116,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/database/seeding.md → docs/admin/seeding.md b/docs/database/seeding.md → docs/admin/seeding.md
@@ -31,4 +31,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/api/API_Doc.md b/docs/api/API_Doc.md
@@ -0,0 +1,19 @@
+# API Documentation
+
+This document provides information on the endpoints.
+
+## OpenAPI Specifications
+
+There is an [OpenAPI 3.0.1 specification document](./asr-service.yaml) available.
+
+## Postman
+
+There is a [postman collection](./postman) containing information on how to provide master data and some basic data to test the application.
+
+## 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: 2024 Contributors to the Eclipse Foundation
+* Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/...aRegistry.Service.postman_collection.json → ...aRegistry.Service.postman_collection.json b/...aRegistry.Service.postman_collection.json → ...aRegistry.Service.postman_collection.json
diff --git a/.../architecture/Architecture Constraints.md → ...chitecture/02_architecture_constraints.md b/.../architecture/Architecture Constraints.md → ...chitecture/02_architecture_constraints.md
@@ -55,4 +55,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Context and scope.md → ...chitecture/03_system_scope_and_context.md b/docs/architecture/Context and scope.md → ...chitecture/03_system_scope_and_context.md
@@ -1,4 +1,4 @@
-# Content and Scope
+# System Scope and Context
 
 ## Business Context
 
@@ -31,4 +31,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Solution strategy.md → docs/architecture/04_solution_strategy.md b/docs/architecture/Solution strategy.md → docs/architecture/04_solution_strategy.md
@@ -10,4 +10,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Whitebox Overall System.md → docs/architecture/05_building_block_view.md b/docs/architecture/Whitebox Overall System.md → docs/architecture/05_building_block_view.md
@@ -1,4 +1,4 @@
-# Whitebox Overall System
+# Building Block View
 
 ## Summary
 
@@ -30,4 +30,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Operational Concept.md → ...architecture/08_01_operational_concept.md b/docs/architecture/Operational Concept.md → ...architecture/08_01_operational_concept.md
@@ -44,4 +44,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Development Concept.md → ...architecture/08_02_development_concept.md b/docs/architecture/Development Concept.md → ...architecture/08_02_development_concept.md
@@ -2,7 +2,7 @@
 
 ## Build, test, deploy
 
-Details to the build, test and deploy process can get found under the following md file: [Release Process](/docs/technical-documentation/release-process/Release%20Process.md)
+Details to the build, test and deploy process can get found under the following md file: [Release Process](/docs/admin/release-process/Release%20Process.md)
 
 ## Development Guidelines
 
@@ -128,4 +128,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Security_Assessment.md → docs/architecture/08_03_security_concept.md b/docs/architecture/Security_Assessment.md → docs/architecture/08_03_security_concept.md
@@ -46,9 +46,9 @@ flowchart LR
 
 ### Additional information
 
-* The customer can request the available credentials with their providing authorities.
-* It is possible to validate the schema of credentials.
-* All actions are logged within the Registry DB.
+- The customer can request the available credentials with their providing authorities.
+- It is possible to validate the schema of credentials.
+- All actions are logged within the Registry DB.
 
 ### Changes compared to last Security Assessment
 
@@ -96,4 +96,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/08_concepts.md b/docs/architecture/08_concepts.md
@@ -0,0 +1,15 @@
+# Cross-cutting Concepts
+
+## Table of Content
+
+- [Operational concepts](./08_01_operational_concept.md)
+- [Developer concepts](./08_02_development_concept.md)
+- [Security Concept](./08_03_security_concept.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: 2024 Contributors to the Eclipse Foundation
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Requirements.md → docs/architecture/10_quality_requirements.md b/docs/architecture/Requirements.md → docs/architecture/10_quality_requirements.md
@@ -1,4 +1,4 @@
-# Requirements overview
+# Quality Requirements
 
 The development and deployment of the Self-Sovereign Identity (SSI) Authority & Schema Registry necessitate a comprehensive set of requirements that span across various domains including functional, security, performance, and usability aspects. This overview encapsulates the fundamental requirements that will guide the design and implementation of the SSI Authority & Schema Registry to ensure it meets the intended objectives and user needs.
 
@@ -39,4 +39,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
-- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/12_glossary.md b/docs/architecture/12_glossary.md
@@ -0,0 +1,28 @@
+# Glossary
+
+## Business Glossary
+
+| Name     | Abrv. | Description                                                                                                       |
+|----------|-------|-------------------------------------------------------------------------------------------------------------------|
+| Issuer   |       | An entity that creates and issues credentials to individuals or organizations.                                    |
+| Holder   |       | An individual or organization that receives and stores credentials issued by an issuer.                           |
+| Verifier |       | An entity that requests and verifies credentials presented by a holder to confirm the authenticity of the claims. |
+
+## Technical Glossary
+
+| Name                    | Abrv. | Description |
+|-------------------------|-------|-------------|
+| Self-Sovereign Identity | SSI   | A decentralized identity model where individuals or organizations have control over their digital identities without relying on a central authority. |
+| Schema                   |      | A structured framework or blueprint that defines the format and types of data that can be stored in a credential. |
+| Credential               |      | A digital document that certifies certain attributes or claims about an individual or organization, issued by a trusted authority. |
+| Credential Definition    |      | A specific implementation of a schema that includes additional metadata and rules for issuing and verifying credentials. |
+| Decentralized Identifier | DID  | A globally unique identifier that is created, owned, and controlled by the individual or organization it represents, without the need for a central registry. |
+| Verifiable Credential    |      | A tamper-evident credential that can be cryptographically verified to ensure its authenticity and integrity. |
+
+## 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: 2024 Contributors to the Eclipse Foundation
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>
diff --git a/docs/architecture/Index.md b/docs/architecture/Index.md
@@ -0,0 +1,26 @@
+# Arc42
+
+This documentation follows the arc42 template to provide a comprehensive overview of the SSI Authority & Schema Registry App.
+
+## Table of Content
+
+- [01. Introduction and Goals (To be added.)](./Index.md)
+- [02. Architecture Constraints](./02_architecture_constraints.md)
+- [03. Context and Scope](./03_system_scope_and_context.md)
+- [04. Solution Strategy](./04_solution_strategy.md)
+- [05. Building Block View](./05_building_block_view.md)
+- [06. Runtime View (To be added.)](./Index.md)
+- [07. Deployment View (To be added.)](./Index.md)
+- [08. Concepts](./08_concepts.md)
+- [09. Architecture Decisions (To be added)](./Index.md)
+- [10. Quality Requirements](./10_quality_requirements.md)
+- [11. Technical Risks (To be added)](./Index.md)
+- [12. Glossary](12_glossary.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: 2024 Contributors to the Eclipse Foundation
+- Source URL: <https://github.com/eclipse-tractusx/ssi-authority-schema-registry>