Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

What This Module Is (Big Picture)

The survey module manages questionnaires used to collect structured information from customers.
Financial institutions often collect information beyond basic customer data. For example:
  • household income
  • employment details
  • financial literacy
  • risk profile
  • social impact indicators
Surveys allow the system to collect this information in a structured way.

Layman Example

A microfinance institution wants to evaluate the financial health of borrowers.
They create a survey with questions such as:
Loan officers ask these questions during client onboarding.
The responses are stored in the system.
The fineract-survey module manages these questionnaires and responses.

Where the Code Lives

Key Package

org.apache.fineract.infrastructure.survey
Responsibilities include:
  • defining surveys
  • defining survey questions
  • recording survey responses
  • calculating survey scores

Core Domain Entity:

Survey.java

Path
fineract-survey/src/main/java/org/apache/fineract/infrastructure/survey/domain/Survey.java
This entity represents a survey definition.

Key fields on

Survey

Survey Questions

Surveys contain multiple questions.
Each question collects a specific piece of information.
Examples
These questions are stored in a separate entity.

Core Entity:

SurveyQuestion.java

Path
fineract-survey/src/main/java/org/apache/fineract/infrastructure/survey/domain/SurveyQuestion.java
This entity represents a question within a survey.

Key fields on

SurveyQuestion

Survey Responses

When a survey is conducted, responses are stored.
Example
Survey: Financial Health Survey
These responses are stored and linked to the client.

Example Response Storage Code

plain text
QUBITS OF DPK
1public void recordResponse(Long surveyId, Long questionId, String answer) {
2
3    SurveyResponse response = new SurveyResponse();
4
5    response.setSurveyId(surveyId);
6    response.setQuestionId(questionId);
7    response.setAnswer(answer);
8
9    surveyResponseRepository.save(response);
10}
This records a response for a survey question.

Survey Scoring

Some surveys calculate scores based on answers.
Example
Financial Health Score:
Total score determines the client’s risk level.

API Layer

Main controller
SurveyApiResource
Example endpoints
plain text
QUBITS OF DPK
1GET  /v1/surveys
2POST /v1/surveys
3GET  /v1/surveys/{surveyId}
4POST /v1/surveys/{surveyId}/responses
These APIs allow administrators to:
  • create surveys
  • retrieve surveys
  • submit responses
  • retrieve survey results

Read Services

Read services retrieve survey information.
Examples include:
  • retrieving survey definitions
  • retrieving survey questions
  • retrieving client survey responses
These services help display surveys and results.

Write Services

Write services manage survey operations.
Responsibilities include:
  • creating surveys
  • adding questions
  • recording responses
  • calculating survey scores

Repository Layer

Exceptions

These ensure survey data remains valid.

How It All Connects (Full Flow)

Example: Loan officer conducting a survey
plain text
QUBITS OF DPK
1Loan Officer
2    │ Conduct survey
3    ▼
4SurveyApiResource
5    ▼
6SurveyService
7    │ Store responses
8    ▼
9Database (survey tables)
10    ▼
11Survey score calculated

Why This Module Matters

Surveys help institutions:
  • evaluate borrower risk
  • collect socio-economic data
  • measure financial inclusion impact
They are widely used in microfinance and social lending programs.

One-Sentence Summary

fineract-survey manages questionnaires used to collect structured information from clients and store their responses for analysis and scoring.