Merge pull request #473 from catenax-ng/docs/add_pool_component_diagrams

Docs: Add diagrams for pool components

docs/arc42/diagrams/create_legal_entity_diagram.md

@@ -0,0 +1,67 @@
+# Sequence Diagram for Business Partner Data Management (BPDM) Pool
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as Client
+    participant Controller as Controller
+    participant BPBuildService as BusinessPartnerBuildService
+    participant ValidationService as RequestValidationService
+    participant ChangelogService as ChangelogService
+    participant Repository as LegalEntityRepository
+
+    Note over Client,Controller: Path: /api/catena/legal-entities
+    Note over Client,Controller: Method: POST
+
+    Client->>Controller: createBusinessPartners(List<LegalEntityPartnerCreateRequest>)
+    Controller->>BPBuildService: createLegalEntities(List<LegalEntityPartnerCreateRequest>)
+    BPBuildService->>ValidationService: validateLegalEntityCreates(List<LegalEntityPartnerCreateRequest>)
+    ValidationService-->>BPBuildService: List<ErrorInfo<LegalEntityCreateError>>
+    BPBuildService->>ChangelogService: createChangelogEntries(List<LegalEntity>) and createChangelogEntries(List<Address>)
+
+    Note over BPBuildService: Create legal entities and addresses
+    BPBuildService->>Repository: saveAll(List<LegalEntity>)
+    BPBuildService-->>Controller: LegalEntityPartnerCreateResponseWrapper
+    Note over Controller: Response: 200 OK (Legal entity created)
+    Note over Controller: Content-Type: application/json
+    Controller-->>Client: Response (LegalEntityPartnerCreateResponseWrapper)
+```
+
+## BPDM Pool Sequence Diagram Explanation
+
+### 1. Client Request
+
+The client sends a request to create business partners. This is the initial trigger for the entire flow.
+
+### 2. Controller Handling
+
+The controller receives the client's request and forwards it to the `BusinessPartnerBuildService` for processing.
+
+### 3. Business Partner Creation
+
+The `BusinessPartnerBuildService` initiates the process to create legal entities based on the provided request.
+
+### 4. Validation
+
+Before creating the legal entities, the `RequestValidationService` validates the request.
+
+This ensures that the data provided meets the necessary criteria and is free of errors on legal entitys and address.
+
+If there are any errors during validation, the `RequestValidationService` returns a list of error messages to the `BusinessPartnerBuildService` if no error are
+find it will be empty.
+
+### 5. Changelog for Legal Entities and Addresses
+
+The `BusinessPartnerBuildService` logs the creation of new legal entities and their associated addresses using the `ChangelogService`.
+
+### 6. Repository Save
+
+The validated and processed legal entities are then saved to the repository.
+
+### 7. Response Preparation
+
+After successfully saving the legal entities, the `BusinessPartnerBuildService` prepares a response wrapper containing the details of the created entities.
+
+### 8. Controller Response
+
+The controller sends the prepared response back to the client, indicating the successful creation of the legal entities.

docs/arc42/diagrams/search_legal_entity_diagram.md

@@ -0,0 +1,57 @@
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as Client
+    participant Controller as Controller
+
+    Note over Client,Controller: Path: /api/catena/legal-entities/search
+    Note over Client,Controller: Method: POST
+
+    Client->>Controller: searchLegalEntities(bpnLs)
+    Controller->>BPFetchService: fetchDtosByBpns(bpnLs)
+    BPFetchService->>LegalEntityRepository: findDistinctByBpnIn(bpns)
+    LegalEntityRepository-->>BPFetchService: Return List of LegalEntities
+    BPFetchService->>BPFetchService: fetchLegalEntityDependencies(partners)
+    Note over BPFetchService: Join various attributes of LegalEntities
+    BPFetchService->>Controller: Return List of PoolLegalEntityVerboseDto
+    Note over Controller: Response: 200 OK (List of PoolLegalEntityVerboseDto)
+    Note over Controller: Content-Type: application/json
+    Controller-->>Client: Response (Collection<PoolLegalEntityVerboseDto>)
+```
+
+## Sequence Diagram Explanation for Searching Legal Entities
+
+### 1. Client Request
+
+The client sends a request to search for specific legal entities based on their string list BPNs.
+
+### 2. Controller Handling
+
+The controller receives the client's request and forwards it to the `BusinessPartnerFetchService` for processing.
+
+### 3. Fetch Legal Entities DTOs
+
+The `BusinessPartnerFetchService` fetches the Data Transfer Objects (DTOs) of the legal entities based on the provided BPNs.
+
+### 4. Retrieve Legal Entities from Repository
+
+The `BusinessPartnerFetchService` queries the `LegalEntityRepository` to retrieve the distinct legal entities based on the provided BPNs.
+
+### 5. Fetch Legal Entity Dependencies
+
+After retrieving the legal entities, the `BusinessPartnerFetchService` fetches additional dependencies for these entities.
+
+### 6. Join Attributes
+
+Inside the `BusinessPartnerFetchService`, various attributes of the legal entities are joined, such as identifiers, states, classifications, relations, and
+legal forms.
+
+### 7. Response Preparation
+
+After fetching and joining the necessary attributes, the `BusinessPartnerFetchService` prepares a list of `PoolLegalEntityVerboseDto` to be returned.
+
+### 8. Controller Response
+
+The controller sends the prepared list of `PoolLegalEntityVerboseDto` back to the client, indicating a successful search operation.

docs/arc42/diagrams/update_legal_entity_diagram.md

@@ -0,0 +1,69 @@
+# Sequence Diagram for Business Partner Data Management (BPDM) Pool
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as Client
+    participant Controller as Controller
+    participant BPBuildService as BusinessPartnerBuildService
+    participant ValidationService as RequestValidationService
+    participant ChangelogService as ChangelogService
+    participant Repository as LegalEntityRepository
+
+    Note over Client,Controller: Path: /api/catena/legal-entities
+    Note over Client,Controller: Method: PUT
+
+    Client->>Controller: updateBusinessPartners(List<LegalEntityPartnerUpdateRequest>)
+    Controller->>BPBuildService: updateLegalEntities(List<LegalEntityPartnerUpdateRequest>)
+    BPBuildService->>ValidationService: validateLegalEntityUpdates(List<LegalEntityPartnerUpdateRequest>)
+    ValidationService-->>BPBuildService: List<ErrorInfo<LegalEntityUpdateError>>
+    BPBuildService->>Repository: findDistinctByBpnIn(bpnsToFetch) 
+    BPBuildService->>ChangelogService: createChangelogEntries(legalEntities) and createChangelogEntries(legalAddresses)
+    Note over BPBuildService: Update legal entities and addresses
+    BPBuildService->>Repository: save(legalEntity)
+    BPBuildService-->>Controller: LegalEntityPartnerUpdateResponseWrapper
+    Note over Controller: Response: 200 OK (Legal entity updated)
+    Note over Controller: Content-Type: application/json
+    Controller-->>Client: Response (LegalEntityPartnerUpdateResponseWrapper)
+```
+
+## Sequence Diagram Explanation for Updating Legal Entities
+
+### 1. **Client Request**
+
+The client sends a request to update business partners. This is the initial trigger for the entire flow.
+
+### 2. **Controller Handling**
+
+Upon receiving the client's request, the controller forwards it to the `BusinessPartnerBuildService` for further processing.
+
+### 3. **Business Partner Update**
+
+The `BusinessPartnerBuildService` starts the process to update legal entities based on the provided request.
+
+### 4. **Validation**
+
+Before proceeding with the update, the `RequestValidationService` validates the request. This step ensures that the data provided meets the necessary criteria
+and is free of errors. If there are any discrepancies during validation, the `RequestValidationService` returns a list of error messages to
+the `BusinessPartnerBuildService`if no error are find it will be empty.
+
+### 5. **Repository Fetch**
+
+The `BusinessPartnerBuildService` retrieves existing legal entities from the repository based on the provided BPNs.
+
+### 6. **Changelog for Legal Entities and Addresses**
+
+Every update made to the legal entities and their associated addresses is logged by the `BusinessPartnerBuildService` using the `ChangelogService`.
+
+### 7. **Repository Update**
+
+After validation and processing, the legal entities are updated in the repository.
+
+### 8. **Response Preparation**
+
+Post the successful update of the legal entities, the `BusinessPartnerBuildService` prepares a response wrapper that contains the details of the updated
+entities.
+
+### 9. **Controller Response**
+
+Finally, the controller sends the prepared response back to the client, signaling the successful update of the legal entities.