Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

Relevance to Your Proposal 2

FINERACT-2485 (Transaction Idempotency) specifically targets the Savings module transaction APIs. The idempotency gaps are most visible here — a customer retrying a withdrawal on unstable network could be double-debited. This is exactly the problem your proposal fixes.

fineract-savings

— Full Codebase Explanation

Apache Fineract is open-source

What This Module Is (Big Picture)

The savings module manages deposit accounts.
Unlike loans where money flows from bank → customer, savings accounts represent money flowing from customer → bank.
This module manages:
  • opening savings accounts
  • deposits
  • withdrawals
  • interest calculation
  • balance tracking
  • account closure
Layman
If a customer opens a savings account, the bank must:
  1. #
    Create an account record
  2. #
    Accept deposits
  3. #
    Allow withdrawals
  4. #
    Calculate interest
  5. #
    Maintain account balance
The fineract-savings module automates these operations.

Where the Code Lives

Layman
  • fineract-savings = savings department
  • fineract-core = financial utilities
  • fineract-provider = operational services
  • fineract-accounting = ledger system

Key Package 1:

org.apache.fineract.portfolio.savings

This package contains the core savings account domain logic.

The Main Entity:

SavingsAccount.java

Path
plain text
QUBITS OF DPK
1fineract-savings/src/main/java/org/apache/fineract/portfolio/savings/domain/SavingsAccount.java
This class represents a savings account owned by a customer or group.
Each SavingsAccount object corresponds to one real savings account in the bank.

Key fields on

SavingsAccount

Key methods inside

SavingsAccount.java

plain text
QUBITS OF DPK
1public void activate(LocalDate activationDate) {
2    this.status = SavingsAccountStatus.ACTIVE;
3}
4
5public void deposit(BigDecimal amount) {
6    this.balance = this.balance.add(amount);
7}
8
9public void withdraw(BigDecimal amount) {
10    this.balance = this.balance.subtract(amount);
11}
12
13public void close() {
14    this.status = SavingsAccountStatus.CLOSED;
15}
These methods represent basic banking actions:
  • activate account
  • deposit money
  • withdraw money
  • close account

Savings Account Lifecycle

plain text
QUBITS OF DPK
1Account Application
2       ↓
3Pending Approval
4       ↓
5Approved
6       ↓
7Active
8       ↓
9Transactions (Deposits / Withdrawals)
10       ↓
11Closed
Savings accounts move through different lifecycle states during their operation.

DTO Layer:

SavingsAccountData.java

Path
plain text
QUBITS OF DPK
1fineract-savings/src/main/java/org/apache/fineract/portfolio/savings/data/SavingsAccountData.java
This DTO represents savings account data returned by APIs.

Key fields

plain text
QUBITS OF DPK
1id
2clientId
3productId
4balance
5interestRate
6status
7activationDate
8transactions
These fields allow the UI to display:
  • account details
  • balance
  • transaction history

API Layer

SavingsAccountsApiResource.java

Path
plain text
QUBITS OF DPK
1fineract-provider/src/main/java/org/apache/fineract/portfolio/savings/api/SavingsAccountsApiResource.java
This is the REST controller for savings account operations.

Key endpoints

plain text
QUBITS OF DPK
1GET    /v1/savingsaccounts
2GET    /v1/savingsaccounts/{accountId}
3POST   /v1/savingsaccounts
4POST   /v1/savingsaccounts/{accountId}?command=activate
5POST   /v1/savingsaccounts/{accountId}/transactions?command=deposit
6POST   /v1/savingsaccounts/{accountId}/transactions?command=withdraw
7POST   /v1/savingsaccounts/{accountId}?command=close
These endpoints allow the system to:
  • create accounts
  • activate accounts
  • deposit money
  • withdraw money
  • close accounts

Read Services

SavingsAccountReadPlatformService

Paths
plain text
QUBITS OF DPK
1fineract-savings/.../service/SavingsAccountReadPlatformService.java
2fineract-provider/.../service/SavingsAccountReadPlatformServiceImpl.java
This service retrieves savings account information.

Key read operations

plain text
QUBITS OF DPK
1retrieveSavingsAccount(Long accountId)
2retrieveSavingsAccountsByClient(Long clientId)
3retrieveSavingsAccountTransactions(Long accountId)
4retrieveSavingsAccountTemplate()
These methods retrieve:
  • account details
  • transaction history
  • template information for creating accounts

Write Services

SavingsAccountWritePlatformService

Paths
plain text
QUBITS OF DPK
1fineract-provider/.../service/SavingsAccountWritePlatformService.java
2fineract-provider/.../service/SavingsAccountWritePlatformServiceJpaRepositoryImpl.java
Handles account changes and transactions.

Key write operations

plain text
QUBITS OF DPK
1createSavingsAccount(JsonCommand)
2activateSavingsAccount(Long accountId)
3deposit(Long accountId, BigDecimal amount)
4withdraw(Long accountId, BigDecimal amount)
5closeSavingsAccount(Long accountId)
These represent real operations performed on savings accounts.

Interest Calculation

Example simplified interest calculation:
plain text
QUBITS OF DPK
1public BigDecimal calculateInterest(BigDecimal balance, BigDecimal interestRate) {
2
3    BigDecimal interest = balance.multiply(interestRate)
4                                 .divide(BigDecimal.valueOf(100));
5
6    return interest;
7}
If a customer has ₹10,000 with a 5% interest rate, the interest calculation would produce ₹500 annually.

Command Handlers

Path
plain text
QUBITS OF DPK
1fineract-provider/.../portfolio/savings/handler/
Key handlers include
plain text
QUBITS OF DPK
1CreateSavingsAccountCommandHandler
2ActivateSavingsAccountCommandHandler
3DepositSavingsAccountCommandHandler
4WithdrawSavingsAccountCommandHandler
5CloseSavingsAccountCommandHandler
Each handler processes a specific savings account operation.

Repository and Data Access Layer

Exceptions

These exceptions prevent invalid financial operations.

How It All Connects (Full Flow)

Example: Customer deposits money
plain text
QUBITS OF DPK
1Mobile App / Admin UI
2        │ POST /v1/savingsaccounts/{id}/transactions?command=deposit
3        ▼
4SavingsAccountsApiResource
5        ▼
6CommandProcessingService
7        ▼
8DepositSavingsAccountCommandHandler
9        ▼
10SavingsAccountWritePlatformService
11        │ → Validate transaction
12        │ → Update account balance
13        │ → Save transaction
14        ▼
15Database
16        ▼
17Response returned to UI

Why This Module Matters

Savings accounts interact with several modules.
Examples:
  • fineract-portfolio → connects savings accounts to clients
  • fineract-branch → accounts belong to branches
  • fineract-accounting → deposits recorded in general ledger
  • fineract-reporting → generates account reports

One-Sentence Summary

fineract-savings manages deposit accounts, including account creation, deposits, withdrawals, interest calculation, and balance tracking.