Skip to content

byron-villegas/ms-bank

BranchesTags

Repository files navigation

ms-bank

Bank Microservice API

CI/CD License Java Spring Boot GitHub code size GitHub repo size GitHub contributors

GitHub stars GitHub forks

Table of Contents

Installation

Install JDK 25

  1. Download JDK 25 from the official Oracle website: https://www.oracle.com/java/technologies/javase/jdk25-archive-downloads.html
  2. Follow the installation instructions for your operating system.

Install Maven

  1. Download Maven binary from the official Apache Maven website: https://maven.apache.org/download.cgi
  2. Extract the downloaded archive to a directory of your choice.

Install Gradle

  1. Download Gradle binary from the official Gradle website: https://gradle.org/releases/
  2. Extract the downloaded archive to a directory of your choice.

Install JMeter

  1. Download JMeter binary from the official Apache JMeter website: https://jmeter.apache.org/download_jmeter.cgi
  2. Extract the downloaded archive to a directory of your choice.

Configure Environment Variables

Java

Windows

  1. Set the JAVA_HOME environment variable to point to the JDK installation directory.
  2. Add the bin directory of the JDK to your system's PATH environment variable.

macOS/Linux

  1. Open a terminal and edit the shell profile file (e.g., ~/.bash_profile, ~/.zshrc, ~/.bashrc or ~/.zshenv).
  2. Add the following lines to set the JAVA_HOME environment variable and update the PATH:
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-25.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

Maven

Windows

  1. Set the MAVEN_HOME environment variable to point to the Maven installation directory.
  2. Add the bin directory of Maven to your system's PATH environment variable.

macOS/Linux

  1. Open a terminal and edit the shell profile file (e.g., ~/.bash_profile, ~/.zshrc, ~/.bashrc or ~/.zshenv).
  2. Add the following lines to set the MAVEN_HOME environment variable and update the PATH:
export MAVEN_HOME=/opt/apache-maven-3.9.4
export PATH=$MAVEN_HOME/bin:$PATH

Gradle

Windows

  1. Set the GRADLE_HOME environment variable to point to the Gradle installation directory.
  2. Add the bin directory of Gradle to your system's PATH environment variable.

macOS/Linux

  1. Open a terminal and edit the shell profile file (e.g., ~/.bash_profile, ~/.zshrc, ~/.bashrc or ~/.zshenv).
  2. Add the following lines to set the GRADLE_HOME environment variable and update the PATH:
export GRADLE_HOME=/opt/gradle-8.5
export PATH=$GRADLE_HOME/bin:$PATH

JMeter

Windows

  1. Set the JMETER_HOME environment variable to point to the JMeter installation directory.
  2. Add the bin directory of JMeter to your system's PATH environment variable.

macOS/Linux

  1. Open a terminal and edit the shell profile file (e.g., ~/.bash_profile, ~/.zshrc, ~/.bashrc or ~/.zshenv).
  2. Add the following lines to set the JMETER_HOME environment variable and update the PATH:
export JMETER_HOME=/opt/apache-jmeter-5.6.3
export PATH=$JMETER_HOME/bin:$PATH

Running the Application

To run the Bank Microservice API, use the following command in the terminal:

./gradlew bootRun

This command will start the application, and you can access the API endpoints at http://localhost:8080/ms-bank. Make sure you have Gradle installed and properly configured in your environment to run the application successfully.

Running with Docker

To run the Bank Microservice API using Docker, follow these steps:

  1. Build the Docker image using the following command:
docker build -t ms-bank:latest .
  1. Run the Docker container using the following command:
docker run -d \
  --name ms-bank \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e JAVA_OPTS="-Xms128m -Xmx256m" \
  ms-bank:latest

This command will start the Docker container in detached mode, map port 8080 of the container to port 8080 on the host machine, and set the active Spring profile to "prod". You can access the API endpoints at http://localhost:8080/ms-bank. Make sure you have Docker installed and properly configured in your environment to run the application successfully.

OPENAPI Documentation

The OPENAPI documentation for the Bank Microservice API is available at the following URL: http://localhost:8080/ms-bank/swagger-ui/index.html. This documentation provides a comprehensive overview of the API endpoints, request and response formats, and other relevant information to help you understand how to interact with the API effectively. You can use this documentation to explore the available endpoints, test the API functionality, and integrate it into your applications.

Actuator Endpoints

The Bank Microservice API includes Actuator endpoints that provide insights into the application's health, metrics, and other operational information. You can access the Actuator endpoints at the following URL: http://localhost:8080/ms-bank/actuator. Some of the commonly used Actuator endpoints include:

  • /health: Provides information about the health status of the application.
  • /metrics: Provides various metrics about the application, such as memory usage, CPU usage,
  • /info: Provides general information about the application, such as version and build details.

Database

The Bank Microservice API uses an in-memory H2 database for data storage. The database is automatically configured and initialized when you run the application. You can access the H2 database console at the following URL: http://localhost:8080/ms-bank/h2-console. Use the following credentials to log in:

  • JDBC URL: jdbc:h2:mem:bankdb
  • Username: sa
  • Password: admin123

Mermaid Diagram

erDiagram
    OFFICE {
        int code PK
        varchar name
        varchar address
        varchar commune "length 5"
        double latitude
        double longitude
        timestamp modified_at
        timestamp created_at
    }
    
    EXECUTIVE {
        varchar username PK "length 10"
        int office FK
        varchar names "length 100"
        varchar first_last_name "length 50"
        varchar second_last_name "length 50"
        varchar email "length 60"
        varchar password "length 256"
        timestamp modified_at
        timestamp created_at
    }
    
    PLAN {
        varchar code PK "length 3"
        varchar name "length 25"
        timestamp modified_at
        timestamp created_at
    }
    
    CLIENT_TYPE {
        char code PK "length 1"
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    CLIENT {
        bigint rut PK
        char dv "length 1"
        char type FK
        int office FK
        varchar executive FK
        varchar plan FK
        varchar banking
        varchar economic_activity "length 6"
        char status "length 1"
        timestamp modified_at
        timestamp created_at
    }
    
    PERSON {
        bigint id PK "auto increment"
        bigint rut FK
        varchar names "length 100"
        varchar first_last_name "length 50"
        varchar second_last_name "length 50"
        char sex "length 1"
        date birth_date
        double rent
        timestamp modified_at
        timestamp created_at
    }
    
    COMPANY {
        bigint id PK "auto increment"
        bigint rut FK
        varchar name "length 300"
        varchar fantasy_name "length 100"
        date start_date
        double average_sales
        timestamp modified_at
        timestamp created_at
    }
    
    COMPANY_PARTNER_TYPE {
        varchar code PK "length 3"
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    COMPANY_PARTNER {
        bigint id PK "auto increment"
        bigint company_id FK
        bigint person_id FK
        varchar type FK "length 3"
        decimal participation_percentage "5,2"
        char status "length 1"
        timestamp modified_at
        timestamp created_at
    }
    
    PASSWORD {
        bigint id PK "auto increment"
        bigint rut FK
        int group_code FK
        varchar detail "length 256"
        char status "length 1"
        timestamp last_used_at
        timestamp modified_at
        timestamp created_at
    }
    
    CONTACT_TYPE {
        char code PK "length 1"
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    CONTACT {
        bigint id PK "auto increment"
        bigint rut FK
        char type FK
        varchar detail "length 60"
        char status "length 1"
        timestamp modified_at
        timestamp created_at
    }
    
    DIRECTION_TYPE {
        char code PK "length 1"
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    DIRECTION {
        bigint id PK "auto increment"
        bigint rut FK
        char type FK
        varchar street "length 60"
        varchar number "length 10"
        varchar commune "length 5"
        char status "length 1"
        timestamp modified_at
        timestamp created_at
    }
    
    ACCOUNT_TYPE {
        varchar code PK "length 3"
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    ACCOUNT {
        bigint number PK
        bigint rut FK
        varchar type FK
        int office FK
        varchar executive FK
        varchar plan FK
        double balance
        char status "length 1"
        timestamp modified_at
        timestamp created_at
    }
    
    ACCOUNT_SEQUENCE {
        bigint id PK "auto increment"
        int office FK
        bigint last_sequence
        bigint start_range
        bigint end_range
        timestamp modified_at
        timestamp created_at
    }
    
    CARD_TYPE {
        varchar code PK "length 2"
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    CARD {
        bigint pan PK
        bigint number FK
        varchar type FK
        varchar provider "length 20"
        varchar cvv "length 3"
        date expiration_date
        varchar password "length 256"
        double balance
        double credit_limit
        char status "length 1"
        timestamp last_used_at
        timestamp modified_at
        timestamp created_at
    }
    
    CHANNEL_GROUP {
        int code PK
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    CHANNEL {
        int code PK
        int group_code FK
        varchar name "length 50"
        timestamp modified_at
        timestamp created_at
    }
    
    OFFICE ||--o{ EXECUTIVE : "has"
    OFFICE ||--o{ CLIENT : "has"
    OFFICE ||--o{ ACCOUNT : "has"
    OFFICE ||--o{ ACCOUNT_SEQUENCE : "has"
    EXECUTIVE ||--o{ CLIENT : "manages"
    EXECUTIVE ||--o{ ACCOUNT : "manages"
    PLAN ||--o{ CLIENT : "assigned to"
    PLAN ||--o{ ACCOUNT : "assigned to"
    CLIENT_TYPE ||--o{ CLIENT : "categorizes"
    CLIENT ||--o| PERSON : "can be"
    CLIENT ||--o| COMPANY : "can be"
    CLIENT ||--o{ PASSWORD : "has"
    CLIENT ||--o{ CONTACT : "has"
    CLIENT ||--o{ DIRECTION : "has"
    CLIENT ||--o{ ACCOUNT : "owns"
    COMPANY ||--o{ COMPANY_PARTNER : "has"
    PERSON ||--o{ COMPANY_PARTNER : "participates in"
    COMPANY_PARTNER_TYPE ||--o{ COMPANY_PARTNER : "defines"
    CONTACT_TYPE ||--o{ CONTACT : "defines"
    DIRECTION_TYPE ||--o{ DIRECTION : "defines"
    ACCOUNT_TYPE ||--o{ ACCOUNT : "defines"
    ACCOUNT ||--o{ CARD : "has"
    CARD_TYPE ||--o{ CARD : "defines"
    CHANNEL_GROUP ||--o{ CHANNEL : "groups"
    CHANNEL_GROUP ||--o{ PASSWORD : "categorizes"
Loading

Architectural Diagram

graph TB
    subgraph "API Layer"
        Controller[Controllers]
        ExceptionHandler[Exception Handler]
        BasicAuth[Basic Authentication]
        TokenAuth[Token Authentication]
        RoleBasedAccess[Role-Based Access Control]
    end

    subgraph "Security Layer"
        AuthFilter[Authentication Filter]
        TokenProvider[Token Provider]
        PasswordEncoder[Password Encoder]
        TokenValidator[Token Validator]
        RoleValidator[Role Validator]
    end

    subgraph "Role Management"
        RoleService[Role Service]
        RoleRepository[Role Repository]
        RoleEntity[Role Entity]
        ClientRole[Client-Role Mapping]
    end

    subgraph "Business Layer"
        Service[Services]
        Validator[Validators]
        Mapper[Mappers]
    end

    subgraph "Error Handling"
        BusinessError[Business Error]
        TechnicalError[Technical Error]
        ErrorResponse[Error Response DTO]
        ForbiddenError[Forbidden Error 403]
    end

    subgraph "Data Layer"
        Repository[Repositories]
        Entity[Entities]
        H2DB[(H2 Database)]
    end

    subgraph "Integration Layer"
        WebClient[WebClient]
        ExternalAPI[External APIs]
    end

    subgraph "Configuration"
        AppConfig[Application Config]
        SecurityConfig[Security Config]
        WebClientConfig[WebClient Config]
    end

    Controller -->|uses| Service
    Controller -->|validates| RoleBasedAccess
    Controller -->|throws| BusinessError
    Controller -->|throws| TechnicalError
    Controller -->|throws| ForbiddenError

    ExceptionHandler -->|catches| BusinessError
    ExceptionHandler -->|catches| TechnicalError
    ExceptionHandler -->|catches| ForbiddenError
    ExceptionHandler -->|returns| ErrorResponse

    BasicAuth -->|validates| AuthFilter
    TokenAuth -->|validates| TokenValidator
    RoleBasedAccess -->|validates| RoleValidator
    
    AuthFilter -->|generates| TokenProvider
    TokenProvider -->|includes roles| TokenValidator
    TokenValidator -->|validates roles| RoleValidator
    
    RoleValidator -->|checks| RoleService
    RoleService -->|uses| RoleRepository
    RoleRepository -->|queries| RoleEntity
    RoleEntity -->|maps to| ClientRole

    Service -->|uses| Repository
    Service -->|uses| Validator
    Service -->|uses| Mapper
    Service -->|uses| WebClient
    Service -->|uses| RoleService
    Service -->|throws| BusinessError
    Service -->|throws| TechnicalError

    Validator -->|uses| PasswordEncoder

    Repository -->|queries| H2DB
    Repository -->|maps| Entity

    WebClient -->|calls| ExternalAPI

    SecurityConfig -->|configures| AuthFilter
    SecurityConfig -->|configures| TokenProvider
    SecurityConfig -->|configures| RoleValidator
    AppConfig -->|configures| H2DB
    WebClientConfig -->|configures| WebClient

    style Controller fill:#4CAF50
    style Service fill:#2196F3
    style Repository fill:#FF9800
    style ExceptionHandler fill:#F44336
    style TokenProvider fill:#9C27B0
    style WebClient fill:#00BCD4
    style RoleValidator fill:#E91E63
    style RoleService fill:#673AB7
Loading

Unit Testing

The unit tests for the Bank Microservice API are implemented using Spock Framework. To run the tests, use the following command in the terminal:

./gradlew test

This command will execute all the unit tests and provide a report of the test results. Make sure you have Gradle installed and properly configured in your environment to run the tests successfully.

Jacoco Report

The jacoco report for the Bank Microservice API is generated automatically when you run the tests. After running the tests, you can find the jacoco reports in the following directories:

HTML Report

build/jacoco/test/html/index.html

Open the index.html file in a web browser to view the code coverage report, which provides insights into which parts of the code are covered by the tests and which parts are not.

GitHub Actions Artifact

After each CI/CD pipeline run, the coverage report is also available as a downloadable artifact in GitHub Actions:

  1. Go to the Actions tab in the repository
  2. Select the latest workflow run
  3. Download the jacoco-html artifact to access the code coverage report locally.
    • Open the index.html file in a web browser to view the code coverage report, which provides insights into which parts of the code are covered by the tests and which parts are not.
  4. Download the test-reports artifact to access the test execution reports.
  5. Download the test-results artifact to access the raw test results.

Automated Testing

The automated tests for the Bank Microservice API are implemented using Karate Framework. To run the automated tests, use the following command in the terminal:

./gradlew automatedTest

this command will execute all the automated tests and provide a report of the test results. Make sure you have Gradle installed and properly configured in your environment to run the tests successfully. The automated tests will validate the functionality of the API endpoints and ensure that they are working as expected.

GitHub Actions Artifact

After each CI/CD pipeline run, the automated test reports are also available as a downloadable artifact in GitHub Actions:

  1. Go to the Actions tab in the repository
  2. Select the latest workflow run
  3. Download the automated-test-reports artifact to access the automated test execution reports.
  4. Download the automated-test-results artifact to access the raw automated test results.
  5. Download the karate-reports artifact to access the Karate test reports, which provide insights into the execution of the automated tests and their results.

Performance Testing

The performance tests for the Bank Microservice API are implemented using Apache JMeter. To open the JMeter GUI, use the following command in the terminal:

jmeter -JvPROTOCOL=http -JvHOST=localhost -JvPORT=8080 -JvBASEPATH=/ms-bank -JvTIMEOUT=8000 -JvTHREADS=5 -JvRAMPUP=1

This command will launch the JMeter GUI, where you can open the /external-test/load/jmeter/ms-bank.jmx file and run performance test plans to evaluate the performance of the Bank Microservice API under different load conditions. You can configure the number of threads, ramp-up time, and other parameters to simulate various scenarios and analyze the results to identify potential bottlenecks and optimize the performance of the API.

Variables

  • vPROTOCOL: The protocol to use for the API requests (e.g., http or https).
  • vHOST: The hostname or IP address of the server where the API is hosted (e.g., localhost).
  • vPORT: The port number on which the API is listening (e.g., 8080).
  • vBASEPATH: The base path of the API (e.g., /ms-bank).
  • vTIMEOUT: The timeout duration for API requests in milliseconds (e.g., 8000).
  • vTHREADS: The number of threads to use for the performance test (e.g., 5).
  • vRAMPUP: The ramp-up time in seconds for the performance test (e.g., 1). This is the time it takes for all threads to start executing the test plan. A ramp-up time of 1 second means that all threads will start executing the test plan within 1 second. Adjust this value based on the desired load and testing requirements.

GitHub Actions Artifact

After each CI/CD pipeline run, the performance test results are also available as a downloadable artifact in GitHub Actions:

  1. Go to the Actions tab in the repository
  2. Select the latest workflow run
  3. Download the jmeter-report artifact to access the performance test execution reports.
  4. Download the jmeter-results artifact to access the raw performance test results, which include detailed information about the performance of the API under different load conditions. Analyzing these results can help identify potential bottlenecks and optimize the performance of the API.

About

Bank Microservice API

Topics

java spring-boot spring-framework jmeter-tests banking-api karate-framework

Resources

Readme

License

MIT license
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages