Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

What This Module Is (Big Picture)

The document module manages files uploaded into the banking system.
Financial institutions often require supporting documents for operations such as:
  • loan applications
  • client verification
  • identity validation
  • collateral documentation
This module allows the system to:
  • upload documents
  • store document metadata
  • attach documents to entities
  • retrieve or delete documents
Entities that may have documents include:
  • clients
  • loans
  • groups
  • offices
  • accounts

Layman Example

A customer applies for a loan.
The bank requires the following documents:
  • ID proof
  • address proof
  • income statement
The documents are uploaded into the system and attached to the loan or client record.
The fineract-document module manages this file storage and linking.

Where the Code Lives

Key Package

org.apache.fineract.infrastructure.document
Responsibilities include:
  • uploading files
  • storing document metadata
  • linking documents to entities
  • retrieving and deleting documents

Core Domain Entity:

Document.java

Path
fineract-document/src/main/java/org/apache/fineract/infrastructure/document/domain/Document.java
This entity represents a document stored in the system.

Key fields on

Document

Document Storage Model

Documents consist of two parts:
  1. #
    File storage
  2. #
    Document metadata
Example
This separation allows the system to manage documents efficiently.

Example Document Upload Code

plain text
QUBITS OF DPK
1public Document uploadDocument(String fileName,
2                               String entityType,
3                               Long entityId) {
4
5    Document document = new Document();
6    document.setFileName(fileName);
7    document.setEntityType(entityType);
8    document.setEntityId(entityId);
9
10    return documentRepository.save(document);
11}
This method creates a document record and links it to an entity.

Linking Documents to Entities

Documents can be attached to multiple entity types.
Examples
This is handled through:
entityType
entityId

API Layer

Main controller
DocumentsApiResource
Example endpoints
plain text
QUBITS OF DPK
1GET  /v1/documents
2POST /v1/documents
3GET  /v1/{entityType}/{entityId}/documents
4POST /v1/{entityType}/{entityId}/documents
5DELETE /v1/documents/{documentId}
These APIs allow administrators to:
  • upload documents
  • retrieve documents
  • delete documents
  • list documents linked to entities

Read Services

Read services retrieve document information.
Examples include:
  • retrieving documents for an entity
  • retrieving document metadata
  • retrieving document file paths
These services are used when users view document attachments.

Write Services

Write services manage document uploads and updates.
Responsibilities include:
  • uploading documents
  • attaching documents to entities
  • deleting documents
  • updating document metadata

Repository Layer

Exceptions

These ensure document operations remain valid.

How It All Connects (Full Flow)

Example: Uploading a client document
plain text
QUBITS OF DPK
1Admin UI
2    │ Upload document
3    ▼
4DocumentsApiResource
5    ▼
6DocumentService
7    │ Save file
8    │ Create metadata
9    ▼
10Database (document table)
11    │ File stored on disk/cloud

Why This Module Matters

The document module helps financial institutions:
  • maintain compliance records
  • store customer verification documents
  • manage loan paperwork
  • keep audit trails
Document management is critical for KYC (Know Your Customer) and regulatory compliance.

One-Sentence Summary

fineract-document manages file uploads and document attachments for entities such as clients, loans, and accounts within the system.