This DTO provides a standard response format with a response code
+ * and message for various API operations.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Response {
+ /** Response code indicating the result (e.g., "200", "400"). */
private String responseCode;
+ /** Human-readable message describing the result. */
private String message;
}
diff --git a/Transaction-Service/src/main/java/org/training/transactions/model/response/TransactionRequest.java b/Transaction-Service/src/main/java/org/training/transactions/model/response/TransactionRequest.java
index 7f69080..4401679 100644
--- a/Transaction-Service/src/main/java/org/training/transactions/model/response/TransactionRequest.java
+++ b/Transaction-Service/src/main/java/org/training/transactions/model/response/TransactionRequest.java
@@ -8,23 +8,39 @@
import java.math.BigDecimal;
import java.time.LocalDateTime;
+/**
+ * Response DTO for transaction history queries.
+ *
+ * This DTO is used to return transaction details in API responses
+ * when querying transaction history.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class TransactionRequest {
+ /** Unique reference ID for tracking the transaction. */
private String referenceId;
+ /** Account number associated with this transaction. */
private String accountId;
+ /** Type of transaction (DEPOSIT, WITHDRAWAL, etc.). */
private String transactionType;
+ /** Transaction amount. */
private BigDecimal amount;
+ /** Timestamp when the transaction occurred. */
private LocalDateTime localDateTime;
+ /** Current status of the transaction. */
private String transactionStatus;
+ /** Additional comments or description. */
private String comments;
}
diff --git a/Transaction-Service/src/main/java/org/training/transactions/repository/TransactionRepository.java b/Transaction-Service/src/main/java/org/training/transactions/repository/TransactionRepository.java
index a5bd09c..24410e5 100644
--- a/Transaction-Service/src/main/java/org/training/transactions/repository/TransactionRepository.java
+++ b/Transaction-Service/src/main/java/org/training/transactions/repository/TransactionRepository.java
@@ -5,6 +5,17 @@
import java.util.List;
+/**
+ * Repository interface for {@link Transaction} entity persistence operations.
+ *
+ * This repository extends JpaRepository to provide standard CRUD operations
+ * and adds custom query methods for finding transactions by account ID and
+ * reference ID.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.transactions.model.entity.Transaction
+ */
public interface TransactionRepository extends JpaRepository {
/**
diff --git a/Transaction-Service/src/main/java/org/training/transactions/service/TransactionService.java b/Transaction-Service/src/main/java/org/training/transactions/service/TransactionService.java
index 7743556..12af15a 100644
--- a/Transaction-Service/src/main/java/org/training/transactions/service/TransactionService.java
+++ b/Transaction-Service/src/main/java/org/training/transactions/service/TransactionService.java
@@ -6,6 +6,16 @@
import java.util.List;
+/**
+ * Service interface defining transaction operations.
+ *
+ * This interface defines the contract for transaction business operations
+ * including creating transactions and retrieving transaction history.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.transactions.service.implementation.TransactionServiceImpl
+ */
public interface TransactionService {
/**
diff --git a/Transaction-Service/src/main/java/org/training/transactions/service/implementation/TransactionServiceImpl.java b/Transaction-Service/src/main/java/org/training/transactions/service/implementation/TransactionServiceImpl.java
index 6f69187..26512c4 100644
--- a/Transaction-Service/src/main/java/org/training/transactions/service/implementation/TransactionServiceImpl.java
+++ b/Transaction-Service/src/main/java/org/training/transactions/service/implementation/TransactionServiceImpl.java
@@ -27,16 +27,40 @@
import java.util.UUID;
import java.util.stream.Collectors;
+/**
+ * Implementation of the {@link TransactionService} interface.
+ *
+ * This service handles all transaction business logic including creating
+ * transactions, processing internal transfers, and retrieving transaction history.
+ * It coordinates with the Account Service for balance updates.
+ *
+ * Key features:
+ *
+ * - Deposit and withdrawal transactions
+ * - Internal transfer transaction recording
+ * - Account balance validation
+ * - Transaction history retrieval
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.transactions.service.TransactionService
+ */
@Slf4j
@Service
@RequiredArgsConstructor
public class TransactionServiceImpl implements TransactionService {
+ /** Repository for transaction data persistence. */
private final TransactionRepository transactionRepository;
+
+ /** Feign client for Account Service communication. */
private final AccountService accountService;
+ /** Mapper for converting between Transaction entities and DTOs. */
private final TransactionMapper transactionMapper = new TransactionMapper();
+ /** Response code for successful operations. */
@Value("${spring.application.ok}")
private String ok;
diff --git a/User-Service/src/main/java/org/training/user/service/UserServiceApplication.java b/User-Service/src/main/java/org/training/user/service/UserServiceApplication.java
index 70d2cbf..37ee34d 100644
--- a/User-Service/src/main/java/org/training/user/service/UserServiceApplication.java
+++ b/User-Service/src/main/java/org/training/user/service/UserServiceApplication.java
@@ -5,11 +5,47 @@
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import org.springframework.cloud.openfeign.EnableFeignClients;
+/**
+ * Main entry point for the User Service microservice.
+ *
+ * This microservice manages user operations including user registration,
+ * profile management, and status updates. It integrates with Keycloak for
+ * authentication and authorization, storing user credentials in Keycloak
+ * while maintaining application-specific user data in MySQL.
+ *
+ * Key responsibilities:
+ *
+ * - User registration with Keycloak integration
+ * - User profile management (personal information, contact details)
+ * - User status management (PENDING, APPROVED, DISABLED, REJECTED)
+ * - User lookup by ID, email, or account number
+ * - Admin approval workflow for new user registrations
+ *
+ *
+ * The service uses a dual storage approach:
+ *
+ * - Keycloak: Credentials, email, verification status
+ * - MySQL: Application data (userId, contactNo, identificationNumber, status, userProfile)
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.service.UserService
+ * @see org.training.user.service.controller.UserController
+ */
@SpringBootApplication
@EnableFeignClients
@EnableEurekaClient
public class UserServiceApplication {
+ /**
+ * Main method that starts the User Service application.
+ *
+ * Initializes the Spring Boot application context and starts the embedded
+ * web server. The service registers itself with Eureka for service discovery.
+ *
+ * @param args command line arguments passed to the application
+ */
public static void main(String[] args) {
SpringApplication.run(UserServiceApplication.class, args);
}
diff --git a/User-Service/src/main/java/org/training/user/service/config/KeyCloakManager.java b/User-Service/src/main/java/org/training/user/service/config/KeyCloakManager.java
index ae9d158..4729e0b 100644
--- a/User-Service/src/main/java/org/training/user/service/config/KeyCloakManager.java
+++ b/User-Service/src/main/java/org/training/user/service/config/KeyCloakManager.java
@@ -4,10 +4,22 @@
import org.keycloak.admin.client.resource.RealmResource;
import org.springframework.stereotype.Component;
+/**
+ * Manager class for obtaining Keycloak client instances.
+ *
+ * This component provides access to the Keycloak Admin Client configured
+ * for the banking-service realm. It abstracts the Keycloak connection details
+ * and provides a simple interface for services to interact with Keycloak.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.config.KeyCloakProperties
+ */
@Component
@RequiredArgsConstructor
public class KeyCloakManager {
+ /** Configuration properties for Keycloak connection. */
private final KeyCloakProperties keyCloakProperties;
/**
diff --git a/User-Service/src/main/java/org/training/user/service/config/KeyCloakProperties.java b/User-Service/src/main/java/org/training/user/service/config/KeyCloakProperties.java
index 52fb3d2..3c9f8f8 100644
--- a/User-Service/src/main/java/org/training/user/service/config/KeyCloakProperties.java
+++ b/User-Service/src/main/java/org/training/user/service/config/KeyCloakProperties.java
@@ -6,22 +6,45 @@
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
+/**
+ * Configuration properties for Keycloak Admin Client.
+ *
+ * This component holds the configuration properties needed to connect to Keycloak
+ * and provides a singleton instance of the Keycloak Admin Client. It uses the
+ * client_credentials grant type for administrative operations.
+ *
+ * Configuration is loaded from application properties:
+ *
+ * - app.config.keycloak.server-url - Keycloak server URL
+ * - app.config.keycloak.realm - The banking-service realm
+ * - app.config.keycloak.client-id - Client ID for admin operations
+ * - app.config.keycloak.client-secret - Client secret for authentication
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Slf4j
@Component
public class KeyCloakProperties {
+ /** Keycloak server URL (e.g., http://localhost:8571). */
@Value("${app.config.keycloak.server-url}")
private String serverUrl;
+ /** The Keycloak realm name (banking-service). */
@Value("${app.config.keycloak.realm}")
private String realm;
+ /** Client ID for Keycloak admin operations. */
@Value("${app.config.keycloak.client-id}")
private String clientId;
+ /** Client secret for authentication. */
@Value("${app.config.keycloak.client-secret}")
private String clientSecret;
+ /** Singleton instance of the Keycloak Admin Client. */
private static Keycloak keycloakInstance = null;
/**
diff --git a/User-Service/src/main/java/org/training/user/service/controller/UserController.java b/User-Service/src/main/java/org/training/user/service/controller/UserController.java
index 1ca6139..80fcbf8 100644
--- a/User-Service/src/main/java/org/training/user/service/controller/UserController.java
+++ b/User-Service/src/main/java/org/training/user/service/controller/UserController.java
@@ -14,6 +14,27 @@
import java.util.List;
+/**
+ * REST controller for user management operations.
+ *
+ * This controller exposes endpoints for user registration, retrieval, and updates.
+ * It handles HTTP requests and delegates business logic to the {@link UserService}.
+ *
+ * Available endpoints:
+ *
+ * - POST /api/users/register - Register a new user (public endpoint)
+ * - GET /api/users - Retrieve all users
+ * - GET /api/users/{userId} - Retrieve user by ID
+ * - GET /api/users/auth/{authId} - Retrieve user by Keycloak auth ID
+ * - GET /api/users/accounts/{accountId} - Retrieve user by account ID
+ * - PATCH /api/users/{id} - Update user status (admin approval)
+ * - PUT /api/users/{id} - Update user profile information
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.service.UserService
+ */
@Slf4j
@RestController
@RequestMapping("/api/users")
diff --git a/User-Service/src/main/java/org/training/user/service/exception/EmptyFields.java b/User-Service/src/main/java/org/training/user/service/exception/EmptyFields.java
index 626854b..4db8ff3 100644
--- a/User-Service/src/main/java/org/training/user/service/exception/EmptyFields.java
+++ b/User-Service/src/main/java/org/training/user/service/exception/EmptyFields.java
@@ -1,6 +1,23 @@
package org.training.user.service.exception;
+/**
+ * Exception thrown when required fields are empty or incomplete.
+ *
+ * This exception is thrown when a user profile has empty fields that must
+ * be filled before certain operations (like status approval) can proceed.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.exception.GlobalException
+ */
public class EmptyFields extends GlobalException{
+
+ /**
+ * Constructs an EmptyFields exception with the specified message and error code.
+ *
+ * @param message the detailed error message
+ * @param errorCode the error code for this exception
+ */
public EmptyFields(String message, String errorCode) {
super(message, errorCode);
}
diff --git a/User-Service/src/main/java/org/training/user/service/exception/ErrorResponse.java b/User-Service/src/main/java/org/training/user/service/exception/ErrorResponse.java
index c1c0f8f..4806e4d 100644
--- a/User-Service/src/main/java/org/training/user/service/exception/ErrorResponse.java
+++ b/User-Service/src/main/java/org/training/user/service/exception/ErrorResponse.java
@@ -5,13 +5,25 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * Data Transfer Object for error responses.
+ *
+ * This class represents the structure of error responses returned by the API
+ * when an exception occurs. It provides a consistent format for error information
+ * that clients can parse and handle appropriately.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class ErrorResponse {
+ /** The error code (e.g., "400", "404", "409"). */
private String errorCode;
+ /** A human-readable error message describing what went wrong. */
private String errorMessage;
}
diff --git a/User-Service/src/main/java/org/training/user/service/exception/GlobalError.java b/User-Service/src/main/java/org/training/user/service/exception/GlobalError.java
index bda280e..e69d8ba 100644
--- a/User-Service/src/main/java/org/training/user/service/exception/GlobalError.java
+++ b/User-Service/src/main/java/org/training/user/service/exception/GlobalError.java
@@ -1,6 +1,17 @@
package org.training.user.service.exception;
+/**
+ * Constants class containing standard HTTP error codes used throughout the User Service.
+ *
+ * This utility class provides centralized error code constants that are used
+ * when creating exception responses. Using constants ensures consistency across
+ * all error handling in the service.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
public class GlobalError {
+ /** HTTP 404 Not Found - Resource does not exist. */
public static final String NOT_FOUND = "404";
}
diff --git a/User-Service/src/main/java/org/training/user/service/exception/GlobalException.java b/User-Service/src/main/java/org/training/user/service/exception/GlobalException.java
index 686fe2a..4740a65 100644
--- a/User-Service/src/main/java/org/training/user/service/exception/GlobalException.java
+++ b/User-Service/src/main/java/org/training/user/service/exception/GlobalException.java
@@ -4,15 +4,32 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * Base exception class for all custom exceptions in the User Service.
+ *
+ * This runtime exception serves as the parent class for all application-specific
+ * exceptions. It carries an error code and message that can be used to provide
+ * meaningful error responses to API clients.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class GlobalException extends RuntimeException{
+ /** A human-readable error message describing the exception. */
private String message;
+ /** The error code associated with this exception (e.g., "400", "404", "409"). */
private String errorCode;
+ /**
+ * Constructs a GlobalException with only a message.
+ *
+ * @param message the detailed error message
+ */
public GlobalException(String message) {
this.message = message;
}
diff --git a/User-Service/src/main/java/org/training/user/service/exception/GlobalExceptionHandler.java b/User-Service/src/main/java/org/training/user/service/exception/GlobalExceptionHandler.java
index 6b555af..8f61d0a 100644
--- a/User-Service/src/main/java/org/training/user/service/exception/GlobalExceptionHandler.java
+++ b/User-Service/src/main/java/org/training/user/service/exception/GlobalExceptionHandler.java
@@ -10,15 +10,35 @@
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
+/**
+ * Global exception handler for the User Service.
+ *
+ * This class provides centralized exception handling across all controllers
+ * in the User Service. It intercepts exceptions thrown during request processing
+ * and converts them into appropriate HTTP responses with error details.
+ *
+ * Handled exceptions:
+ *
+ * - {@link MethodArgumentNotValidException} - Validation errors
+ * - {@link GlobalException} - Custom application exceptions
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler
+ */
@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
+ /** Error code for bad request responses (400). */
@Value("${spring.application.bad_request}")
private String errorCodeBadRequest;
+ /** Error code for conflict responses (409). */
@Value("${spring.application.conflict}")
private String errorCodeConflict;
+ /** Error code for not found responses (404). */
@Value("${spring.application.not_found}")
private String errorCodeNotFound;
diff --git a/User-Service/src/main/java/org/training/user/service/exception/ResourceConflictException.java b/User-Service/src/main/java/org/training/user/service/exception/ResourceConflictException.java
index 2d163e7..7ebc607 100644
--- a/User-Service/src/main/java/org/training/user/service/exception/ResourceConflictException.java
+++ b/User-Service/src/main/java/org/training/user/service/exception/ResourceConflictException.java
@@ -1,23 +1,29 @@
package org.training.user.service.exception;
+/**
+ * Exception thrown when a resource conflict occurs.
+ *
+ * This exception is thrown when an operation would create a duplicate resource
+ * or violate a uniqueness constraint. For example, attempting to register a user
+ * with an email that is already registered. It results in an HTTP 409 Conflict response.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.exception.GlobalException
+ */
public class ResourceConflictException extends GlobalException{
/**
- * Constructs a new runtime exception with {@code null} as its
- * detail message. The cause is not initialized, and may subsequently be
- * initialized by a call to {@link #initCause}.
+ * Constructs a ResourceConflictException with a default message.
*/
public ResourceConflictException() {
super("Resource already present on the server!!!");
}
/**
- * Constructs a new runtime exception with the specified detail message.
- * The cause is not initialized, and may subsequently be initialized by a
- * call to {@link #initCause}.
+ * Constructs a ResourceConflictException with a custom message.
*
- * @param message the detail message. The detail message is saved for
- * later retrieval by the {@link #getMessage()} method.
+ * @param message the detailed error message
*/
public ResourceConflictException(String message) {
super(message);
diff --git a/User-Service/src/main/java/org/training/user/service/exception/ResourceNotFound.java b/User-Service/src/main/java/org/training/user/service/exception/ResourceNotFound.java
index 8d9d6b8..7f0a75f 100644
--- a/User-Service/src/main/java/org/training/user/service/exception/ResourceNotFound.java
+++ b/User-Service/src/main/java/org/training/user/service/exception/ResourceNotFound.java
@@ -1,11 +1,30 @@
package org.training.user.service.exception;
+/**
+ * Exception thrown when a requested resource cannot be found.
+ *
+ * This exception is thrown when an operation attempts to access a resource
+ * (such as a user) that does not exist in the system. It results in an
+ * HTTP 404 Not Found response.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.exception.GlobalException
+ */
public class ResourceNotFound extends GlobalException{
+ /**
+ * Constructs a ResourceNotFound exception with a default message.
+ */
public ResourceNotFound() {
super("Resource not found on the server", GlobalError.NOT_FOUND);
}
+ /**
+ * Constructs a ResourceNotFound exception with a custom message.
+ *
+ * @param message the detailed error message
+ */
public ResourceNotFound(String message) {
super(message, GlobalError.NOT_FOUND);
}
diff --git a/User-Service/src/main/java/org/training/user/service/external/AccountService.java b/User-Service/src/main/java/org/training/user/service/external/AccountService.java
index b9e50c3..03567e2 100644
--- a/User-Service/src/main/java/org/training/user/service/external/AccountService.java
+++ b/User-Service/src/main/java/org/training/user/service/external/AccountService.java
@@ -7,6 +7,17 @@
import org.springframework.web.bind.annotation.RequestParam;
import org.training.user.service.model.external.Account;
+/**
+ * Feign client interface for communicating with the Account Service.
+ *
+ * This interface defines the contract for making HTTP requests to the Account Service
+ * microservice. It enables the User Service to retrieve account information for users.
+ *
+ * The client is configured to use the "account-service" name for service discovery.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@FeignClient(name = "account-service", configuration = FeignClientProperties.FeignClientConfiguration.class)
public interface AccountService {
diff --git a/User-Service/src/main/java/org/training/user/service/model/Status.java b/User-Service/src/main/java/org/training/user/service/model/Status.java
index 15c804a..074fe84 100644
--- a/User-Service/src/main/java/org/training/user/service/model/Status.java
+++ b/User-Service/src/main/java/org/training/user/service/model/Status.java
@@ -1,6 +1,26 @@
package org.training.user.service.model;
+/**
+ * Enumeration representing the possible statuses of a user account.
+ *
+ * Users follow an approval workflow where they start as PENDING after registration
+ * and must be approved by an administrator to become APPROVED. Users can also be
+ * DISABLED or REJECTED.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
public enum Status {
- PENDING, APPROVED, DISABLED, REJECTED
+ /** User is awaiting admin approval after registration. */
+ PENDING,
+
+ /** User has been approved and can access the system. */
+ APPROVED,
+
+ /** User account has been disabled by an administrator. */
+ DISABLED,
+
+ /** User registration has been rejected by an administrator. */
+ REJECTED
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/dto/CreateUser.java b/User-Service/src/main/java/org/training/user/service/model/dto/CreateUser.java
index 40fb0ba..7ebe054 100644
--- a/User-Service/src/main/java/org/training/user/service/model/dto/CreateUser.java
+++ b/User-Service/src/main/java/org/training/user/service/model/dto/CreateUser.java
@@ -5,19 +5,33 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * Data Transfer Object for user registration requests.
+ *
+ * This DTO contains the information required to create a new user account.
+ * It is used by the public registration endpoint (/api/users/register).
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class CreateUser {
+ /** User's first name. */
private String firstName;
+ /** User's last name. */
private String lastName;
+ /** User's contact phone number. */
private String contactNumber;
+ /** User's email address (used as username in Keycloak). */
private String emailId;
+ /** User's password for authentication. */
private String password;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/dto/UserDto.java b/User-Service/src/main/java/org/training/user/service/model/dto/UserDto.java
index 8633423..faae34c 100644
--- a/User-Service/src/main/java/org/training/user/service/model/dto/UserDto.java
+++ b/User-Service/src/main/java/org/training/user/service/model/dto/UserDto.java
@@ -6,23 +6,39 @@
import lombok.NoArgsConstructor;
import org.training.user.service.model.Status;
+/**
+ * Data Transfer Object for user information.
+ *
+ * This DTO is used to transfer user data between layers and to external services.
+ * It contains the essential user information including profile details.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class UserDto {
+ /** Unique identifier for the user. */
private Long userId;
+ /** User's email address. */
private String emailId;
+ /** User's password (typically not populated in responses). */
private String password;
+ /** Unique identification number (UUID) assigned at registration. */
private String identificationNumber;
+ /** Keycloak authentication ID. */
private String authId;
+ /** Current status of the user account. */
private Status status;
+ /** User's profile information. */
private UserProfileDto userProfileDto;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/dto/UserProfileDto.java b/User-Service/src/main/java/org/training/user/service/model/dto/UserProfileDto.java
index 3cc980c..c29cc47 100644
--- a/User-Service/src/main/java/org/training/user/service/model/dto/UserProfileDto.java
+++ b/User-Service/src/main/java/org/training/user/service/model/dto/UserProfileDto.java
@@ -5,23 +5,40 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * Data Transfer Object for user profile information.
+ *
+ * This DTO contains the user's personal profile information that is stored
+ * separately from authentication data. It is used in API responses and
+ * nested within UserDto.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class UserProfileDto {
+ /** User's first name. */
private String firstName;
+ /** User's last name. */
private String lastName;
+ /** User's gender. */
private String gender;
+ /** User's residential address. */
private String address;
+ /** User's occupation or profession. */
private String occupation;
+ /** User's marital status. */
private String martialStatus;
+ /** User's nationality. */
private String nationality;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdate.java b/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdate.java
index e2ec1f4..3876f8a 100644
--- a/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdate.java
+++ b/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdate.java
@@ -5,25 +5,42 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * Data Transfer Object for user profile update requests.
+ *
+ * This DTO contains the fields that can be updated for an existing user's profile.
+ * It is used by the PUT /api/users/{id} endpoint.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class UserUpdate {
+ /** User's first name. */
private String firstName;
+ /** User's last name. */
private String lastName;
+ /** User's contact phone number. */
private String contactNo;
+ /** User's residential address. */
private String address;
+ /** User's gender. */
private String gender;
+ /** User's occupation or profession. */
private String occupation;
+ /** User's marital status. */
private String martialStatus;
+ /** User's nationality. */
private String nationality;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdateStatus.java b/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdateStatus.java
index 5c65516..57ec3c2 100644
--- a/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdateStatus.java
+++ b/User-Service/src/main/java/org/training/user/service/model/dto/UserUpdateStatus.java
@@ -6,11 +6,23 @@
import lombok.NoArgsConstructor;
import org.training.user.service.model.Status;
+/**
+ * Data Transfer Object for user status update requests.
+ *
+ * This DTO is used by administrators to update a user's status, typically
+ * for approving or rejecting user registrations. It is used by the
+ * PATCH /api/users/{id} endpoint.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.model.Status
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class UserUpdateStatus {
+ /** The new status to set for the user. */
private Status status;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/dto/response/Response.java b/User-Service/src/main/java/org/training/user/service/model/dto/response/Response.java
index bb4a580..6865cd9 100644
--- a/User-Service/src/main/java/org/training/user/service/model/dto/response/Response.java
+++ b/User-Service/src/main/java/org/training/user/service/model/dto/response/Response.java
@@ -5,13 +5,25 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * Generic response DTO for API operations.
+ *
+ * This class represents a standard response structure for API operations
+ * that don't return specific data. It provides a response code and message
+ * to indicate the result of the operation.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Response {
+ /** The response code indicating success or failure (e.g., "200", "OK"). */
private String responseCode;
+ /** A human-readable message describing the result of the operation. */
private String responseMessage;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/entity/User.java b/User-Service/src/main/java/org/training/user/service/model/entity/User.java
index cf0de9c..fb8df18 100644
--- a/User-Service/src/main/java/org/training/user/service/model/entity/User.java
+++ b/User-Service/src/main/java/org/training/user/service/model/entity/User.java
@@ -10,6 +10,22 @@
import javax.persistence.*;
import java.time.LocalDate;
+/**
+ * Entity class representing a user in the banking system.
+ *
+ * This entity stores application-specific user data in MySQL. User credentials
+ * and authentication data are stored separately in Keycloak, linked via the authId field.
+ *
+ * The dual storage approach separates concerns:
+ *
+ * - Keycloak: Credentials, email verification, enabled status
+ * - MySQL (this entity): Contact info, identification, status, profile
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.model.entity.UserProfile
+ */
@Entity
@AllArgsConstructor
@NoArgsConstructor
@@ -17,25 +33,33 @@
@Data
public class User {
+ /** Unique identifier for the user (auto-generated). */
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long userId;
+ /** User's email address (also stored in Keycloak). */
private String emailId;
+ /** User's contact phone number. */
private String contactNo;
+ /** Keycloak authentication ID linking to the identity provider. */
private String authId;
+ /** Unique identification number (UUID) assigned at registration. */
private String identificationNumber;
+ /** Date when the user account was created. */
@CreationTimestamp
private LocalDate creationOn;
+ /** Current status of the user (PENDING, APPROVED, DISABLED, REJECTED). */
@Enumerated(EnumType.STRING)
private Status status;
+ /** User's profile containing additional personal information. */
@OneToOne(cascade = CascadeType.ALL)
@JoinColumn(name = "user_profile_id", referencedColumnName = "userProfileId")
private UserProfile userProfile;
-}
\ No newline at end of file
+}
diff --git a/User-Service/src/main/java/org/training/user/service/model/entity/UserProfile.java b/User-Service/src/main/java/org/training/user/service/model/entity/UserProfile.java
index e0a983f..f6c21bf 100644
--- a/User-Service/src/main/java/org/training/user/service/model/entity/UserProfile.java
+++ b/User-Service/src/main/java/org/training/user/service/model/entity/UserProfile.java
@@ -10,6 +10,16 @@
import javax.persistence.GenerationType;
import javax.persistence.Id;
+/**
+ * Entity class representing a user's profile information.
+ *
+ * This entity stores additional personal information about a user that is not
+ * required for authentication. It has a one-to-one relationship with the User entity.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.model.entity.User
+ */
@Entity
@Data
@AllArgsConstructor
@@ -17,21 +27,29 @@
@Builder
public class UserProfile {
+ /** Unique identifier for the user profile (auto-generated). */
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long userProfileId;
+ /** User's first name. */
private String firstName;
+ /** User's last name. */
private String lastName;
+ /** User's gender. */
private String gender;
+ /** User's residential address. */
private String address;
+ /** User's occupation or profession. */
private String occupation;
+ /** User's marital status. */
private String martialStatus;
+ /** User's nationality. */
private String nationality;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/external/Account.java b/User-Service/src/main/java/org/training/user/service/model/external/Account.java
index a73e0c2..5fefc39 100644
--- a/User-Service/src/main/java/org/training/user/service/model/external/Account.java
+++ b/User-Service/src/main/java/org/training/user/service/model/external/Account.java
@@ -7,21 +7,36 @@
import java.math.BigDecimal;
+/**
+ * Data Transfer Object representing account information from the Account Service.
+ *
+ * This DTO is used to receive account data from the Account Service via Feign client.
+ * It contains the essential account information needed by the User Service.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Account {
+ /** Unique identifier for the account. */
private Long accountId;
+ /** The account number (unique identifier for banking operations). */
private String accountNumber;
+ /** The type of account (e.g., SAVINGS, CURRENT). */
private String accountType;
+ /** The current status of the account (e.g., ACTIVE, BLOCKED, CLOSED). */
private String accountStatus;
+ /** The available balance in the account. */
private BigDecimal availableBalance;
+ /** The ID of the user who owns this account. */
private Long userId;
}
diff --git a/User-Service/src/main/java/org/training/user/service/model/mapper/BaseMapper.java b/User-Service/src/main/java/org/training/user/service/model/mapper/BaseMapper.java
index 89934d1..02c2249 100644
--- a/User-Service/src/main/java/org/training/user/service/model/mapper/BaseMapper.java
+++ b/User-Service/src/main/java/org/training/user/service/model/mapper/BaseMapper.java
@@ -5,10 +5,36 @@
import java.util.Set;
import java.util.stream.Collectors;
+/**
+ * Abstract base class for entity-DTO mapping operations.
+ *
+ * This class provides a generic framework for converting between entity objects
+ * and their corresponding Data Transfer Objects (DTOs). Concrete implementations
+ * must provide the specific conversion logic for their entity-DTO pairs.
+ *
+ * @param the entity type
+ * @param the DTO type
+ * @author Training Team
+ * @version 1.0
+ */
public abstract class BaseMapper {
+ /**
+ * Converts a DTO to its corresponding entity.
+ *
+ * @param dto the DTO to convert
+ * @param args optional additional arguments for conversion
+ * @return the converted entity
+ */
public abstract E convertToEntity(D dto, Object... args);
+ /**
+ * Converts an entity to its corresponding DTO.
+ *
+ * @param entity the entity to convert
+ * @param args optional additional arguments for conversion
+ * @return the converted DTO
+ */
public abstract D convertToDto(E entity, Object... args);
public Collection convertToEntity(Collection dto, Object... args) {
diff --git a/User-Service/src/main/java/org/training/user/service/model/mapper/UserMapper.java b/User-Service/src/main/java/org/training/user/service/model/mapper/UserMapper.java
index 9ddbff9..08abea1 100644
--- a/User-Service/src/main/java/org/training/user/service/model/mapper/UserMapper.java
+++ b/User-Service/src/main/java/org/training/user/service/model/mapper/UserMapper.java
@@ -9,10 +9,32 @@
import java.util.Objects;
+/**
+ * Mapper class for converting between {@link User} entities and {@link UserDto} objects.
+ *
+ * This mapper extends {@link BaseMapper} and provides specific implementation
+ * for converting user data between the persistence layer (entities) and the
+ * API layer (DTOs). It handles nested UserProfile conversion as well.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.model.mapper.BaseMapper
+ */
public class UserMapper extends BaseMapper{
+ /** ModelMapper instance for object mapping. */
private final ModelMapper mapper = new ModelMapper();
+ /**
+ * Converts a {@link UserDto} to a {@link User} entity.
+ *
+ * Uses Spring's BeanUtils to copy properties from the DTO to a new entity.
+ * Also handles nested UserProfileDto to UserProfile conversion.
+ *
+ * @param dto the UserDto to convert
+ * @param args optional additional arguments (not used)
+ * @return the converted User entity
+ */
@Override
public User convertToEntity(UserDto dto, Object... args) {
@@ -28,6 +50,16 @@ public User convertToEntity(UserDto dto, Object... args) {
return user;
}
+ /**
+ * Converts a {@link User} entity to a {@link UserDto}.
+ *
+ * Uses Spring's BeanUtils to copy properties from the entity to a new DTO.
+ * Also handles nested UserProfile to UserProfileDto conversion.
+ *
+ * @param entity the User entity to convert
+ * @param args optional additional arguments (not used)
+ * @return the converted UserDto
+ */
@Override
public UserDto convertToDto(User entity, Object... args) {
diff --git a/User-Service/src/main/java/org/training/user/service/repository/UserRepository.java b/User-Service/src/main/java/org/training/user/service/repository/UserRepository.java
index fc83ce6..674bb52 100644
--- a/User-Service/src/main/java/org/training/user/service/repository/UserRepository.java
+++ b/User-Service/src/main/java/org/training/user/service/repository/UserRepository.java
@@ -5,6 +5,16 @@
import java.util.Optional;
+/**
+ * Repository interface for User entity persistence operations.
+ *
+ * This interface extends JpaRepository to provide CRUD operations for User entities.
+ * It also defines custom query methods for finding users by specific criteria.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.model.entity.User
+ */
public interface UserRepository extends JpaRepository {
/**
diff --git a/User-Service/src/main/java/org/training/user/service/service/KeycloakService.java b/User-Service/src/main/java/org/training/user/service/service/KeycloakService.java
index 6d15ab8..b4455d6 100644
--- a/User-Service/src/main/java/org/training/user/service/service/KeycloakService.java
+++ b/User-Service/src/main/java/org/training/user/service/service/KeycloakService.java
@@ -4,6 +4,20 @@
import java.util.List;
+/**
+ * Service interface for Keycloak authentication operations.
+ *
+ * This interface defines the contract for interacting with Keycloak as the
+ * identity provider. It provides methods for user management operations in
+ * Keycloak including creation, retrieval, and updates.
+ *
+ * The service uses the Keycloak Admin Client to perform administrative
+ * operations on the banking-service realm.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.service.implementation.KeycloakServiceImpl
+ */
public interface KeycloakService {
/**
diff --git a/User-Service/src/main/java/org/training/user/service/service/UserService.java b/User-Service/src/main/java/org/training/user/service/service/UserService.java
index 62db177..bd70fd5 100644
--- a/User-Service/src/main/java/org/training/user/service/service/UserService.java
+++ b/User-Service/src/main/java/org/training/user/service/service/UserService.java
@@ -8,6 +8,17 @@
import java.util.List;
+/**
+ * Service interface defining user management operations.
+ *
+ * This interface defines the contract for user-related business operations
+ * including registration, retrieval, and status management. Implementations
+ * coordinate with Keycloak for authentication and the database for user data.
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.service.implementation.UserServiceImpl
+ */
public interface UserService {
/**
diff --git a/User-Service/src/main/java/org/training/user/service/service/implementation/KeycloakServiceImpl.java b/User-Service/src/main/java/org/training/user/service/service/implementation/KeycloakServiceImpl.java
index 6886ce5..075b6dd 100644
--- a/User-Service/src/main/java/org/training/user/service/service/implementation/KeycloakServiceImpl.java
+++ b/User-Service/src/main/java/org/training/user/service/service/implementation/KeycloakServiceImpl.java
@@ -11,10 +11,31 @@
import java.util.List;
import java.util.stream.Collectors;
+/**
+ * Implementation of the {@link KeycloakService} interface.
+ *
+ * This service provides the actual implementation for Keycloak operations
+ * using the Keycloak Admin Client. It manages user lifecycle operations in
+ * the Keycloak identity provider.
+ *
+ * Operations include:
+ *
+ * - Creating new users in Keycloak
+ * - Searching users by email
+ * - Retrieving user details by auth ID
+ * - Updating user properties (enabled, emailVerified)
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.service.KeycloakService
+ * @see org.training.user.service.config.KeyCloakManager
+ */
@Service
@RequiredArgsConstructor
public class KeycloakServiceImpl implements KeycloakService {
+ /** Manager for obtaining Keycloak client instances. */
private final KeyCloakManager keyCloakManager;
/**
diff --git a/User-Service/src/main/java/org/training/user/service/service/implementation/UserServiceImpl.java b/User-Service/src/main/java/org/training/user/service/service/implementation/UserServiceImpl.java
index 7e416ba..4b00653 100644
--- a/User-Service/src/main/java/org/training/user/service/service/implementation/UserServiceImpl.java
+++ b/User-Service/src/main/java/org/training/user/service/service/implementation/UserServiceImpl.java
@@ -32,16 +32,42 @@
import java.util.function.Function;
import java.util.stream.Collectors;
+/**
+ * Implementation of the {@link UserService} interface.
+ *
+ * This service handles all user-related business logic including registration,
+ * profile management, and status updates. It coordinates between Keycloak for
+ * authentication and the local database for application-specific user data.
+ *
+ * Key features:
+ *
+ * - User registration with Keycloak integration (dual storage)
+ * - Admin approval workflow for new registrations
+ * - User profile updates and status management
+ * - Integration with Account Service for user-account lookups
+ *
+ *
+ * @author Training Team
+ * @version 1.0
+ * @see org.training.user.service.service.UserService
+ * @see org.training.user.service.service.KeycloakService
+ */
@Slf4j
@Service
@RequiredArgsConstructor
@Transactional
public class UserServiceImpl implements UserService {
+ /** Repository for user data persistence. */
private final UserRepository userRepository;
+
+ /** Service for Keycloak authentication operations. */
private final KeycloakService keycloakService;
+
+ /** Feign client for Account Service communication. */
private final AccountService accountService;
+ /** Mapper for converting between User entities and DTOs. */
private UserMapper userMapper = new UserMapper();
@Value("${spring.application.success}")
diff --git a/User-Service/src/main/java/org/training/user/service/utils/FieldChecker.java b/User-Service/src/main/java/org/training/user/service/utils/FieldChecker.java
index bf4288a..d3a23fe 100644
--- a/User-Service/src/main/java/org/training/user/service/utils/FieldChecker.java
+++ b/User-Service/src/main/java/org/training/user/service/utils/FieldChecker.java
@@ -2,10 +2,24 @@
import java.util.Arrays;
+/**
+ * Utility class for checking field values in objects.
+ *
+ * This class provides utility methods for validating object fields,
+ * particularly useful for checking if required fields are populated
+ * before performing certain operations like user approval.
+ *
+ * @author Training Team
+ * @version 1.0
+ */
public class FieldChecker {
/**
* Checks if an object has empty fields.
+ *
+ * Recursively checks all declared fields of the object. Returns true if
+ * any field is null (except for enum fields). For nested objects, it
+ * recursively checks their fields as well.
*
* @param object the object to check
* @return true if the object has empty fields, false otherwise