What actually happens in a Fineract end-of-day run

Apache Fineract is not a screen. It is a ledger that advances time. Most of the work members never see happens after the last teller logs out: interest that should accrue, charges that fall due, loans that age into a new arrears bucket.

Until a job hangs, that night run feels like a black box. It is not. It is a set of scheduled jobs, a last-closed business date, and a database that has to finish before the counter opens.

This is written for people who run or integrate the engine — not as a substitute for the Fineract docs, and not as a claim that every deployment uses the same job names.

What the night is for

Close of business (COB), or the cluster of jobs that play that role, is how the core answers: “Given yesterday’s postings, what is true this morning?”

Typical work in that window:

• Interest. Accrual or posting, depending on how the product and accounting are set. A declining-balance loan that was current yesterday is not automatically current this morning if a repayment was missed.
• Charges. Fees that are due because a date arrived, not because a teller typed them.
• Delinquency. Aging: how many days late, which bucket, whether a penalty applies.
• Catch-up. If the job did not run on Sunday, Monday’s run has to close more than one business day without inventing postings that already exist.

The operational rule is simple: do not let tellers disburse and repay on a day the core has not closed behind.

Halfway failure and double posting

The fear is always the same. The job dies at loan 4,812 of 12,000. Do you re-run and credit interest twice?

A well-run core treats a business date as work that can be resumed, not as a script you fire twice from zero. Fineract tracks progress against a last-closed (or last-processed) business date and against accounts already stepped for that date. The safe move when a run fails is: read the job history, see which date is actually closed, fix the cause, then continue — not “run everything again because we are late.”

If your deployment’s jobs are not idempotent in practice — and some custom jobs are not — write that down. A custom charge job that always inserts is more dangerous than a slow standard job.

We do not publish a guarantee that every community job is safe to double-click. We do say: treat a failed night as an incident with a date and a last successful account, not as a reboot.

The database is the bottleneck

Tens of thousands of active accounts means the night is a scan, not a click. On PostgreSQL or MariaDB the usual pain is the same:

• Missing or stale indexes on the tables the job actually touches (loan accounts, transactions, schedule periods) — not “add indexes everywhere.”
• A working set that no longer fits memory, so the run pages.
• One report or integration query that locks rows the batch needs.

Tuning is specific to the instance. The habit is not: after every release, time the night run on a copy of production data, and keep a short list of the statements that dominate.

Hosting on your server, your cloud, or ours does not change the physics. It changes who is awake when the job is still at 40% at 07:10.

Know before 08:00

Tellers should not be the monitoring system. Before the floor opens you want a yes or a no:

• Did the scheduled jobs for last night finish?
• Is the last closed business date yesterday (or Friday, if you do not run Sunday)?
• Did any job finish with a failed or abandoned state?

That can be a script against the job tables and a message to WhatsApp or email. It does not have to be a dashboard. It has to arrive early enough that you do not discover the hang in the queue.

BANKAYO runs and supports Fineract instances. When we attach the operator workspace or change a product in the core, the night jobs are part of that support — not a surprise we leave to the first member at the window.

If a run is already failing, or you are about to grow past the volume your current job window can close, tell us how the instance is hosted and which jobs you actually schedule. We will say what to fix first.