Cosmic Module

O

Qubits of DPK

March 20, 2026

Core Open Source
These 6 modules are the heart of Fineract — they implement the actual financial products that microfinance institutions offer to their clients.

1. fineract-loan

What it is

The main loan engine of Fineract. This is the biggest and most complex module in the entire codebase — it handles everything about lending money to customers.

Layman Analogy

Think of this as the entire brain of a bank's lending department. When someone walks in, asks for a loan, gets approved, receives the money, makes repayments, gets charged late fees — every single step is managed here.

Key Packages

  • fineract-loan/src/main/java/org/apache/fineract/portfolio/loanaccount/ — Core loan domain
  • fineract-loan/src/main/java/org/apache/fineract/portfolio/loanproduct/ — Loan product templates
  • fineract-loan/src/main/java/org/apache/fineract/portfolio/loanaccount/service/ — Business logic

Core Classes

Loan.java (the most important class in Fineract)
  • A JPA entity representing a single loan account
  • Has ~100+ fields: principal, interest rate, repayment schedule, status, transactions, charges
  • State machine with statuses: SUBMITTED_AND_PENDING_APPROVAL → APPROVED → ACTIVE → CLOSED
  • Every action (disburse, repay, waive) is a method on this class
LoanProduct.java
  • A template defining loan rules: max amount, interest type, repayment frequency, grace periods
  • Think of it as a "product catalog item" — e.g. "30-day personal loan at 5% monthly"
  • Multiple loan accounts can be created from one product
LoanTransaction.java
  • Each money movement on a loan: disbursement, repayment, fee charge, write-off
  • Immutable once created — reversals create new transactions with reversed = true
  • Linked to an accounting journal entry
LoanRepaymentScheduleInstallment.java
  • One row in the repayment schedule (e.g., "Pay $100 on March 1st")
  • Tracks what's due, what's paid, outstanding balance per component (principal, interest, fees, penalties)

Loan Lifecycle Flow

javascript
QUBITS OF DPK
1[Client applies] → LoanApplicationWritePlatformServiceJpaRepositoryImpl.submitLoanApplication()
2      ↓
3[Officer approves] → approveLoanApplication()
4      ↓
5[Money sent] → disburseLoan() → creates LoanTransaction(DISBURSEMENT)
6      ↓
7[Client pays] → makeLoanRepayment() → creates LoanTransaction(REPAYMENT)
8      ↓ (multiple repayments over time)
9[Loan paid off] → status changes to CLOSED

Interest Types Supported

  • Flat: Same interest every period regardless of outstanding balance
  • Declining Balance: Interest recalculated on reducing principal (most common)
  • EMI (Equal Monthly Installment): Fixed payment amount throughout

Why It's So Complex

  • Must handle partial payments, overpayments, underpayments
  • Configurable allocation order (e.g., pay fees first, then interest, then principal)
  • Backdated transactions that recalculate everything retroactively
  • Interest recalculation on prepayment
  • Grace periods (no payment required for first N periods)
  • Multiple charge types applied at different points in lifecycle

2. fineract-progressive-loan

What it is

An enhanced loan calculation engine that implements advanced amortization schedules — specifically for loans where equal installments are required with proper principal/interest splitting.

Layman Analogy

If fineract-loan is a basic calculator, fineract-progressive-loan is a financial calculator with advanced amortization tables. When you take a mortgage or car loan and see a table showing exactly how much goes to principal vs interest each month — that's progressive loan calculation.

Key Concept: EMI Amortization

For a $10,000 loan at 10% annual interest for 12 months:
  • Month 1: Pay $879 total → $83 interest + $796 principal
  • Month 2: Pay $879 total → $76 interest + $803 principal
  • Month 12: Pay $879 total → $7 interest + $872 principal
The total payment is the same every month, but the split changes.

Key Packages

  • fineract-progressive-loan/src/main/java/org/apache/fineract/portfolio/loanaccount/loanschedule/ — Schedule calculation

Core Classes

ProgressiveLoanInterestScheduleModel
  • Holds the complete amortization model for a loan
  • Calculates EMI using the standard financial formula
  • Handles edge cases: odd days, interest rate changes, prepayments
EMICalculator
  • The math engine that computes Equal Monthly Installment
  • Formula: EMI = P × r × (1+r)^n / ((1+r)^n - 1) where P=principal, r=monthly rate, n=periods

Why Separate from fineract-loan?

  • Progressive loan has its own schedule generation strategy (PROGRESSIVE enum value)
  • Allows fineract-loan to use it as a pluggable strategy without coupling
  • Supports dynamic interest rate changes mid-loan (variable rate mortgages)

3. fineract-savings

What it is

The savings account engine — manages deposit accounts where clients store money and earn interest.

Layman Analogy

This is the savings bank side of Fineract. Just as fineract-loan handles borrowing money, fineract-savings handles saving money — deposits, withdrawals, interest accrual, fixed deposits.

Key Packages

  • fineract-savings/src/main/java/org/apache/fineract/portfolio/savings/ — Core savings domain
  • fineract-savings/src/main/java/org/apache/fineract/portfolio/savings/domain/ — JPA entities
  • fineract-savings/src/main/java/org/apache/fineract/portfolio/savings/service/ — Business logic

Core Classes

SavingsAccount.java
  • JPA entity for one savings account
  • Status: SUBMITTED → APPROVED → ACTIVE → CLOSED
  • Tracks running balance, interest accrued, transactions
SavingsAccountTransaction.java
  • Each money movement: deposit, withdrawal, interest posting, fee charge, annual fee
  • Immutable — reversals create new reversed=true transactions
FixedDepositAccount.java (extends SavingsAccount)
  • Term deposits — money locked for a fixed period at a guaranteed interest rate
  • Premature closure is allowed but with penalty
RecurringDepositAccount.java (extends SavingsAccount)
  • Regular installment savings — client commits to depositing a fixed amount each period
  • Similar to recurring investment plans (RD accounts in Indian banking)

Savings Products

Just like loan products, savings products are templates:
  • Minimum opening balance
  • Interest rate and compounding period (daily, monthly, quarterly)
  • Withdrawal limits
  • Dormancy thresholds

Interest Calculation Flow

javascript
QUBITS OF DPK
1COB Job runs nightly:
2  → PostInterestAsOnDateScheduledJob
3  → SavingsAccountInterestPostingService
4  → Calculates daily average balance
5  → Posts interest transaction
6  → Updates account balance

4. fineract-charge

What it is

The fee and penalty management module — defines and applies all types of charges to loans and savings accounts.

Layman Analogy

If loans and savings accounts are cars, charges are all the fees on your car bill: loan origination fee, late payment penalty, monthly service fee, annual fee, prepayment penalty. This module defines all of them and knows when and how to apply them.

Key Packages

  • fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/ — Charge definitions

Core Classes

Charge.java
  • Master charge template: name, amount/percentage, applies-to (loan/savings), when it applies
  • Examples: "Late Payment Penalty: 2% of outstanding", "Origination Fee: $50 flat"
LoanCharge.java
  • Instance of a Charge applied to a specific loan
  • Tracks due amount, paid amount, waived amount
  • Can be applied: at disbursement, on specific date, on installment due date, on overdue
SavingsAccountCharge.java
  • Instance of a Charge applied to a savings account
  • Monthly maintenance fee, annual fee, withdrawal fee

Charge Calculation Types

When Charges Fire

  • Disbursement: Deducted from loan amount when money is sent
  • Specified Due Date: Fixed calendar date
  • Installment Fee: Added to each repayment installment
  • Overdue: Applied when payment is late (penalty)
  • Annual Fee: Yearly charge on savings accounts

5. fineract-tax

What it is

The tax calculation module — computes and records taxes (like GST, VAT) that apply to charges and interest.

Layman Analogy

When a bank charges you a service fee, the government might require the bank to collect 18% GST on top of that fee. fineract-tax is the module that knows the tax rules and automatically adds the right tax amount when charges are applied.

Key Packages

  • fineract-tax/src/main/java/org/apache/fineract/portfolio/tax/ — Tax group definitions

Core Classes

TaxGroup.java
  • A named collection of tax components: e.g., "Standard GST Group" = 9% CGST + 9% SGST
  • Assigned to a Charge definition
TaxComponent.java
  • One tax: name, percentage, effective from/to dates (rates can change)
  • When a charge is applied, each TaxComponent in the group fires
TaxGroupMappings.java
  • Links a TaxComponent to a TaxGroup
  • A TaxGroup can contain multiple components (central + state tax)

How Tax Works End-to-End

javascript
QUBITS OF DPK
1Charge applied (e.g., $100 origination fee)
2  ↓
3fineract-charge calculates: $100
4  ↓
5fineract-tax checks: this charge has TaxGroup "GST18"
6  ↓
7Tax = 18% of $100 = $18
8  ↓
9Total deducted from disbursement: $100 + $18 = $118
10  ↓
11Accounting journal: debit client $118, credit fee income $100, credit tax payable $18

Why Separate Module?

  • Tax rules change (rate changes, new taxes, exemptions)
  • Not all MFIs operate in countries with transaction taxes
  • Separation means you can add/remove tax without touching charge logic

6. fineract-accounting

What it is

The double-entry bookkeeping module — automatically creates accounting journal entries for every financial transaction.

Layman Analogy

Every time money moves in a bank, an accountant writes it down in two places (double-entry): one debit and one credit that must balance. fineract-accounting is the robot accountant that does this automatically whenever a loan is disbursed, repaid, a fee is charged, or interest is posted.

Key Packages

  • fineract-accounting/src/main/java/org/apache/fineract/accounting/journalentry/ — Journal entries
  • fineract-accounting/src/main/java/org/apache/fineract/accounting/glaccount/ — Chart of accounts
  • fineract-accounting/src/main/java/org/apache/fineract/accounting/producttoaccountmapping/ — Product mappings

Core Classes

GLAccount.java (General Ledger Account)
  • One account in the chart of accounts: Assets, Liabilities, Income, Expenses, Equity
  • Example accounts: "Loans Receivable" (Asset), "Interest Income" (Income), "Deposits" (Liability)
JournalEntry.java
  • One debit or credit entry: account, amount, date, reference
  • Always created in pairs (debit + credit)
ProductToGLAccountMapping.java
  • Maps a loan/savings product to specific GL accounts
  • Example: "Product A disbursements → debit 'Loans Receivable' account #1001"
AccountingProcessorHelper.java
  • The core helper that creates journal entries for different transaction types
  • Called by loan and savings event listeners (BusinessEvent subscribers)

Double-Entry Example

When a $1,000 loan is disbursed:
javascript
QUBITS OF DPK
1DEBIT:  Loans Receivable (Asset)    $1,000  ← bank is owed money now
2CREDIT: Cash/Bank Account (Asset)   $1,000  ← bank paid out cash
When client pays $100 repayment ($80 principal + $20 interest):
javascript
QUBITS OF DPK
1DEBIT:  Cash/Bank Account           $100  ← bank received cash
2CREDIT: Loans Receivable (Asset)    $80   ← loan balance reduced
3CREDIT: Interest Income (Income)    $20   ← interest earned

Accounting Rules Types

  • Cash Basis: Record income when cash is received
  • Accrual Basis: Record income when it's earned (even before cash received)
  • Periodic Accrual: Accrue daily via COB job, post monthly
  • Upfront Accrual: Post all future income immediately at disbursement

Accounting is Event-Driven

javascript
QUBITS OF DPK
1LoanTransaction saved
2  ↓
3BusinessEvent published: LoanTransactionMadeEvent
4  ↓
5LoanAccountingProcessorService.onLoanTransactionMade(event)
6  ↓
7AccountingProcessorHelper.createJournalEntries()
8  ↓
9GL entries written to m_journal_entry table

Summary Table — Group B