Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

fineract-group

— Full Codebase Explanation

What is Apache Fineract?
Apache Fineract is open-source core banking software used by microfinance institutions and digital lenders. It manages customers, branches, financial products, loans, savings accounts, and transactions.

What This Module Is (Big Picture)

The group layer models microfinance borrower groups.
Many microfinance institutions do not lend only to individuals.
Instead, they lend to groups of borrowers who share responsibility for repayment.
This module manages:
  • borrower groups
  • membership relationships
  • group lifecycle
  • group hierarchy under centers and offices
Layman:
Imagine a village microfinance program. Instead of lending to one person, the bank lends to a self-help group of 10 people. The group guarantees repayment collectively.
fineract-group is the system that manages these groups.
If fineract-portfolio manages individual clients, then fineract-group manages collections of clients that borrow together.

Where the Code Lives

Group functionality is distributed across multiple modules.
Layman:
Think of it like a department in a company.
  • fineract-group → the department label
  • fineract-core → the rulebook and data definitions
  • fineract-provider → the employees doing the work

Key Package 1:

org.apache.fineract.portfolio.group

This is the main package responsible for borrower group management.

The Main Entity:

Group.java

Path:
plain text
QUBITS OF DPK
1fineract-core/src/main/java/org/apache/fineract/portfolio/group/domain/Group.java
This is the main JPA entity representing a borrower group.
Layman — JPA entity:
Think of this like one row in the bank’s
Each Group object represents a real borrower group in the system.

Key fields on

Group

Key methods on

Group.java

java
QUBITS OF DPK
1createNew(...)
2activate(...)
3close(...)
4update(...)
5addClient(...)
6removeClient(...)
Layman explanation:
These methods represent real-world group actions:
  • creating a group
  • activating it
  • updating group information
  • adding or removing members
It is similar to managing a team roster in a company system.

The Important Idea: Group Lending

Group lending is a major concept in microfinance.
Example structure:
plain text
QUBITS OF DPK
1Office
2   │
3   └── Center
4          │
5          └── Group
6                 │
7                 ├── Client A
8                 ├── Client B
9                 ├── Client C
Instead of giving loans individually, the bank may lend to the entire group.
Layman:
If one member struggles to repay, the group encourages repayment because everyone’s reputation is linked.

DTO Layer:

GroupData.java

Path
java
QUBITS OF DPK
1fineract-core/src/main/java/org/apache/fineract/portfolio/group/data/GroupData.java
This is the Data Transfer Object (DTO) used when sending group data to APIs or UI.
Layman — DTO:
Instead of sending the raw database object, the system sends a

Key fields in

GroupData

java
QUBITS OF DPK
1id
2name
3officeId
4officeName
5centerId
6centerName
7status
8activationDate
9clientMembers
Layman:
This is like the summary view of a group profile page.

Key Package 2: API Layer

GroupsApiResource.java

Path
java
QUBITS OF DPK
1fineract-provider/src/main/java/org/apache/fineract/portfolio/group/api/GroupsApiResource.java
This class is the REST controller for group operations.
Layman — REST controller:
When a frontend or admin panel asks the system about groups, this class receives the request.

Key endpoints

java
QUBITS OF DPK
1GET    /v1/groups                 -> List groups
2GET    /v1/groups/{groupId}       -> Retrieve group
3POST   /v1/groups                 -> Create group
4PUT    /v1/groups/{groupId}       -> Update group
5POST   /v1/groups/{groupId}/activate -> Activate group
6POST   /v1/groups/{groupId}/close -> Close group
Layman:
This API allows the bank’s system to:
  • create borrower groups
  • view group details
  • activate groups
  • update group information

Key Package 3: Read Services

GroupReadPlatformService

Paths
java
QUBITS OF DPK
1fineract-core/.../service/GroupReadPlatformService.java
2fineract-provider/.../service/GroupReadPlatformServiceImpl.java
This service handles read operations.
Layman:
It retrieves information about groups from the database.

Key read operations

java
QUBITS OF DPK
1retrieveAllGroups()
2retrieveGroup(groupId)
3retrieveGroupsByOffice()
4retrieveGroupMembers()
5retrieveGroupTemplate()

Important behavior

Group queries often filter results based on office hierarchy.
This ensures that:
  • branch managers only see groups from their branch
  • regional managers see groups from their region

Key Package 4: Write Services

GroupWritePlatformService

Paths
java
QUBITS OF DPK
1fineract-provider/.../service/GroupWritePlatformService.java
2fineract-provider/.../service/GroupWritePlatformServiceJpaRepositoryImpl.java
This service handles group creation and updates.

Key write operations

java
QUBITS OF DPK
1createGroup(JsonCommand)
2updateGroup(groupId, JsonCommand)
3activateGroup(groupId)
4closeGroup(groupId)
5addClientToGroup(...)
6removeClientFromGroup(...)

Important behavior inside the write service

Before performing operations, the system validates:
  • user permissions
  • group status
  • office hierarchy
Layman:
A branch manager cannot modify groups belonging to another branch.

Command Handlers

Path
plain text
QUBITS OF DPK
1fineract-provider/.../portfolio/group/handler/
Key handlers include:
plain text
QUBITS OF DPK
1CreateGroupCommandHandler.java
2UpdateGroupCommandHandler.java
3ActivateGroupCommandHandler.java
4CloseGroupCommandHandler.java
Layman — Command pattern:
Each action is handled by a separate class to keep the system modular and easy to maintain.

Validators / Deserializers

GroupCommandFromApiJsonDeserializer.java

Validates API input when creating or updating groups.
Fields validated include:
plain text
QUBITS OF DPK
1name
2officeId
3centerId
4activationDate
5externalId
Rules include:
  • group name cannot be empty
  • office must exist
  • activation date must be valid
Layman:
Before creating a group, the system checks the form data for errors.

Repository and Data Access Layer

Exceptions

Group-related errors include:
Layman:
These prevent invalid operations like modifying non-existent groups.

How It All Connects (Full Flow)

Example: Creating a new borrower group.
plain text
QUBITS OF DPK
1Admin UI
2   │ POST /v1/groups
3   ▼
4GroupsApiResource
5   │
6   ▼
7CommandProcessingService
8   │
9   ▼
10CreateGroupCommandHandler
11   │
12   ▼
13GroupWritePlatformServiceJpaRepositoryImpl
14   │ → Validate input
15   │ → Check office permissions
16   │ → Create Group entity
17   │ → Save group
18   ▼
19Database (m_group table)
20   │
21   ▼
22Response returned to Admin UI
Layman:
The system checks your form, verifies your permissions, creates the group record, saves it in the database, and returns the group ID.

Why This Module Matters to the Rest of Fineract

Many other modules depend on group data.
Examples:
  • Loans may be issued to groups
  • Savings accounts may belong to groups
  • Reporting may aggregate group activity
Layman:
Groups are a core part of

One-Sentence Layman Summary

fineract-group manages borrower groups and their membership relationships, enabling Fineract to support group-based microfinance lending models.