chore(docs): improve documentation of arc42 - cross-cutting

docs/src/docs/arc42/architecture-constraints/index.adoc

@@ -8,24 +8,24 @@
 |Cloud Agnostic Architecture approach
 |IRS provides a reference application/implementation which is deployable on any cloud ecosystem. There is no vendor lock to any cloud vendor.
 
-|Spring Boot and the Spring framework is used as underlying framework for Java development.
-|Spring Boot and Framework is used to build an easy and production-grade based application which could be deployed without any further infrastructure components.
+|Spring Boot and the Spring Framework are used as the underlying framework for Java development.
+|Spring Boot and the Spring Framework are used to create a simple, production-grade based application that can be deployed without any additional infrastructure components.
 
-Orchestrating application components and integrating with other libraries/frameworks.
+Orchestration of application components and integration with other libraries/frameworks.
 
 |Lombok
-|Lombok for generating boilerplate code. Keeping code concise increases quality and maintainability.
+|Lombok for boilerplate code generation. Keeping code concise improves quality and maintainability.
 
 
-|Kubernetes is used for Container Orchestration
+|Kubernetes is used for container orchestration
 |Kubernetes as container orchestration system used for software deployment, scaling and management of the IRS application.  This supports our software infrastructure and ensures efficient management and scalability of the IRS reference application.
 
-|Docker Container are used to provide a microservice oriented architecture
+|Docker containers are used to provide a microservice oriented architecture
 
-|Deployment made on reliable production ready images. Avoiding repetitive, mundane configuration tasks for container orchestration.
+|Deployments are made on reliable production-ready images. Avoiding repetitive, mundane configuration tasks for container orchestration.
 
-|Docker Compose is used to define and tune multi container application based on docker container technologies.
-|Docker container to develop independently of the underlying OS.
+|Docker Compose is used to define and tune multi-container applications based on Docker container technologies.
+|Docker containers to develop independently of the underlying OS.
 |===
 
 == Organizational Constraints
@@ -38,19 +38,19 @@ Orchestrating application components and integrating with other libraries/framew
 |
 
 |App Marketplace & API Connection
-|IRS Application has to be accessible for the user in the App Marketplace.
+|The IRS Application must be available to the user in the App Marketplace.
 |App Marketplace & API Connection
 
 |Federal Ministry for Economic Affairs and Energy (BMWi) promotion
 |The Federal Ministry for Economic Affairs and Energy (BMWi) promotes the project and provides funds for the project.
 |
 
-|Technology Readiness Level (TRL) for products developed within the CX Consortia
+|Technology Readiness Level (TRL) for products developed within the CX consortia
 |As IRS is a reference implementation, the Technology Readiness Level (TRL) must not be above TRL 8.
 |
 
 |Operational Readiness for Release 1 has to be fulfilled
-|Minimum requirements for release 1 has to be archived. Later on, the Operational Readiness for Release has to be fulfilled accordingly to the requirements of the C-X consortia.
+|The minimum requirements for release 1 has to be archived. Later on, the Operational Readiness for Release has to be fulfilled according to the requirements of the C-X consortia.
 |
 |===
 
@@ -60,11 +60,11 @@ Orchestrating application components and integrating with other libraries/framew
 |Name |Description
 
 |Open Source
-|FOSS licenses approved by the eclipse foundation has to be used. It could represent the initial set that the CX community agrees on to regulate the content contribution under FOSS licenses.
+|FOSS licenses approved by the Eclipse Foundation must be used. This could represent the initial set that the CX community agrees on to regulate the content contribution under FOSS licenses.
 |Apache License 2.0
-|Apache License 2.0 is one of the approved licenses which should be used to respect and guarantee Intellectual property (IP).
+|Apache License 2.0 is one of the approved licenses that should be used to respect and guarantee Intellectual Property (IP).
 |Java OpenJDK Version JDK >= 17
-|IRS provides an open source application standard. OpenJDK is used, which is licensed under GNU General Public License (GNU GPL) Version 2.
+|IRS provides an open source application standard. It uses OpenJDK, which is licensed under the GNU General Public License (GNU GPL) version 2.
 |===
 
 
@@ -74,16 +74,16 @@ Orchestrating application components and integrating with other libraries/framew
 |Name |Description
 
 |Architecture documentation
-|Architectural documentation of IRS reference application/implementation according to ARC42 template.
+|Architectural documentation of the IRS reference application/implementation following the ARC42 template.
 |Coding guidelines
-|We follow the Google Java Style Guide. That is ensured by using the unified code formatter in the team and enforcing the style via Maven and Checkstyle / PMD.
-|Executable Bundle provided over the App Marketplace
-|As IRS is available in the App Marketplace, the application should be provided in one executable bundle.
+|We follow the Google Java Style Guide. This is ensured by using the unified code formatter in the team and enforcing the style via Maven and Checkstyle / PMD.
+|Executable Bundle provided via the App Marketplace
+|Since IRS is available in the App Marketplace, the application should be provided in one executable bundle.
 |Module structure
-|The entire build is driven from a Maven file, itself run from a single Dockerfile.
+|The entire build is driven by a Maven file, which runs itself from a single Dockerfile.
 |Code Analysis, Linting and Code Coverage
-|Consistent style increases readability and maintainability of the code base. Hence, we use analyzers to enforce consistency and style rules. We enforce the code style and rules in the CI to avoid merging code that does not comply with standards.
-|We integrate the code coverage tool JaCoCo within our build stage. The tool builds when the test coverage falls below a minimum threshold. >> Code Analysis, Linting and Code Coverage
+|A consistent style increases the readability and maintainability of the code base. Hence, we use analyzers to enforce consistency and style rules. We enforce the code style and rules in the CI to avoid merging non-compliant code.
+|We integrate the code coverage tool JaCoCo within our build stage. The tool builds when the test coverage falls below a minimum threshold. >> Code analysis, linting and code coverage
 |===
 
 
@@ -93,29 +93,29 @@ Orchestrating application components and integrating with other libraries/framew
 |Tool |Scope |Rule |Configuration (via files / annotations)
 
 |Tidy
-|Enforce Maven POM Code Convention
+|Enforce Maven POM code convention
 |Fail build on untidy pom.xml
 |N/A
 
 |SpotBugs
-|Static analysis to look for bugs in Java code. Successor of popular FindBugs tool
+|Static analysis to find bugs in Java code. Successor to the popular FindBugs tool
 |Fail build on violations
 |.config/spotbugs-excludes.xml
 @SuppressFBWarnings(...)
 
 |FindSecBugs
-|SpotBugs plugin adding security bugs coverage
+|SpotBugs plugin to add security bug coverage
 |Fail build on violations
 |N/A
 
 |Checkstyle
-|Enforce coding standard
+|Enforce coding standards
 |Fail build on violations
 |.config/checkstyle-suppressions.xml
 @SuppressWarnings("checkstyle:XXX")
 
 |PMD
-|Source code analyzer to finds common programming flaws
+|Source code analyzer to find common programming flaws
 |Fail build on violations
 |.config/pmd-rules.xml
 @SuppressWarnings("PMD.XXX")
@@ -130,17 +130,17 @@ Orchestrating application components and integrating with other libraries/framew
 a|
 - Scan source code for vulnerabilities (SAST)
 - Scan dependencies for known vulnerabilities (SCA)
-- Check used licenses (FOSS Licenses)
+- Check used licenses (FOSS licenses)
 |
 |https://web.analysiscenter.veracode.com/
 
 |Dependabot
-|Automated dependency updates built into GitHub. Provided pull requests on dependency updates.
-|Any dependency update generates a pull request automatically.
+|Automated dependency updates built into GitHub. Provides pull requests for dependency updates.
+|Every dependency update automatically generates a pull request.
 |.github/dependabot.yml
 
 |CodeQl
-|Discover vulnerabilities across a codebase.
+|Discover vulnerabilities across a code base.
 |
 |.github/workflows/codeql.yml
 |===

docs/src/docs/arc42/cross-cutting/architecture-design-patterns.adoc

@@ -4,18 +4,18 @@
 
 For the IRS, we utilize the dependency inversion mechanisms provided by Spring Boot as much as possible.
 
-The principle says:
+The principle is:
 
-High-level modules should not import anything from low-level modules. Both should depend on abstractions (e.g., interfaces).
+High-level modules should not import from low-level modules. Both should depend on abstractions (e.g. interfaces).
 Abstractions should not depend on details. Details (concrete implementations) should depend on abstractions.
 
-Adhering to this, we define clear interfaces between the different domains (e.g. job orchestration and AAS communication) in the IRS and let dependencies be injected by the framework. This improves testability of the classes as well.
+Following this, we define clear interfaces between the different domains (e.g. job orchestration and AAS communication) in the IRS and let the framework inject the dependencies. This also improves the testability of the classes.
 
 == Hexagonal architecture
 
-The hexagonal architecture divides a system into several loosely-coupled interchangeable components, such as the application core, the database, the user interface, test scripts and interfaces with other systems. This approach is an alternative to the traditional layered architecture.
+The hexagonal architecture divides a system into several loosely coupled interchangeable components, such as the application core, the database, the user interface, test scripts and interfaces to other systems. This approach is an alternative to the traditional layered architecture.
 
-For the IRS, this means decoupling the application logic from components like the BLOB store, the REST API controllers or the AAS client connection. With an interface between the parts (so-called port), it is easy to switch to other implementations, e.g. if you want to change the persistence implementation. No changes to the application logic will be necessary.
+For the IRS, this means decoupling the application logic from components such as the BLOB store, the REST API controllers or the AAS client connection. With an interface between the parts (called a port), it is easy to switch to other implementations, e.g. if you want to change the persistence implementation. No changes to the application logic are required.
 
 
 [plantuml, target=architecture, format=svg]

docs/src/docs/arc42/cross-cutting/development-concepts.adoc

@@ -1,34 +1,34 @@
 = Development concepts
 
 == Build, test, deploy
-The IRS is built using Maven and utilizes all the standard concepts of it. Test execution is part of the build process and a minimum test coverage of 80% is enforced.
+The IRS is built using Maven and utilizes all of its standard concepts. Testing is part of the build process and a minimum test coverage of 80% is enforced.
 
-The project setup contains a multi-module Maven build. Commonly used classes (like the IRS data model) should be extracted into a separate submodule and reused across the project. However, this is not a "one-size-fits-all" solution. New submodules should be created with care and require a review by the team.
+The project setup includes a multi-module Maven build. Commonly used classes (such as the IRS data model) should be extracted into a separate submodule and reused throughout the project. However, this is not a one-size-fits-all solution. New submodules should be created with care and require a review by the team.
 
-The Maven build alone only leads up to the JAR artifact of the IRS. Do create Docker images, the Docker build feature is used. This copies all resources into a builder image, builds the software and creates a final Docker image at the end that can then be deployed.
+The Maven build alone will only lead to the JAR artifact of the IRS. When creating Docker images, the Docker build feature is used. This copies all the resources into a builder image, builds the software and creates a final Docker image at the end that can then be deployed.
 
-Although the Docker image can be deployed in various ways, the standard solution are the provided Helm charts, which describe the required components as well.
+Although the Docker image can be deployed in various ways, the standard solution is to use the provided Helm charts, which also describe the components required.
 
 == Code generation
 There are two methods of code generation in the IRS:
 
 === Lombok
-The Lombok library is heavily used to generate boilerplate code (like Constructors, Getters, Setters, Builders...).
-This way, code can be written faster and this boilerplate code is excluded from test coverage, which keeps the test base lean.
+The Lombok library is heavily used to generate boilerplate code (such as constructors, getters, setters, builders...).
+This allows code to be written faster and this boilerplate code is excluded from test coverage, keeping the test base lean.
 
 === Swagger / OpenAPI
-The API uses OpenAPI annotations to describe the endpoints with all necessary information. The annotations are then used to automatically generate the OpenAPI specification file, which can be viewed in the Swagger UI that is deployed with the application.
+The API uses OpenAPI annotations to describe the endpoints with all the necessary information. The annotations are then used to automatically generate the OpenAPI specification file, which can be viewed in the Swagger UI that is deployed with the application.
 
-The generated OpenAPI specification file is automatically compared to a fixed, stored version of it to avoid unwanted changes of the API.
+The generated OpenAPI specification file is automatically compared to a fixed, stored version of it to avoid unwanted changes to the API.
 
 == Migration
-There currently is no data migration mechanism for the IRS.
-In case the model of the persisted data (Jobs) changes, data is dropped and Jobs will need to be recreated.
+There is currently no data migration mechanism for the IRS.
+If the model of the persisted data (jobs) changes, data will be dropped and jobs will have to be re-created.
 
 == Configurability
-The IRS utilizes the configuration mechanism provided by Spring Boot. Configuration properties can be defined in the file `+src/main/resources/application.yml+`
+The IRS utilizes the configuration mechanism provided by Spring Boot. Configuration properties can be defined in the `+src/main/resources/application.yml+` file.
 
-For local testing purposes, there is an additional configuration file called `+application-local.yml+`. Values can be overriden there to support the local dev environment.
+For local testing purposes there is an additional configuration file called `+application-local.yml+`. Values can be overridden there to support the local development environment.
 
-Other profiles should be avoided. Instead, the configuration can be overwritten using Spring's external configuration mechanism (see https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/html/boot-features-external-config.html). The operator must have total control over the configuration of the IRS.
+Other profiles should be avoided. Instead, the configuration can be overwritten using Spring's external configuration mechanism (see https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/html/boot-features-external-config.html). The operator must have full control over the configuration of the IRS.
 

docs/src/docs/arc42/cross-cutting/domain-concepts.adoc

@@ -28,8 +28,8 @@ A job can be in one of the following states:
 |UNSAVED |The job was created, but not yet stored by the system.
 |INITIAL |The job was stored by the system and is now queued for processing.
 |IN_PROGRESS |The job is currently being processed.
-|TRANSFERS_FINISHED |All transfers for the job have been finished, and it is now being finalized.
-|COMPLETED |The job has completed. See the job response for details on the data.
+|TRANSFERS_FINISHED |All transfers for the job have been completed, and it is now being finalized.
+|COMPLETED |The job has completed. See the job response for details of the data.
 |ERROR |The job could not be processed correctly by the IRS due to a technical problem.
 |===