Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

fineract-shares

— Full Codebase Explanation

Apache Fineract supports not only loans and savings but also

What This Module Is (Big Picture)

The shares module manages equity ownership in the financial institution.
Many microfinance systems operate as:
  • cooperatives
  • member-owned financial institutions
  • credit unions
In these systems, customers can buy shares in the institution.
This module manages:
  • share accounts
  • share purchases
  • share redemptions
  • dividend calculations
Layman
Imagine joining a cooperative bank.
Instead of only saving money, you can buy ownership shares in the bank.
Example:
  • Customer buys 100 shares
  • Each share is worth ₹100
  • Customer owns ₹10,000 equity in the institution
The fineract-shares module manages this ownership system.

Where the Code Lives

Key Package 1:

org.apache.fineract.portfolio.shareaccounts

This package contains the core share account domain logic.

The Main Entity:

ShareAccount.java

Path
java
QUBITS OF DPK
1fineract-shares/src/main/java/org/apache/fineract/portfolio/shareaccounts/domain/ShareAccount.java
This class represents a share account owned by a client or group.
Each share account tracks the ownership stake of a customer.

Key fields on

ShareAccount

Key methods inside

ShareAccount.java

java
QUBITS OF DPK
1public void purchaseShares(int shares) {
2    this.totalShares = this.totalShares + shares;
3}
4
5public void redeemShares(int shares) {
6    this.totalShares = this.totalShares - shares;
7}
8
9public BigDecimal calculateShareValue() {
10    return shareValue.multiply(BigDecimal.valueOf(totalShares));
11}
These methods represent:
  • purchasing shares
  • redeeming shares
  • calculating total share value

Share Account Lifecycle

java
QUBITS OF DPK
1Application
2    ↓
3Approved
4    ↓
5Active
6    ↓
7Share Purchases / Redemptions
8    ↓
9Closed
Customers may buy or redeem shares during the lifecycle.

DTO Layer:

ShareAccountData.java

Path
java
QUBITS OF DPK
1fineract-shares/src/main/java/org/apache/fineract/portfolio/shareaccounts/data/ShareAccountData.java
This DTO represents share account data returned through APIs.

Key fields

plain text
QUBITS OF DPK
1id
2clientId
3shareProductId
4totalShares
5shareValue
6status
7purchasedShares
8redeemedShares
This allows the UI to display:
  • total shares owned
  • share value
  • share transaction history

API Layer

ShareAccountsApiResource.java

Path
java
QUBITS OF DPK
1fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/api/ShareAccountsApiResource.java
This REST controller exposes share account operations.

Key endpoints

java
QUBITS OF DPK
1GET    /v1/shareaccounts
2GET    /v1/shareaccounts/{accountId}
3POST   /v1/shareaccounts
4POST   /v1/shareaccounts/{accountId}?command=approve
5POST   /v1/shareaccounts/{accountId}/shares?command=purchase
6POST   /v1/shareaccounts/{accountId}/shares?command=redeem
7POST   /v1/shareaccounts/{accountId}?command=close
These APIs allow:
  • creating share accounts
  • approving accounts
  • purchasing shares
  • redeeming shares
  • closing accounts

Read Services

ShareAccountReadPlatformService

Paths
java
QUBITS OF DPK
1fineract-shares/.../service/ShareAccountReadPlatformService.java
2fineract-provider/.../service/ShareAccountReadPlatformServiceImpl.java
This service retrieves share account information.

Key read operations

java
QUBITS OF DPK
1retrieveShareAccount(Long accountId)
2retrieveShareAccountsByClient(Long clientId)
3retrieveShareAccountTransactions(Long accountId)
4retrieveShareProductTemplate()
These queries return:
  • share account details
  • share ownership information
  • share transaction history

Write Services

ShareAccountWritePlatformService

Paths
java
QUBITS OF DPK
1fineract-provider/.../service/ShareAccountWritePlatformService.java
2fineract-provider/.../service/ShareAccountWritePlatformServiceJpaRepositoryImpl.java
Handles changes to share accounts.

Key write operations

java
QUBITS OF DPK
1createShareAccount(JsonCommand)
2approveShareAccount(Long accountId)
3purchaseShares(Long accountId, int shares)
4redeemShares(Long accountId, int shares)
5closeShareAccount(Long accountId)
These represent ownership transactions.

Dividend Calculation

Shareholders may receive dividends based on profits.
Example simplified logic:
java
QUBITS OF DPK
1public BigDecimal calculateDividend(int sharesOwned, BigDecimal dividendPerShare) {
2    return dividendPerShare.multiply(BigDecimal.valueOf(sharesOwned));
3}
Example:
  • dividend per share = ₹10
  • shares owned = 100
Dividend earned = ₹1000

Command Handlers

Path
java
QUBITS OF DPK
1fineract-provider/.../portfolio/shareaccounts/handler/
Key handlers include
java
QUBITS OF DPK
1CreateShareAccountCommandHandler
2ApproveShareAccountCommandHandler
3PurchaseSharesCommandHandler
4RedeemSharesCommandHandler
5CloseShareAccountCommandHandler
Each handler processes a specific share account command.

Repository and Data Access Layer

Exceptions

These prevent invalid share operations.

How It All Connects (Full Flow)

Example: Customer purchases shares
java
QUBITS OF DPK
1Mobile App / Admin UI
2        │ POST /v1/shareaccounts/{id}/shares?command=purchase
3        ▼
4ShareAccountsApiResource
5        ▼
6CommandProcessingService
7        ▼
8PurchaseSharesCommandHandler
9        ▼
10ShareAccountWritePlatformService
11        │ → Validate request
12        │ → Update share count
13        │ → Save transaction
14        ▼
15Database (share account tables)
16        ▼
17Response returned to UI

Why This Module Matters

The share module integrates with several systems.
Examples:
  • fineract-portfolio → links shares to clients
  • fineract-accounting → records equity transactions
  • fineract-reporting → calculates shareholder distributions

One-Sentence Summary

fineract-shares manages ownership shares in the financial institution, allowing clients to purchase, redeem, and track equity investments.