docs: add documentation

Refs: #63 #60
SAP · Aug 1, 2024 · a27739c · a27739c
1 parent 2853060
commit a27739c
Show file tree

Hide file tree

Showing 16 changed files with 1,130 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -32,6 +32,10 @@ This project is open to feature requests/suggestions, bug reports etc. via [GitH
 ## Security / Disclosure
 If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/SAP/ssi-dim-middle-layer/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.
 
+## Known Issues and Limitations
+
+See [Known Knowns](/docs/admin/known-knowns/known-issues-and-limitations.md).
+
 ## Code of Conduct
 
 We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times.

diff --git a/docs/admin/database/db-view.md b/docs/admin/database/db-view.md
@@ -0,0 +1,206 @@
+# Database View
+
+- [Database View](#database-view)
+  - [Database Overview](#database-overview)
+  - [Database Structure](#database-structure)
+    - [PROCESS\_STEP\_STATUSES](#process_step_statuses)
+      - [Possible Values](#possible-values)
+    - [PROCESS\_STEP\_TYPES](#process_step_types)
+      - [Possible Values](#possible-values-1)
+    - [PROCESS\_STEPS](#process_steps)
+    - [PROCESS\_TYPES](#process_types)
+      - [Possible Values](#possible-values-2)
+    - [PROCESSES](#processes)
+    - [TECHNICAL\_USER](#technical_user)
+    - [TENANTS](#tenants)
+    - [Enum Value Tables](#enum-value-tables)
+    - [Process Handling](#process-handling)
+  - [NOTICE](#notice)
+
+## Database Overview
+
+```mermaid
+erDiagram
+    PROCESS_STEP_STATUSES {
+        integer id PK
+        text label PK
+    }
+    PROCESS_STEP_TYPES {
+        integer id PK
+        text label
+    }
+    PROCESS_STEPS {
+        uuid id PK
+        integer process_step_type_id FK
+        integer process_step_status_id FK
+        uuid process_id FK
+        timestamp date_created
+        timestamp date_last_changed
+        text message
+    }
+    PROCESS_TYPES {
+        integer id PK
+        text label
+    }
+    PROCESSES {
+        uuid id PK
+        integer process_type_id FK
+        timestamp lock_expiry_date
+        uuid version
+    }
+    TECHNICAL_USER {
+        uuid id PK
+        uuid tenant_id FK
+        uuid external_id
+        text technical_user_name
+        text token_address
+        text client_id
+        bytea client_secret
+        bytea initialization_vector
+        integer encryption_mode
+        uuid process_id FK
+    }
+    TENANTS {
+        uuid id PK
+        text company_name
+        text bpn
+        text did_document_location
+        bool is_issuer
+        uuid process_id FK
+        uuid sub_account_id
+        text service_instance_id
+        text service_binding_name
+        uuid space_id
+        uuid dim_instance_id
+        text did_download_url
+        text did
+        text application_id
+        uuid company_id
+        text application_key
+        uuid operator_id
+    }
+```
+
+## Database Structure
+
+The database is organized into several key tables, each serving a specific purpose:
+
+### PROCESS_STEP_STATUSES
+
+id (INTEGER): A unique identifier for the process step status. This is the primary key of the table.
+label (TEXT): The label of the process step status.
+
+#### Possible Values
+
+- `TODO`: The process step is still to be executed.
+- `DONE`: The process step was already executed successfully.
+- `SKIPPED`: The execution of the process step was skipped.
+- `FAILED`: The process step execution failed due to an error.
+- `DUPLICATE`: The process step did already exist.
+
+### PROCESS_STEP_TYPES
+
+id (INTEGER): A unique identifier for the process step type. This is the primary key of the table.
+label (TEXT): The label of the process step type.
+
+#### Possible Values
+
+- `CREATE_SUBACCOUNT`: Creates the sub account in sap
+- `CREATE_SERVICEMANAGER_BINDINGS`: Creates the service manager binding for the created subaccount
+- `ASSIGN_ENTITLEMENTS`: Assigns the entitlements
+- `CREATE_SERVICE_INSTANCE`: Creates the service instance
+- `CREATE_SERVICE_BINDING`: Creates the service binding for the created service instance
+- `SUBSCRIBE_APPLICATION`: Subscribes to the `decentralized-identity-management-app` application
+- `CREATE_CLOUD_FOUNDRY_ENVIRONMENT`: Creates the cloud foundry environment
+- `CREATE_CLOUD_FOUNDRY_SPACE`: Creates the cloud foundry space for the created environment
+- `ADD_SPACE_MANAGER_ROLE`: Adds the space manager role for the created subaccount
+- `ADD_SPACE_DEVELOPER_ROLE`: Adds the space developer role for the created subaccount
+- `CREATE_DIM_SERVICE_INSTANCE`: Creates the dim instance
+- `CREATE_SERVICE_INSTANCE_BINDING`: Creates the binding for to the created dim instance
+- `GET_DIM_DETAILS`: Retrieves the dim details from SAP Dim
+- `CREATE_APPLICATION`: Creates the application in the wallet
+- `CREATE_COMPANY_IDENTITY`: Creates a company identity for the wallet
+- `ASSIGN_COMPANY_APPLICATION`: Assigns the company identity to the application
+- `CREATE_STATUS_LIST`: Creates a statuslist for a company
+- `SEND_CALLBACK`: Sends the callback to the portal to transmit the data of the created wallet and did
+- `CREATE_TECHNICAL_USER`: Creates a new technical user for a wallet
+- `GET_TECHNICAL_USER_DATA`: Retrieves the technical user data from the SAP Dim
+- `SEND_TECHNICAL_USER_CREATION_CALLBACK`: Sends the technical user data back to the portal
+- `DELETE_TECHNICAL_USER`: Deletes the technical user from the database and from the SAP Dim
+- `SEND_TECHNICAL_USER_DELETION_CALLBACK`: Sends a status to the portal if the deletion was successful
+
+### PROCESS_STEPS
+
+id (UUID): A unique identifier for the process step. This is the primary key of the table.
+process_step_type_id (INTEGER): A foreign key referencing id in the PROCESS_STEP_TYPES table.
+process_step_status_id (INTEGER): A foreign key referencing id in the PROCESS_STEP_STATUSES table.
+process_id (UUID): A foreign key referencing id in the PROCESSES table.
+date_created (TIMESTAMP): The timestamp when the process step was created.
+date_last_changed (TIMESTAMP): The timestamp when the process step was last changed.
+message (TEXT): A message associated with the process step.
+
+### PROCESS_TYPES
+
+id (INTEGER): A unique identifier for the process type. This is the primary key of the table.
+label (TEXT): The label of the process type.
+
+#### Possible Values
+
+- `SETUP_DIM`: Process to create wallets.
+- `TECHNICAL_USER`: Process to create and delete technical users.
+
+### PROCESSES
+
+id (UUID): A unique identifier for the process. This is the primary key of the table.
+process_type_id (INTEGER): A foreign key referencing id in the PROCESS_TYPES table.
+lock_expiry_date (TIMESTAMP): The lock expiry date of the process.
+version (UUID): The version of the process.
+
+### TECHNICAL_USER
+
+id (UUID): A unique identifier for the technical user. This is the primary key of the table
+tenant_id (UUID): A unique identifier for the tenant. This is a foreign key referencing id in the TENANT table
+external_id (UUID): the id of the technical user in the dim
+technical_user_name (TEXT): The name of the technical user
+token_address (TEXT): The address for the authentication of the technical user
+client_id (TEXT): The client id which is needed for authentication
+client_secret (BYTEA): The encrypted client secret
+initialization_vector (BYTEA): The used initialization vector which is needed for decrypting the secret
+encryption_mode (INTEGER): The used encryption mode for the secret
+process_id (UUID): A unique identifier for the process. This is a foreign key referencing id in the PROCESS table
+
+### TENANTS
+
+id (UUID): A unique identifier for the technical user. This is the primary key of the table
+company_name (TEXT): Name of the company must be unique in combination with the bpn
+bpn (TEXT): Bpn of the company must be unique in combination with the name
+did_document_location (TEXT): The location of the did document (url)
+is_issuer (BOOL): Defines if the requesting tenant is an issuer
+process_id (UUID): A unique identifier for the process. This is a foreign key referencing id in the PROCESS table
+sub_account_id (UUID): A unique identifier of the sub account in the SAP DIM
+service_instance_id (TEXT): A unique identifier of the service instance id in the SAP DIM
+service_binding_name (TEXT): The service binding name in the SAP DIM
+space_id (UUID): A unique identifier of the space id in the SAP DIM
+dim_instance_id (UUID): A unique identifier of the dim instance in the SAP DIM
+did_download_url (TEXT): The url of the did document.
+did (TEXT): The did of the wallet
+application_id (TEXT): A unique identifier of the application in the SAP DIM
+company_id (UUID): A unique identifier of the company in the SAP DIM
+application_key (TEXT): The key of the application in the SAP DIM
+operator_id (UUID): A unique identifier of the operator which is used for the wallet creation
+
+### Enum Value Tables
+
+`process_step_statuses`, `process_step_types`, `process_steps`, `process_types` are tables designed to store enum values. They contain an id and label, derived from the backend enums.
+
+### Process Handling
+
+The tables `processes`, `process_steps` are used for the processing of the wallet creation and technical user management.
+
+## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors
+- Source URL: https://github.com/SAP/ssi-dim-middle-layer
diff --git a/docs/admin/dev-process/Dev-flow_deploy-dev-env.md b/docs/admin/dev-process/Dev-flow_deploy-dev-env.md
@@ -0,0 +1,28 @@
+# Dev flow with deployment to dev environment
+
+```mermaid
+flowchart LR
+    subgraph local
+    D(Developer)
+    end
+    subgraph eclipse-tractusx
+        direction LR
+        D -- PR* to main*--> SDML(ssi-dim-middle-layer**)
+        click SCI "https://github.com/eclipse-tractusx/ssi-dim-middle-layer"
+    end
+    subgraph Argo CD - sync to k8s cluster
+    SCI -- auto-sync --> A(Argo CD dev)
+    end
+```
+
+Note\* Every pull request (PR) requires at least one approving review by a committer
+
+Note\*\* Unit tests and code analysis checks run at pull request
+
+## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors
+- Source URL: https://github.com/SAP/ssi-dim-middle-layer
diff --git a/docs/admin/dev-process/Enumeration Handling.md b/docs/admin/dev-process/Enumeration Handling.md
@@ -0,0 +1,39 @@
+# Enumeration
+
+Enum or enumeration are used for data type consisting of named values like elements, status workflow, types, etc., that represent integral constants. Enums are non-transactional (so called static data) which can only get changed in a new application version. Changes in the operation mode of an application are not allowed since this will result into possible system breaks.
+
+List of used enums in the ssi dim middle layer application
+
+- process_step_statuses
+- process_step_types
+- process_steps
+- process_types
+
+## Add Enums
+
+New enums can get added easily be enhancing the enumeration table (via the seeding data). With the next deployment; the new enum is getting auto deployed to the respective env.
+Since enums have an enhanced impact on the system functionality; it is mandatorily needed to test (FE wise) the impacted screens / flows before releasing new enums. It is likely that the enum has an enhanced impact on the user journey / flow and break the system if not well tested.
+
+## Change Enums
+
+Change of enums (labels) is possible but need to be done carefully and only if necessarily needed.
+In the case a change is getting executed; the system configuration / appsettings / env. variables need to get checked to ensure that those don't refer to the enum which is getting changed/ updated.
+
+## Delete Enums
+
+Deletion of enums have following impacts
+
+- Seeding data update needed (likely data need to get deleted / changed)
+- Data inside the database in the different running environments need to get updated
+- User flow process impacted
+- Business logic impacted
+
+**It is not recommended to delete enums.**
+
+## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors
+- Source URL: https://github.com/SAP/ssi-dim-middle-layer
diff --git a/docs/admin/dev-process/How to contribute.md b/docs/admin/dev-process/How to contribute.md
@@ -0,0 +1,109 @@
+# Contribution details
+
+To contribute to the SSI DIM Middle Layer as part of the open source community, please read the details defined below.
+Besides a generic "how to", some commit and pull request (PR) guidelines are defined to ensure readability and make newly created PRs easier to review. Additionally, changelogs can get validated as well as written with more ease. Moreover, similar patterns are in use across the contributor community.
+
+**Content**:
+
+- [Commit How To](#how-to-contribute)
+- [Commits, branches and pull requests guidelines](#commits-branches-and-pull-requests-guidelines)
+
+## How To Contribute
+
+### 1 Create a fork
+
+[Create a fork of the respective repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+
+### 2 Fork setup
+
+Setup your fork by entering a name and make sure that you unselect the "main branch only" selection, in case the upstream repository maintains release branches besides the main branch.
+
+Click "Create fork".
+
+### 3 Commit
+
+With the newly created fork, you can now start to contribute. Create a new branch in your own fork and start to implement the planned changes or new features.
+When the implementation is ready, create a PR against the upstream repository.
+
+The PR will get reviewed by the repository owners/official committers.
+As part of the PR review, checks will run automatically, and unit tests (if configured) will get executed. The PR owner is responsible to check the results and fix possible findings.
+
+## Commits, branches and pull requests guidelines
+
+### Commits and branches
+
+The suggestion is to use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+Here are some examples:
+
+#### Feature branch
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+gitGraph
+    commit id: "chore: initial commit"
+    branch feature/feature1 order: 2
+    commit id:"feat(function): add feature1"
+    commit id:"feat(function): enable feature1"
+    checkout main
+    merge feature/feature1
+```
+
+#### Bugfix branch
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+gitGraph
+    commit id: "build(v0.1.0): merge in main"
+    branch bug/bug1  order: 2
+    commit id: "fix(function): change bug"
+    checkout bug/bug1
+    commit id:"fix(function): refactor bug"
+    checkout main
+    merge bug/bug1
+```
+
+#### Release branch
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+gitGraph
+    commit id: "build(v0.1.0): merge in main"
+    branch release/v1.0.0 order: 2
+    commit id: "build(v1.0.0): bump version, changelog..." tag: "v1.0.0"
+    checkout main
+    merge release/v1.0.0
+```
+
+#### Hotfix branch
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+gitGraph
+    commit id: "release: v1.0.0"
+    branch release/v1.0.0 order: 2
+    commit id: "build(v1.0.0): bump version, changelog..." tag: "v1.0.0"
+    checkout main
+    merge release/v1.0.0
+    checkout release/v1.0.0
+    branch hotfix/v1.0.1 order: 3
+    checkout hotfix/v1.0.1
+    commit id: "hotfix(v1.0.1): bump version, changelog..." tag: "v1.0.1"
+```
+
+### PR title
+
+The suggested naming convention is '{type}{(function)}: {short summary}'.
+
+### PR description
+
+Add details to the change, fix or feature in the PR description.
+What was changed, why was it changed (e.g. which issue was fixed or which requirement was implemented), and how was it changed.
+
+## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors
+- Source URL: https://github.com/SAP/ssi-dim-middle-layer