Understanding Fineract Instance Types: Motivation, Roles, and Configuration

Apache Fineract is a powerful, modular, and scalable core banking platform. As deployments grow in scale and complexity – especially in environments with high transaction volumes or concurrent operations – performance bottlenecks can arise if all responsibilities are handled by a single instance.

To address this, Fineract introduced Instance Types – a mechanism for segregating the platform’s workload across multiple instance roles to improve performance, scalability, and reliability.

Why Instance Types Were Introduced

In traditional deployments, a single Fineract instance was responsible for all tasks, including:

• Serving API requests (both reads and writes)
• Running scheduled batch jobs
• Performing event publishing and consumption
• Executing database migrations

This monolithic handling often resulted in:

• Performance degradation under high load
• Tight coupling between unrelated services (API traffic vs. scheduled jobs)
• Difficulty scaling based on specific workload types

Fineract Instance Types were introduced to decouple responsibilities and enable horizontal scalability in cloud-native or distributed deployments.

Types of Fineract Instances

Fineract supports three main instance types, each with specific roles and capabilities:

Feature	Read Instance	Write Instance	Batch Instance
Read-only DB connection	✅	❌	❌
Scheduled batch jobs / API-triggered jobs	❌	❌	✅
Receives events (hooks, business events)	❌	✅	❌
Sends events	❌	✅	✅
Supports Read APIs (GET requests)	✅	✅	❌
Supports Write APIs (POST/PUT/DELETE)	❌	✅	❌
Supports Batch Job APIs	❌	❌	✅
Liquibase migrations at startup	❌	✅	❌

---

Configuration Options

Each instance type is toggled using the following environment variables (or via Spring Boot application.properties):

fineract.mode.read-enabled=${FINERACT_MODE_READ_ENABLED:true}
fineract.mode.write-enabled=${FINERACT_MODE_WRITE_ENABLED:true}
fineract.mode.batch-worker-enabled=${FINERACT_MODE_BATCH_WORKER_ENABLED:true}
fineract.mode.batch-manager-enabled=${FINERACT_MODE_BATCH_MANAGER_ENABLED:true}

• All values default to true. This means a single-instance deployment supports all modes.
• If all are false, the application will fail to start.

Alternatively, you can set the environment variables directly:

export FINERACT_MODE_READ_ENABLED=false
export FINERACT_MODE_WRITE_ENABLED=true
export FINERACT_MODE_BATCH_WORKER_ENABLED=false
export FINERACT_MODE_BATCH_MANAGER_ENABLED=false

---

Deployment Scenarios

Single-Instance Deployment (Development or Small Scale)

• No configuration needed. All modes enabled by default.
• Suitable for testing and development environments.

Multi-Instance Deployment (Production-Scale)

A common pattern for production involves:

• 1 Write instance
• 1 Batch instance
• Multiple Read instances, each pointing to a read-replica database

Benefits:

• Read traffic is offloaded to read replicas
• Batch processing runs in isolation without affecting API traffic
• Write instance handles API commands and event management

Advanced CoB (Close of Business) Setup

In high-volume setups:

• 1 Batch Manager instance orchestrates
• Multiple Batch Worker instances execute CoB jobs
• CoB jobs are parallelized across workers

This isolates the resource-intensive batch processing from both read and write APIs.

Internal API Behavior

• GET requests are handled by read and write instances
• POST/PUT/DELETE requests are only processed by write instances
• Batch job APIs are only exposed by batch instances
• Liquibase database migrations (schema updates) are only executed by write instances during startup

Accessing Instance Type Programmatically

Fineract exposes these configuration via properties class:

FineractProperties.FineractModeProperties

With methods like:

isReadMode()
isWriteMode()
isBatchMode()
isReadOnlyMode()

These help developers or extensions conditionally execute logic depending on the instance type.

Conclusion

The introduction of Fineract Instance Types allows fine-grained control over deployment architecture. By isolating concerns—read operations, write operations, and batch jobs—you can optimize Fineract for both performance and maintainability in enterprise-grade environments.

Proper configuration ensures that your deployment remains efficient, scalable, and resilient—even under significant operational load.

Let me know if you’d like this article exported as Markdown, PDF, or embedded in your documentation platform.

Important 

Keep in mind that Apache Fineract® is a complex project, and you may encounter issues or need to configure additional settings based on your specific environment and requirements. It’s a good practice to refer to the official Apache Fineract® documentation and the project’s developer community for more details and troubleshooting!