Cosmic Module

O

Qubits of DPK

March 20, 2026

Core Open Source
These modules handle how Fineract communicates with the outside world: auto-generated API clients, event streaming, document storage, loan origination, and global reporting standards.

1. fineract-client

What it is

An auto-generated Java client library that contains all the request/response model classes for the Fineract REST API.

Layman Analogy

When you build an app that talks to Fineract's REST API, you need Java classes to represent the JSON payloads. Instead of writing these by hand, Fineract uses OpenAPI Generator to automatically create them from the API spec. fineract-client is that auto-generated library.

How It's Generated

  1. #
    Fineract's source code has @Operation Swagger annotations
  2. #
    At build time, Gradle runs OpenAPI Generator
  3. #
    Generator reads the spec and produces Java classes in fineract-client/build/generated/
  4. #
    These classes are compiled and published as a library

What's Inside

javascript
QUBITS OF DPK
1fineract-client/build/generated/java/src/main/java/org/apache/fineract/client/
2├── models/     — ~400+ request/response POJO classes
3│   ├── PostClientsRequest.java
4│   ├── GetClientsClientIdResponse.java
5│   ├── PostLoansLoanIdRequest.java
6│   └── ... (every API payload)
7└── services/   — Retrofit interface definitions for each API group
8    ├── ClientApi.java  (or accessed via FineractClient.clients)
9    └── LoansApi.java

CRITICAL: Do Not Edit These Files!

  • All files in build/generated/ are regenerated on every build
  • Any manual edits will be lost
  • If you need to change a model, change the Swagger annotation in the source code and regenerate

Model Class Anatomy

java
QUBITS OF DPK
1public class PostClientsRequest {
2    @SerializedName("officeId")      // maps to JSON field name
3    private Long officeId;
4
5    @SerializedName("firstname")
6    private String firstname;
7
8    // Builder-style setters for chaining:
9    public PostClientsRequest officeId(Long officeId) {
10        this.officeId = officeId;
11        return this;  // allows .officeId(1L).firstname("John")
12    }
13    // ...getters, setters, equals, hashCode, toString
14}

Why This Matters for You (FINERACT-2441)

You're migrating tests to use these auto-generated client classes instead of raw HTTP calls — that's exactly the purpose of this module.

2. fineract-client-feign

What it is

The Feign HTTP client wrapper — provides a configured, ready-to-use FineractClient that integration tests and external apps use to call the Fineract API.

Layman Analogy

fineract-client gives you the models (the "vocabulary"). fineract-client-feign gives you the fully configured phone to make the call — it knows the server URL, handles authentication, serializes/deserializes JSON, and gives you typed method calls.

The FineractClient Object

java
QUBITS OF DPK
1FineractClient client = FineractClientHelper.getFineractClient();
2
3// Access any API via typed fields:
4client.clients          → ClientApi
5client.loans            → LoansApi
6client.jobs             → JobsApi
7client.jobsScheduler    → SchedulerJobApiApi
8client.savingsAccounts  → SavingsAccountApi
9// ...30+ more API groups

FineractClientHelper

java
QUBITS OF DPK
1// Located in integration-tests/common/
2public class FineractClientHelper {
3    public static FineractClient getFineractClient() {
4        return FineractClient.builder()
5            .baseURL("https://localhost:8443/fineract-provider/api/v1/")
6            .basicAuth("mifos", "password")
7            .tenant("default")
8            .build();
9    }
10}

Calls.ok() Utility

java
QUBITS OF DPK
1// In org.apache.fineract.client.util.Calls:
2public static <T> T ok(Call<T> call) {
3    Response<T> response = call.execute();
4    if (!response.isSuccessful()) {
5        throw new CallFailedRuntimeException(response);
6    }
7    return response.body();
8}
9
10// Usage:
11GetClientsClientIdResponse client = Calls.ok(
12    FineractClientHelper.getFineractClient().clients.retrieveOneClientById(1L, null)
13);

CallFailedRuntimeException

  • Thrown by Calls.ok() when HTTP response is not 2xx
  • Carries the full response: status code, headers, error body
  • Used in tests: assertThrows(CallFailedRuntimeException.class, () -> ...)

Under the Hood: Retrofit + OkHttp

javascript
QUBITS OF DPK
1Your test code
2  ↓ Calls.ok(client.clients.retrieveOneClientById(1L))
3  ↓ Retrofit converts method call to HTTP request
4  ↓ OkHttp sends HTTP GET to /clients/1
5  ↓ Gson deserializes JSON response to GetClientsClientIdResponse
6  ↓ Calls.ok() checks status and returns the object

3. fineract-avro-schemas

What it is

The Apache Avro schema definitions for Fineract's event streaming system — defines the structure of all business events published to message brokers (Kafka, ActiveMQ).

Layman Analogy

When Fineract does something important (a loan is disbursed, a client is created), it broadcasts a message to other systems. Avro is the format of those messages — like a standardized form that all systems agree on. fineract-avro-schemas is the collection of all these form templates.

What is Apache Avro?

  • A data serialization format (like JSON but binary, faster, smaller)
  • Schema-first: you define the schema .avsc file, then generate Java classes
  • Self-describing: the schema travels with the data

Schema Files

javascript
QUBITS OF DPK
1fineract-avro-schemas/src/main/avro/
2├── LoanTransactionDataV1.avsc    — loan payment event
3├── ClientDataV1.avsc             — client created/updated event
4├── SavingsTransactionDataV1.avsc — savings deposit/withdrawal event
5└── ... (one schema per business event type)

Why Avro Instead of JSON?

Event Flow

javascript
QUBITS OF DPK
1Loan repayment saved
2  ↓
3LoanTransactionMadeBusinessEvent published in-process
4  ↓
5Avro serializer converts to binary using LoanTransactionDataV1 schema
6  ↓
7Published to Kafka topic: fineract.loan.transaction.made
8  ↓
9External systems (analytics, SMS gateway, notification service) consume

External Events Configuration

  • Feature flag: fineract.events.external.enabled=true
  • Configure Kafka broker URL in application properties
  • Each event type can be individually enabled/disabled

4. fineract-document

What it is

The document management module — handles uploading, storing, and retrieving files attached to Fineract entities (clients, loans, etc.).

Layman Analogy

When a loan officer processes a loan application, they need to scan and upload the borrower's ID, income proof, and application form. fineract-document is like the digital filing cabinet where all these documents are stored and linked to the right client or loan.

Supported Storage Backends

  • Local filesystem: Files stored on the server disk
  • Amazon S3: Files stored in cloud object storage
  • Azure Blob Storage: Microsoft cloud storage

Key Classes

DocumentManagementService
  • saveDocument(entityType, entityId, inputStream, name, description) — stores a file
  • retrieveDocument(entityType, entityId, documentId) — fetches file bytes
Document.java
  • JPA entity: name, description, fileName, type, entityType (CLIENT/LOAN), entityId, storageLocation
Configurable Storage
java
QUBITS OF DPK
1@ConditionalOnProperty(name = "fineract.content.filesystem.enabled", havingValue = "true")
2public class FileSystemContentRepository implements ContentRepository
3
4@ConditionalOnProperty(name = "fineract.content.s3.enabled", havingValue = "true")
5public class S3ContentRepository implements ContentRepository

Key Packages

javascript
QUBITS OF DPK
1fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/
2├── domain/       — Document.java
3├── service/      — DocumentManagementService
4└── contentrepository/ — Filesystem, S3, Azure implementations

5. fineract-loan-origination

What it is

The loan origination process module — manages the early stages of loan processing before the loan is formally submitted: credit scoring, eligibility checks, pre-screening.

Layman Analogy

Before a bank even creates a loan application in its system, it might want to check: Does this person qualify? What credit limit should we offer? What's the risk rating? fineract-loan-origination handles this pre-loan decision-making phase.

Key Concepts

Loan Decision Engine
  • Rule-based evaluation of applicant data
  • Outputs: approve/decline recommendation, suggested amount, risk grade
Credit Score Integration
  • Hook points for external credit bureau calls
  • Score stored with the application for audit trail
Origination Workflow
  • Multi-stage process: application → credit check → committee review → approval
  • Each stage can be assigned to different staff roles

Note on Maturity

This module is newer and less complete than the core loan module. It represents the direction Fineract is heading — a full end-to-end loan origination platform, not just loan servicing.

6. fineract-mix

What it is

The MIX Market reporting module — generates standardized reports for the Microfinance Information eXchange (MIX), a global platform where MFIs report their performance data.

Layman Analogy

Just like publicly listed companies must file quarterly reports with SEC, MFIs that are members of MIX Market must submit standardized financial performance reports. fineract-mix automates this reporting — it pulls data from the system and formats it exactly as MIX requires.

What is MIX Market?

  • Global data platform for microfinance performance data
  • MFIs report: number of active borrowers, loan portfolio size, operating costs, financial ratios
  • Investors and donors use this data to evaluate MFIs

Key Classes

MixTaxonomyMapping
  • Maps internal Fineract GL accounts to MIX taxonomy fields
  • Example: Fineract "Loans Receivable" → MIX taxonomy field "Gross Loan Portfolio"
XBRLReport
  • Output format: XBRL (eXtensible Business Reporting Language) — the standard for financial data exchange
  • Fineract generates XBRL XML files that can be submitted directly to MIX
MixReportWritePlatformService
  • Orchestrates the report generation
  • Queries financial data, applies taxonomy mapping, outputs XBRL

Key Packages

javascript
QUBITS OF DPK
1fineract-mix/src/main/java/org/apache/fineract/mix/
2├── domain/    — MixTaxonomy, XBRLReport
3├── service/   — MixReportWritePlatformService
4└── api/       — XBRLApiResource

Summary Table — Group D