# vecfonds/customer-service architecture

> Architecture diagram of the GitHub repository vecfonds/customer-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vecfonds/customer-service
- Repository: https://github.com/vecfonds/customer-service

## Overview

##### Project Type and Purpose
- The project is a Java-based microservice built with Maven. It implements a customer-service component (likely part of a larger banking application) handling customer and account-related functionality.
- The package names and directory structure immediately indicate a layered (or hexagonal) architecture design – dividing responsibilities among controllers, services, persistence, DTOs, exception handling, and supporting shared utilities.

##### File Structure
- Top-Level Directories: You have the Maven build files (pom.xml, mvnw, etc.) and a source directory structure following the common standard:
- src/main/java: Custom application code organized under com/hdbank/customer_service.
- src/main/resources: Contains configuration (application.yml) for the service.
- Key Folders within the code:
- controller: Contains AccountController and CustomerController, exposing REST API endpoints.
- service and service/impl: Business logic layers are encapsulated here. Their interaction with controllers (for handling requests) and repositories (for data persistence) should be highlighted.
- dto: Separate sub-packages for request and response DTOs, which illustrate the movement of data between the client and the service – supporting clear input/output contracts.
- persistence: Divided into entity and repository packages showing database entities (Account, Customer) and their data access layers.
- shared: Contains constants, enumerations, mappers, and exception classes. The mapper packages (for AccountMapper and CustomerMapper) indicate transformation logic between entities and DTOs.
- advice: Hosts the GlobalExceptionHandler to manage cross-cutting concerns like error handling.

##### Elements
a. Main Components:
- Service Layer: Represent the business logic segmented into AccountService and CustomerService (and their respective implementations).
- Data Transfer Layer: Illustrate the DTOs used for requests and responses ensuring data format standardization.
- Persistence Layer: Show entities (Account, Customer) and repositories (AccountRepository, CustomerRepository) as the interface to your database.
- Exception Handling: Include the GlobalExceptionHandler as a cross-cutting concern that intercepts errors from the controllers or services.
- Shared/Support Utilities: Add components like mappers and enumerations that support data transformation and domain constants.

b. Relationships and Interactions:
- Controllers receive client requests, transform them into business calls via services.
- Services contain the primary business logic and call the repositories for CRUD operations.
- DTOs mediate between the controller and business logic layers.
- Mappers convert between DTOs and persistence entities.
- Exception handling is triggered by any runtime errors, with a global advice capturing and formatting error responses.

c. Architectural Patterns/Design Principles:
- Layered architecture: Separate layers for presentation, business logic, and persistence.
- Use of DTOs and mappers highlights separation of concerns – data format conversion from API layer to domain model.
- The overall design is modular, making it easier to test and maintain.
- Emphasis on exception handling as a global application concern which improves robustness.

d. Technologies, Frameworks, and Libraries:
- Java with Spring Boot (implied by the typical package structure and REST controller naming conventions).
- Maven for dependency management and build automation.
- YAML-based configuration via application.yml.
- Likely usage of Spring’s component scanning and exception handling mechanisms via @ControllerAdvice (GlobalExceptionHandler).

## Diagram (Mermaid)

```mermaid
flowchart TD
    extClient("External Client"):::external

    subgraph "REST API Layer"
        cc("CustomerController"):::api
        ac("AccountController"):::api
    end

    subgraph "Service Layer"
        cs("CustomerService (Interface)"):::service
        csi("CustomerServiceImpl"):::service
        as("AccountService (Interface)"):::service
        asi("AccountServiceImpl"):::service
    end

    subgraph "Data Transfer Layer"
        arq("AccountRequest DTO"):::dto
        crq("CustomerRequest DTO"):::dto
        ar("AccountResponse DTO"):::dto
        cr("CustomerResponse DTO"):::dto
        br("BaseResponse DTO"):::dto
    end

    subgraph "Persistence Layer"
        ae("Account Entity"):::persistence
        ce("Customer Entity"):::persistence
        arpo("AccountRepository"):::persistence
        crpo("CustomerRepository"):::persistence
    end

    subgraph "Exception Handling"
        geh("GlobalExceptionHandler"):::exception
    end

    subgraph "Shared Utilities"
        sc("SharedConstant"):::shared
        ate("AccountTypeEnum"):::shared
        ge("GenderEnum"):::shared
        re("ResponseEnum"):::shared
        am("AccountMapper"):::shared
        cm("CustomerMapper"):::shared
    end

    %% Connections from External Client to API Layer
    extClient -->|"SendsRequest"| cc
    extClient -->|"SendsRequest"| ac

    %% API Layer to Service Layer
    cc -->|"calls"| cs
    ac -->|"calls"| as

    %% Service Layer: Interface implemented by Implementation
    cs -->|"implementedBy"| csi
    as -->|"implementedBy"| asi

    %% Service Layer to Persistence Layer
    csi -->|"calls"| arpo
    asi -->|"calls"| crpo

    %% Repositories manage Entities
    arpo -->|"manages"| ae
    crpo -->|"manages"| ce

    %% Global Exception Handling connections
    cc -->|"errors"| geh
    ac -->|"errors"| geh
    csi -->|"errors"| geh
    asi -->|"errors"| geh

    %% Service Layer uses Shared Mappers
    csi -->|"uses"| am
    asi -->|"uses"| cm

    %% Mappers convert between DTOs and Entities
    am -->|"maps-to"| ar
    am -->|"maps-to"| ae
    cm -->|"maps-to"| cr
    cm -->|"maps-to"| ce

    %% Class Definitions for Styling
    classDef external fill:#E8DAEF,stroke:#7D3C98,stroke-width:2px;
    classDef api fill:#F8C471,stroke:#B7950B,stroke-width:2px;
    classDef service fill:#82E0AA,stroke:#117A65,stroke-width:2px;
    classDef dto fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef persistence fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef exception fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef shared fill:#F9E79F,stroke:#B7950B,stroke-width:2px;

    %% Click Events for REST API Layer
    click cc "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/controller/CustomerController.java"
    click ac "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/controller/AccountController.java"

    %% Click Events for Service Layer (Interfaces and Implementations)
    click cs "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/service/CustomerService.java"
    click as "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/service/AccountService.java"
    click csi "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/service/impl/CustomerServiceImpl.java"
    click asi "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/service/impl/AccountServiceImpl.java"

    %% Click Events for Data Transfer Layer (DTOs)
    click arq "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/dto/request/AccountRequest.java"
    click crq "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/dto/request/CustomerRequest.java"
    click ar "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/dto/response/AccountResponse.java"
    click cr "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/dto/response/CustomerResponse.java"
    click br "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/dto/response/BaseResponse.java"

    %% Click Events for Persistence Layer (Entities and Repositories)
    click ae "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/persistence/entity/Account.java"
    click ce "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/persistence/entity/Customer.java"
    click arpo "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/persistence/repository/AccountRepository.java"
    click crpo "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/persistence/repository/CustomerRepository.java"

    %% Click Event for Exception Handling
    click geh "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/advice/GlobalExceptionHandler.java"

    %% Click Events for Shared Utilities (Constants, Enumerations, Mappers)
    click sc "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/shared/constant/SharedConstant.java"
    click ate "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/shared/enumeration/AccountTypeEnum.java"
    click ge "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/shared/enumeration/GenderEnum.java"
    click re "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/shared/enumeration/ResponseEnum.java"
    click am "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/shared/mapper/AccountMapper.java"
    click cm "https://github.com/vecfonds/customer-service/blob/develop/src/main/java/com/hdbank/customer_service/shared/mapper/CustomerMapper.java"
```
