Cosmic Module

Qubits of DPK

March 20, 2026

Core Open Source

These modules handle specialized banking operations: investments, nightly batch processing, interest rates, branch management, reporting, and a new loan product type.

1. fineract-investor

What it is

The loan portfolio sale/purchase module — handles the buying and selling of loan portfolios between financial institutions (secondary market transactions).

Layman Analogy

Imagine a small microfinance bank that has given out 1,000 loans. They need cash now but can't wait for all borrowers to repay. So they sell these loans to a big investor (like a bank or fund) — the investor pays cash upfront and now collects the repayments. fineract-investor manages this entire transaction.

Key Concepts

External Asset Owner

The investor/entity that buys the loan portfolio
Tracked in m_external_asset_owner table

Asset Ownership Transfer

ExternalAssetOwnerTransfer.java — records when loans move from MFI to investor
Has states: PENDING → ACTIVE → BUYBACK or CANCELLED
Buyback: When the MFI repurchases its loans back from the investor

Business Events Involved

When a loan repayment is made on a sold loan — the money goes to the investor's account
Accounting entries are created to reflect the ownership change

Why This Matters for GSoC

FINERACT-2439 (BFF layer) needs to expose these APIs cleanly
Securitization and portfolio sales are growing in microfinance
Integration tests for investor transfers are in integration-tests module

Key Packages

javascript

QUBITS OF DPK

1fineract-investor/src/main/java/org/apache/fineract/investor/
2├── domain/        — ExternalAssetOwner, ExternalAssetOwnerTransfer
3├── service/       — ExternalAssetOwnerTransferService
4└── api/           — ExternalAssetOwnersApiResource

2. fineract-cob

What it is

The Close of Business (COB) batch processing module — the nightly job that processes every active loan in the system.

Layman Analogy

At the end of every banking day, there's a massive overnight operation where the bank:

Checks which loans missed payments
Applies late fees to overdue accounts
Calculates interest accrued for the day
Classifies loans by how overdue they are
Updates all account balances

fineract-cob is the night shift crew that does all this automatically while no one is watching.

Architecture

COB is built on Spring Batch — a framework for processing millions of records in chunks:

javascript

QUBITS OF DPK

1Spring Batch Job: "Loan COB"
2  ↓
3Job splits all active loans into chunks (e.g., 100 loans per chunk)
4  ↓
5For each chunk, run in parallel:
6  ↓
7LoanCOBWorkerService.processLoan(loanId):
8  1. Acquire lock on loan (m_loan_cob_account_lock)
9  2. Run all LoanCOBBusinessStep implementations:
10     - CheckLoanRepaymentDueBusinessStep
11     - ApplyChargeToOverdueLoanBusinessStep
12     - LoanDelinquencyClassificationBusinessStep
13     - LoanAccrualActivityBusinessStep
14     - InlineLoanCOBExecutorBusinessStep
15  3. Advance COB processed date on loan
16  4. Release lock

Key Classes

LoanCOBBusinessStep (interface)

Each step in the COB pipeline implements this
Steps are ordered (via @Order) and composable
MFIs can configure which steps to run

LoanAccountLock

Prevents concurrent modification: if COB is processing a loan, user can't make repayments until it finishes
Inline COB: If a user tries to modify a loan that hasn't been COB-processed yet, COB runs synchronously first

BusinessDateService

COB runs for a specific business date (configurable, not wall-clock date)
Lets you "fast forward" in tests by setting business date artificially

DelinquencyBucket

Classification tier: e.g., 1-30 days overdue, 31-60 days, 61-90 days, 90+ days
LoanDelinquencyClassificationBusinessStep assigns each loan to a bucket nightly

COB in Tests

java

QUBITS OF DPK

1// Tests fast-forward time day by day, running COB for each day
2schedulerJobHelper.fastForwardTime(startDate, endDate, "Loan COB", responseSpec);
3// Under the hood:
4// 1. Set COB_DATE to current date
5// 2. Run "Loan COB" job
6// 3. Increment date by 1
7// 4. Repeat until target date

Key Packages

javascript

QUBITS OF DPK

1fineract-cob/src/main/java/org/apache/fineract/cob/
2├── loan/          — LoanCOBBusinessStep implementations
3├── data/          — COB data transfer objects
4└── service/       — LoanCOBWorkerService, COB scheduler

3. fineract-rates

What it is

The currency rate management module — handles foreign exchange rates for multi-currency operations.

Layman Analogy

MFIs operating in multiple countries need to deal with different currencies (USD, EUR, KES, BDT). When reporting consolidated financials or doing cross-currency transactions, you need to know today's exchange rate. fineract-rates is like having a live currency converter built into the system.

Key Concepts

Rate.java

Exchange rate definition: from-currency, to-currency, rate value, effective date
Historical rates are kept (you can query what the rate was on any past date)

RateApiResource

REST endpoints: GET /rates, POST /rates, PUT /rates/{id}
Used by reporting to normalize values to a base currency

Scope

This is a relatively small, focused module — it doesn't do currency conversion itself, but provides the rate data that other modules (like reporting) use.

Key Packages

javascript

QUBITS OF DPK

1fineract-rates/src/main/java/org/apache/fineract/portfolio/rate/
2├── domain/   — Rate.java
3├── service/  — RateReadPlatformService
4└── api/      — RateApiResource

4. fineract-branch

What it is

The organizational hierarchy module — manages offices (branches) and their tree structure.

Layman Analogy

A bank has a head office and many branch offices (like: HQ → Region East → City Branch → Village Sub-branch). fineract-branch manages this tree of offices and ensures every client, loan, and savings account is linked to exactly one office.

Key Classes

Office.java

One node in the office hierarchy
Has parent office, name, opening date
Head office has parent = null
Stored as a tree using Materialized Path pattern

OfficeTransaction.java

Inter-office money transfers (e.g., head office sends cash to branch for loan disbursements)
Creates accounting entries at both offices

Staff.java

A staff member assigned to an office
Loan officers are staff members linked to clients and their loans

Why Important

Every Client is assigned to an Office
Reports can be filtered by office/branch
Role-based access can be restricted to an officer's own office

Key Packages

javascript

QUBITS OF DPK

1fineract-branch/src/main/java/org/apache/fineract/organisation/
2├── office/   — Office.java, OfficeTransaction.java
3└── staff/    — Staff.java

5. fineract-report

What it is

The reporting and analytics module — generates financial reports, performance indicators, and data exports.

Layman Analogy

After the bank does all its operations, management needs dashboards and reports: How many loans are active? What's the total portfolio at risk? How much interest income was earned this month? fineract-report is the BI/reporting engine that answers all these questions.

Report Types

Pentaho Reports

.prpt files — visual reports generated by Pentaho Business Intelligence
Output: PDF, Excel, HTML
Accessed via GET /reports/{reportName}

Stretchy Reports (SQL-based)

Custom SQL queries stored in database (m_report table)
Parameterized — user provides date range, office, product filters
Output: JSON or CSV
Example: "Show all loans disbursed between X and Y date in office Z"

Scheduled Reports

Run automatically (daily, weekly, monthly) via scheduler
Sent by email or stored for download

Key Classes

ReportingProcessServiceImpl

Executes Stretchy Report SQL with dynamic parameter substitution
Returns data as JSON map

PentahoReportingProcessServiceImpl

Invokes Pentaho engine with .prpt file
Streams output (PDF bytes) to client

ElasticSearchReportingService (optional)

If ElasticSearch is configured, index loan/client data for fast full-text search

Key Packages

javascript

QUBITS OF DPK

1fineract-report/src/main/java/org/apache/fineract/infrastructure/report/
2├── service/  — ReportingProcessService
3└── provider/ — PentahoReportingProcessServiceImpl

6. fineract-working-capital-loan

What it is

A specialized loan product module for working capital loans — short-term business loans used to fund day-to-day operations.

Layman Analogy

A small business owner needs cash to buy inventory before the harvest season, then pays back after selling. This is a working capital loan — different from a home mortgage because it's short-term, the amount varies based on business needs, and repayment often comes from a future business event rather than fixed monthly salary.

What Makes Working Capital Loans Different

Revolving Credit: Client can borrow, repay, borrow again up to a limit
Usage-Based Interest: Interest only on amount actually drawn, not the full credit limit
Delinquency Buckets: Special classification for WC loan overdue amounts
Flexible Repayment: Tied to business cash flow cycles, not fixed dates

Key Contribution (FINERACT-2455)

This is the most recent work in the codebase (commit c3434d682):

Added Working Capital delinquency bucket configuration
New DTOs and field value handling for WC loans
E2E test scenarios for WC delinquency management

Key Packages

javascript

QUBITS OF DPK

1fineract-working-capital-loan/src/main/java/org/apache/fineract/
2├── portfolio/workingcapital/   — WC loan domain
3└── portfolio/delinquency/     — WC delinquency classification

1. fineract-investor

What it is

Layman Analogy

Key Concepts

Why This Matters for GSoC

Key Packages

2. fineract-cob

What it is

Layman Analogy

Architecture

Key Classes

COB in Tests

Key Packages

3. fineract-rates

What it is

Layman Analogy

Key Concepts

Scope

Key Packages

4. fineract-branch

What it is

Layman Analogy

Key Classes

Why Important

Key Packages

5. fineract-report

What it is

Layman Analogy

Report Types

Key Classes

Key Packages

6. fineract-working-capital-loan

What it is

Layman Analogy

What Makes Working Capital Loans Different

Key Contribution (FINERACT-2455)

Key Packages

Summary Table — Group C