CoopCredit

This repository contains the credit-application-service, a core component of the CoopCredit system. It is a microservice designed to manage the entire lifecycle of credit applications, from affiliate registration to automated evaluation, following a robust Hexagonal Architecture.

This system is part of a distributed architecture that includes:

1. credit-application-service (This service): Manages affiliates, credit applications, and user security. It orchestrates the credit evaluation process.
2. risk-central-mock-service: A separate mock service that simulates an external risk assessment central, providing a risk score for applicants.

---

Table of Contents

• About The Project
  • External Services
• Architecture
  • Microservice Overview
  • Hexagonal Architecture (Ports & Adapters)
• Getting Started
  • Prerequisites
  • Execution with Docker Compose (Recommended)
  • Manual Execution
• Roles and Flows
  • User Roles
  • Main Application Flow
• API Documentation & Testing
• Technology Stack

---

About The Project

The main goal of this service is to provide a scalable and maintainable solution for processing credit applications.

Key Features:

• Affiliate Management: CRUD operations for affiliates.
• Credit Application Management: Creation and evaluation of credit applications.
• Robust Security: Stateless authentication and authorization using Spring Security and JWT.
• Hexagonal Architecture: Clean separation between domain logic and infrastructure concerns.
• Advanced Persistence: Uses JPA/Hibernate with Flyway for database migrations.
• Observability: Exposes key metrics for monitoring using Actuator and Micrometer.
• Standardized Error Handling: Provides detailed error responses using RFC 7807 ProblemDetail.

External Services

• risk-central-mock-service: A mock service that simulates an external risk assessment central, providing risk scores for applicants.

Repository: https://github.com/Carturo8/risk-central-mock-service

---

Architecture

Microservice Overview

The system is composed of two microservices that communicate via a REST API. The database is managed by this service.

+-----------+      (REST API)      +----------------------------+      (REST API)      +---------------------------+
|   User    | <------------------> | credit-application-service | <------------------> | risk-central-mock-service |
+-----------+                      +----------------------------+                      +---------------------------+
                                             |
                                             | (JDBC)
                                             v
                                     +----------------+
                                     | PostgreSQL DB  |
                                     +----------------+

Hexagonal Architecture (Ports & Adapters)

The credit-application-service is built following the Hexagonal Architecture pattern. This isolates the core business logic from external technologies and frameworks.

• Domain (Core): Contains the pure business models (e.g., Affiliate, CreditApplication) and the business rules. It also defines the Ports (Java interfaces) that dictate how the core communicates with the outside world, without knowing any implementation details.

  • Examples: CreditApplicationRepositoryPort, RiskCentralPort, CreateCreditApplicationUseCase.

• Application: This layer orchestrates the execution of use cases. It implements the use case interfaces defined in the domain and contains the application-specific business logic.

  • Examples: CreateCreditApplicationUseCaseImpl, EvaluateCreditApplicationUseCaseImpl.

• Infrastructure (Adapters): This is the outermost layer. It contains the concrete implementations of the ports and all the code related to external technologies.

  • Inbound Adapters (Driving): Handle requests from the outside and translate them into calls to the application layer.
    • Example: Spring MVC REST Controllers (/api/v1/...).
  • Outbound Adapters (Driven): Implement the outbound ports to communicate with external systems.
    • Examples: JPA implementations for repositories (AffiliateRepositoryAdapter), REST clients to call the risk-central-mock-service.

---

Getting Started

Follow these instructions to get a copy of the project up and running on your local machine.

Prerequisites

• JDK 21 or higher
• Maven 3.8+
• Docker and Docker Compose

Execution with Docker Compose (Recommended)

This is the simplest way to run the entire system, including the database and the mock service.
Important: Both credit-application-service and risk-central-mock-service must be cloned into the same parent directory (same folder/level) so that Docker Compose can start all containers correctly.

1. Clone the main service repository:

   git clone https://github.com/Carturo8/credit-application-service
   cd credit-application-service

2. Clone the mock service repository at the same level:

   git clone https://github.com/Carturo8/risk-central-mock-service

3. Run Docker Compose from the root of the main service:: From the root of the project, run the following command:

   docker compose up --build -d

   This will build and start three containers:

   • credit-application-service (this application)
   • risk-central-mock-service
   • db (PostgreSQL database)

4. Access the application: The service will be available at http://localhost:8080.

Manual Execution

For development and debugging, you can run the service directly from your IDE or the command line.

1. Start Dependencies: Ensure you have a running PostgreSQL instance and that the risk-central-mock-service is also running.

2. Configure Environment Variables: Set the following environment variables or update application.yml:

   • SPRING_DATASOURCE_URL: The JDBC URL of your database.
   • SPRING_DATASOURCE_USERNAME: Your database username.
   • SPRING_DATASOURCE_PASSWORD: Your database password.
   • APPLICATION_SECURITY_JWT_SECRET-KEY: A secure secret key for JWT signing.
   • APPLICATION_EXTERNAL_RISK-SERVICE_URL: The URL of the running risk-central-mock-service.

3. Run the application using Maven:

   mvn spring-boot:run

---

Roles and Flows

User Roles

The application defines three user roles with specific permissions:

• ROLE_ADMIN: Has full access to the system. Can manage affiliates and all credit applications.
• ROLE_ANALYST: Can view and evaluate pending credit applications.
• ROLE_AFFILIATE: Can create new credit applications and view the status of their own applications only.

Main Application Flow

1. An Admin registers a new user with the ROLE_AFFILIATE role.
2. The Affiliate logs in using /auth/login to get a JWT.
3. The Affiliate, using their JWT, submits a new credit application via the API. The application is created with a PENDING status.
4. An Analyst (or an automated trigger) requests the evaluation of the pending application.
5. The service performs a series of validations:
   • Checks the affiliate's employment seniority.
   • Validates the requested amount against their salary.
   • Calls the risk-central-mock-service to get a risk score.
6. Based on the validation results, the application status is updated to APPROVED or REJECTED.

---

API Documentation & Testing

The API is documented using OpenAPI (Swagger). Once the application is running, you can access the interactive Swagger UI here:

• Swagger UI: http://localhost:8080/swagger-ui/index.html

Postman Collection

A Postman collection with sample requests for all endpoints is available.

• Download the Postman Collection

---

Technology Stack

• Framework: Spring Boot 3
• Language: Java 21
• Security: Spring Security (JWT)
• Database: PostgreSQL with JPA/Hibernate
• Migrations: Flyway
• Mapping: MapStruct
• Observability: Micrometer & Spring Boot Actuator
• Testing: JUnit 5, Mockito, Spring Boot Test, Testcontainers
• Containerization: Docker & Docker Compose