Cosmic Module

Qubits of DPK

March 23, 2026

Core Open Source

Connection to Your PRs

PR #5668 (LoanWithdrawnByApplicantIntegrationTest) tests the withdrawal state transition in this module. PR #5670 (ClientLoanAccountLockIntegrationTest) tests the COB lock mechanism in this module.

What This Module Is (Big Picture)

The loan module is the heart of the banking system.

Most financial institutions using Fineract primarily operate as lenders. This module manages the entire lifecycle of loans.

That lifecycle includes:

loan application
loan approval
loan disbursement
repayment schedule generation
installment tracking
interest calculation
delinquency handling
loan closure

Layman:

Imagine a bank employee processing a loan.

Steps:

#
Customer applies for a loan
#
Bank approves the loan
#
Money is disbursed
#
Customer repays monthly installments
#
System tracks payments and interest

The loan module automates all of this.

Where the Code Lives

Loan functionality spans multiple modules.

Layman:

fineract-loan = loan department
fineract-core = financial tools and rules
fineract-provider = staff executing loan operations
fineract-accounting = ledger system recording transactions

Key Package 1:

org.apache.fineract.portfolio.loanaccount

This package manages loan accounts.

The Main Entity:

Loan.java

Path

plain text

QUBITS OF DPK

1fineract-loan/src/main/java/org/apache/fineract/portfolio/loanaccount/domain/Loan.java

This is the central domain entity representing a loan account.

Layman — JPA Entity:

Each Loan object represents one

Key fields on

Loan

Key methods inside

Loan.java

java

QUBITS OF DPK

1public Loan approve(...)
2public Loan disburse(...)
3public void makeRepayment(...)
4public void close(...)
5public LoanSchedule generateSchedule(...)

Layman Explanation

These methods represent the real actions performed during the loan lifecycle.

Example:

approve() → bank approves the loan
disburse() → money is sent to borrower
makeRepayment() → borrower pays installment
generateSchedule() → system calculates payment schedule

The Important Idea: Loan Lifecycle

Loans follow a state machine.

java

QUBITS OF DPK

1Loan Application
2       ↓
3Pending Approval
4       ↓
5Approved
6       ↓
7Disbursed
8       ↓
9Active Loan
10       ↓
11Fully Repaid
12       ↓
13Closed

Layman:

Just like a real bank, the loan moves through stages from application to final repayment.

DTO Layer:

LoanData.java

Path

java

QUBITS OF DPK

1fineract-loan/src/main/java/org/apache/fineract/portfolio/loanaccount/data/LoanData.java

This DTO represents loan information sent to APIs or UI.

Layman:

This is the

Key fields in

LoanData

java

QUBITS OF DPK

1id
2clientId
3loanProductId
4principal
5interestRate
6loanStatus
7repaymentSchedule
8disbursementDate

This object allows the UI to show:

loan details
repayment schedule
outstanding balance

Key Package 2: API Layer

LoansApiResource.java

Path

java

QUBITS OF DPK

1fineract-provider/src/main/java/org/apache/fineract/portfolio/loanaccount/api/LoansApiResource.java

This is the REST controller for loan operations.

Layman:

This class receives requests from mobile apps, web dashboards, or integrations asking to create or manage loans.

Key endpoints

java

QUBITS OF DPK

1GET    /v1/loans
2GET    /v1/loans/{loanId}
3POST   /v1/loans
4POST   /v1/loans/{loanId}?command=approve
5POST   /v1/loans/{loanId}?command=disburse
6POST   /v1/loans/{loanId}/repayments
7POST   /v1/loans/{loanId}?command=close

Layman:

These endpoints allow the system to:

create loans
approve loans
disburse funds
record repayments
close loans

Key Package 3: Read Services

LoanReadPlatformService

Paths

java

QUBITS OF DPK

1fineract-loan/.../service/LoanReadPlatformService.java
2fineract-provider/.../service/LoanReadPlatformServiceImpl.java

This service handles loan queries.

Key read operations

java

QUBITS OF DPK

1retrieveLoan(Long loanId)
2retrieveLoansByClient(Long clientId)
3retrieveLoanSchedule(Long loanId)
4retrieveLoanTransactions(Long loanId)

Layman:

This service retrieves loan data from the database so the system can display loan details.

Key Package 4: Write Services

LoanWritePlatformService

Paths

java

QUBITS OF DPK

1fineract-provider/.../service/LoanWritePlatformService.java
2fineract-provider/.../service/LoanWritePlatformServiceJpaRepositoryImpl.java

Handles loan modifications.

Key write operations

java

QUBITS OF DPK

1createLoan(JsonCommand)
2approveLoan(Long loanId)
3disburseLoan(Long loanId)
4makeRepayment(Long loanId)
5closeLoan(Long loanId)

Layman:

These methods represent real banking operations.

For example:

create loan record
approve application
send funds
track repayments

Repayment Schedule Generation

One of the most important parts of the loan module is generating the repayment schedule.

Example simplified schedule logic:

java

QUBITS OF DPK

1public List<Installment> generateSchedule(BigDecimal principal, BigDecimal interestRate, int months) {
2
3    List<Installment> schedule = new ArrayList<>();
4
5    BigDecimal monthlyInterest = principal.multiply(interestRate)
6                                           .divide(BigDecimal.valueOf(12));
7
8    BigDecimal installmentAmount = principal.divide(BigDecimal.valueOf(months))
9                                            .add(monthlyInterest);
10
11    for (int i = 1; i <= months; i++) {
12
13        Installment installment = new Installment(i, installmentAmount);
14        schedule.add(installment);
15    }
16
17    return schedule;
18}

Technical Explanation

This method:

#
Calculates monthly interest
#
Calculates installment amount
#
Creates installment objects
#
Generates the repayment schedule

Layman Explanation

If someone borrows:

₹10,000
for 10 months

The system calculates:

monthly payment
interest portion
principal portion

Then builds the payment schedule.

Command Handlers

Path

java

QUBITS OF DPK

1fineract-provider/.../portfolio/loanaccount/handler/

Key handlers include:

java

QUBITS OF DPK

1CreateLoanCommandHandler
2ApproveLoanCommandHandler
3DisburseLoanCommandHandler
4MakeLoanRepaymentCommandHandler
5CloseLoanCommandHandler

Layman:

Each loan action has its own handler to keep the system modular.

Repository and Data Access Layer

Exceptions

Layman:

These errors prevent invalid loan operations.

How It All Connects (Full Flow)

Example: Customer applies for a loan.

java

QUBITS OF DPK

1Admin UI
2   │ POST /v1/loans
3   ▼
4LoansApiResource
5   │
6   ▼
7CommandProcessingService
8   │
9   ▼
10CreateLoanCommandHandler
11   │
12   ▼
13LoanWritePlatformServiceJpaRepositoryImpl
14   │ → Validate input
15   │ → Create Loan entity
16   │ → Generate repayment schedule
17   │ → Save loan
18   ▼
19Database (m_loan table)
20   │
21   ▼
22Response returned to UI

Layman:

The system validates the loan request, creates the loan account, generates the repayment schedule, stores it, and returns the loan ID.

Why This Module Matters to the Rest of Fineract

Many modules interact with the loan module.

Examples:

fineract-portfolio → links loans to clients
fineract-group → supports group loans
fineract-accounting → records loan transactions in GL
fineract-reporting → generates loan performance reports

Layman:

The loan module is the

One-Sentence Layman Summary

fineract-loan manages the entire lifecycle of loans — from application and approval to disbursement, repayment tracking, and final closure.