Daily accrual calculator¶


ID	`MOD-005`
System	SD01
Repo	`bank-core`
Build status	Deployed
Deployed	Yes
Last commit	`35402a8a7d9c6f1e2b5c8d0e4f7a3b6c9d2e5f8a`

Runs on each account at end of day. Applies the correct rate, day-count convention, and product rules. Posts accrual to GL without human intervention.

v2 — COB partitioning for portfolio scale¶

The current v1 implementation is a single-Lambda sequential pass across all interest-bearing accounts. This is correct and sufficient at early portfolio sizes. ADR-061 documents the partitioned execution model that v2 will adopt when the active account count exceeds the COB_PARTITION_THRESHOLD environment variable (default: 50,000 accounts).

How v2 works. A coordinator Lambda fans out the account population across N parallel Step Functions branches. Each branch processes one hash-bucketed partition of accounts. The coordinator waits for all branches to complete, then publishes bank.core.accrual_run_completed with the full run summary. The partition count is controlled by COB_PARTITION_COUNT (default: 10).

Trigger for v2 build. A CloudWatch alarm is configured to fire when the active account count exceeds COB_PARTITION_THRESHOLD for three consecutive nightly runs. That alarm is the signal to begin the v2 build. There is no manual action required before the alarm fires — v1 continues to operate correctly below the threshold.

Idempotency. Each partition posts accruals via MOD-001 using an idempotency key derived from (accrual_date, account_id). If a partition Lambda fails and Step Functions retries it, MOD-001 deduplicates on the key and the partition completes cleanly. No duplicate accrual entries are possible.

Same pattern for other portfolio-scale batch jobs. MOD-008 (dormancy assessment) and MOD-031 (ECL recalculation) will adopt the same partitioned Step Functions shape when they reach the equivalent scale threshold. The COB partition pattern in MOD-005 v2 is the reference implementation.

Design reference. Fineract's Close-of-Business engine (partitioned Spring Batch jobs across the loan portfolio) was studied as the battle-tested reference for this pattern. See fineract-design-reference.md.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	Posts accrual entries to the ledger — requires the posting engine to persist interest entries.
MOD-002	Immutable transaction log	Required	—	Reads account balances from the transaction log to compute interest-bearing principal.
MOD-003	Real-time balance engine	Required	—	Uses real-time balance to determine the current balance for daily accrual calculation.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, S3, KMS, Kinesis, Cognito) is required before this module can be deployed.
MOD-103	Neon database platform bootstrap	Required	—	Neon database and schema provisioned by MOD-103 must exist before this module can read or write Postgres.

Required by¶

Module	Title	As	Contract
MOD-006	Rate change propagation	Hard dependency	—
MOD-111	Term deposit maturity engine	Hard dependency	—
MOD-112	Amortisation schedule engine	Optional enhancement	—
MOD-116	Mortgage servicing engine	Optional enhancement	—
MOD-117	Overdraft management engine	Optional enhancement	—
MOD-121	Construction loan drawdown engine	Hard dependency	—
MOD-130	Notice account management	Hard dependency	—
MOD-162	Loan facility & component manager	Hard dependency	—
MOD-167	Credit card facility engine	Optional enhancement	—

Policies satisfied¶

Policy	Title	Mode	How
REP-004	Financial Statements Policy	`AUTO`	IFRS 9 interest income recognised on accrual basis — automated and auditable
CON-005	Fee & Pricing Transparency Policy	`AUTO`	Interest earned displayed to customer reflects actual accrual — no rounding manipulation
CLQ-004	Interest Rate Risk in the Banking Book (IRRBB) Policy	`CALC`	Rate-sensitive asset/liability positions updated automatically as accruals post
CRE-006	Impairment & Provisioning Policy	`AUTO`	Effective interest rate method applied consistently across all loan accounts

Capabilities satisfied¶

Capability	Title	Mode	How
CAP-051	High-interest savings account	`CALC`	Computes and posts daily interest on savings balances at the applicable high-interest rate.
CAP-076	Daily interest accrual display	`AUTO`	Posts each daily accrual figure to the ledger so the customer-visible interest total is always current.
CAP-078	Loan amortisation engine	`CALC`	Generates and maintains the full amortisation schedule for each loan, recalculating after early repayments or rate changes.
CAP-079	Interest accrual & capitalisation (loan)	`CALC`	Calculates daily interest on outstanding loan balances and capitalises unpaid interest onto principal where product terms require it.

Part of SD01 — Core Banking Platform Compiled 2026-05-22 from source/entities/modules/MOD-005.yaml