Service Layer
Relevant source files
The following files were used as context for generating this wiki page:- src/main/java/com/paymaster/backend/domain/service/CustomerService.java
- src/main/java/com/paymaster/backend/domain/service/ContractService.java
- src/main/java/com/paymaster/backend/domain/service/InstallmentService.java
- src/main/java/com/paymaster/backend/domain/service/DashboardService.java
- src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
- src/main/java/com/paymaster/backend/domain/entity/Customer.java
The Service Layer in the PayMaster application encapsulates the core business logic. It acts as an intermediary between the Presentation Layer (Controllers) and the Data Access Layer (Repositories). This layer is responsible for orchestrating business processes, performing calculations, enforcing validation rules, and managing the application's domain entities such as Customer, Contract, and Installment. All services are marked with the @Service annotation, making them Spring-managed beans available for dependency injection.
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java:18, src/main/java/com/paymaster/backend/domain/service/DashboardService.java:16, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:23-28
Architecture and Dependencies
The Service Layer follows a standard layered architecture pattern. The HomeController from the presentation layer injects and calls various services to handle user requests. These services, in turn, use repositories (e.g., ContractRepository, CustomerRepository) to interact with the database and may depend on other services to fulfill complex operations.
This diagram illustrates the dependency flow from controllers to services and their internal dependencies.
The following class diagram shows the direct dependencies between the primary services.
Core Services
ContractService
This service manages all business logic related to contracts. Its primary responsibilities include creating new contracts, generating unique contract numbers, performing financial calculations, creating associated installments, and managing the contract lifecycle.
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java
Key Methods
| Method | Description |
|---|---|
createContract(...) | Creates a new contract, calculates interest and total amounts, and generates all associated installments. This is a transactional method. |
generateContractNumber() | Generates a unique, sequential contract number based on the current Persian year, e.g., C14040001. |
generateInstallments(...) | Creates Installment entities for a given contract, distributing the principal and interest. It handles rounding adjustments on the final installment. |
cancelContract(...) | Changes a contract's status to CANCELLED and appends the cancellation reason to the description. |
updateContractStatuses() | A batch process to update contract statuses to COMPLETED if all installments are paid, or OVERDUE if any installment is past its due date. |
findByStatus(...) | Retrieves contracts filtered by a specific ContractStatus with pagination. |
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java:82, src/main/java/com/paymaster/backend/domain/service/ContractService.java:130, src/main/java/com/paymaster/backend/domain/service/ContractService.java:155, src/main/java/com/paymaster/backend/domain/service/ContractService.java:204, src/main/java/com/paymaster/backend/domain/service/ContractService.java:240
Contract Creation Flow
The createContract method follows a specific sequence to ensure data integrity.
CustomerService
This service handles all operations related to customer management. It provides methods for creating, reading, updating, deleting (CRUD), and searching for customers.
Sources: src/main/java/com/paymaster/backend/presentation/controller/CustomerService.java, src/main/java/com/paymaster/backend/domain/entity/Customer.java
Key Methods
| Method | Description |
|---|---|
search(...) | Searches for customers by a keyword in their full name, national code, or mobile number, with pagination support. |
save(...) | Saves a new customer entity to the database. |
update(...) | Updates an existing customer's information. |
delete(...) | Deletes a customer by their ID. |
findById(...) | Retrieves a single customer by their unique ID. |
count() / countActive() | Counts total and active customers, respectively. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:70, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:103, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:110, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:160, src/main/java/com/paymaster/backend/domain/service/DashboardService.java:34
InstallmentService
This service is responsible for managing individual installments. Its core functions include processing payments, tracking installment statuses, and querying for installments based on their due dates.
Sources: src/main/java/com/paymaster/backend/domain/service/InstallmentService.java
Key Methods
| Method | Description |
|---|---|
payInstallment(...) | Records a payment for an installment, updating its status and paid amount. |
quickPay(...) | A convenience method to fully pay the remaining amount of an installment. |
findOverdueInstallments() | Finds all installments that are past their due date and not fully paid. |
findInstallmentsDueThisWeek() | Retrieves a list of installments with a due date in the current week. |
sumPaidAmount() / sumOverdueAmount() | Calculates the total amount paid across all installments and the total overdue amount, respectively. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:319, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:338, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:298, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:309, src/main/java/com/paymaster/backend/domain/service/DashboardService.java:40-41
Installment Payment Sequence
The following diagram shows the interaction when a user pays an installment via the HomeController.
DashboardService
The DashboardService acts as an aggregator, collecting key performance indicators (KPIs) and statistics from other services to provide a consolidated overview for the main dashboard.
Sources: src/main/java/com/paymaster/backend/domain/service/DashboardService.java
DashboardStats Data Structure
The getDashboardStats() method returns a DashboardStats object, which contains a snapshot of the system's state.
| Field | Description | Source Service |
|---|---|---|
totalCustomers | Total number of customers in the system. | CustomerService |
activeContracts | Number of contracts with ACTIVE status. | ContractService |
overdueInstallments | Count of installments past their due date. | InstallmentService |
totalReceivable | Sum of the totalAmount for all active contracts. | ContractService |
totalReceived | Sum of all payments made for all installments. | InstallmentService |
totalOverdue | Sum of remaining amounts for overdue installments. | InstallmentService |
todayPersianDate | The current date in Persian format. | DateUtils |
Sources: src/main/java/com/paymaster/backend/domain/service/DashboardService.java:32-45, src/main/java/com/paymaster/backend/domain/service/DashboardService.java:70-82
Supporting Services
CalculationService
This is a utility service injected into other services to perform financial calculations. It ensures that calculations are consistent across the application.
calculateSimpleInterest(...): Calculates the total simple interest for a loan.calculateInstallmentAmount(...): Calculates the amount for each installment by dividing the total amount by the number of months.
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java:100-102, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:391-392
DateUtils
A helper class used for date-related operations, particularly for converting between Gregorian and Persian calendars and for date arithmetic like adding months to a start date. This is crucial for a system targeting Iranian users.
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java:24, src/main/java/com/paymaster/backend/domain/service/ContractService.java:106, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:27