DDS: Agent settlement (Agent Tran), Close Party account, reports (Supplementary-DDS/Master Data Export/Close Register), Party-Savings link, product category field

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitignore

@@ -36,4 +36,5 @@ gradleExp/
 
 .windsurf/
 
+# Application logs
 fineract-provider/logs/

auth.json

@@ -0,0 +1 @@
+{"username":"mifos", "password":"password"}

build.gradle

@@ -159,7 +159,7 @@ gitVersioning.apply {
 }
 
 ext['groovy.version'] = '4.0.17'
-ext['swaggerFile'] = "$rootDir/fineract-provider/build/resources/main/static/fineract.json".toString()
+ext['swaggerFile'] = "$rootDir/fineract-provider/build/resources/main/static/fineract.json".toString().replace(" ", "%20")
 
 // Apply static weaving configuration to all subprojects
 subprojects { subproject ->

fetch_accounts.js

@@ -0,0 +1,18 @@
+const https = require('https');
+const agent = new https.Agent({ rejectUnauthorized: false });
+
+fetch('https://localhost:8443/fineract-provider/api/v1/authentication?username=mifos&password=password&tenantIdentifier=default', {
+    method: 'POST',
+    agent: agent
+}).then(res => res.json()).then(data => {
+    const token = data.base64EncodedAuthenticationKey;
+    return fetch('https://localhost:8443/fineract-provider/api/v1/clients/9/accounts?tenantIdentifier=default', {
+        headers: {
+            'Authorization': 'Basic ' + token,
+            'Fineract-Platform-TenantId': 'default'
+        },
+        agent: agent
+    });
+}).then(res => res.json()).then(data => {
+    console.log(JSON.stringify(data, null, 2));
+}).catch(console.error);

fineract-accounting/src/main/java/org/apache/fineract/accounting/journalentry/JournalEntryMapper.java

@@ -18,7 +18,6 @@
  */
 package org.apache.fineract.accounting.journalentry;
 
-import java.time.OffsetDateTime;
 import org.apache.fineract.accounting.glaccount.domain.GLAccountType;
 import org.apache.fineract.accounting.journalentry.data.JournalEntryData;
 import org.apache.fineract.accounting.journalentry.domain.JournalEntry;

fineract-accounting/src/main/java/org/apache/fineract/accounting/producttoaccountmapping/service/ProductToGLAccountMappingHelper.java

@@ -277,14 +277,14 @@ public class ProductToGLAccountMappingHelper {
         }
 
         final JsonArray chargeToIncomeAccountMappingArray = this.fromApiJsonHelper.extractJsonArrayNamed(arrayFragmentName, element);
-        /**
+        /*
          * Variable stores a map representation of charges (key) and their associated income Id's (value) extracted from
          * the passed in Jsoncommand
-         **/
+         */
         final Map<Long, Long> inputChargeToIncomeAccountMap = new HashMap<>();
-        /***
+        /*
          * Variable stores all charges which have already been mapped to Income Accounts in the system
-         **/
+         */
         final Set<Long> existingCharges = new HashSet<>();
         if (chargeToIncomeAccountMappingArray != null) {
             if (changes != null) {
@@ -301,13 +301,13 @@ public class ProductToGLAccountMappingHelper {
             // If input map is empty, delete all existing mappings
             if (inputChargeToIncomeAccountMap.size() == 0) {
                 this.accountMappingRepository.deleteAll(existingChargeToIncomeAccountMappings);
-            } /**
+            } /*
                * Else, <br/>
                * update existing mappings OR <br/>
                * delete old mappings (which are already present, but not passed in as a part of Jsoncommand)<br/>
                * Create new mappings for charges that are passed in as a part of the Jsoncommand but not already present
                *
-               **/
+               */
             else {
                 for (final ProductToGLAccountMapping chargeToIncomeAccountMapping : existingChargeToIncomeAccountMappings) {
                     final Long currentCharge = chargeToIncomeAccountMapping.getCharge().getId();
@@ -356,14 +356,14 @@ public class ProductToGLAccountMappingHelper {
                 .findAllPaymentTypeToFundSourceMappings(productId, portfolioProductType.getValue());
         final JsonArray paymentChannelMappingArray = this.fromApiJsonHelper
                 .extractJsonArrayNamed(LoanProductAccountingParams.PAYMENT_CHANNEL_FUND_SOURCE_MAPPING.getValue(), element);
-        /**
+        /*
          * Variable stores a map representation of Payment channels (key) and their fund sources (value) extracted from
          * the passed in Jsoncommand
-         **/
+         */
         final Map<Long, Long> inputPaymentChannelFundSourceMap = new HashMap<>();
-        /***
+        /*
          * Variable stores all payment types which have already been mapped to Fund Sources in the system
-         **/
+         */
         final Set<Long> existingPaymentTypes = new HashSet<>();
         if (paymentChannelMappingArray != null) {
             if (changes != null) {
@@ -381,14 +381,14 @@ public class ProductToGLAccountMappingHelper {
             // If input map is empty, delete all existing mappings
             if (inputPaymentChannelFundSourceMap.isEmpty()) {
                 this.accountMappingRepository.deleteAll(existingPaymentChannelToFundSourceMappings);
-            } /**
+            } /*
                * Else, <br/>
                * update existing mappings OR <br/>
                * delete old mappings (which re already present, but not passed in as a part of Jsoncommand)<br/>
                * Create new mappings for payment types that are passed in as a part of the Jsoncommand but not already
                * present
                *
-               **/
+               */
             else {
                 for (final ProductToGLAccountMapping existingPaymentChannelToFundSourceMapping : existingPaymentChannelToFundSourceMappings) {
                     final Long currentPaymentChannelId = existingPaymentChannelToFundSourceMapping.getPaymentType().getId();
@@ -584,9 +584,9 @@ public class ProductToGLAccountMappingHelper {
         // based on input condition
 
         GLAccount glAccount;
-        /**
+        /*
          * Both CASH and Accrual placeholders have the same value for income from Interest and penalties
-         **/
+         */
         CashAccountsForLoan placeHolderAccountType;
         if (isPenalty) {
             glAccount = getAccountByIdAndType(LoanProductAccountingParams.INCOME_ACCOUNT_ID.getValue(), GLAccountType.INCOME,

fineract-accounting/src/main/resources/jpa/static-weaving/module/fineract-accounting/persistence.xml

@@ -54,6 +54,7 @@
         <class>org.apache.fineract.portfolio.group.domain.StaffAssignmentHistory</class>
         <class>org.apache.fineract.portfolio.group.domain.Group</class>
         <class>org.apache.fineract.portfolio.client.domain.Client</class>
+        <class>org.apache.fineract.portfolio.client.domain.ClientKyc</class>
         <class>org.apache.fineract.infrastructure.event.external.repository.domain.ExternalEventConfiguration</class>
         <class>org.apache.fineract.portfolio.group.domain.GroupRole</class>
         <class>org.apache.fineract.portfolio.paymenttype.domain.PaymentType</class>

fineract-branch/src/main/java/org/apache/fineract/organisation/teller/api/TellerApiResource.java

@@ -181,12 +181,12 @@ public class TellerApiResource {
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces(MediaType.APPLICATION_JSON)
     @Operation(summary = "Create Cashiers", description = """
-            Mandatory Fields:\s
+            Mandatory Fields:
             Cashier/staff, Fromm Date, To Date, Full Day or From time and To time
 
 
 
-            Optional Fields:\s
+            Optional Fields:
             Description/Notes""")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = TellerApiResourceSwagger.PostTellersTellerIdCashiersRequest.class)))
     @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = TellerApiResourceSwagger.PostTellersTellerIdCashiersResponse.class)))

fineract-branch/src/main/resources/jpa/static-weaving/module/fineract-branch/persistence.xml

@@ -54,6 +54,7 @@
         <class>org.apache.fineract.portfolio.group.domain.StaffAssignmentHistory</class>
         <class>org.apache.fineract.portfolio.group.domain.Group</class>
         <class>org.apache.fineract.portfolio.client.domain.Client</class>
+        <class>org.apache.fineract.portfolio.client.domain.ClientKyc</class>
         <class>org.apache.fineract.infrastructure.event.external.repository.domain.ExternalEventConfiguration</class>
         <class>org.apache.fineract.portfolio.group.domain.GroupRole</class>
         <class>org.apache.fineract.portfolio.paymenttype.domain.PaymentType</class>

fineract-charge/src/main/resources/jpa/static-weaving/module/fineract-charge/persistence.xml

@@ -54,6 +54,7 @@
         <class>org.apache.fineract.portfolio.group.domain.StaffAssignmentHistory</class>
         <class>org.apache.fineract.portfolio.group.domain.Group</class>
         <class>org.apache.fineract.portfolio.client.domain.Client</class>
+        <class>org.apache.fineract.portfolio.client.domain.ClientKyc</class>
         <class>org.apache.fineract.infrastructure.event.external.repository.domain.ExternalEventConfiguration</class>
         <class>org.apache.fineract.portfolio.group.domain.GroupRole</class>
         <class>org.apache.fineract.portfolio.paymenttype.domain.PaymentType</class>

fineract-client/build.gradle

@@ -183,7 +183,7 @@ task cleanupGeneratedJavaFiles() {
 // Configure Java compilation
 tasks.named('compileJava') {
     outputs.cacheIf { true }
-    dependsOn(buildJavaSdk, buildTypescriptAngularSdk, buildAsciidoc, cleanupGeneratedJavaFiles, licenseFormatMain, spotlessMiscApply)
+    dependsOn(buildJavaSdk, cleanupGeneratedJavaFiles, licenseFormatMain, spotlessMiscApply)
     mustRunAfter(licenseFormatMain, cleanupGeneratedJavaFiles)
 }
 

fineract-cob/src/main/resources/jpa/static-weaving/module/fineract-cob/persistence.xml

@@ -53,6 +53,7 @@
         <class>org.apache.fineract.portfolio.group.domain.StaffAssignmentHistory</class>
         <class>org.apache.fineract.portfolio.group.domain.Group</class>
         <class>org.apache.fineract.portfolio.client.domain.Client</class>
+        <class>org.apache.fineract.portfolio.client.domain.ClientKyc</class>
         <class>org.apache.fineract.infrastructure.event.external.repository.domain.ExternalEventConfiguration</class>
         <class>org.apache.fineract.portfolio.group.domain.GroupRole</class>
         <class>org.apache.fineract.portfolio.paymenttype.domain.PaymentType</class>

fineract-core/src/main/java/org/apache/fineract/accounting/common/AccountingConstants.java

@@ -436,7 +436,9 @@ public final class AccountingConstants {
         CASH_AT_TELLER(102, "cashAtTeller", GLAccountType.ASSET), //
         OPENING_BALANCES_TRANSFER_CONTRA(300, "openingBalancesTransferContra", GLAccountType.EQUITY), //
         ASSET_FUND_SOURCE(103, "fundSource", GLAccountType.ASSET), //
-        PAYABLE_DIVIDENDS(201, "payableDividends", GLAccountType.LIABILITY); //
+        PAYABLE_DIVIDENDS(201, "payableDividends", GLAccountType.LIABILITY), //
+        RESERVE_FOR_DIVIDEND(301, "reserveForDividend", GLAccountType.EQUITY), //
+        DIVIDEND_FORFEITED_INCOME(400, "dividendForfeitedIncome", GLAccountType.INCOME); //
 
         private final Integer value;
         private final String code;

fineract-core/src/main/java/org/apache/fineract/commands/service/CommandWrapperBuilder.java

@@ -71,6 +71,344 @@ public class CommandWrapperBuilder {
                 this.sanitizeJsonKeys);
     }
 
+    public CommandWrapperBuilder createChequeSeries() {
+        this.actionName = "CREATE";
+        this.entityName = "CHEQUESERIES";
+        this.entityId = null;
+        this.href = "/chequeseries";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateChequeSeries(final Long seriesId) {
+        this.actionName = "UPDATE";
+        this.entityName = "CHEQUESERIES";
+        this.entityId = seriesId;
+        this.href = "/chequeseries/" + seriesId;
+        return this;
+    }
+
+    public CommandWrapperBuilder deleteChequeSeries(final Long seriesId) {
+        this.actionName = "DELETE";
+        this.entityName = "CHEQUESERIES";
+        this.entityId = seriesId;
+        this.href = "/chequeseries/" + seriesId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createChequeStockLot() {
+        this.actionName = "CREATE";
+        this.entityName = "CHEQUESTOCKLOT";
+        this.entityId = null;
+        this.href = "/chequestocklots";
+        return this;
+    }
+
+    public CommandWrapperBuilder reportLostChequeStockLot(final Long lotId) {
+        this.actionName = "REPORTLOST";
+        this.entityName = "CHEQUESTOCKLOT";
+        this.entityId = lotId;
+        this.href = "/chequestocklots/" + lotId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createChequeStockTransfer() {
+        this.actionName = "CREATE";
+        this.entityName = "CHEQUESTOCKTRANSFER";
+        this.entityId = null;
+        this.href = "/chequestocktransfers";
+        return this;
+    }
+
+    public CommandWrapperBuilder receiveChequeStockTransfer(final Long transferId) {
+        this.actionName = "RECEIVE";
+        this.entityName = "CHEQUESTOCKTRANSFER";
+        this.entityId = transferId;
+        this.href = "/chequestocktransfers/" + transferId;
+        return this;
+    }
+
+    public CommandWrapperBuilder rejectChequeStockTransfer(final Long transferId) {
+        this.actionName = "REJECT";
+        this.entityName = "CHEQUESTOCKTRANSFER";
+        this.entityId = transferId;
+        this.href = "/chequestocktransfers/" + transferId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createChequeBook() {
+        this.actionName = "CREATE";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = null;
+        this.href = "/chequebooks";
+        return this;
+    }
+
+    public CommandWrapperBuilder issueChequeBook(final Long chequeBookId) {
+        this.actionName = "ISSUE";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder rejectChequeBook(final Long chequeBookId) {
+        this.actionName = "REJECT";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder withdrawChequeBook(final Long chequeBookId) {
+        this.actionName = "WITHDRAW";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder stopPaymentChequeBook(final Long chequeBookId) {
+        this.actionName = "STOPPAYMENT";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder revokeStopPaymentChequeBook(final Long chequeBookId) {
+        this.actionName = "REVOKESTOPPAYMENT";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder reportLostChequeBook(final Long chequeBookId) {
+        this.actionName = "REPORTLOST";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder cancelLeafChequeBook(final Long chequeBookId) {
+        this.actionName = "CANCELLEAF";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder markUsedChequeBook(final Long chequeBookId) {
+        this.actionName = "MARKUSED";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder returnChequeBook(final Long chequeBookId) {
+        this.actionName = "RETURN";
+        this.entityName = "CHEQUEBOOK";
+        this.entityId = chequeBookId;
+        this.href = "/chequebooks/" + chequeBookId;
+        return this;
+    }
+
+    public CommandWrapperBuilder approveChequeBookPendingRequest(final Long pendingRequestId) {
+        this.actionName = "APPROVE";
+        this.entityName = "CHEQUEBOOKPENDINGREQUEST";
+        this.entityId = pendingRequestId;
+        this.href = "/chequebook/pending-requests/" + pendingRequestId;
+        return this;
+    }
+
+    public CommandWrapperBuilder rejectChequeBookPendingRequest(final Long pendingRequestId) {
+        this.actionName = "REJECT";
+        this.entityName = "CHEQUEBOOKPENDINGREQUEST";
+        this.entityId = pendingRequestId;
+        this.href = "/chequebook/pending-requests/" + pendingRequestId;
+        return this;
+    }
+
+    // ===== Clearing (CTS + NACH) command wrappers =====
+
+    public CommandWrapperBuilder createClearingSettlementBatch() {
+        this.actionName = "CREATE";
+        this.entityName = "CLEARINGSETTLEMENTBATCH";
+        this.entityId = null;
+        this.href = "/clearing/settlement-batches";
+        return this;
+    }
+
+    public CommandWrapperBuilder postClearingSettlementBatch(final Long settlementBatchId) {
+        this.actionName = "POST";
+        this.entityName = "CLEARINGSETTLEMENTBATCH";
+        this.entityId = settlementBatchId;
+        this.href = "/clearing/settlement-batches/" + settlementBatchId;
+        return this;
+    }
+
+    public CommandWrapperBuilder rejectClearingSettlementBatch(final Long settlementBatchId) {
+        this.actionName = "REJECT";
+        this.entityName = "CLEARINGSETTLEMENTBATCH";
+        this.entityId = settlementBatchId;
+        this.href = "/clearing/settlement-batches/" + settlementBatchId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createClearingReconciliation() {
+        this.actionName = "CREATE";
+        this.entityName = "CLEARINGRECONCILIATION";
+        this.entityId = null;
+        this.href = "/clearing/reconciliations";
+        return this;
+    }
+
+    public CommandWrapperBuilder createInwardClearingBatch() {
+        this.actionName = "CREATE";
+        this.entityName = "INWARDCLEARINGBATCH";
+        this.entityId = null;
+        this.href = "/ctsclearing/inward-batches";
+        return this;
+    }
+
+    public CommandWrapperBuilder validateInwardClearingBatch(final Long batchId) {
+        this.actionName = "VALIDATE";
+        this.entityName = "INWARDCLEARINGBATCH";
+        this.entityId = batchId;
+        this.href = "/ctsclearing/inward-batches/" + batchId;
+        return this;
+    }
+
+    public CommandWrapperBuilder passInwardClearingItem(final Long itemId) {
+        this.actionName = "PASS";
+        this.entityName = "INWARDCLEARINGITEM";
+        this.entityId = itemId;
+        this.href = "/ctsclearing/inward-items/" + itemId;
+        return this;
+    }
+
+    public CommandWrapperBuilder returnInwardClearingItem(final Long itemId) {
+        this.actionName = "RETURN";
+        this.entityName = "INWARDCLEARINGITEM";
+        this.entityId = itemId;
+        this.href = "/ctsclearing/inward-items/" + itemId;
+        return this;
+    }
+
+    public CommandWrapperBuilder verifyInwardClearingItemSignature(final Long itemId) {
+        this.actionName = "VERIFY_SIGNATURE";
+        this.entityName = "INWARDCLEARINGITEM";
+        this.entityId = itemId;
+        this.href = "/ctsclearing/inward-items/" + itemId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createPositivePayRegistration() {
+        this.actionName = "CREATE";
+        this.entityName = "POSITIVEPAYREGISTRATION";
+        this.entityId = null;
+        this.href = "/ctsclearing/positive-pay";
+        return this;
+    }
+
+    public CommandWrapperBuilder cancelPositivePayRegistration(final Long registrationId) {
+        this.actionName = "CANCEL";
+        this.entityName = "POSITIVEPAYREGISTRATION";
+        this.entityId = registrationId;
+        this.href = "/ctsclearing/positive-pay/" + registrationId;
+        return this;
+    }
+
+    public CommandWrapperBuilder sendPendingOutwardClearingBatch() {
+        this.actionName = "SENDBATCH";
+        this.entityName = "OUTWARDCLEARINGPRESENTMENT";
+        this.entityId = null;
+        this.href = "/ctsclearing/outward-presentments/send-pending-batch";
+        return this;
+    }
+
+    public CommandWrapperBuilder createOutwardClearingPresentment() {
+        this.actionName = "CREATE";
+        this.entityName = "OUTWARDCLEARINGPRESENTMENT";
+        this.entityId = null;
+        this.href = "/ctsclearing/outward-presentments";
+        return this;
+    }
+
+    public CommandWrapperBuilder sendOutwardClearingPresentment(final Long presentmentId) {
+        this.actionName = "SEND";
+        this.entityName = "OUTWARDCLEARINGPRESENTMENT";
+        this.entityId = presentmentId;
+        this.href = "/ctsclearing/outward-presentments/" + presentmentId;
+        return this;
+    }
+
+    public CommandWrapperBuilder settleOutwardClearingPresentment(final Long presentmentId) {
+        this.actionName = "SETTLE";
+        this.entityName = "OUTWARDCLEARINGPRESENTMENT";
+        this.entityId = presentmentId;
+        this.href = "/ctsclearing/outward-presentments/" + presentmentId;
+        return this;
+    }
+
+    public CommandWrapperBuilder dishonourOutwardClearingPresentment(final Long presentmentId) {
+        this.actionName = "DISHONOUR";
+        this.entityName = "OUTWARDCLEARINGPRESENTMENT";
+        this.entityId = presentmentId;
+        this.href = "/ctsclearing/outward-presentments/" + presentmentId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createNachMandate() {
+        this.actionName = "CREATE";
+        this.entityName = "NACHMANDATE";
+        this.entityId = null;
+        this.href = "/nachclearing/mandates";
+        return this;
+    }
+
+    public CommandWrapperBuilder cancelNachMandate(final Long mandateId) {
+        this.actionName = "CANCEL";
+        this.entityName = "NACHMANDATE";
+        this.entityId = mandateId;
+        this.href = "/nachclearing/mandates/" + mandateId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createNachBatch() {
+        this.actionName = "CREATE";
+        this.entityName = "NACHBATCH";
+        this.entityId = null;
+        this.href = "/nachclearing/batches";
+        return this;
+    }
+
+    public CommandWrapperBuilder processNachBatch(final Long batchId) {
+        this.actionName = "PROCESS";
+        this.entityName = "NACHBATCH";
+        this.entityId = batchId;
+        this.href = "/nachclearing/batches/" + batchId;
+        return this;
+    }
+
+    public CommandWrapperBuilder passNachTransaction(final Long transactionId) {
+        this.actionName = "PASS";
+        this.entityName = "NACHTRANSACTION";
+        this.entityId = transactionId;
+        this.href = "/nachclearing/transactions/" + transactionId;
+        return this;
+    }
+
+    public CommandWrapperBuilder returnNachTransaction(final Long transactionId) {
+        this.actionName = "RETURN";
+        this.entityName = "NACHTRANSACTION";
+        this.entityId = transactionId;
+        this.href = "/nachclearing/transactions/" + transactionId;
+        return this;
+    }
+
     public CommandWrapperBuilder updateCreditBureau() {
         this.actionName = "UPDATE";
         this.entityName = "ORGANISATIONCREDITBUREAU";
@@ -302,6 +640,14 @@ public class CommandWrapperBuilder {
         return this;
     }
 
+    public CommandWrapperBuilder createUserAgreement() {
+        this.actionName = "CREATE";
+        this.entityName = "USERAGREEMENT";
+        this.entityId = null;
+        this.href = "/useragreements";
+        return this;
+    }
+
     public CommandWrapperBuilder createOffice() {
         this.actionName = "CREATE";
         this.entityName = "OFFICE";
@@ -318,6 +664,78 @@ public class CommandWrapperBuilder {
         return this;
     }
 
+    public CommandWrapperBuilder createAgent() {
+        this.actionName = "CREATE";
+        this.entityName = "AGENT";
+        this.entityId = null;
+        this.href = "/dds/agents/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateAgent(final Long agentId) {
+        this.actionName = "UPDATE";
+        this.entityName = "AGENT";
+        this.entityId = agentId;
+        this.href = "/dds/agents/" + agentId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createParty() {
+        this.actionName = "CREATE";
+        this.entityName = "PARTY";
+        this.entityId = null;
+        this.href = "/dds/parties/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateParty(final Long partyId) {
+        this.actionName = "UPDATE";
+        this.entityName = "PARTY";
+        this.entityId = partyId;
+        this.href = "/dds/parties/" + partyId;
+        return this;
+    }
+
+    public CommandWrapperBuilder closeParty(final Long partyId) {
+        this.actionName = "CLOSE";
+        this.entityName = "PARTY";
+        this.entityId = partyId;
+        this.href = "/dds/parties/" + partyId + "?command=close";
+        return this;
+    }
+
+    public CommandWrapperBuilder createPartyTransaction() {
+        this.actionName = "CREATE";
+        this.entityName = "PARTYTRANSACTION";
+        this.entityId = null;
+        this.href = "/dds/partytransactions/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder createCommissionSlabs() {
+        this.actionName = "CREATE";
+        this.entityName = "COMMISSIONSLAB";
+        this.entityId = null;
+        this.href = "/dds/commissionslabs/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder generateDdsBatchRun() {
+        this.actionName = "GENERATE";
+        this.entityName = "DDSBATCH";
+        this.entityId = null;
+        this.href = "/dds/batchruns/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder postDdsBatchRun(final Long batchRunId) {
+        this.actionName = "POST";
+        this.entityName = "DDSBATCH";
+        this.entityId = batchRunId;
+        this.href = "/dds/batchruns/" + batchRunId;
+        return this;
+    }
+
     public CommandWrapperBuilder createOfficeTransaction() {
         this.actionName = "CREATE";
         this.entityName = "OFFICETRANSACTION";

fineract-core/src/main/java/org/apache/fineract/infrastructure/core/serialization/GoogleGsonSerializerHelper.java

@@ -1,116 +1,150 @@
-/**
+/**
- * Licensed to the Apache Software Foundation (ASF) under one
+ * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
+ * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
+ * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
+ * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
+ * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
+ * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
+ * with the License. You may obtain a copy of the License at
- *
+ *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
- * Unless required by applicable law or agreed to in writing,
+ * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
+ * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied. See the License for the
+ * KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations
+ * specific language governing permissions and limitations
- * under the License.
+ * under the License.
- */
+ */
-package org.apache.fineract.infrastructure.core.serialization;
+package org.apache.fineract.infrastructure.core.serialization;
-
+
-import com.google.gson.ExclusionStrategy;
+import com.google.gson.ExclusionStrategy;
-import com.google.gson.Gson;
+import com.google.gson.Gson;
-import com.google.gson.GsonBuilder;
+import com.google.gson.GsonBuilder;
-import java.time.LocalDate;
+import com.google.gson.TypeAdapter;
-import java.time.LocalDateTime;
+import com.google.gson.TypeAdapterFactory;
-import java.time.LocalTime;
+import com.google.gson.reflect.TypeToken;
-import java.time.MonthDay;
+import com.google.gson.stream.JsonReader;
-import java.time.OffsetDateTime;
+import com.google.gson.stream.JsonWriter;
-import java.time.ZonedDateTime;
+import java.io.IOException;
-import java.util.ArrayList;
+import java.time.LocalDate;
-import java.util.HashSet;
+import java.time.LocalDateTime;
-import java.util.Set;
+import java.time.LocalTime;
-import org.apache.fineract.infrastructure.core.api.DateAdapter;
+import java.time.MonthDay;
-import org.apache.fineract.infrastructure.core.api.ExternalIdAdapter;
+import java.time.OffsetDateTime;
-import org.apache.fineract.infrastructure.core.api.JodaDateTimeAdapter;
+import java.time.ZonedDateTime;
-import org.apache.fineract.infrastructure.core.api.JodaMonthDayAdapter;
+import java.util.ArrayList;
-import org.apache.fineract.infrastructure.core.api.LocalDateAdapter;
+import java.util.HashSet;
-import org.apache.fineract.infrastructure.core.api.LocalDateTimeAdapter;
+import java.util.Set;
-import org.apache.fineract.infrastructure.core.api.LocalTimeAdapter;
+import org.apache.fineract.infrastructure.core.api.DateAdapter;
-import org.apache.fineract.infrastructure.core.api.OffsetDateTimeAdapter;
+import org.apache.fineract.infrastructure.core.api.ExternalIdAdapter;
-import org.apache.fineract.infrastructure.core.api.ParameterListExclusionStrategy;
+import org.apache.fineract.infrastructure.core.api.JodaDateTimeAdapter;
-import org.apache.fineract.infrastructure.core.api.ParameterListInclusionStrategy;
+import org.apache.fineract.infrastructure.core.api.JodaMonthDayAdapter;
-import org.apache.fineract.infrastructure.core.domain.ExternalId;
+import org.apache.fineract.infrastructure.core.api.LocalDateAdapter;
-import org.apache.fineract.infrastructure.core.exception.UnsupportedParameterException;
+import org.apache.fineract.infrastructure.core.api.LocalDateTimeAdapter;
-import org.springframework.stereotype.Service;
+import org.apache.fineract.infrastructure.core.api.LocalTimeAdapter;
-
+import org.apache.fineract.infrastructure.core.api.OffsetDateTimeAdapter;
-/**
+import org.apache.fineract.infrastructure.core.api.ParameterListExclusionStrategy;
- * Helper class for serialization of Java objects into JSON using Google's GSON.
+import org.apache.fineract.infrastructure.core.api.ParameterListInclusionStrategy;
- */
+import org.apache.fineract.infrastructure.core.domain.ExternalId;
-@Service
+import org.apache.fineract.infrastructure.core.exception.UnsupportedParameterException;
-public final class GoogleGsonSerializerHelper {
+import org.springframework.stereotype.Service;
-
+
-    public Gson createGsonBuilderForPartialResponseFiltering(final Set<String> responseParameters) {
+/**
-        final ExclusionStrategy strategy = new ParameterListInclusionStrategy(responseParameters);
+ * Helper class for serialization of Java objects into JSON using Google's GSON.
-
+ */
-        final GsonBuilder builder = new GsonBuilder().addSerializationExclusionStrategy(strategy);
+@Service
-        registerTypeAdapters(builder);
+public final class GoogleGsonSerializerHelper {
-        return builder.create();
+
-    }
+    public Gson createGsonBuilderForPartialResponseFiltering(final Set<String> responseParameters) {
-
+        final ExclusionStrategy strategy = new ParameterListInclusionStrategy(responseParameters);
-    public Gson createGsonBuilderWithParameterExclusionSerializationStrategy(final Set<String> supportedParameters,
+
-            final Set<String> responseParameters) {
+        final GsonBuilder builder = new GsonBuilder().addSerializationExclusionStrategy(strategy);
-
+        registerTypeAdapters(builder);
-        final Set<String> parameterNamesToSkip = new HashSet<>();
+        return builder.create();
-
+    }
-        if (!responseParameters.isEmpty()) {
+
-            // strip out all known support parameters from expected response to
+    public Gson createGsonBuilderWithParameterExclusionSerializationStrategy(final Set<String> supportedParameters,
-            // see if unsupported parameters requested for response.
+            final Set<String> responseParameters) {
-            final Set<String> differentParametersDetectedSet = new HashSet<>(responseParameters);
+
-            differentParametersDetectedSet.removeAll(supportedParameters);
+        final Set<String> parameterNamesToSkip = new HashSet<>();
-
+
-            if (!differentParametersDetectedSet.isEmpty()) {
+        if (!responseParameters.isEmpty()) {
-                throw new UnsupportedParameterException(new ArrayList<>(differentParametersDetectedSet));
+            // strip out all known support parameters from expected response to
-            }
+            // see if unsupported parameters requested for response.
-
+            final Set<String> differentParametersDetectedSet = new HashSet<>(responseParameters);
-            parameterNamesToSkip.addAll(supportedParameters);
+            differentParametersDetectedSet.removeAll(supportedParameters);
-            parameterNamesToSkip.removeAll(responseParameters);
+
-        }
+            if (!differentParametersDetectedSet.isEmpty()) {
-
+                throw new UnsupportedParameterException(new ArrayList<>(differentParametersDetectedSet));
-        final ExclusionStrategy strategy = new ParameterListExclusionStrategy(parameterNamesToSkip);
+            }
-
+
-        final GsonBuilder builder = new GsonBuilder().addSerializationExclusionStrategy(strategy);
+            parameterNamesToSkip.addAll(supportedParameters);
-        registerTypeAdapters(builder);
+            parameterNamesToSkip.removeAll(responseParameters);
-        return builder.create();
+        }
-    }
+
-
+        final ExclusionStrategy strategy = new ParameterListExclusionStrategy(parameterNamesToSkip);
-    public String serializedJsonFrom(final Gson serializer, final Object[] dataObjects) {
+
-        return serializer.toJson(dataObjects);
+        final GsonBuilder builder = new GsonBuilder().addSerializationExclusionStrategy(strategy);
-    }
+        registerTypeAdapters(builder);
-
+        return builder.create();
-    public String serializedJsonFrom(final Gson serializer, final Object singleDataObject) {
+    }
-        return serializer.toJson(singleDataObject);
+
-    }
+    public String serializedJsonFrom(final Gson serializer, final Object[] dataObjects) {
-
+        return serializer.toJson(dataObjects);
-    public static Gson createSimpleGson() {
+    }
-        return createGsonBuilder().create();
+
-    }
+    public String serializedJsonFrom(final Gson serializer, final Object singleDataObject) {
-
+        return serializer.toJson(singleDataObject);
-    public static GsonBuilder createGsonBuilder() {
+    }
-        final GsonBuilder builder = new GsonBuilder();
+
-        registerTypeAdapters(builder);
+    public static Gson createSimpleGson() {
-        return builder;
+        return createGsonBuilder().create();
-    }
+    }
-
+
-    public static void registerTypeAdapters(final GsonBuilder builder) {
+    public static GsonBuilder createGsonBuilder() {
-        builder.registerTypeAdapter(java.util.Date.class, new DateAdapter());
+        final GsonBuilder builder = new GsonBuilder();
-        builder.registerTypeAdapter(LocalDate.class, new LocalDateAdapter());
+        registerTypeAdapters(builder);
-        // NOTE: was missing, necessary for GSON serialization with JDK 21's restrictive module access
+        return builder;
-        builder.registerTypeAdapter(LocalTime.class, new LocalTimeAdapter());
+    }
-        builder.registerTypeAdapter(ZonedDateTime.class, new JodaDateTimeAdapter());
+
-        builder.registerTypeAdapter(MonthDay.class, new JodaMonthDayAdapter());
+    public static void registerTypeAdapters(final GsonBuilder builder) {
-        builder.registerTypeAdapter(LocalDateTime.class, new LocalDateTimeAdapter());
+        builder.registerTypeAdapter(java.util.Date.class, new DateAdapter());
-        builder.registerTypeAdapter(OffsetDateTime.class, new OffsetDateTimeAdapter());
+        builder.registerTypeAdapter(LocalDate.class, new LocalDateAdapter());
-        builder.registerTypeAdapter(ExternalId.class, new ExternalIdAdapter());
+        // NOTE: was missing, necessary for GSON serialization with JDK 21's restrictive module access
-    }
+        builder.registerTypeAdapter(LocalTime.class, new LocalTimeAdapter());
-}
+        builder.registerTypeAdapter(ZonedDateTime.class, new JodaDateTimeAdapter());
+        builder.registerTypeAdapter(MonthDay.class, new JodaMonthDayAdapter());
+        builder.registerTypeAdapter(LocalDateTime.class, new LocalDateTimeAdapter());
+        builder.registerTypeAdapter(OffsetDateTime.class, new OffsetDateTimeAdapter());
+        builder.registerTypeAdapter(ExternalId.class, new ExternalIdAdapter());
+        // Use runtime type when serializing interface-typed fields (e.g. Collection<? extends IGuarantor>)
+        builder.registerTypeAdapterFactory(new TypeAdapterFactory() {
+            @Override
+            @SuppressWarnings("unchecked")
+            public <T> TypeAdapter<T> create(final Gson gson, final TypeToken<T> type) {
+                if (!type.getRawType().isInterface()) {
+                    return null;
+                }
+                final TypeAdapterFactory self = this;
+                return new TypeAdapter<T>() {
+                    @Override
+                    public void write(final JsonWriter out, final T value) throws IOException {
+                        if (value == null) {
+                            out.nullValue();
+                            return;
+                        }
+                        TypeAdapter<T> delegate = (TypeAdapter<T>) gson.getDelegateAdapter(self,
+                                TypeToken.get((Class<T>) value.getClass()));
+                        delegate.write(out, value);
+                    }
+
+                    @Override
+                    public T read(final JsonReader in) throws IOException {
+                        return null;
+                    }
+                };
+            }
+        });
+    }
+}

fineract-core/src/main/java/org/apache/fineract/infrastructure/documentmanagement/adapter/EntitySignatureIdAdapter.java

@@ -0,0 +1,56 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.infrastructure.documentmanagement.adapter;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Optional;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * Decouples the entity "current signature" pointer from the generic document service, the same
+ * way {@link EntityImageIdAdapter} decouples the "current photo" pointer — lets
+ * DocumentWritePlatformServiceImpl (fineract-document module) give single-slot upsert semantics to
+ * signature uploads without depending on portfolio-module entities directly.
+ */
+public interface EntitySignatureIdAdapter {
+
+    /** @param documentName the m_document.name of the document being created/removed */
+    boolean accept(String entityType, String documentName);
+
+    Optional<SignatureIdResult> get(Long entityId);
+
+    Optional<SignatureIdResult> set(Long entityId, Long signatureId);
+
+    @Builder
+    @Data
+    @NoArgsConstructor
+    @AllArgsConstructor
+    class SignatureIdResult implements Serializable {
+
+        @Serial
+        private static final long serialVersionUID = 1L;
+
+        private Long id;
+        private String displayName;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/infrastructure/jobs/service/JobName.java

@@ -38,6 +38,7 @@ public enum JobName {
     GENERATE_RD_SCEHDULE("Generate Mandatory Savings Schedule"), //
     GENERATE_LOANLOSS_PROVISIONING("Generate Loan Loss Provisioning"), //
     POST_DIVIDENTS_FOR_SHARES("Post Dividends For Shares"), //
+    FORFEIT_UNCLAIMED_DIVIDENDS("Forfeit Unclaimed Dividends"), //
     UPDATE_SAVINGS_DORMANT_ACCOUNTS("Update Savings Dormant Accounts"), //
     ADD_PERIODIC_ACCRUAL_ENTRIES_FOR_LOANS_WITH_INCOME_POSTED_AS_TRANSACTIONS(
             "Add Accrual Transactions For Loans With Income Posted As Transactions"), //
@@ -64,6 +65,9 @@ public enum JobName {
     IMPS_DEEMED_RECONCILE("IMPS DEEMED Reconciliation"), //
     NEFT_BATCH_PROCESS("NEFT Batch Process"), //
     VERIFICATION_TOKEN_CLEANUP("Verification Token Cleanup"), //
+    OUTWARD_CLEARING_BATCH_SEND("CTS Outward Clearing Batch Send"), //
+    CTR_REPORT_GENERATION("AML Monthly CTR Report Generation"), //
+    AML_STR_WEEKLY_DIGEST("AML STR Weekly Digest"), //
     ; //
 
     private final String name;

fineract-core/src/main/java/org/apache/fineract/organisation/agent/data/AgentData.java

@@ -0,0 +1,148 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.Collection;
+import lombok.Getter;
+
+/**
+ * Immutable data object representing a DDS agent, including its collection-limit history and
+ * guarantors. Carries the collection/commission/security-account fields merged in from SubAgent
+ * (2026-08-24) - Agent now does the daily collection work directly.
+ */
+@Getter
+public final class AgentData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long clientId;
+    private final String clientName;
+    private final String agentCode;
+    private final String agentNameId;
+    private final String agentAddress1;
+    private final String agentAddress2;
+    private final String agentCity;
+    private final String agentPinCode;
+    private final String agentTelephone;
+    private final String agentSavingAccountType;
+    private final String agentSavingAccountNo;
+    private final LocalDate agentOpeningDate;
+    private final LocalDate agentBirthDate;
+    private final BigDecimal agentCurrentBalance;
+    private final BigDecimal agentOpeningBalance;
+    private final String homeBranch;
+    private final String savingBranch;
+    private final Boolean tdsApplicable;
+    private final BigDecimal tdsPercent;
+    private final BigDecimal currentTds;
+    private final BigDecimal tdsAmount;
+    private final String transferBranch;
+    private final String transferAmountAccountType;
+    private final String transferAccountNo;
+    private final Boolean commissionCalculation;
+    private final BigDecimal limit;
+    private final BigDecimal machineRent;
+    private final String agentSecurityBranch;
+    private final String agentSecurityAccountType;
+    private final String agentSecurityAccountNo;
+    private final BigDecimal commission;
+    private final BigDecimal otherCommission;
+    private final BigDecimal agentDeposit;
+    private final BigDecimal festivalAdvance;
+    private final BigDecimal otherDeduction;
+    private final Collection<AgentLimitData> limits;
+    private final Collection<AgentGuarantorData> guarantors;
+
+    public static AgentData instance(final Long id, final Long clientId, final String clientName, final String agentCode,
+            final String agentNameId, final String agentAddress1, final String agentAddress2, final String agentCity,
+            final String agentPinCode, final String agentTelephone, final String agentSavingAccountType,
+            final String agentSavingAccountNo, final LocalDate agentOpeningDate, final LocalDate agentBirthDate,
+            final BigDecimal agentCurrentBalance, final BigDecimal agentOpeningBalance, final String homeBranch,
+            final String savingBranch, final Boolean tdsApplicable, final BigDecimal tdsPercent, final BigDecimal currentTds,
+            final BigDecimal tdsAmount, final String transferBranch, final String transferAmountAccountType,
+            final String transferAccountNo, final Boolean commissionCalculation, final BigDecimal limit, final BigDecimal machineRent,
+            final String agentSecurityBranch, final String agentSecurityAccountType, final String agentSecurityAccountNo,
+            final BigDecimal commission, final BigDecimal otherCommission, final BigDecimal agentDeposit,
+            final BigDecimal festivalAdvance, final BigDecimal otherDeduction, final Collection<AgentLimitData> limits,
+            final Collection<AgentGuarantorData> guarantors) {
+        return new AgentData(id, clientId, clientName, agentCode, agentNameId, agentAddress1, agentAddress2, agentCity, agentPinCode,
+                agentTelephone, agentSavingAccountType, agentSavingAccountNo, agentOpeningDate, agentBirthDate, agentCurrentBalance,
+                agentOpeningBalance, homeBranch, savingBranch, tdsApplicable, tdsPercent, currentTds, tdsAmount, transferBranch,
+                transferAmountAccountType, transferAccountNo, commissionCalculation, limit, machineRent, agentSecurityBranch,
+                agentSecurityAccountType, agentSecurityAccountNo, commission, otherCommission, agentDeposit, festivalAdvance,
+                otherDeduction, limits, guarantors);
+    }
+
+    private AgentData(final Long id, final Long clientId, final String clientName, final String agentCode, final String agentNameId,
+            final String agentAddress1, final String agentAddress2, final String agentCity, final String agentPinCode,
+            final String agentTelephone, final String agentSavingAccountType, final String agentSavingAccountNo,
+            final LocalDate agentOpeningDate, final LocalDate agentBirthDate, final BigDecimal agentCurrentBalance,
+            final BigDecimal agentOpeningBalance, final String homeBranch, final String savingBranch, final Boolean tdsApplicable,
+            final BigDecimal tdsPercent, final BigDecimal currentTds, final BigDecimal tdsAmount, final String transferBranch,
+            final String transferAmountAccountType, final String transferAccountNo, final Boolean commissionCalculation,
+            final BigDecimal limit, final BigDecimal machineRent, final String agentSecurityBranch,
+            final String agentSecurityAccountType, final String agentSecurityAccountNo, final BigDecimal commission,
+            final BigDecimal otherCommission, final BigDecimal agentDeposit, final BigDecimal festivalAdvance,
+            final BigDecimal otherDeduction, final Collection<AgentLimitData> limits, final Collection<AgentGuarantorData> guarantors) {
+        this.id = id;
+        this.clientId = clientId;
+        this.clientName = clientName;
+        this.agentCode = agentCode;
+        this.agentNameId = agentNameId;
+        this.agentAddress1 = agentAddress1;
+        this.agentAddress2 = agentAddress2;
+        this.agentCity = agentCity;
+        this.agentPinCode = agentPinCode;
+        this.agentTelephone = agentTelephone;
+        this.agentSavingAccountType = agentSavingAccountType;
+        this.agentSavingAccountNo = agentSavingAccountNo;
+        this.agentOpeningDate = agentOpeningDate;
+        this.agentBirthDate = agentBirthDate;
+        this.agentCurrentBalance = agentCurrentBalance;
+        this.agentOpeningBalance = agentOpeningBalance;
+        this.homeBranch = homeBranch;
+        this.savingBranch = savingBranch;
+        this.tdsApplicable = tdsApplicable;
+        this.tdsPercent = tdsPercent;
+        this.currentTds = currentTds;
+        this.tdsAmount = tdsAmount;
+        this.transferBranch = transferBranch;
+        this.transferAmountAccountType = transferAmountAccountType;
+        this.transferAccountNo = transferAccountNo;
+        this.commissionCalculation = commissionCalculation;
+        this.limit = limit;
+        this.machineRent = machineRent;
+        this.agentSecurityBranch = agentSecurityBranch;
+        this.agentSecurityAccountType = agentSecurityAccountType;
+        this.agentSecurityAccountNo = agentSecurityAccountNo;
+        this.commission = commission;
+        this.otherCommission = otherCommission;
+        this.agentDeposit = agentDeposit;
+        this.festivalAdvance = festivalAdvance;
+        this.otherDeduction = otherDeduction;
+        this.limits = limits;
+        this.guarantors = guarantors;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/data/AgentGuarantorData.java

@@ -0,0 +1,59 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import lombok.Getter;
+
+/**
+ * Immutable data object representing a single agent guarantor.
+ */
+@Getter
+public final class AgentGuarantorData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long clientId;
+    private final String guarantorName;
+    private final String address1;
+    private final String address2;
+    private final String city;
+    private final String pinCode;
+    private final String telephone;
+
+    public static AgentGuarantorData instance(final Long id, final Long clientId, final String guarantorName, final String address1,
+            final String address2, final String city, final String pinCode, final String telephone) {
+        return new AgentGuarantorData(id, clientId, guarantorName, address1, address2, city, pinCode, telephone);
+    }
+
+    private AgentGuarantorData(final Long id, final Long clientId, final String guarantorName, final String address1,
+            final String address2, final String city, final String pinCode, final String telephone) {
+        this.id = id;
+        this.clientId = clientId;
+        this.guarantorName = guarantorName;
+        this.address1 = address1;
+        this.address2 = address2;
+        this.city = city;
+        this.pinCode = pinCode;
+        this.telephone = telephone;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/data/AgentLimitData.java

@@ -0,0 +1,48 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+
+@Getter
+public final class AgentLimitData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final LocalDate fromDate;
+    private final LocalDate toDate;
+    private final BigDecimal limit;
+
+    public static AgentLimitData instance(final Long id, final LocalDate fromDate, final LocalDate toDate, final BigDecimal limit) {
+        return new AgentLimitData(id, fromDate, toDate, limit);
+    }
+
+    private AgentLimitData(final Long id, final LocalDate fromDate, final LocalDate toDate, final BigDecimal limit) {
+        this.id = id;
+        this.fromDate = fromDate;
+        this.toDate = toDate;
+        this.limit = limit;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/domain/Agent.java

@@ -0,0 +1,440 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.domain;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+import org.apache.fineract.portfolio.client.domain.Client;
+
+/**
+ * A DDS (Daily Deposit Scheme) collection agent. Can represent either a person or, at the top of the
+ * hierarchy, the bank itself acting as its own agent. Holds its own settlement savings account and one
+ * or more guarantors.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_agent", uniqueConstraints = { @UniqueConstraint(columnNames = { "agent_code" }, name = "agent_code_UNIQUE") })
+public class Agent extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @Column(name = "agent_code", length = 20, nullable = false)
+    private String agentCode;
+
+    @Column(name = "agent_name", length = 100, nullable = false)
+    private String agentName;
+
+    @Column(name = "agent_address1", length = 200, nullable = false)
+    private String agentAddress1;
+
+    @Column(name = "agent_address2", length = 200)
+    private String agentAddress2;
+
+    @Column(name = "agent_city", length = 100, nullable = false)
+    private String agentCity;
+
+    @Column(name = "agent_pincode", length = 20, nullable = false)
+    private String agentPinCode;
+
+    @Column(name = "agent_telephone", length = 20)
+    private String agentTelephone;
+
+    @Column(name = "agent_saving_account_type", length = 100, nullable = false)
+    private String agentSavingAccountType;
+
+    @Column(name = "agent_saving_account_no", length = 50, nullable = false)
+    private String agentSavingAccountNo;
+
+    @Column(name = "agent_opening_date", nullable = false)
+    private LocalDate agentOpeningDate;
+
+    @Column(name = "agent_birth_date", nullable = false)
+    private LocalDate agentBirthDate;
+
+    @Column(name = "agent_current_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal agentCurrentBalance;
+
+    @Column(name = "agent_opening_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal agentOpeningBalance;
+
+    // Fields below were merged in from SubAgent (2026-08-24) - the Agent itself now does the daily
+    // collection work directly; SubAgent no longer exists as a separate tier. Ag.Level / Upper Ag.Level
+    // / Collector (MLM) / CRPB Points / Level Update Date were dropped - they only ever meant anything
+    // for a multi-level hierarchy, which no longer exists here.
+    @Column(name = "home_branch", length = 100, nullable = false)
+    private String homeBranch;
+
+    @Column(name = "saving_branch", length = 100, nullable = false)
+    private String savingBranch;
+
+    @Column(name = "tds_applicable", nullable = false)
+    private boolean tdsApplicable;
+
+    @Column(name = "tds_percent", scale = 6, precision = 19)
+    private BigDecimal tdsPercent;
+
+    @Column(name = "current_tds", scale = 6, precision = 19, nullable = false)
+    private BigDecimal currentTds;
+
+    @Column(name = "tds_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal tdsAmount;
+
+    @Column(name = "transfer_branch", length = 100)
+    private String transferBranch;
+
+    @Column(name = "transfer_amount_account_type", length = 100)
+    private String transferAmountAccountType;
+
+    @Column(name = "transfer_account_no", length = 50)
+    private String transferAccountNo;
+
+    @Column(name = "collector_commission_calculation", nullable = false)
+    private boolean commissionCalculation;
+
+    @Column(name = "collector_limit_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal limitAmount;
+
+    @Column(name = "machine_rent", scale = 6, precision = 19, nullable = false)
+    private BigDecimal machineRent;
+
+    @Column(name = "agent_security_branch", length = 100)
+    private String agentSecurityBranch;
+
+    @Column(name = "agent_security_account_type", length = 100)
+    private String agentSecurityAccountType;
+
+    @Column(name = "agent_security_account_no", length = 50)
+    private String agentSecurityAccountNo;
+
+    @Column(name = "commission", scale = 6, precision = 19, nullable = false)
+    private BigDecimal commission;
+
+    @Column(name = "other_commission", scale = 6, precision = 19, nullable = false)
+    private BigDecimal otherCommission;
+
+    @Column(name = "agent_deposit", scale = 6, precision = 19, nullable = false)
+    private BigDecimal agentDeposit;
+
+    @Column(name = "festival_advance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal festivalAdvance;
+
+    @Column(name = "other_deduction", scale = 6, precision = 19, nullable = false)
+    private BigDecimal otherDeduction;
+
+    @Column(name = "last_commission_date")
+    private LocalDate lastCommissionDate;
+
+    @OneToMany(mappedBy = "agent", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+    @OrderBy("id")
+    private List<AgentGuarantor> guarantors = new ArrayList<>();
+
+    @OneToMany(mappedBy = "agent", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+    @OrderBy("id")
+    private List<AgentLimit> limits = new ArrayList<>();
+
+    protected Agent() {
+        //
+    }
+
+    private Agent(final Client client, final String agentCode, final String agentName, final String agentAddress1,
+            final String agentAddress2, final String agentCity, final String agentPinCode, final String agentTelephone,
+            final String agentSavingAccountType, final String agentSavingAccountNo, final LocalDate agentOpeningDate,
+            final LocalDate agentBirthDate, final BigDecimal agentOpeningBalance, final JsonCommand command) {
+        this.client = client;
+        this.agentCode = agentCode;
+        this.agentName = agentName;
+        this.agentAddress1 = agentAddress1;
+        this.agentAddress2 = StringUtils.defaultIfEmpty(agentAddress2, null);
+        this.agentCity = agentCity;
+        this.agentPinCode = agentPinCode;
+        this.agentTelephone = StringUtils.defaultIfEmpty(agentTelephone, null);
+        this.agentSavingAccountType = agentSavingAccountType;
+        this.agentSavingAccountNo = agentSavingAccountNo;
+        this.agentOpeningDate = agentOpeningDate;
+        this.agentBirthDate = agentBirthDate;
+        this.agentOpeningBalance = agentOpeningBalance == null ? BigDecimal.ZERO : agentOpeningBalance;
+        this.agentCurrentBalance = this.agentOpeningBalance;
+
+        this.homeBranch = command.stringValueOfParameterNamed("homeBranch");
+        this.savingBranch = command.stringValueOfParameterNamed("savingBranch");
+        this.tdsApplicable = command.booleanPrimitiveValueOfParameterNamed("tdsApplicable");
+        this.tdsPercent = command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("tdsPercent");
+        this.currentTds = BigDecimal.ZERO;
+        this.tdsAmount = BigDecimal.ZERO;
+        this.transferBranch = StringUtils.defaultIfEmpty(command.stringValueOfParameterNamedAllowingNull("transferBranch"), null);
+        this.transferAmountAccountType = StringUtils
+                .defaultIfEmpty(command.stringValueOfParameterNamedAllowingNull("transferAmountAccountType"), null);
+        this.transferAccountNo = StringUtils.defaultIfEmpty(command.stringValueOfParameterNamedAllowingNull("transferAccountNo"), null);
+        this.commissionCalculation = command.booleanPrimitiveValueOfParameterNamed("commissionCalculation");
+        this.limitAmount = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("limit"));
+        this.machineRent = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("machineRent"));
+        this.agentSecurityBranch = StringUtils.defaultIfEmpty(command.stringValueOfParameterNamedAllowingNull("agentSecurityBranch"),
+                null);
+        this.agentSecurityAccountType = StringUtils
+                .defaultIfEmpty(command.stringValueOfParameterNamedAllowingNull("agentSecurityAccountType"), null);
+        this.agentSecurityAccountNo = StringUtils.defaultIfEmpty(command.stringValueOfParameterNamedAllowingNull("agentSecurityAccountNo"),
+                null);
+        this.commission = BigDecimal.ZERO;
+        this.otherCommission = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("otherCommission"));
+        this.agentDeposit = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("agentDeposit"));
+        this.festivalAdvance = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("festivalAdvance"));
+        this.otherDeduction = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("otherDeduction"));
+    }
+
+    public static Agent fromJson(final Client client, final String agentCode, final JsonCommand command) {
+        final String agentName = command.stringValueOfParameterNamed("agentNameId");
+        final String agentAddress1 = command.stringValueOfParameterNamed("agentAddress1");
+        final String agentAddress2 = command.stringValueOfParameterNamedAllowingNull("agentAddress2");
+        final String agentCity = command.stringValueOfParameterNamed("agentCity");
+        final String agentPinCode = command.stringValueOfParameterNamed("agentPinCode");
+        final String agentTelephone = command.stringValueOfParameterNamedAllowingNull("agentTelephone");
+        final String agentSavingAccountType = command.stringValueOfParameterNamed("agentSavingAccountType");
+        final String agentSavingAccountNo = command.stringValueOfParameterNamed("agentSavingAccountNo");
+        final LocalDate agentOpeningDate = command.localDateValueOfParameterNamed("agentOpeningDate");
+        final LocalDate agentBirthDate = command.localDateValueOfParameterNamed("agentBirthDate");
+        final BigDecimal agentOpeningBalance = command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("agentOpeningBalance");
+
+        return new Agent(client, agentCode, agentName, agentAddress1, agentAddress2, agentCity, agentPinCode, agentTelephone,
+                agentSavingAccountType, agentSavingAccountNo, agentOpeningDate, agentBirthDate, agentOpeningBalance, command);
+    }
+
+    private static BigDecimal orZero(final BigDecimal value) {
+        return value == null ? BigDecimal.ZERO : value;
+    }
+
+    public void addGuarantor(final AgentGuarantor guarantor) {
+        guarantor.setAgent(this);
+        this.guarantors.add(guarantor);
+    }
+
+    public void resetGuarantors() {
+        this.guarantors.clear();
+    }
+
+    public void addLimit(final AgentLimit limit) {
+        limit.setAgent(this);
+        this.limits.add(limit);
+    }
+
+    public void resetLimits() {
+        this.limits.clear();
+    }
+
+    /**
+     * Adds a Commission Posting's amount to this agent's running commission total and stamps the date
+     * commission was last calculated through, so the next Commission Calculation batch only covers
+     * collections since then.
+     */
+    public void postCommission(final BigDecimal amount, final LocalDate throughDate) {
+        this.commission = this.commission.add(amount);
+        this.lastCommissionDate = throughDate;
+    }
+
+    /**
+     * Cash this agent has collected from parties but not yet handed over to a branch (an Agent Tran
+     * settlement). Raised by a Party Tran collection, lowered by an Agent Tran settlement - this is the
+     * figure an Agent's collection limit is enforced against.
+     */
+    public BigDecimal credit(final BigDecimal amount) {
+        this.agentCurrentBalance = this.agentCurrentBalance.add(amount);
+        return this.agentCurrentBalance;
+    }
+
+    public BigDecimal settle(final BigDecimal amount) {
+        this.agentCurrentBalance = this.agentCurrentBalance.subtract(amount);
+        return this.agentCurrentBalance;
+    }
+
+    public void changeClient(final Client newClient) {
+        this.client = newClient;
+    }
+
+    public Long clientId() {
+        return this.client.getId();
+    }
+
+    public Map<String, Object> update(final JsonCommand command) {
+
+        final Map<String, Object> actualChanges = new LinkedHashMap<>(10);
+
+        if (command.isChangeInLongParameterNamed("clientId", this.client.getId())) {
+            actualChanges.put("clientId", command.longValueOfParameterNamed("clientId"));
+        }
+
+        if (command.isChangeInStringParameterNamed("agentNameId", this.agentName)) {
+            final String newValue = command.stringValueOfParameterNamed("agentNameId");
+            actualChanges.put("agentNameId", newValue);
+            this.agentName = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentAddress1", this.agentAddress1)) {
+            final String newValue = command.stringValueOfParameterNamed("agentAddress1");
+            actualChanges.put("agentAddress1", newValue);
+            this.agentAddress1 = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentAddress2", this.agentAddress2)) {
+            final String newValue = command.stringValueOfParameterNamed("agentAddress2");
+            actualChanges.put("agentAddress2", newValue);
+            this.agentAddress2 = StringUtils.defaultIfEmpty(newValue, null);
+        }
+
+        if (command.isChangeInStringParameterNamed("agentCity", this.agentCity)) {
+            final String newValue = command.stringValueOfParameterNamed("agentCity");
+            actualChanges.put("agentCity", newValue);
+            this.agentCity = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentPinCode", this.agentPinCode)) {
+            final String newValue = command.stringValueOfParameterNamed("agentPinCode");
+            actualChanges.put("agentPinCode", newValue);
+            this.agentPinCode = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentTelephone", this.agentTelephone)) {
+            final String newValue = command.stringValueOfParameterNamed("agentTelephone");
+            actualChanges.put("agentTelephone", newValue);
+            this.agentTelephone = StringUtils.defaultIfEmpty(newValue, null);
+        }
+
+        if (command.isChangeInStringParameterNamed("agentSavingAccountType", this.agentSavingAccountType)) {
+            final String newValue = command.stringValueOfParameterNamed("agentSavingAccountType");
+            actualChanges.put("agentSavingAccountType", newValue);
+            this.agentSavingAccountType = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentSavingAccountNo", this.agentSavingAccountNo)) {
+            final String newValue = command.stringValueOfParameterNamed("agentSavingAccountNo");
+            actualChanges.put("agentSavingAccountNo", newValue);
+            this.agentSavingAccountNo = newValue;
+        }
+
+        if (command.isChangeInDateParameterNamed("agentOpeningDate", this.agentOpeningDate)) {
+            actualChanges.put("agentOpeningDate", command.stringValueOfParameterNamed("agentOpeningDate"));
+            this.agentOpeningDate = command.localDateValueOfParameterNamed("agentOpeningDate");
+        }
+
+        if (command.isChangeInDateParameterNamed("agentBirthDate", this.agentBirthDate)) {
+            actualChanges.put("agentBirthDate", command.stringValueOfParameterNamed("agentBirthDate"));
+            this.agentBirthDate = command.localDateValueOfParameterNamed("agentBirthDate");
+        }
+
+        stringChange(command, actualChanges, "homeBranch", this.homeBranch, v -> this.homeBranch = v);
+        stringChange(command, actualChanges, "savingBranch", this.savingBranch, v -> this.savingBranch = v);
+
+        if (command.isChangeInBooleanParameterNamed("tdsApplicable", this.tdsApplicable)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("tdsApplicable");
+            actualChanges.put("tdsApplicable", newValue);
+            this.tdsApplicable = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("tdsPercent", this.tdsPercent)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("tdsPercent");
+            actualChanges.put("tdsPercent", newValue);
+            this.tdsPercent = newValue;
+        }
+
+        stringChange(command, actualChanges, "transferBranch", this.transferBranch,
+                v -> this.transferBranch = StringUtils.defaultIfEmpty(v, null));
+        stringChange(command, actualChanges, "transferAmountAccountType", this.transferAmountAccountType,
+                v -> this.transferAmountAccountType = StringUtils.defaultIfEmpty(v, null));
+        stringChange(command, actualChanges, "transferAccountNo", this.transferAccountNo,
+                v -> this.transferAccountNo = StringUtils.defaultIfEmpty(v, null));
+
+        if (command.isChangeInBooleanParameterNamed("commissionCalculation", this.commissionCalculation)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("commissionCalculation");
+            actualChanges.put("commissionCalculation", newValue);
+            this.commissionCalculation = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("limit", this.limitAmount)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("limit");
+            actualChanges.put("limit", newValue);
+            this.limitAmount = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("machineRent", this.machineRent)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("machineRent");
+            actualChanges.put("machineRent", newValue);
+            this.machineRent = newValue;
+        }
+
+        stringChange(command, actualChanges, "agentSecurityBranch", this.agentSecurityBranch,
+                v -> this.agentSecurityBranch = StringUtils.defaultIfEmpty(v, null));
+        stringChange(command, actualChanges, "agentSecurityAccountType", this.agentSecurityAccountType,
+                v -> this.agentSecurityAccountType = StringUtils.defaultIfEmpty(v, null));
+        stringChange(command, actualChanges, "agentSecurityAccountNo", this.agentSecurityAccountNo,
+                v -> this.agentSecurityAccountNo = StringUtils.defaultIfEmpty(v, null));
+
+        if (command.isChangeInBigDecimalParameterNamed("otherCommission", this.otherCommission)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("otherCommission");
+            actualChanges.put("otherCommission", newValue);
+            this.otherCommission = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("agentDeposit", this.agentDeposit)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("agentDeposit");
+            actualChanges.put("agentDeposit", newValue);
+            this.agentDeposit = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("festivalAdvance", this.festivalAdvance)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("festivalAdvance");
+            actualChanges.put("festivalAdvance", newValue);
+            this.festivalAdvance = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("otherDeduction", this.otherDeduction)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("otherDeduction");
+            actualChanges.put("otherDeduction", newValue);
+            this.otherDeduction = newValue;
+        }
+
+        return actualChanges;
+    }
+
+    private void stringChange(final JsonCommand command, final Map<String, Object> actualChanges, final String paramName,
+            final String existingValue, final java.util.function.Consumer<String> setter) {
+        if (command.isChangeInStringParameterNamed(paramName, existingValue)) {
+            final String newValue = command.stringValueOfParameterNamed(paramName);
+            actualChanges.put(paramName, newValue);
+            setter.accept(newValue);
+        }
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/domain/AgentGuarantor.java

@@ -0,0 +1,83 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+
+/**
+ * A single guarantor recorded against an {@link Agent} (or, reused with the same shape, against a
+ * SubAgent). Always created/replaced as part of its parent agent's own create/update command - it has
+ * no independent API of its own.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_agent_guarantor")
+public class AgentGuarantor extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    @Column(name = "client_id", nullable = false)
+    private Long clientId;
+
+    @Column(name = "guarantor_name", length = 100, nullable = false)
+    private String guarantorName;
+
+    @Column(name = "address1", length = 200, nullable = false)
+    private String address1;
+
+    @Column(name = "address2", length = 200)
+    private String address2;
+
+    @Column(name = "city", length = 100, nullable = false)
+    private String city;
+
+    @Column(name = "pin_code", length = 20, nullable = false)
+    private String pinCode;
+
+    @Column(name = "telephone", length = 20)
+    private String telephone;
+
+    protected AgentGuarantor() {
+        //
+    }
+
+    public AgentGuarantor(final Long clientId, final String guarantorName, final String address1, final String address2,
+            final String city, final String pinCode, final String telephone) {
+        this.clientId = clientId;
+        this.guarantorName = guarantorName;
+        this.address1 = address1;
+        this.address2 = StringUtils.defaultIfEmpty(address2, null);
+        this.city = city;
+        this.pinCode = pinCode;
+        this.telephone = StringUtils.defaultIfEmpty(telephone, null);
+    }
+
+    void setAgent(final Agent agent) {
+        this.agent = agent;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/domain/AgentLimit.java

@@ -0,0 +1,66 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+
+/**
+ * One row of an Agent's time-bound collection-limit history (From Date / To Date / Limit) - an
+ * Agent's authorized collection limit can change over time and every change is kept, not overwritten.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_agent_limit")
+public class AgentLimit extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    @Column(name = "from_date", nullable = false)
+    private LocalDate fromDate;
+
+    @Column(name = "to_date", nullable = false)
+    private LocalDate toDate;
+
+    @Column(name = "limit_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal limitAmount;
+
+    protected AgentLimit() {
+        //
+    }
+
+    public AgentLimit(final LocalDate fromDate, final LocalDate toDate, final BigDecimal limitAmount) {
+        this.fromDate = fromDate;
+        this.toDate = toDate;
+        this.limitAmount = limitAmount;
+    }
+
+    void setAgent(final Agent agent) {
+        this.agent = agent;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentNotFoundException.java

@@ -0,0 +1,40 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+import org.springframework.dao.EmptyResultDataAccessException;
+
+/**
+ * A {@link RuntimeException} thrown when a DDS agent resource is not found.
+ */
+public class AgentNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public AgentNotFoundException(final Long id) {
+        super("error.msg.agent.id.invalid", "Agent with identifier " + id + " does not exist", id);
+    }
+
+    public AgentNotFoundException(final Long id, final EmptyResultDataAccessException e) {
+        super("error.msg.agent.id.invalid", "Agent with identifier " + id + " does not exist", id, e);
+    }
+
+    public AgentNotFoundException(final String agentCode) {
+        super("error.msg.agent.code.invalid", "Agent with code " + agentCode + " does not exist", agentCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/commissionslab/data/CommissionSlabData.java

@@ -0,0 +1,39 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.commissionslab.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+public final class CommissionSlabData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final String slabType;
+    private final BigDecimal slabFrom;
+    private final BigDecimal slabTo;
+    private final BigDecimal commissionPercent;
+}

fineract-core/src/main/java/org/apache/fineract/organisation/commissionslab/domain/CommissionSlab.java

@@ -0,0 +1,61 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.commissionslab.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+
+/**
+ * One row of the agent commission chart: an ACCOUNT slab (commission percentage on collection
+ * volume) or a COMMISSION slab (the override a senior agent earns on a sub-agent's commission).
+ * Append-only reference data, like the legacy screen it replaces - there is deliberately no update or
+ * delete API; a superseded slab range is retired by adding a new row, not editing history.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_commission_slab")
+public class CommissionSlab extends AbstractPersistableCustom<Long> {
+
+    @Column(name = "slab_type", length = 20, nullable = false)
+    private String slabType;
+
+    @Column(name = "slab_from", scale = 6, precision = 19, nullable = false)
+    private BigDecimal slabFrom;
+
+    @Column(name = "slab_to", scale = 6, precision = 19, nullable = false)
+    private BigDecimal slabTo;
+
+    @Column(name = "commission_percent", scale = 6, precision = 19, nullable = false)
+    private BigDecimal commissionPercent;
+
+    protected CommissionSlab() {
+        //
+    }
+
+    public CommissionSlab(final String slabType, final BigDecimal slabFrom, final BigDecimal slabTo, final BigDecimal commissionPercent) {
+        this.slabType = slabType;
+        this.slabFrom = slabFrom;
+        this.slabTo = slabTo;
+        this.commissionPercent = commissionPercent;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlert.java

@@ -0,0 +1,160 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.useradministration.domain.AppUser;
+
+/**
+ * One row per {@link AmlTransactionRule} hit on a live transaction. Raised regardless of the
+ * client's current KYC risk category - alerting is never suppressed by a client being Low/Medium
+ * risk. First reviewed by an AML Officer (whitelist or escalate); an ESCALATED alert spawns an
+ * {@link AmlStrCase} for the Principal Officer.
+ */
+@Entity
+@Table(name = "m_aml_alert")
+public class AmlAlert extends AbstractAuditableWithUTCDateTimeCustom<Long> {
+
+    @Column(name = "transaction_type", nullable = false, length = 20)
+    private String transactionType;
+
+    @Column(name = "transaction_id", nullable = false)
+    private Long transactionId;
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @ManyToOne
+    @JoinColumn(name = "rule_id", nullable = false)
+    private AmlTransactionRule rule;
+
+    @Column(name = "amount", nullable = false, precision = 19, scale = 6)
+    private BigDecimal amount;
+
+    @Column(name = "currency_code", length = 3)
+    private String currencyCode;
+
+    @Column(name = "raised_on", nullable = false)
+    private LocalDateTime raisedOn;
+
+    @Column(name = "status", nullable = false, length = 20)
+    private String status;
+
+    @ManyToOne
+    @JoinColumn(name = "reviewed_by")
+    private AppUser reviewedBy;
+
+    @Column(name = "reviewed_on")
+    private LocalDateTime reviewedOn;
+
+    @Column(name = "review_notes", length = 1000)
+    private String reviewNotes;
+
+    @Column(name = "disposition", length = 20)
+    private String disposition;
+
+    protected AmlAlert() {}
+
+    public static AmlAlert raise(AmlTransactionType transactionType, Long transactionId, Client client, AmlTransactionRule rule,
+            BigDecimal amount, String currencyCode, LocalDateTime raisedOn) {
+        final AmlAlert alert = new AmlAlert();
+        alert.transactionType = transactionType.name();
+        alert.transactionId = transactionId;
+        alert.client = client;
+        alert.rule = rule;
+        alert.amount = amount;
+        alert.currencyCode = currencyCode;
+        alert.raisedOn = raisedOn;
+        alert.status = AmlAlertStatus.RAISED.name();
+        return alert;
+    }
+
+    public void whitelist(AppUser reviewer, String notes) {
+        this.reviewedBy = reviewer;
+        this.reviewedOn = LocalDateTime.now();
+        this.reviewNotes = notes;
+        this.disposition = AmlAlertDisposition.WHITELIST.name();
+        this.status = AmlAlertStatus.WHITELISTED.name();
+    }
+
+    public void escalate(AppUser reviewer, String notes) {
+        this.reviewedBy = reviewer;
+        this.reviewedOn = LocalDateTime.now();
+        this.reviewNotes = notes;
+        this.disposition = AmlAlertDisposition.ESCALATE.name();
+        this.status = AmlAlertStatus.ESCALATED.name();
+    }
+
+    public Long getTransactionId() {
+        return transactionId;
+    }
+
+    public AmlTransactionType getTransactionType() {
+        return AmlTransactionType.valueOf(transactionType);
+    }
+
+    public Client getClient() {
+        return client;
+    }
+
+    public AmlTransactionRule getRule() {
+        return rule;
+    }
+
+    public BigDecimal getAmount() {
+        return amount;
+    }
+
+    public String getCurrencyCode() {
+        return currencyCode;
+    }
+
+    public LocalDateTime getRaisedOn() {
+        return raisedOn;
+    }
+
+    public AmlAlertStatus getStatus() {
+        return AmlAlertStatus.valueOf(status);
+    }
+
+    public AppUser getReviewedBy() {
+        return reviewedBy;
+    }
+
+    public LocalDateTime getReviewedOn() {
+        return reviewedOn;
+    }
+
+    public String getReviewNotes() {
+        return reviewNotes;
+    }
+
+    public AmlAlertDisposition getDisposition() {
+        return disposition == null ? null : AmlAlertDisposition.valueOf(disposition);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlertDisposition.java

@@ -0,0 +1,25 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+/** The AML Officer's first-level disposition of an {@link AmlAlert}. */
+public enum AmlAlertDisposition {
+
+    WHITELIST, ESCALATE
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlertRepository.java

@@ -0,0 +1,47 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+public interface AmlAlertRepository extends JpaRepository<AmlAlert, Long> {
+
+    List<AmlAlert> findByStatusOrderByRaisedOnAsc(String status);
+
+    @Query("SELECT COALESCE(SUM(a.amount), 0) FROM AmlAlert a WHERE a.client.id = :clientId "
+            + "AND a.transactionType = :transactionType AND a.raisedOn >= :since")
+    BigDecimal sumAmountForClientSince(@Param("clientId") Long clientId, @Param("transactionType") String transactionType,
+            @Param("since") LocalDateTime since);
+
+    long countByClientId(Long clientId);
+
+    /** Alerts for one customer inside the recurring-behaviour observation window. */
+    long countByClient_IdAndRaisedOnGreaterThanEqual(Long clientId, LocalDateTime since);
+
+    /**
+     * Alerts already raised against one transaction under one rule. Used to stop the same ledger entry being marked
+     * twice, which would put two STR cases in front of the Principal Officer for a single transaction.
+     */
+    List<AmlAlert> findByRule_IdAndTransactionId(Long ruleId, Long transactionId);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlertStatus.java

@@ -0,0 +1,24 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+public enum AmlAlertStatus {
+
+    RAISED, UNDER_REVIEW, WHITELISTED, ESCALATED
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAppliesTo.java

@@ -0,0 +1,29 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+/** Which transaction type(s) an {@link AmlTransactionRule} evaluates against. */
+public enum AmlAppliesTo {
+
+    SAVINGS, LOAN, TRANSFER, ALL;
+
+    public boolean matches(AmlTransactionType transactionType) {
+        return this == ALL || this.name().equals(transactionType.name());
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlCtrReport.java

@@ -0,0 +1,97 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+
+/**
+ * Monthly, mechanical CTR batch header - purely threshold-based (₹10L+ cash, individually or
+ * connected), no Principal Officer judgment involved. One row per calendar month.
+ */
+@Entity
+@Table(name = "m_aml_ctr_report")
+public class AmlCtrReport extends AbstractAuditableWithUTCDateTimeCustom<Long> {
+
+    @Column(name = "report_month", nullable = false, length = 7)
+    private String reportMonth;
+
+    @Column(name = "generated_on", nullable = false)
+    private LocalDateTime generatedOn;
+
+    @Column(name = "record_count", nullable = false)
+    private int recordCount;
+
+    @Column(name = "file_reference", length = 150)
+    private String fileReference;
+
+    @Column(name = "status", nullable = false, length = 20)
+    private String status;
+
+    @Column(name = "submitted_on")
+    private LocalDateTime submittedOn;
+
+    protected AmlCtrReport() {}
+
+    public static AmlCtrReport draft(String reportMonth, LocalDateTime generatedOn, int recordCount) {
+        final AmlCtrReport report = new AmlCtrReport();
+        report.reportMonth = reportMonth;
+        report.generatedOn = generatedOn;
+        report.recordCount = recordCount;
+        report.status = AmlCtrReportStatus.DRAFT.name();
+        return report;
+    }
+
+    public void markGenerated(String fileReference) {
+        this.fileReference = fileReference;
+        this.status = AmlCtrReportStatus.GENERATED.name();
+    }
+
+    public void markSubmitted(LocalDateTime submittedOn) {
+        this.submittedOn = submittedOn;
+        this.status = AmlCtrReportStatus.SUBMITTED.name();
+    }
+
+    public String getReportMonth() {
+        return reportMonth;
+    }
+
+    public LocalDateTime getGeneratedOn() {
+        return generatedOn;
+    }
+
+    public int getRecordCount() {
+        return recordCount;
+    }
+
+    public String getFileReference() {
+        return fileReference;
+    }
+
+    public AmlCtrReportStatus getStatus() {
+        return AmlCtrReportStatus.valueOf(status);
+    }
+
+    public LocalDateTime getSubmittedOn() {
+        return submittedOn;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlCtrReportLine.java

@@ -0,0 +1,103 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+
+/**
+ * One line per transaction (or connected-transaction group, when {@link #connectedGroup} is true)
+ * feeding a monthly {@link AmlCtrReport}.
+ */
+@Entity
+@Table(name = "m_aml_ctr_report_line")
+public class AmlCtrReportLine {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne
+    @JoinColumn(name = "ctr_report_id", nullable = false)
+    private AmlCtrReport ctrReport;
+
+    @Column(name = "transaction_type", nullable = false, length = 20)
+    private String transactionType;
+
+    @Column(name = "transaction_id")
+    private Long transactionId;
+
+    @Column(name = "client_id", nullable = false)
+    private Long clientId;
+
+    @Column(name = "amount", nullable = false, precision = 19, scale = 6)
+    private BigDecimal amount;
+
+    @Column(name = "is_connected_group", nullable = false)
+    private boolean connectedGroup;
+
+    protected AmlCtrReportLine() {}
+
+    public static AmlCtrReportLine of(AmlCtrReport ctrReport, AmlTransactionType transactionType, Long transactionId, Long clientId,
+            BigDecimal amount, boolean connectedGroup) {
+        final AmlCtrReportLine line = new AmlCtrReportLine();
+        line.ctrReport = ctrReport;
+        line.transactionType = transactionType.name();
+        line.transactionId = transactionId;
+        line.clientId = clientId;
+        line.amount = amount;
+        line.connectedGroup = connectedGroup;
+        return line;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public AmlCtrReport getCtrReport() {
+        return ctrReport;
+    }
+
+    public AmlTransactionType getTransactionType() {
+        return AmlTransactionType.valueOf(transactionType);
+    }
+
+    public Long getTransactionId() {
+        return transactionId;
+    }
+
+    public Long getClientId() {
+        return clientId;
+    }
+
+    public BigDecimal getAmount() {
+        return amount;
+    }
+
+    public boolean isConnectedGroup() {
+        return connectedGroup;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlCtrReportLineRepository.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AmlCtrReportLineRepository extends JpaRepository<AmlCtrReportLine, Long> {
+
+    List<AmlCtrReportLine> findByCtrReport_Id(Long ctrReportId);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlCtrReportRepository.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AmlCtrReportRepository extends JpaRepository<AmlCtrReport, Long> {
+
+    Optional<AmlCtrReport> findByReportMonth(String reportMonth);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlCtrReportStatus.java

@@ -0,0 +1,24 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+public enum AmlCtrReportStatus {
+
+    DRAFT, GENERATED, SUBMITTED
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlRecurringReview.java

@@ -0,0 +1,109 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.useradministration.domain.AppUser;
+
+/**
+ * A reviewer's judgement on a customer who repeatedly trips the AML engine.
+ *
+ * Distinct from the per-transaction disposition held on {@link AmlAlert}: that answers "was this
+ * transaction acceptable", this answers "is this customer's pattern of behaviour acceptable".
+ * {@link #alertCountAtReview} is what lets the queue clear — see the 0460 changelog.
+ */
+@Entity
+@Table(name = "m_aml_recurring_review")
+public class AmlRecurringReview {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne(optional = false)
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @Column(name = "alert_count_at_review", nullable = false)
+    private Integer alertCountAtReview;
+
+    @Column(name = "outcome", nullable = false, length = 30)
+    private String outcome;
+
+    @Column(name = "notes", nullable = false, length = 1000)
+    private String notes;
+
+    @ManyToOne(optional = false)
+    @JoinColumn(name = "reviewed_by", nullable = false)
+    private AppUser reviewedBy;
+
+    @Column(name = "reviewed_on", nullable = false)
+    private LocalDateTime reviewedOn;
+
+    protected AmlRecurringReview() {}
+
+    public static AmlRecurringReview record(final Client client, final int alertCountAtReview,
+            final AmlRecurringReviewOutcome outcome, final String notes, final AppUser reviewedBy) {
+        final AmlRecurringReview review = new AmlRecurringReview();
+        review.client = client;
+        review.alertCountAtReview = alertCountAtReview;
+        review.outcome = outcome.name();
+        review.notes = notes;
+        review.reviewedBy = reviewedBy;
+        review.reviewedOn = LocalDateTime.now();
+        return review;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public Client getClient() {
+        return client;
+    }
+
+    public Integer getAlertCountAtReview() {
+        return alertCountAtReview;
+    }
+
+    public AmlRecurringReviewOutcome getOutcome() {
+        return AmlRecurringReviewOutcome.valueOf(outcome);
+    }
+
+    public String getNotes() {
+        return notes;
+    }
+
+    public AppUser getReviewedBy() {
+        return reviewedBy;
+    }
+
+    public LocalDateTime getReviewedOn() {
+        return reviewedOn;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlRecurringReviewOutcome.java

@@ -0,0 +1,30 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+/** What a reviewer concluded about a customer's repeated AML activity. */
+public enum AmlRecurringReviewOutcome {
+
+    /** Behaviour explained and acceptable — nothing further, but the customer stays visible if it recurs. */
+    CLEARED,
+    /** Not conclusive; keep watching this customer more closely. */
+    MONITOR,
+    /** Warrants an STR case; the reviewer escalates the individual alerts separately. */
+    ESCALATED
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlRecurringReviewRepository.java

@@ -0,0 +1,28 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AmlRecurringReviewRepository extends JpaRepository<AmlRecurringReview, Long> {
+
+    /** Newest first, so the caller can take the head as the latest review for a customer. */
+    List<AmlRecurringReview> findByClient_IdOrderByReviewedOnDesc(Long clientId);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlRuleType.java

@@ -0,0 +1,33 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+/**
+ * How an {@link AmlTransactionRule} is evaluated.
+ *
+ * <ul>
+ * <li>THRESHOLD - a single transaction at or above {@code thresholdAmount}</li>
+ * <li>STRUCTURING - connected transactions summing at/above {@code thresholdAmount} within {@code windowDays}</li>
+ * <li>VELOCITY - unusual frequency of transactions within {@code windowDays}, independent of a fixed amount</li>
+ * </ul>
+ */
+public enum AmlRuleType {
+
+    THRESHOLD, STRUCTURING, VELOCITY
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlStrCase.java

@@ -0,0 +1,164 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDate;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.useradministration.domain.AppUser;
+
+/**
+ * Created when an {@link AmlAlert} is escalated past first-level review. {@link #concludedOn} is
+ * the Principal Officer's conclusion date - the RBI-mandated 7-working-day FIU filing clock
+ * ({@link #fiuDueDate}) starts here, never at the alert or transaction date.
+ */
+@Entity
+@Table(name = "m_aml_str_case")
+public class AmlStrCase extends AbstractAuditableWithUTCDateTimeCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "alert_id", nullable = false)
+    private AmlAlert alert;
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @ManyToOne
+    @JoinColumn(name = "assigned_po")
+    private AppUser assignedPo;
+
+    @Column(name = "investigation_notes", length = 2000)
+    private String investigationNotes;
+
+    @Column(name = "source_of_funds_notes", length = 2000)
+    private String sourceOfFundsNotes;
+
+    @Column(name = "conclusion", length = 20)
+    private String conclusion;
+
+    @ManyToOne
+    @JoinColumn(name = "concluded_by")
+    private AppUser concludedBy;
+
+    @Column(name = "concluded_on")
+    private LocalDate concludedOn;
+
+    @Column(name = "fiu_due_date")
+    private LocalDate fiuDueDate;
+
+    @Column(name = "str_filed_on")
+    private LocalDate strFiledOn;
+
+    @Column(name = "str_reference_no", length = 100)
+    private String strReferenceNo;
+
+    @Column(name = "status", nullable = false, length = 25)
+    private String status;
+
+    protected AmlStrCase() {}
+
+    public static AmlStrCase openFor(AmlAlert alert) {
+        final AmlStrCase strCase = new AmlStrCase();
+        strCase.alert = alert;
+        strCase.client = alert.getClient();
+        strCase.status = AmlStrCaseStatus.OPEN.name();
+        return strCase;
+    }
+
+    public void assignPrincipalOfficer(AppUser po) {
+        this.assignedPo = po;
+    }
+
+    /** {@code fiuDueDate} is computed by the caller using the working-days calendar, not here. */
+    public void conclude(AppUser po, AmlStrConclusion conclusion, String investigationNotes, String sourceOfFundsNotes,
+            LocalDate concludedOn, LocalDate fiuDueDate) {
+        this.concludedBy = po;
+        this.conclusion = conclusion.name();
+        this.investigationNotes = investigationNotes;
+        this.sourceOfFundsNotes = sourceOfFundsNotes;
+        this.concludedOn = concludedOn;
+        this.status = conclusion == AmlStrConclusion.SUSPICIOUS ? AmlStrCaseStatus.CONCLUDED_SUSPICIOUS.name()
+                : AmlStrCaseStatus.CONCLUDED_CLEAR.name();
+        this.fiuDueDate = conclusion == AmlStrConclusion.SUSPICIOUS ? fiuDueDate : null;
+    }
+
+    public void fileStr(String referenceNo, LocalDate filedOn) {
+        this.strReferenceNo = referenceNo;
+        this.strFiledOn = filedOn;
+        this.status = AmlStrCaseStatus.FILED.name();
+    }
+
+    public Long getClientId() {
+        return client.getId();
+    }
+
+    public AmlAlert getAlert() {
+        return alert;
+    }
+
+    public Client getClient() {
+        return client;
+    }
+
+    public AppUser getAssignedPo() {
+        return assignedPo;
+    }
+
+    public String getInvestigationNotes() {
+        return investigationNotes;
+    }
+
+    public String getSourceOfFundsNotes() {
+        return sourceOfFundsNotes;
+    }
+
+    public AmlStrConclusion getConclusion() {
+        return conclusion == null ? null : AmlStrConclusion.valueOf(conclusion);
+    }
+
+    public AppUser getConcludedBy() {
+        return concludedBy;
+    }
+
+    public LocalDate getConcludedOn() {
+        return concludedOn;
+    }
+
+    public LocalDate getFiuDueDate() {
+        return fiuDueDate;
+    }
+
+    public LocalDate getStrFiledOn() {
+        return strFiledOn;
+    }
+
+    public String getStrReferenceNo() {
+        return strReferenceNo;
+    }
+
+    public AmlStrCaseStatus getStatus() {
+        return AmlStrCaseStatus.valueOf(status);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlStrCaseRepository.java

@@ -0,0 +1,38 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.time.LocalDate;
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+public interface AmlStrCaseRepository extends JpaRepository<AmlStrCase, Long> {
+
+    long countByClient_Id(Long clientId);
+
+    List<AmlStrCase> findByStatus(String status);
+
+    @Query("SELECT c FROM AmlStrCase c WHERE c.status = 'CONCLUDED_SUSPICIOUS' AND c.concludedOn BETWEEN :from AND :to")
+    List<AmlStrCase> findConcludedSuspiciousBetween(@Param("from") LocalDate from, @Param("to") LocalDate to);
+
+    @Query("SELECT c FROM AmlStrCase c WHERE c.status = 'CONCLUDED_SUSPICIOUS' AND c.fiuDueDate < :asOf")
+    List<AmlStrCase> findOverdueForFiling(@Param("asOf") LocalDate asOf);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlStrCaseStatus.java

@@ -0,0 +1,24 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+public enum AmlStrCaseStatus {
+
+    OPEN, CONCLUDED_CLEAR, CONCLUDED_SUSPICIOUS, FILED
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlStrConclusion.java

@@ -0,0 +1,25 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+/** The Principal Officer's final conclusion on an {@link AmlStrCase}. */
+public enum AmlStrConclusion {
+
+    NOT_SUSPICIOUS, SUSPICIOUS
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlTransactionRule.java

@@ -0,0 +1,163 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+
+/**
+ * A machine-evaluable transaction-monitoring rule. Distinct from {@code ClientRiskRule}
+ * (client-profile, KYC-time scoring) - these are checked against live savings/loan/transfer
+ * transactions as they post. {@link #sourceClientRiskRuleId} optionally traces a rule back to its
+ * originating entry in the 221-rule AML catalog seeded in {@code m_client_risk_rule}.
+ */
+@Entity
+@Table(name = "m_aml_transaction_rule")
+public class AmlTransactionRule {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "rule_code", nullable = false, length = 50)
+    private String ruleCode;
+
+    @Column(name = "description", nullable = false, length = 500)
+    private String description;
+
+    @Column(name = "applies_to", nullable = false, length = 20)
+    private String appliesTo;
+
+    @Column(name = "threshold_amount", precision = 19, scale = 6)
+    private BigDecimal thresholdAmount;
+
+    /** Risk-category-tiered overrides of {@link #thresholdAmount}. Null on both means the rule is
+     *  not tiered; {@link #thresholdAmount} is used for every client regardless of risk category. */
+    @Column(name = "threshold_amount_medium_risk", precision = 19, scale = 6)
+    private BigDecimal thresholdAmountMediumRisk;
+
+    @Column(name = "threshold_amount_high_risk", precision = 19, scale = 6)
+    private BigDecimal thresholdAmountHighRisk;
+
+    /**
+     * Declarative band the rule covers, shown on the AML Rules Master screen. Purely
+     * descriptive: unlike the tiered columns above these never take part in matching, so
+     * changing them cannot alter which transactions raise an alert. A null maximum means
+     * the rule is genuinely open-ended.
+     */
+    @Column(name = "min_limit_amount", precision = 19, scale = 6)
+    private BigDecimal minLimitAmount;
+
+    @Column(name = "max_limit_amount", precision = 19, scale = 6)
+    private BigDecimal maxLimitAmount;
+
+    @Column(name = "rule_type", nullable = false, length = 20)
+    private String ruleType;
+
+    @Column(name = "window_days")
+    private Integer windowDays;
+
+    @Column(name = "source_client_risk_rule_id")
+    private Long sourceClientRiskRuleId;
+
+    @Column(name = "is_active", nullable = false)
+    private boolean active;
+
+    protected AmlTransactionRule() {}
+
+    /**
+     * Builds the live-transaction counterpart of a {@code ClientRiskRule} authored from the AML
+     * Rules Master screen. {@code sourceClientRiskRuleId} is the link the read side joins on, so
+     * the two rows are always created together and the rule code is derived from it.
+     */
+    public static AmlTransactionRule createForRiskRule(final Long sourceClientRiskRuleId, final String description,
+            final AmlAppliesTo appliesTo, final AmlRuleType ruleType, final Integer windowDays,
+            final BigDecimal thresholdAmount, final BigDecimal minLimitAmount, final BigDecimal maxLimitAmount) {
+        final AmlTransactionRule rule = new AmlTransactionRule();
+        rule.sourceClientRiskRuleId = sourceClientRiskRuleId;
+        // rule_code is UNIQUE; the source rule id is unique per row, so this cannot collide.
+        rule.ruleCode = "CRR-" + sourceClientRiskRuleId;
+        rule.description = description;
+        rule.appliesTo = appliesTo.name();
+        rule.ruleType = ruleType.name();
+        rule.windowDays = windowDays;
+        rule.thresholdAmount = thresholdAmount;
+        rule.minLimitAmount = minLimitAmount;
+        rule.maxLimitAmount = maxLimitAmount;
+        rule.active = true;
+        return rule;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public String getRuleCode() {
+        return ruleCode;
+    }
+
+    public String getDescription() {
+        return description;
+    }
+
+    public AmlAppliesTo getAppliesTo() {
+        return AmlAppliesTo.valueOf(appliesTo);
+    }
+
+    public BigDecimal getThresholdAmount() {
+        return thresholdAmount;
+    }
+
+    public BigDecimal getThresholdAmountMediumRisk() {
+        return thresholdAmountMediumRisk;
+    }
+
+    public BigDecimal getThresholdAmountHighRisk() {
+        return thresholdAmountHighRisk;
+    }
+
+    public BigDecimal getMinLimitAmount() {
+        return minLimitAmount;
+    }
+
+    public BigDecimal getMaxLimitAmount() {
+        return maxLimitAmount;
+    }
+
+    public AmlRuleType getRuleType() {
+        return AmlRuleType.valueOf(ruleType);
+    }
+
+    public Integer getWindowDays() {
+        return windowDays;
+    }
+
+    public Long getSourceClientRiskRuleId() {
+        return sourceClientRiskRuleId;
+    }
+
+    public boolean isActive() {
+        return active;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlTransactionRuleRepository.java

@@ -0,0 +1,35 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.util.List;
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AmlTransactionRuleRepository extends JpaRepository<AmlTransactionRule, Long> {
+
+    List<AmlTransactionRule> findByActiveTrueAndAppliesTo(String appliesTo);
+
+    /**
+     * Looks a rule up by its code irrespective of {@code is_active}. Needed for MANUAL_REFERRAL, which is deliberately
+     * seeded inactive so the evaluation engine never fires it, yet must still be attachable to an alert a user raises
+     * by hand from the ledger.
+     */
+    Optional<AmlTransactionRule> findByRuleCode(String ruleCode);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlTransactionType.java

@@ -0,0 +1,25 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+/** The kind of ledger transaction an {@link AmlAlert} was raised against. */
+public enum AmlTransactionType {
+
+    SAVINGS, LOAN, TRANSFER
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/ClientRiskCategoryHistory.java

@@ -0,0 +1,138 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.useradministration.domain.AppUser;
+
+/**
+ * Immutable, append-only audit trail of a client's KYC risk-category changes. Backs the AML menu's
+ * existing "Risk Update History Report" item, which previously had no data behind it. Written both
+ * for manual re-categorization and for the automatic escalation triggered on a client's 3rd
+ * cumulative {@link AmlStrCase}.
+ */
+@Entity
+@Table(name = "m_client_risk_category_history")
+public class ClientRiskCategoryHistory {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @Column(name = "previous_category", nullable = false)
+    private Integer previousCategory;
+
+    @Column(name = "new_category", nullable = false)
+    private Integer newCategory;
+
+    @Column(name = "reason", nullable = false, length = 500)
+    private String reason;
+
+    @Column(name = "triggered_by", nullable = false, length = 30)
+    private String triggeredBy;
+
+    @ManyToOne
+    @JoinColumn(name = "str_case_id")
+    private AmlStrCase strCase;
+
+    @Column(name = "changed_on", nullable = false)
+    private LocalDateTime changedOn;
+
+    @ManyToOne
+    @JoinColumn(name = "changed_by", nullable = false)
+    private AppUser changedBy;
+
+    protected ClientRiskCategoryHistory() {}
+
+    public static ClientRiskCategoryHistory autoEscalation(Client client, Integer previousCategory, Integer newCategory,
+            AmlStrCase triggeringCase, AppUser systemActor, LocalDateTime changedOn) {
+        final ClientRiskCategoryHistory history = new ClientRiskCategoryHistory();
+        history.client = client;
+        history.previousCategory = previousCategory;
+        history.newCategory = newCategory;
+        history.reason = "Auto-escalated after client's 3rd cumulative AML STR case (case #" + triggeringCase.getId() + ")";
+        history.triggeredBy = RiskCategoryChangeTrigger.AML_AUTO_ESCALATION.name();
+        history.strCase = triggeringCase;
+        history.changedOn = changedOn;
+        history.changedBy = systemActor;
+        return history;
+    }
+
+    public static ClientRiskCategoryHistory manual(Client client, Integer previousCategory, Integer newCategory, String reason,
+            AppUser changedBy, LocalDateTime changedOn) {
+        final ClientRiskCategoryHistory history = new ClientRiskCategoryHistory();
+        history.client = client;
+        history.previousCategory = previousCategory;
+        history.newCategory = newCategory;
+        history.reason = reason;
+        history.triggeredBy = RiskCategoryChangeTrigger.MANUAL.name();
+        history.changedBy = changedBy;
+        history.changedOn = changedOn;
+        return history;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public Client getClient() {
+        return client;
+    }
+
+    public Integer getPreviousCategory() {
+        return previousCategory;
+    }
+
+    public Integer getNewCategory() {
+        return newCategory;
+    }
+
+    public String getReason() {
+        return reason;
+    }
+
+    public RiskCategoryChangeTrigger getTriggeredBy() {
+        return RiskCategoryChangeTrigger.valueOf(triggeredBy);
+    }
+
+    public AmlStrCase getStrCase() {
+        return strCase;
+    }
+
+    public LocalDateTime getChangedOn() {
+        return changedOn;
+    }
+
+    public AppUser getChangedBy() {
+        return changedBy;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/ClientRiskCategoryHistoryRepository.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface ClientRiskCategoryHistoryRepository extends JpaRepository<ClientRiskCategoryHistory, Long> {
+
+    List<ClientRiskCategoryHistory> findByClient_IdOrderByChangedOnDesc(Long clientId);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/RiskCategoryChangeTrigger.java

@@ -0,0 +1,24 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+public enum RiskCategoryChangeTrigger {
+
+    AML_AUTO_ESCALATION, MANUAL
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/cfcfrms/domain/CfcfrmsSimulatorLog.java

@@ -23,6 +23,7 @@ import jakarta.persistence.Entity;
 import jakarta.persistence.Table;
 import java.time.OffsetDateTime;
 import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
 
 /**
  * Simulator-side audit log for CFCFRMS (I4C/MHA) events.
@@ -69,7 +70,7 @@ public class CfcfrmsSimulatorLog extends AbstractAuditableWithUTCDateTimeCustom<
         this.eventType = eventType;
         this.payload = payload;
         this.responsePayload = responsePayload;
-        this.eventTimestamp = OffsetDateTime.now();
+        this.eventTimestamp = DateUtils.getOffsetDateTimeOfTenant();
     }
 
     public CfcfrmsSimulatorLog(final String cfcfrmsRef, final String ticketId, final String bankIfsc,

fineract-core/src/main/java/org/apache/fineract/portfolio/cfcfrms/domain/ComplaintAuditLog.java

@@ -23,6 +23,7 @@ import jakarta.persistence.Entity;
 import jakarta.persistence.Table;
 import java.time.OffsetDateTime;
 import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
 
 /**
  * Audit trail for every status change on a CFCFRMS complaint ticket.
@@ -54,7 +55,7 @@ public class ComplaintAuditLog extends AbstractAuditableWithUTCDateTimeCustom<Lo
         this.event = event;
         this.description = description;
         this.actor = actor;
-        this.eventTimestamp = OffsetDateTime.now();
+        this.eventTimestamp = DateUtils.getOffsetDateTimeOfTenant();
     }
 
     public ComplaintAuditLog(final String ticketId, final String event, final String description,

fineract-core/src/main/java/org/apache/fineract/portfolio/cfcfrms/domain/ComplaintTicket.java

@@ -26,6 +26,7 @@ import jakarta.persistence.Table;
 import java.math.BigDecimal;
 import java.time.OffsetDateTime;
 import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
 
 /**
  * CFCFRMS Complaint Ticket — represents a cyber fraud complaint pushed by MHA/I4C to the bank.
@@ -121,7 +122,7 @@ public class ComplaintTicket extends AbstractAuditableWithUTCDateTimeCustom<Long
         ticket.status = ComplaintStatus.RECEIVED;
         ticket.assignedOfficer = assignedOfficer;
         ticket.statePoliceRef = statePoliceRef;
-        ticket.receivedAt = OffsetDateTime.now();
+        ticket.receivedAt = DateUtils.getOffsetDateTimeOfTenant();
         return ticket;
     }
 
@@ -132,7 +133,7 @@ public class ComplaintTicket extends AbstractAuditableWithUTCDateTimeCustom<Long
         this.status = newStatus;
         this.actionTaken = actionNote;
         if (newStatus == ComplaintStatus.RESOLVED || newStatus == ComplaintStatus.REJECTED) {
-            this.resolvedAt = OffsetDateTime.now();
+            this.resolvedAt = DateUtils.getOffsetDateTimeOfTenant();
         }
     }
 

fineract-core/src/main/java/org/apache/fineract/portfolio/client/adapter/ClientSignatureIdAdapter.java

@@ -0,0 +1,66 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.adapter;
+
+import static java.util.Objects.nonNull;
+
+import java.util.Optional;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.fineract.infrastructure.documentmanagement.adapter.EntitySignatureIdAdapter;
+import org.apache.fineract.portfolio.client.domain.ClientRepository;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+@Slf4j
+@RequiredArgsConstructor
+@Component
+class ClientSignatureIdAdapter implements EntitySignatureIdAdapter {
+
+    private static final String ENTITY_TYPE = "clients";
+    private static final String DOCUMENT_NAME = "clientSignature";
+
+    private final ClientRepository repository;
+
+    @Override
+    public boolean accept(String entityType, String documentName) {
+        return ENTITY_TYPE.equalsIgnoreCase(entityType) && DOCUMENT_NAME.equalsIgnoreCase(documentName);
+    }
+
+    @Override
+    @Transactional(readOnly = true)
+    public Optional<SignatureIdResult> get(Long entityId) {
+        return repository.findById(entityId).filter(client -> nonNull(client.getSignatureId()))
+                .map(client -> SignatureIdResult.builder().id(client.getSignatureId()).displayName(client.getDisplayName()).build());
+    }
+
+    @Override
+    @Transactional
+    public Optional<SignatureIdResult> set(Long entityId, Long signatureId) {
+        final var result = get(entityId);
+
+        if (signatureId == null) {
+            repository.removeSignatureId(entityId);
+        } else {
+            repository.updateByIdAndSignatureId(entityId, signatureId);
+        }
+
+        return result;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/api/ClientApiConstants.java

@@ -63,6 +63,7 @@ public class ClientApiConstants {
     public static final String CLIENT_CLASSIFICATION = "ClientClassification";
 
     public static final String OCCUPATION_CATEGORY = "OccupationCategory";
+    public static final String PWD_CATEGORY = "PwdCategory";
     public static final String OCCUPATION = "Occupation";
 
     public static final String CLIENT_NON_PERSON_CONSTITUTION = "Constitution";
@@ -96,6 +97,15 @@ public class ClientApiConstants {
     public static final String mobileNoParamName = "mobileNo";
     public static final String alternateMobileNoParamName = "alternateMobileNo";
     public static final String emailAddressParamName = "emailAddress";
+    // Dual-OTP contact-change verification (see ClientContactOtpService) — required only when
+    // mobileNo or emailAddress is being changed via PUT /clients/{id}. Reference an already
+    // VERIFIED m_otp_log row for the OLD destination (current DB value) and the NEW destination
+    // (incoming value) respectively. Field-specific (not a single generic pair) so mobileNo and
+    // emailAddress can both change in the same request without ambiguity.
+    public static final String mobileOldOtpIdParamName = "mobileOldOtpId";
+    public static final String mobileNewOtpIdParamName = "mobileNewOtpId";
+    public static final String emailOldOtpIdParamName = "emailOldOtpId";
+    public static final String emailNewOtpIdParamName = "emailNewOtpId";
     public static final String firstnameParamName = "firstname";
     public static final String middlenameParamName = "middlename";
     public static final String lastnameParamName = "lastname";
@@ -138,7 +148,13 @@ public class ClientApiConstants {
     public static final String religionParamName = "religion";
     public static final String socialCategoryParamName = "socialCategory";
     public static final String monthlyIncomeParamName = "monthlyIncome";
+    public static final String annualIncomeParamName = "annualIncome";
     public static final String annualTurnoverParamName = "annualTurnover";
+    public static final String monthlyTurnoverParamName = "monthlyTurnover";
+    public static final String isSeniorCitizenParamName = "isSeniorCitizen";
+    public static final String isPwdParamName = "isPwd";
+    public static final String pwdCategoryIdParamName = "pwdCategoryId";
+    public static final String pwdCategoryParamName = "pwdCategory";
     public static final String agricultureIncomeParamName = "agricultureIncome";
     public static final String nonAgricultureIncomeParamName = "nonAgricultureIncome";
     public static final String ageYearsParamName = "ageYears";
@@ -175,6 +191,7 @@ public class ClientApiConstants {
     public static final String constitutionIdParamName = "constitutionId";
     public static final String mainBusinessLineIdParamName = "mainBusinessLineId";
     public static final String authorizedSignatoryParamName = "authorizedSignatory";
+    public static final String authorizedSignatoryClientIdsParamName = "authorizedSignatoryClientIds";
     public static final String additionalInfoParamName = "additionalInfo";
     public static final String dateOfRegistrationParamName = "dateOfRegistration";
 
@@ -248,8 +265,9 @@ public class ClientApiConstants {
             staffOptionsParamName, dateOfBirthParamName, genderParamName, clientTypeParamName, clientClassificationParamName,
             salutationParamName, occupationCategoryParamName, occupationParamName, maritalStatusParamName,
             educationLevelParamName, degreeQualificationParamName,
-            religionParamName, socialCategoryParamName, monthlyIncomeParamName,
+            religionParamName, socialCategoryParamName, monthlyIncomeParamName, annualIncomeParamName,
-            annualTurnoverParamName, agricultureIncomeParamName, nonAgricultureIncomeParamName,
+            annualTurnoverParamName, monthlyTurnoverParamName, agricultureIncomeParamName, nonAgricultureIncomeParamName,
+            isSeniorCitizenParamName, isPwdParamName, pwdCategoryParamName,
             ageYearsParamName, ageMonthsParamName, ageDaysParamName,
             nationalityIdParamName, isMinorParamName, guardianClientIdParamName, guardianClientDisplayNameParamName, guardianRelationParamName,
             dipVerifiedParamName, dipLookupLogIdParamName, dipTimestampParamName,

fineract-core/src/main/java/org/apache/fineract/portfolio/client/data/ClientData.java

@@ -82,7 +82,13 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
     private CodeValueData religion;
     private CodeValueData socialCategory;
     private BigDecimal monthlyIncome;
+    private BigDecimal annualIncome;
     private BigDecimal annualTurnover;
+    private BigDecimal monthlyTurnover;
+    private Boolean isSeniorCitizen;
+    private Boolean isPwd;
+    private CodeValueData pwdCategory;
+    private Collection<CodeValueData> pwdCategoryOptions;
     private BigDecimal agricultureIncome;
     private BigDecimal nonAgricultureIncome;
     private Integer ageYears;
@@ -99,6 +105,19 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
     private Boolean alternateDipVerified;
     private Long alternateDipLookupLogId;
     private String alternateDipTimestamp;
+    /**
+     * Live DIP/MNRL status of the number, resolved from the latest lookup rather than the flag
+     * captured at onboarding. A customer cleared at onboarding whose number is later reported or
+     * reassigned would otherwise keep showing "Verified" forever.
+     */
+    private String dipLiveStatus;
+    private String alternateDipLiveStatus;
+    /**
+     * Disposition of the client's most recent flagged sanctions alert, or null when they carry
+     * none. Like the DIP status this is resolved live: nameVerified is captured at onboarding and
+     * would keep reading "Clear" after the client was added to a later list snapshot.
+     */
+    private String sanctionsAlertStatus;
     private Boolean nameVerified;
     private Long screeningLogId;
     private Boolean isStaff;
@@ -400,13 +419,19 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
         data.degreeQualificationOptions = templateData.degreeQualificationOptions;
         data.religionOptions = templateData.religionOptions;
         data.socialCategoryOptions = templateData.socialCategoryOptions;
+        data.pwdCategoryOptions = templateData.pwdCategoryOptions;
         data.maritalStatus = clientData.maritalStatus;
         data.educationLevel = clientData.educationLevel;
         data.degreeQualification = clientData.degreeQualification;
         data.religion = clientData.religion;
         data.socialCategory = clientData.socialCategory;
         data.monthlyIncome = clientData.monthlyIncome;
+        data.annualIncome = clientData.annualIncome;
         data.annualTurnover = clientData.annualTurnover;
+        data.monthlyTurnover = clientData.monthlyTurnover;
+        data.isSeniorCitizen = clientData.isSeniorCitizen;
+        data.isPwd = clientData.isPwd;
+        data.pwdCategory = clientData.pwdCategory;
         data.agricultureIncome = clientData.agricultureIncome;
         data.nonAgricultureIncome = clientData.nonAgricultureIncome;
         data.ageYears = clientData.ageYears;
@@ -424,6 +449,11 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
         data.alternateDipVerified = clientData.alternateDipVerified;
         data.alternateDipLookupLogId = clientData.alternateDipLookupLogId;
         data.alternateDipTimestamp = clientData.alternateDipTimestamp;
+        // Carried across too: these helpers rebuild ClientData field by field, so a field missing
+        // here is silently dropped from the payload the client view loads.
+        data.dipLiveStatus = clientData.dipLiveStatus;
+        data.alternateDipLiveStatus = clientData.alternateDipLiveStatus;
+        data.sanctionsAlertStatus = clientData.sanctionsAlertStatus;
         data.nameVerified = clientData.nameVerified;
         data.screeningLogId = clientData.screeningLogId;
         return data;
@@ -456,13 +486,19 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
         data.degreeQualificationOptions = clientData.degreeQualificationOptions;
         data.religionOptions = clientData.religionOptions;
         data.socialCategoryOptions = clientData.socialCategoryOptions;
+        data.pwdCategoryOptions = clientData.pwdCategoryOptions;
         data.maritalStatus = clientData.maritalStatus;
         data.educationLevel = clientData.educationLevel;
         data.degreeQualification = clientData.degreeQualification;
         data.religion = clientData.religion;
         data.socialCategory = clientData.socialCategory;
         data.monthlyIncome = clientData.monthlyIncome;
+        data.annualIncome = clientData.annualIncome;
         data.annualTurnover = clientData.annualTurnover;
+        data.monthlyTurnover = clientData.monthlyTurnover;
+        data.isSeniorCitizen = clientData.isSeniorCitizen;
+        data.isPwd = clientData.isPwd;
+        data.pwdCategory = clientData.pwdCategory;
         data.agricultureIncome = clientData.agricultureIncome;
         data.nonAgricultureIncome = clientData.nonAgricultureIncome;
         data.ageYears = clientData.ageYears;
@@ -480,6 +516,11 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
         data.alternateDipVerified = clientData.alternateDipVerified;
         data.alternateDipLookupLogId = clientData.alternateDipLookupLogId;
         data.alternateDipTimestamp = clientData.alternateDipTimestamp;
+        // Carried across too: these helpers rebuild ClientData field by field, so a field missing
+        // here is silently dropped from the payload the client view loads.
+        data.dipLiveStatus = clientData.dipLiveStatus;
+        data.alternateDipLiveStatus = clientData.alternateDipLiveStatus;
+        data.sanctionsAlertStatus = clientData.sanctionsAlertStatus;
         data.nameVerified = clientData.nameVerified;
         data.screeningLogId = clientData.screeningLogId;
         return data;
@@ -509,7 +550,12 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
         data.religion = clientData.religion;
         data.socialCategory = clientData.socialCategory;
         data.monthlyIncome = clientData.monthlyIncome;
+        data.annualIncome = clientData.annualIncome;
         data.annualTurnover = clientData.annualTurnover;
+        data.monthlyTurnover = clientData.monthlyTurnover;
+        data.isSeniorCitizen = clientData.isSeniorCitizen;
+        data.isPwd = clientData.isPwd;
+        data.pwdCategory = clientData.pwdCategory;
         data.agricultureIncome = clientData.agricultureIncome;
         data.nonAgricultureIncome = clientData.nonAgricultureIncome;
         data.ageYears = clientData.ageYears;
@@ -527,6 +573,11 @@ public final class ClientData implements Comparable<ClientData>, Serializable {
         data.alternateDipVerified = clientData.alternateDipVerified;
         data.alternateDipLookupLogId = clientData.alternateDipLookupLogId;
         data.alternateDipTimestamp = clientData.alternateDipTimestamp;
+        // Carried across too: these helpers rebuild ClientData field by field, so a field missing
+        // here is silently dropped from the payload the client view loads.
+        data.dipLiveStatus = clientData.dipLiveStatus;
+        data.alternateDipLiveStatus = clientData.alternateDipLiveStatus;
+        data.sanctionsAlertStatus = clientData.sanctionsAlertStatus;
         data.nameVerified = clientData.nameVerified;
         data.screeningLogId = clientData.screeningLogId;
         return data;

fineract-core/src/main/java/org/apache/fineract/portfolio/client/data/ClientFamilyMemberChildData.java

@@ -0,0 +1,35 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fineract.portfolio.client.data;
+
+import java.io.Serializable;
+import java.time.LocalDate;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+public final class ClientFamilyMemberChildData implements Serializable {
+    private final Long id;
+    private final String fullName;
+    private final Long genderId;
+    private final String gender;
+    private final LocalDate dateOfBirth;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/data/ClientFamilyMembersData.java

@@ -84,6 +84,9 @@ public final class ClientFamilyMembersData implements Serializable {
     private final LocalDate marriageDate;
     private final String marriageAuthority;
 
+    @lombok.Setter
+    private java.util.List<ClientFamilyMemberChildData> children;
+
     // template holder
     private final Collection<CodeValueData> relationshipIdOptions;
     private final Collection<CodeValueData> genderIdOptions;

fineract-core/src/main/java/org/apache/fineract/portfolio/client/data/ClientNonPersonData.java

@@ -34,6 +34,8 @@ public class ClientNonPersonData implements Serializable {
     private final CodeValueData mainBusinessLine;
     private final String remarks;
     private final String authorizedSignatory;
+    /** Client ids behind {@link #authorizedSignatory}, comma separated and in the same order. */
+    private final String authorizedSignatoryClientIds;
     private final String additionalInfo;
     private final LocalDate dateOfRegistration;
 
@@ -62,13 +64,24 @@ public class ClientNonPersonData implements Serializable {
         this.constitution = null;
         this.mainBusinessLine = null;
         this.authorizedSignatory = null;
+        this.authorizedSignatoryClientIds = null;
         this.additionalInfo = null;
         this.dateOfRegistration = null;
     }
 
+    /**
+     * Kept for the list/search mappers, whose SQL does not select the signatory client ids.
+     */
     public ClientNonPersonData(CodeValueData constitution, String incorpNo, LocalDate incorpValidityTillDate,
             CodeValueData mainBusinessLine, String remarks, String authorizedSignatory, String additionalInfo,
             LocalDate dateOfRegistration) {
+        this(constitution, incorpNo, incorpValidityTillDate, mainBusinessLine, remarks, authorizedSignatory, additionalInfo,
+                dateOfRegistration, null);
+    }
+
+    public ClientNonPersonData(CodeValueData constitution, String incorpNo, LocalDate incorpValidityTillDate,
+            CodeValueData mainBusinessLine, String remarks, String authorizedSignatory, String additionalInfo,
+            LocalDate dateOfRegistration, String authorizedSignatoryClientIds) {
 
         this.constitution = constitution;
         this.incorpNumber = incorpNo;
@@ -76,6 +89,7 @@ public class ClientNonPersonData implements Serializable {
         this.mainBusinessLine = mainBusinessLine;
         this.remarks = remarks;
         this.authorizedSignatory = authorizedSignatory;
+        this.authorizedSignatoryClientIds = authorizedSignatoryClientIds;
         this.additionalInfo = additionalInfo;
         this.dateOfRegistration = dateOfRegistration;
     }

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/Client.java

@@ -27,6 +27,7 @@ import jakarta.persistence.JoinTable;
 import jakarta.persistence.ManyToMany;
 import jakarta.persistence.ManyToOne;
 import jakarta.persistence.OneToMany;
+import jakarta.persistence.OneToOne;
 import jakarta.persistence.Table;
 import jakarta.persistence.UniqueConstraint;
 import java.time.LocalDate;
@@ -77,6 +78,9 @@ public class Client extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "image_id")
     private Long imageId;
 
+    @Column(name = "signature_id")
+    private Long signatureId;
+
     @Column(name = "status_enum", nullable = false)
     private Integer status;
 
@@ -231,9 +235,28 @@ public class Client extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "monthly_income")
     private java.math.BigDecimal monthlyIncome;
 
+    @Column(name = "annual_income")
+    private java.math.BigDecimal annualIncome;
+
     @Column(name = "annual_turnover")
     private java.math.BigDecimal annualTurnover;
 
+    @Column(name = "monthly_turnover")
+    private java.math.BigDecimal monthlyTurnover;
+
+    @Column(name = "is_senior_citizen")
+    private Boolean isSeniorCitizen;
+
+    @Column(name = "is_pwd")
+    private Boolean isPwd;
+
+    @OneToOne(mappedBy = "client", fetch = FetchType.LAZY)
+    private ClientKyc clientKyc;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "pwd_category_cv_id")
+    private CodeValue pwdCategory;
+
     @Column(name = "agriculture_income")
     private java.math.BigDecimal agricultureIncome;
 
@@ -271,6 +294,17 @@ public class Client extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "alternate_dip_timestamp")
     private String alternateDipTimestamp;
 
+    /**
+     * The DIP/MNRL status the number actually returned — CLEAN, SUSPECTED, DISCONNECTED or
+     * SERVICE_UNAVAILABLE. dipVerified alone cannot tell "checked and clean" apart from "the DoT
+     * service was down", which previously stored both as verified.
+     */
+    @Column(name = "dip_status", length = 40)
+    private String dipStatus;
+
+    @Column(name = "alternate_dip_status", length = 40)
+    private String alternateDipStatus;
+
     @Column(name = "name_verified")
     private Boolean nameVerified;
 
@@ -598,6 +632,10 @@ public class Client extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         return this.office.getId();
     }
 
+    public String getDisplayName() {
+        return this.displayName;
+    }
+
     public String mobileNo() {
         return this.mobileNo;
     }
@@ -832,6 +870,14 @@ public class Client extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         return this.socialCategory != null ? this.socialCategory.getId() : null;
     }
 
+    public Long pwdCategoryId() {
+        return this.pwdCategory != null ? this.pwdCategory.getId() : null;
+    }
+
+    public void updatePwdCategory(CodeValue pwdCategory) {
+        this.pwdCategory = pwdCategory;
+    }
+
     public void updateSocialCategory(CodeValue socialCategory) {
         this.socialCategory = socialCategory;
     }

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientForm60.java

@@ -29,6 +29,7 @@ import lombok.Getter;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.fineract.infrastructure.core.api.JsonCommand;
 import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
 
 /**
  * Form 60 declaration as per Rule 114B of Income Tax Rules, 1962.
@@ -87,7 +88,7 @@ public class ClientForm60 extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         form.estimatedTotalIncome = command.bigDecimalValueOfParameterNamed("estimatedTotalIncome");
         form.reasonForNoPan = StringUtils.defaultIfEmpty(command.stringValueOfParameterNamed("reasonForNoPan"), null);
         form.declaration = command.booleanPrimitiveValueOfParameterNamed("declaration");
-        form.submittedOn = LocalDate.now();
+        form.submittedOn = DateUtils.getLocalDateOfTenant();
         return form;
     }
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKyc.java

@@ -25,13 +25,19 @@ import jakarta.persistence.Entity;
 import jakarta.persistence.JoinColumn;
 import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Table;
+import jakarta.persistence.Transient;
 import jakarta.persistence.UniqueConstraint;
 import java.time.LocalDate;
+import java.math.BigDecimal;
+import java.util.Collections;
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.Map;
+import java.util.Set;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.fineract.infrastructure.core.api.JsonCommand;
 import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
 
 /**
  * Represents a client's KYC (Know Your Customer) record as mandated by the Reserve Bank of India
@@ -59,6 +65,14 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @JoinColumn(name = "client_id", nullable = false)
     private Client client;
 
+    /**
+     * Scratch record of what the in-flight {@link #update} replaced, read back via
+     * {@link #getFieldsOverwrittenByLastUpdate()}. Never persisted and never read outside the
+     * transaction that called update(), which clears it first.
+     */
+    @Transient
+    private final transient Set<String> fieldsOverwrittenByLastUpdate = new LinkedHashSet<>();
+
     /** 100 = PENDING, 200 = IN_PROGRESS, 300 = VERIFIED, 400 = REJECTED, 500 = EXPIRED */
     @Column(name = "kyc_status", nullable = false)
     private Integer kycStatus;
@@ -102,6 +116,36 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "pan_status", length = 20)
     private String panStatus;
 
+    // ── PAN declaration ──────────────────────────────────────────────────────
+    // Accepted in place of a passing PAN check. The Income Tax check matches on name AND date of
+    // birth, so a customer whose PAN card carries a different spelling — or a different DOB — can
+    // never clear it however many times the officer retries. Rather than leave such a client
+    // permanently in KYC exception, the branch takes a signed declaration recording what differs.
+    // Holding that declaration is what suppresses the exception, so it is stored, not just shown.
+
+    /** True once a signed declaration has been accepted for a PAN that could not be verified. */
+    @Column(name = "pan_declaration_taken")
+    private Boolean panDeclarationTaken;
+
+    /** What the declaration covers: "NAME", "DOB", "NAME,DOB", or "NONE" when PAN simply failed. */
+    @Column(name = "pan_declaration_mismatch_fields", length = 100)
+    private String panDeclarationMismatchFields;
+
+    /** Name exactly as printed on the physical PAN card, keyed in by the officer. */
+    @Column(name = "pan_declaration_name_on_pan", length = 200)
+    private String panDeclarationNameOnPan;
+
+    /** Date of birth exactly as printed on the physical PAN card. */
+    @Column(name = "pan_declaration_dob_on_pan")
+    private LocalDate panDeclarationDobOnPan;
+
+    /** Officer's free-text note — why the mismatch exists and what proof was sighted. */
+    @Column(name = "pan_declaration_remarks", length = 500)
+    private String panDeclarationRemarks;
+
+    @Column(name = "pan_declaration_taken_on")
+    private LocalDate panDeclarationTakenOn;
+
     // ── Aadhaar ──────────────────────────────────────────────────────────────
     /** Stored masked (last 4 digits visible). Full number must never be persisted as per UIDAI directive. */
     @Column(name = "aadhaar_number_masked", length = 12)
@@ -113,6 +157,31 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "aadhaar_verified_on")
     private LocalDate aadhaarVerifiedOn;
 
+    // ── Aadhaar enrolment receipt ────────────────────────────────────────────
+    // The counterpart of the PAN declaration, for a customer who has applied for Aadhaar but does
+    // not hold one yet. UIDAI issues an enrolment slip carrying a 28-digit EID, and until Aadhaar
+    // itself is issued there is no number to put through the OTP flow — the check cannot pass
+    // however long the branch waits. Recording the receipt is what waives the exception.
+
+    /** True once the customer's Aadhaar enrolment slip has been sighted and recorded. */
+    @Column(name = "aadhaar_receipt_taken")
+    private Boolean aadhaarReceiptTaken;
+
+    /** 28-digit Enrolment ID from the slip, stored with its printed separators. */
+    @Column(name = "aadhaar_enrolment_id", length = 40)
+    private String aadhaarEnrolmentId;
+
+    /** Enrolment date printed on the slip — a receipt is temporary, so its age matters. */
+    @Column(name = "aadhaar_enrolment_date")
+    private LocalDate aadhaarEnrolmentDate;
+
+    /** Officer's note on what was sighted. */
+    @Column(name = "aadhaar_receipt_remarks", length = 500)
+    private String aadhaarReceiptRemarks;
+
+    @Column(name = "aadhaar_receipt_taken_on")
+    private LocalDate aadhaarReceiptTakenOn;
+
     // ── GSTIN (mandatory for NON_INDIVIDUAL clients) ─────────────────────────
     @Column(name = "gstin_number", length = 15)
     private String gstinNumber;
@@ -194,6 +263,18 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "freeze_authority", length = 100)
     private String freezeAuthority;
 
+    @Column(name = "freeze_date")
+    private LocalDate freezeDate;
+
+    @Column(name = "freeze_amount", precision = 19, scale = 6)
+    private BigDecimal freezeAmount;
+
+    @Column(name = "unfreeze_date")
+    private LocalDate unfreezeDate;
+
+    @Column(name = "no_debit_date")
+    private LocalDate noDebitDate;
+
     // ── Form 60 / Form 15G/15H ───────────────────────────────────────────────
     @Column(name = "form60_type", length = 20)
     private String form60Type;
@@ -240,6 +321,18 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "remarks", length = 500)
     private String remarks;
 
+    @Column(name = "is_exception", nullable = false)
+    private Boolean isException;
+
+    @Column(name = "exception_reason", length = 200)
+    private String exceptionReason;
+
+    @Column(name = "exception_resolved", nullable = false)
+    private Boolean exceptionResolved;
+
+    @Column(name = "exception_resolved_on")
+    private LocalDate exceptionResolvedOn;
+
     // ─────────────────────────────────────────────────────────────────────────
 
     protected ClientKyc() {}
@@ -260,7 +353,9 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         this.gstinVerified = false;
         this.cinVerified = false;
         this.dinVerified = false;
-        this.initiatedOn = LocalDate.now();
+        this.isException = false;
+        this.exceptionResolved = false;
+        this.initiatedOn = DateUtils.getLocalDateOfTenant();
     }
 
     public static ClientKyc initiateKyc(final Client client, final JsonCommand command) {
@@ -287,6 +382,24 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     private void applyExtendedFields(final JsonCommand command) {
         this.panAadhaarSeedingStatus = StringUtils.defaultIfEmpty(
                 command.stringValueOfParameterNamed("panAadhaarSeedingStatus"), this.panAadhaarSeedingStatus);
+        final Boolean panDeclarationTakenVal = command.booleanObjectValueOfParameterNamed("panDeclarationTaken");
+        this.panDeclarationTaken = panDeclarationTakenVal != null ? panDeclarationTakenVal : false;
+        this.panDeclarationMismatchFields = StringUtils.defaultIfEmpty(
+                command.stringValueOfParameterNamed("panDeclarationMismatchFields"), null);
+        this.panDeclarationNameOnPan = StringUtils.defaultIfEmpty(
+                command.stringValueOfParameterNamed("panDeclarationNameOnPan"), null);
+        this.panDeclarationDobOnPan = command.localDateValueOfParameterNamed("panDeclarationDobOnPan");
+        this.panDeclarationRemarks = StringUtils.defaultIfEmpty(
+                command.stringValueOfParameterNamed("panDeclarationRemarks"), null);
+        this.panDeclarationTakenOn = command.localDateValueOfParameterNamed("panDeclarationTakenOn");
+        final Boolean aadhaarReceiptTakenVal = command.booleanObjectValueOfParameterNamed("aadhaarReceiptTaken");
+        this.aadhaarReceiptTaken = aadhaarReceiptTakenVal != null ? aadhaarReceiptTakenVal : false;
+        this.aadhaarEnrolmentId = StringUtils.defaultIfEmpty(
+                command.stringValueOfParameterNamed("aadhaarEnrolmentId"), null);
+        this.aadhaarEnrolmentDate = command.localDateValueOfParameterNamed("aadhaarEnrolmentDate");
+        this.aadhaarReceiptRemarks = StringUtils.defaultIfEmpty(
+                command.stringValueOfParameterNamed("aadhaarReceiptRemarks"), null);
+        this.aadhaarReceiptTakenOn = command.localDateValueOfParameterNamed("aadhaarReceiptTakenOn");
         this.enterprisePan = StringUtils.defaultIfEmpty(
                 command.stringValueOfParameterNamed("enterprisePan"), null);
         this.cinNumber = StringUtils.defaultIfEmpty(
@@ -316,6 +429,10 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
                 command.stringValueOfParameterNamed("freezeReason"), null);
         this.freezeAuthority = StringUtils.defaultIfEmpty(
                 command.stringValueOfParameterNamed("freezeAuthority"), null);
+        this.freezeDate = command.localDateValueOfParameterNamed("freezeDate");
+        this.freezeAmount = command.bigDecimalValueOfParameterNamed("freezeAmount");
+        this.unfreezeDate = command.localDateValueOfParameterNamed("unfreezeDate");
+        this.noDebitDate = command.localDateValueOfParameterNamed("noDebitDate");
         this.form60Type = StringUtils.defaultIfEmpty(
                 command.stringValueOfParameterNamed("form60Type"), null);
         this.form60Date = command.localDateValueOfParameterNamed("form60Date");
@@ -324,15 +441,24 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
                 command.stringValueOfParameterNamed("form15Type"), null);
         this.form15Fy = StringUtils.defaultIfEmpty(
                 command.stringValueOfParameterNamed("form15FY"), null);
+        Boolean isExceptionVal = command.booleanObjectValueOfParameterNamed("isException");
+        this.isException = isExceptionVal != null ? isExceptionVal : false;
+        this.exceptionReason = StringUtils.defaultIfEmpty(
+                command.stringValueOfParameterNamed("exceptionReason"), null);
+        Boolean exceptionResolvedVal = command.booleanObjectValueOfParameterNamed("exceptionResolved");
+        this.exceptionResolved = exceptionResolvedVal != null ? exceptionResolvedVal : false;
+        this.exceptionResolvedOn = command.localDateValueOfParameterNamed("exceptionResolvedOn");
     }
 
     public Map<String, Object> update(final JsonCommand command) {
         final Map<String, Object> actualChanges = new LinkedHashMap<>();
+        this.fieldsOverwrittenByLastUpdate.clear();
 
         final String panNumberParam = "panNumber";
         if (command.isChangeInStringParameterNamed(panNumberParam, this.panNumber)) {
             final String newValue = command.stringValueOfParameterNamed(panNumberParam);
             actualChanges.put(panNumberParam, newValue);
+            recordOverwrite(panNumberParam, this.panNumber);
             this.panNumber = StringUtils.defaultIfEmpty(newValue, null);
         }
 
@@ -340,6 +466,7 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         if (command.isChangeInStringParameterNamed(aadhaarParam, this.aadhaarNumberMasked)) {
             final String newValue = command.stringValueOfParameterNamed(aadhaarParam);
             actualChanges.put(aadhaarParam, newValue);
+            recordOverwrite(aadhaarParam, this.aadhaarNumberMasked);
             this.aadhaarNumberMasked = StringUtils.defaultIfEmpty(newValue, null);
         }
 
@@ -347,6 +474,7 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         if (command.isChangeInStringParameterNamed(gstinParam, this.gstinNumber)) {
             final String newValue = command.stringValueOfParameterNamed(gstinParam);
             actualChanges.put(gstinParam, newValue);
+            recordOverwrite(gstinParam, this.gstinNumber);
             this.gstinNumber = StringUtils.defaultIfEmpty(newValue, null);
         }
 
@@ -354,9 +482,12 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         if (command.isChangeInIntegerParameterNamed(riskParam, this.riskCategory)) {
             final Integer newValue = command.integerValueOfParameterNamed(riskParam);
             actualChanges.put(riskParam, newValue);
+            recordOverwrite(riskParam, this.riskCategory);
             this.riskCategory = newValue;
         }
 
+        // remarks is the audit justification itself, so a change to it is deliberately not recorded
+        // as an overwrite — requiring remarks in order to write remarks would be circular.
         final String remarksParam = "remarks";
         if (command.isChangeInStringParameterNamed(remarksParam, this.remarks)) {
             final String newValue = command.stringValueOfParameterNamed(remarksParam);
@@ -366,6 +497,28 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
 
         updateStringField(command, "panAadhaarSeedingStatus", this.panAadhaarSeedingStatus, actualChanges,
                 v -> this.panAadhaarSeedingStatus = v);
+        updateBooleanField(command, "panDeclarationTaken", this.panDeclarationTaken, actualChanges,
+                v -> this.panDeclarationTaken = v != null ? v : false);
+        updateStringField(command, "panDeclarationMismatchFields", this.panDeclarationMismatchFields, actualChanges,
+                v -> this.panDeclarationMismatchFields = v);
+        updateStringField(command, "panDeclarationNameOnPan", this.panDeclarationNameOnPan, actualChanges,
+                v -> this.panDeclarationNameOnPan = v);
+        updateDateField(command, "panDeclarationDobOnPan", this.panDeclarationDobOnPan, actualChanges,
+                v -> this.panDeclarationDobOnPan = v);
+        updateStringField(command, "panDeclarationRemarks", this.panDeclarationRemarks, actualChanges,
+                v -> this.panDeclarationRemarks = v);
+        updateDateField(command, "panDeclarationTakenOn", this.panDeclarationTakenOn, actualChanges,
+                v -> this.panDeclarationTakenOn = v);
+        updateBooleanField(command, "aadhaarReceiptTaken", this.aadhaarReceiptTaken, actualChanges,
+                v -> this.aadhaarReceiptTaken = v != null ? v : false);
+        updateStringField(command, "aadhaarEnrolmentId", this.aadhaarEnrolmentId, actualChanges,
+                v -> this.aadhaarEnrolmentId = v);
+        updateDateField(command, "aadhaarEnrolmentDate", this.aadhaarEnrolmentDate, actualChanges,
+                v -> this.aadhaarEnrolmentDate = v);
+        updateStringField(command, "aadhaarReceiptRemarks", this.aadhaarReceiptRemarks, actualChanges,
+                v -> this.aadhaarReceiptRemarks = v);
+        updateDateField(command, "aadhaarReceiptTakenOn", this.aadhaarReceiptTakenOn, actualChanges,
+                v -> this.aadhaarReceiptTakenOn = v);
         updateStringField(command, "enterprisePan", this.enterprisePan, actualChanges, v -> this.enterprisePan = v);
         updateStringField(command, "cinNumber", this.cinNumber, actualChanges, v -> this.cinNumber = v);
         updateStringField(command, "dinNumber", this.dinNumber, actualChanges, v -> this.dinNumber = v);
@@ -391,12 +544,23 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         updateStringField(command, "freezeReason", this.freezeReason, actualChanges, v -> this.freezeReason = v);
         updateStringField(command, "freezeAuthority", this.freezeAuthority, actualChanges,
                 v -> this.freezeAuthority = v);
+        updateDateField(command, "freezeDate", this.freezeDate, actualChanges, v -> this.freezeDate = v);
+        updateBigDecimalField(command, "freezeAmount", this.freezeAmount, actualChanges, v -> this.freezeAmount = v);
+        updateDateField(command, "unfreezeDate", this.unfreezeDate, actualChanges, v -> this.unfreezeDate = v);
+        updateDateField(command, "noDebitDate", this.noDebitDate, actualChanges, v -> this.noDebitDate = v);
         updateStringField(command, "form60Type", this.form60Type, actualChanges, v -> this.form60Type = v);
         updateDateField(command, "form60Date", this.form60Date, actualChanges, v -> this.form60Date = v);
         updateBooleanField(command, "form15Applicable", this.form15Applicable, actualChanges,
                 v -> this.form15Applicable = v);
         updateStringField(command, "form15Type", this.form15Type, actualChanges, v -> this.form15Type = v);
         updateStringField(command, "form15FY", this.form15Fy, actualChanges, v -> this.form15Fy = v);
+        updateBooleanField(command, "isException", this.isException, actualChanges, v -> this.isException = v != null ? v : false);
+        updateStringField(command, "exceptionReason", this.exceptionReason, actualChanges, v -> this.exceptionReason = v);
+        updateBooleanField(command, "exceptionResolved", this.exceptionResolved, actualChanges, v -> this.exceptionResolved = v != null ? v : false);
+        updateDateField(command, "exceptionResolvedOn", this.exceptionResolvedOn, actualChanges, v -> this.exceptionResolvedOn = v);
+        updateBooleanField(command, "panVerified", this.panVerified, actualChanges, v -> this.panVerified = v != null ? v : false);
+        updateBooleanField(command, "aadhaarVerified", this.aadhaarVerified, actualChanges, v -> this.aadhaarVerified = v != null ? v : false);
+        updateBooleanField(command, "gstinVerified", this.gstinVerified, actualChanges, v -> this.gstinVerified = v != null ? v : false);
 
         return actualChanges;
     }
@@ -406,6 +570,7 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         if (command.isChangeInStringParameterNamed(param, current)) {
             final String newValue = command.stringValueOfParameterNamed(param);
             changes.put(param, newValue);
+            recordOverwrite(param, current);
             setter.accept(StringUtils.defaultIfEmpty(newValue, null));
         }
     }
@@ -415,6 +580,7 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         if (command.isChangeInLocalDateParameterNamed(param, current)) {
             final LocalDate newValue = command.localDateValueOfParameterNamed(param);
             changes.put(param, newValue);
+            recordOverwrite(param, current);
             setter.accept(newValue);
         }
     }
@@ -425,11 +591,51 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
             final Boolean newValue = command.booleanObjectValueOfParameterNamed(param);
             if ((newValue == null && current != null) || (newValue != null && !newValue.equals(current))) {
                 changes.put(param, newValue);
+                recordOverwrite(param, current);
                 setter.accept(newValue);
             }
         }
     }
 
+    private void updateBigDecimalField(final JsonCommand command, final String param, final BigDecimal current,
+            final Map<String, Object> changes, final java.util.function.Consumer<BigDecimal> setter) {
+        if (command.isChangeInBigDecimalParameterNamed(param, current)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed(param);
+            changes.put(param, newValue);
+            recordOverwrite(param, current);
+            setter.accept(newValue);
+        }
+    }
+
+    /**
+     * Notes that {@code param} replaced a value the record already held. A field going from empty to
+     * populated is the record being completed rather than altered, so it is deliberately not
+     * recorded — see {@link #getFieldsOverwrittenByLastUpdate()}.
+     */
+    private void recordOverwrite(final String param, final Object currentValue) {
+        final boolean wasPopulated = currentValue instanceof String text
+                ? StringUtils.isNotBlank(text)
+                : currentValue != null;
+        if (wasPopulated) {
+            this.fieldsOverwrittenByLastUpdate.add(param);
+        }
+    }
+
+    /**
+     * Parameters whose already-populated value the most recent {@link #update} replaced.
+     *
+     * <p>Distinguishes altering a record from finishing one: a non-individual KYC auto-verifies as
+     * soon as PAN and GSTIN pass, which happens part-way through the create wizard, and the officer
+     * still has to save the KYC document details afterwards. Those fields are empty at that point,
+     * so filling them in leaves this set empty and no audit justification is demanded — while
+     * changing a document number that was already on the verified record does populate it.
+     *
+     * <p>Reset at the start of every {@link #update} and never persisted: it describes one call.
+     */
+    public Set<String> getFieldsOverwrittenByLastUpdate() {
+        return Collections.unmodifiableSet(this.fieldsOverwrittenByLastUpdate);
+    }
+
     /** Called when documents are submitted and 3rd-party verification is initiated. */
     public void markInProgress() {
         this.kycStatus = ClientKycStatus.IN_PROGRESS.getValue();
@@ -456,13 +662,13 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     public void markCkycUploaded(final String ckycNumber, final String batchId) {
         this.ckycNumber = StringUtils.defaultIfEmpty(ckycNumber, null);
         this.ckycBatchId = StringUtils.defaultIfEmpty(batchId, null);
-        this.ckycUploadedOn = LocalDate.now();
+        this.ckycUploadedOn = DateUtils.getLocalDateOfTenant();
     }
 
     /** Called after successful 3rd-party verification of all required documents. */
     public void markVerified(final String ckycNumber) {
         this.kycStatus = ClientKycStatus.VERIFIED.getValue();
-        this.verifiedOn = LocalDate.now();
+        this.verifiedOn = DateUtils.getLocalDateOfTenant();
         this.ckycNumber = StringUtils.defaultIfEmpty(ckycNumber, null);
 
         final KycRiskCategory risk = KycRiskCategory.fromInt(this.riskCategory);
@@ -474,14 +680,14 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     /** Called when verification fails. */
     public void markRejected(final String remarks) {
         this.kycStatus = ClientKycStatus.REJECTED.getValue();
-        this.rejectedOn = LocalDate.now();
+        this.rejectedOn = DateUtils.getLocalDateOfTenant();
         this.remarks = StringUtils.defaultIfEmpty(remarks, this.remarks);
     }
 
     public void markPanVerified(final String fullName, final String firstName, final String lastName,
             final String aadhaarSeedingStatus, final String category, final String status) {
         this.panVerified = true;
-        this.panVerifiedOn = LocalDate.now();
+        this.panVerifiedOn = DateUtils.getLocalDateOfTenant();
         this.panFullName = StringUtils.defaultIfEmpty(fullName, null);
         this.panFirstName = StringUtils.defaultIfEmpty(firstName, null);
         this.panLastName = StringUtils.defaultIfEmpty(lastName, null);
@@ -507,28 +713,28 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
 
     public void markAadhaarVerified() {
         this.aadhaarVerified = true;
-        this.aadhaarVerifiedOn = LocalDate.now();
+        this.aadhaarVerifiedOn = DateUtils.getLocalDateOfTenant();
     }
 
     public void markGstinVerified() {
         this.gstinVerified = true;
-        this.gstinVerifiedOn = LocalDate.now();
+        this.gstinVerifiedOn = DateUtils.getLocalDateOfTenant();
     }
 
     public void markCinVerified() {
         this.cinVerified = true;
-        this.cinVerifiedOn = LocalDate.now();
+        this.cinVerifiedOn = DateUtils.getLocalDateOfTenant();
     }
 
     public void markDinVerified() {
         this.dinVerified = true;
-        this.dinVerifiedOn = LocalDate.now();
+        this.dinVerifiedOn = DateUtils.getLocalDateOfTenant();
     }
 
     public void markDinVerified(final String dinNumber, final String mcaResponseJson) {
         this.dinNumber = dinNumber;
         this.dinVerified = true;
-        this.dinVerifiedOn = LocalDate.now();
+        this.dinVerifiedOn = DateUtils.getLocalDateOfTenant();
         this.isDirector = true;
         this.dinMcaResponse = mcaResponseJson;
     }
@@ -585,6 +791,15 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         return riskCategory;
     }
 
+    /**
+     * Directly sets the risk category outside the normal command-diff update path. Used by the AML
+     * module to auto-escalate a client's risk category after their 3rd cumulative STR case -
+     * every such change is recorded in {@code m_client_risk_category_history} by the caller.
+     */
+    public void escalateRiskCategory(Integer newCategory) {
+        this.riskCategory = newCategory;
+    }
+
     public String getPanNumber() {
         return panNumber;
     }
@@ -621,6 +836,60 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         return panStatus;
     }
 
+    public Boolean getPanDeclarationTaken() {
+        return panDeclarationTaken;
+    }
+
+    /** Null-safe form for callers deciding whether the PAN exception is waived. */
+    public boolean isPanDeclarationTaken() {
+        return Boolean.TRUE.equals(this.panDeclarationTaken);
+    }
+
+    public String getPanDeclarationMismatchFields() {
+        return panDeclarationMismatchFields;
+    }
+
+    public String getPanDeclarationNameOnPan() {
+        return panDeclarationNameOnPan;
+    }
+
+    public LocalDate getPanDeclarationDobOnPan() {
+        return panDeclarationDobOnPan;
+    }
+
+    public String getPanDeclarationRemarks() {
+        return panDeclarationRemarks;
+    }
+
+    public LocalDate getPanDeclarationTakenOn() {
+        return panDeclarationTakenOn;
+    }
+
+    public Boolean getAadhaarReceiptTaken() {
+        return aadhaarReceiptTaken;
+    }
+
+    /** Null-safe form for callers deciding whether the Aadhaar exception is waived. */
+    public boolean isAadhaarReceiptTaken() {
+        return Boolean.TRUE.equals(this.aadhaarReceiptTaken);
+    }
+
+    public String getAadhaarEnrolmentId() {
+        return aadhaarEnrolmentId;
+    }
+
+    public LocalDate getAadhaarEnrolmentDate() {
+        return aadhaarEnrolmentDate;
+    }
+
+    public String getAadhaarReceiptRemarks() {
+        return aadhaarReceiptRemarks;
+    }
+
+    public LocalDate getAadhaarReceiptTakenOn() {
+        return aadhaarReceiptTakenOn;
+    }
+
     public String getAadhaarNumberMasked() {
         return aadhaarNumberMasked;
     }
@@ -785,6 +1054,38 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         return form15Fy;
     }
 
+    public Boolean getIsException() {
+        return isException;
+    }
+
+    public void setIsException(Boolean isException) {
+        this.isException = isException;
+    }
+
+    public String getExceptionReason() {
+        return exceptionReason;
+    }
+
+    public void setExceptionReason(String exceptionReason) {
+        this.exceptionReason = exceptionReason;
+    }
+
+    public Boolean getExceptionResolved() {
+        return exceptionResolved;
+    }
+
+    public void setExceptionResolved(Boolean exceptionResolved) {
+        this.exceptionResolved = exceptionResolved;
+    }
+
+    public LocalDate getExceptionResolvedOn() {
+        return exceptionResolvedOn;
+    }
+
+    public void setExceptionResolvedOn(LocalDate exceptionResolvedOn) {
+        this.exceptionResolvedOn = exceptionResolvedOn;
+    }
+
     @Column(name = "is_active", nullable = false)
     private Boolean isActive = Boolean.TRUE;
 
@@ -836,4 +1137,20 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     public Long getVersion() {
         return this.version;
     }
+
+    public LocalDate getFreezeDate() {
+        return this.freezeDate;
+    }
+
+    public BigDecimal getFreezeAmount() {
+        return this.freezeAmount;
+    }
+
+    public LocalDate getUnfreezeDate() {
+        return this.unfreezeDate;
+    }
+
+    public LocalDate getNoDebitDate() {
+        return this.noDebitDate;
+    }
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKycContactLog.java

@@ -0,0 +1,204 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+
+/**
+ * One customer-outreach attempt against an open KYC exception.
+ *
+ * <p>Append-only by design — there is no setter-driven update path and the API exposes no PUT or
+ * DELETE. A contact log that can be edited after the fact is worthless as evidence, and RBI's KYC
+ * Master Direction expects the bank to be able to show what it told the customer and when.
+ *
+ * <p>Destinations are stored masked ({@code destinationMasked}); the full mobile number / email
+ * lives on {@code m_client} and is resolved server-side at send time, never accepted from the
+ * browser.
+ */
+@Entity
+@Table(name = "m_client_kyc_contact_log")
+public class ClientKycContactLog {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "id")
+    private Long id;
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    /** The KYC record the exception belongs to. Nullable — outreach can precede a KYC row. */
+    @Column(name = "kyc_id")
+    private Long kycId;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "channel", length = 20, nullable = false)
+    private KycContactChannel channel;
+
+    @Column(name = "notes", length = 1000, nullable = false)
+    private String notes;
+
+    @Column(name = "officer_name", length = 200)
+    private String officerName;
+
+    @Column(name = "logged_by_user_id")
+    private Long loggedByUserId;
+
+    @Column(name = "exception_reason", length = 200)
+    private String exceptionReason;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "delivery_status", length = 30, nullable = false)
+    private KycContactDeliveryStatus deliveryStatus;
+
+    @Column(name = "destination_masked", length = 120)
+    private String destinationMasked;
+
+    @Column(name = "provider", length = 40)
+    private String provider;
+
+    @Column(name = "provider_reference", length = 120)
+    private String providerReference;
+
+    @Column(name = "failure_reason", length = 500)
+    private String failureReason;
+
+    @Column(name = "message_body", length = 2000)
+    private String messageBody;
+
+    @Column(name = "contacted_at", nullable = false)
+    private LocalDateTime contactedAt;
+
+    @Column(name = "created_at", nullable = false)
+    private LocalDateTime createdAt;
+
+    protected ClientKycContactLog() {
+        // JPA
+    }
+
+    public ClientKycContactLog(final Client client, final Long kycId, final KycContactChannel channel, final String notes,
+            final String officerName, final Long loggedByUserId, final String exceptionReason, final LocalDateTime contactedAt) {
+        this.client = client;
+        this.kycId = kycId;
+        this.channel = channel;
+        this.notes = notes;
+        this.officerName = officerName;
+        this.loggedByUserId = loggedByUserId;
+        this.exceptionReason = exceptionReason;
+        this.contactedAt = contactedAt;
+        this.createdAt = contactedAt;
+        this.deliveryStatus = KycContactDeliveryStatus.NOT_APPLICABLE;
+    }
+
+    /**
+     * Stamp the outcome of a platform send onto this log row. Called once, before the row is
+     * persisted — the entity is append-only afterwards.
+     */
+    public void recordDeliveryOutcome(final KycContactDeliveryStatus status, final String destinationMasked, final String provider,
+            final String providerReference, final String failureReason, final String messageBody) {
+        this.deliveryStatus = status;
+        this.destinationMasked = destinationMasked;
+        this.provider = provider;
+        this.providerReference = providerReference;
+        this.failureReason = truncate(failureReason, 500);
+        this.messageBody = truncate(messageBody, 2000);
+    }
+
+    private static String truncate(final String value, final int max) {
+        if (value == null || value.length() <= max) {
+            return value;
+        }
+        return value.substring(0, max - 3) + "...";
+    }
+
+    public Long getId() {
+        return this.id;
+    }
+
+    public Client getClient() {
+        return this.client;
+    }
+
+    public Long getKycId() {
+        return this.kycId;
+    }
+
+    public KycContactChannel getChannel() {
+        return this.channel;
+    }
+
+    public String getNotes() {
+        return this.notes;
+    }
+
+    public String getOfficerName() {
+        return this.officerName;
+    }
+
+    public Long getLoggedByUserId() {
+        return this.loggedByUserId;
+    }
+
+    public String getExceptionReason() {
+        return this.exceptionReason;
+    }
+
+    public KycContactDeliveryStatus getDeliveryStatus() {
+        return this.deliveryStatus;
+    }
+
+    public String getDestinationMasked() {
+        return this.destinationMasked;
+    }
+
+    public String getProvider() {
+        return this.provider;
+    }
+
+    public String getProviderReference() {
+        return this.providerReference;
+    }
+
+    public String getFailureReason() {
+        return this.failureReason;
+    }
+
+    public String getMessageBody() {
+        return this.messageBody;
+    }
+
+    public LocalDateTime getContactedAt() {
+        return this.contactedAt;
+    }
+
+    public LocalDateTime getCreatedAt() {
+        return this.createdAt;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKycContactLogRepository.java

@@ -0,0 +1,36 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+public interface ClientKycContactLogRepository extends JpaRepository<ClientKycContactLog, Long> {
+
+    List<ClientKycContactLog> findByClientIdOrderByContactedAtAsc(Long clientId);
+
+    /**
+     * Every contact log for the given clients in one round trip, so the exceptions grid can render
+     * "last contacted" for the whole page without an N+1 query per row.
+     */
+    @Query("SELECT l FROM ClientKycContactLog l WHERE l.client.id IN :clientIds ORDER BY l.contactedAt ASC")
+    List<ClientKycContactLog> findByClientIds(@Param("clientIds") List<Long> clientIds);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKycRepository.java

@@ -33,6 +33,18 @@ public interface ClientKycRepository extends JpaRepository<ClientKyc, Long> {
 
     boolean existsByClientId(Long clientId);
 
+    List<ClientKyc> findByIsExceptionTrueAndExceptionResolvedFalse();
+
+    /**
+     * Resolved exceptions, keyed on {@code exceptionResolved} alone.
+     *
+     * <p>Deliberately does NOT also require {@code isException = true}. Resolving an exception
+     * clears {@code isException} — that flag means "has an OPEN exception", so leaving it set on a
+     * closed one would be wrong. An earlier version of this query required both flags, which made
+     * every resolved record invisible in both tabs the moment it was resolved.
+     */
+    List<ClientKyc> findByExceptionResolvedTrue();
+
     @Query("SELECT k FROM ClientKyc k WHERE k.kycStatus = :status")
     List<ClientKyc> findAllByStatus(@Param("status") Integer status);
 

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientRepository.java

@@ -55,12 +55,13 @@ public interface ClientRepository extends JpaRepository<Client, Long>, JpaSpecif
     @Query("UPDATE Client client SET client.imageId = null WHERE client.id = :clientId")
     void removeImageId(@Param("clientId") Long clientId);
 
-    /**
+    @Modifying
-     * Count clients whose cif_number begins with the given prefix. Used by the CIF number generator
+    @Query("UPDATE Client client SET client.signatureId = :signatureId WHERE client.id = :clientId")
-     * (TTYYYYNNNNNN format) to compute the next sequence within a given (type, year) bucket.
+    void updateByIdAndSignatureId(@Param("clientId") Long clientId, @Param("signatureId") Long signatureId);
-     */
+
-    @Query("SELECT COUNT(c) FROM Client c WHERE c.cifNumber LIKE CONCAT(:prefix, '%')")
+    @Modifying
-    long countByCifNumberPrefix(@Param("prefix") String prefix);
+    @Query("UPDATE Client client SET client.signatureId = null WHERE client.id = :clientId")
+    void removeSignatureId(@Param("clientId") Long clientId);
 
     // ── Pre-save uniqueness probes ───────────────────────────────────────────
     // Why: DB has UNIQUE on mobile_no / email_address, but we want to fail fast with a clear

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientRiskRule.java

@@ -0,0 +1,211 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import org.apache.fineract.infrastructure.codes.domain.CodeValue;
+
+@Entity
+@Table(name = "m_client_risk_rule")
+public class ClientRiskRule {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "rule_name", nullable = false, length = 100)
+    private String ruleName;
+
+    @Column(name = "legal_form_id")
+    private Integer legalFormId;
+
+    @ManyToOne
+    @JoinColumn(name = "occupation_category_cv_id")
+    private CodeValue occupationCategory;
+
+    @ManyToOne
+    @JoinColumn(name = "occupation_cv_id")
+    private CodeValue occupation;
+
+    @Column(name = "min_monthly_income", precision = 19, scale = 6)
+    private BigDecimal minMonthlyIncome;
+
+    @Column(name = "max_monthly_income", precision = 19, scale = 6)
+    private BigDecimal maxMonthlyIncome;
+
+    @Column(name = "min_annual_income", precision = 19, scale = 6)
+    private BigDecimal minAnnualIncome;
+
+    @Column(name = "max_annual_income", precision = 19, scale = 6)
+    private BigDecimal maxAnnualIncome;
+
+    @Column(name = "min_annual_turnover", precision = 19, scale = 6)
+    private BigDecimal minAnnualTurnover;
+
+    @Column(name = "max_annual_turnover", precision = 19, scale = 6)
+    private BigDecimal maxAnnualTurnover;
+
+    @Column(name = "risk_category", nullable = false)
+    private Integer riskCategory;
+
+    @Column(name = "reason", nullable = false, length = 500)
+    private String reason;
+
+    @Column(name = "aml_check_status", length = 20)
+    private String amlCheckStatus;
+
+    @Column(name = "banned_entity_match", length = 10)
+    private String bannedEntityMatch;
+
+    @Column(name = "willful_defaulter", length = 10)
+    private String willfulDefaulter;
+
+    @Column(name = "ecgc_sal_flag", length = 10)
+    private String ecgcSalFlag;
+
+    @Column(name = "dormant_flag", length = 20)
+    private String dormantFlag;
+
+    @Column(name = "order_position", nullable = false)
+    private Integer orderPosition;
+
+    protected ClientRiskRule() {}
+
+    /**
+     * Builds a rule authored from the AML Rules Master screen. Occupation and occupation-category
+     * are attached separately by the caller, which owns the CodeValue lookup.
+     */
+    public static ClientRiskRule create(final String ruleName, final String reason, final Integer riskCategory,
+            final Integer orderPosition, final Integer legalFormId, final BigDecimal minMonthlyIncome,
+            final BigDecimal maxMonthlyIncome, final BigDecimal minAnnualIncome, final BigDecimal maxAnnualIncome,
+            final BigDecimal minAnnualTurnover, final BigDecimal maxAnnualTurnover, final String amlCheckStatus,
+            final String bannedEntityMatch, final String willfulDefaulter, final String ecgcSalFlag,
+            final String dormantFlag) {
+        final ClientRiskRule rule = new ClientRiskRule();
+        rule.ruleName = ruleName;
+        rule.reason = reason;
+        rule.riskCategory = riskCategory;
+        rule.orderPosition = orderPosition;
+        rule.legalFormId = legalFormId;
+        rule.minMonthlyIncome = minMonthlyIncome;
+        rule.maxMonthlyIncome = maxMonthlyIncome;
+        rule.minAnnualIncome = minAnnualIncome;
+        rule.maxAnnualIncome = maxAnnualIncome;
+        rule.minAnnualTurnover = minAnnualTurnover;
+        rule.maxAnnualTurnover = maxAnnualTurnover;
+        rule.amlCheckStatus = amlCheckStatus;
+        rule.bannedEntityMatch = bannedEntityMatch;
+        rule.willfulDefaulter = willfulDefaulter;
+        rule.ecgcSalFlag = ecgcSalFlag;
+        rule.dormantFlag = dormantFlag;
+        return rule;
+    }
+
+    public void setOccupationCategory(final CodeValue occupationCategory) {
+        this.occupationCategory = occupationCategory;
+    }
+
+    public void setOccupation(final CodeValue occupation) {
+        this.occupation = occupation;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public String getRuleName() {
+        return ruleName;
+    }
+
+    public Integer getLegalFormId() {
+        return legalFormId;
+    }
+
+    public CodeValue getOccupationCategory() {
+        return occupationCategory;
+    }
+
+    public CodeValue getOccupation() {
+        return occupation;
+    }
+
+    public BigDecimal getMinMonthlyIncome() {
+        return minMonthlyIncome;
+    }
+
+    public BigDecimal getMaxMonthlyIncome() {
+        return maxMonthlyIncome;
+    }
+
+    public BigDecimal getMinAnnualIncome() {
+        return minAnnualIncome;
+    }
+
+    public BigDecimal getMaxAnnualIncome() {
+        return maxAnnualIncome;
+    }
+
+    public BigDecimal getMinAnnualTurnover() {
+        return minAnnualTurnover;
+    }
+
+    public BigDecimal getMaxAnnualTurnover() {
+        return maxAnnualTurnover;
+    }
+
+    public Integer getRiskCategory() {
+        return riskCategory;
+    }
+
+    public String getReason() {
+        return reason;
+    }
+
+    public Integer getOrderPosition() {
+        return orderPosition;
+    }
+
+    public String getAmlCheckStatus() {
+        return amlCheckStatus;
+    }
+
+    public String getBannedEntityMatch() {
+        return bannedEntityMatch;
+    }
+
+    public String getWillfulDefaulter() {
+        return willfulDefaulter;
+    }
+
+    public String getEcgcSalFlag() {
+        return ecgcSalFlag;
+    }
+
+    public String getDormantFlag() {
+        return dormantFlag;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientRiskRuleRepository.java

@@ -0,0 +1,35 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+
+public interface ClientRiskRuleRepository extends JpaRepository<ClientRiskRule, Long> {
+
+    @Query("SELECT r FROM ClientRiskRule r ORDER BY r.orderPosition ASC")
+    List<ClientRiskRule> findAllOrderedByOrderPosition();
+
+    /** Highest position in use, so a new rule can be appended to the end of the catalog. */
+    @Query("SELECT MAX(r.orderPosition) FROM ClientRiskRule r")
+    Integer findMaxOrderPosition();
+
+    boolean existsByRuleNameIgnoreCase(String ruleName);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/KycContactChannel.java

@@ -0,0 +1,91 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+/**
+ * The channel a KYC officer used (or asked the platform to use) to reach a customer about an open
+ * KYC exception.
+ *
+ * <p>The critical distinction is {@link #isPlatformSent()}:
+ * <ul>
+ *   <li><b>Offline channels</b> ({@code PHONE_CALL}, {@code BRANCH_VISIT}, {@code FIELD_VISIT}) are
+ *       recorded after the fact — the officer already did the thing, the platform only writes it
+ *       down.</li>
+ *   <li><b>Sending channels</b> ({@code SMS}, {@code EMAIL}, {@code WHATSAPP}) cause the platform to
+ *       actually transmit a notice to the customer at save time.</li>
+ * </ul>
+ * Mixing these up would let a "logged" row imply the customer was told something they never
+ * received, so every call site branches on this flag rather than on the channel name.
+ */
+public enum KycContactChannel {
+
+    PHONE_CALL("Phone Call", false),
+    SMS("SMS", true),
+    EMAIL("Email", true),
+    WHATSAPP("WhatsApp Message", true),
+    BRANCH_VISIT("In-Branch Visit", false),
+    FIELD_VISIT("Agent Field Visit", false);
+
+    private final String displayLabel;
+    private final boolean platformSent;
+
+    KycContactChannel(final String displayLabel, final boolean platformSent) {
+        this.displayLabel = displayLabel;
+        this.platformSent = platformSent;
+    }
+
+    public String getDisplayLabel() {
+        return this.displayLabel;
+    }
+
+    /** True when saving a log of this channel must actually transmit a message to the customer. */
+    public boolean isPlatformSent() {
+        return this.platformSent;
+    }
+
+    /**
+     * Lenient parse of whatever the UI sent. Accepts the enum name ({@code SMS}) as well as the
+     * display label, and tolerates the descriptive suffixes the dialog uses — e.g.
+     * {@code "SMS (Aadhaar OTP request)"} and {@code "Email (PAN Link request)"} — because those
+     * labels describe the *purpose* of the message, not a different channel.
+     *
+     * @return the matching channel, or {@code null} when nothing matches.
+     */
+    public static KycContactChannel fromString(final String raw) {
+        if (raw == null || raw.isBlank()) {
+            return null;
+        }
+        final String normalised = raw.trim().toUpperCase();
+        for (final KycContactChannel channel : values()) {
+            if (normalised.equals(channel.name()) || normalised.equals(channel.displayLabel.toUpperCase())) {
+                return channel;
+            }
+        }
+        // Prefix match handles the "(…request)" suffixes. Longest label first so WHATSAPP's
+        // "WHATSAPP MESSAGE" is preferred over a shorter accidental prefix.
+        KycContactChannel best = null;
+        for (final KycContactChannel channel : values()) {
+            final String label = channel.displayLabel.toUpperCase();
+            if (normalised.startsWith(label) && (best == null || label.length() > best.displayLabel.length())) {
+                best = channel;
+            }
+        }
+        return best;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/KycContactDeliveryStatus.java

@@ -0,0 +1,48 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+/**
+ * Outcome of a platform-sent KYC contact notice.
+ *
+ * <p>Every state other than {@link #SENT} means the customer was <em>not</em> reached. The officer
+ * is shown the distinction explicitly, because a contact log that silently swallows a gateway
+ * failure would understate the bank's outreach obligation during a KYC audit.
+ */
+public enum KycContactDeliveryStatus {
+
+    /** Offline channel — nothing was transmitted and nothing was supposed to be. */
+    NOT_APPLICABLE,
+
+    /** The gateway accepted the message for delivery. */
+    SENT,
+
+    /** The gateway was reached but rejected the message, or the call errored. */
+    FAILED,
+
+    /** The customer has no mobile number / email address on file for this channel. */
+    SKIPPED_NO_DESTINATION,
+
+    /** No gateway is configured for this channel in this deployment. */
+    PROVIDER_NOT_CONFIGURED;
+
+    public boolean isDelivered() {
+        return this == SENT;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/data/BatchRunData.java

@@ -0,0 +1,50 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.Collection;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder(toBuilder = true)
+public final class BatchRunData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final String jobType;
+    private final String branchScope;
+    private final LocalDate jobDate;
+    private final Long agentFrom;
+    private final Long agentTo;
+    private final Long partyFrom;
+    private final Long partyTo;
+    private final String status;
+    private final Integer totalRows;
+    private final BigDecimal totalAmount;
+    private final LocalDate generatedOnDate;
+    private final LocalDate postedOnDate;
+    private final Collection<BatchRunRowData> rows;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/data/BatchRunRowData.java

@@ -0,0 +1,41 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+public final class BatchRunRowData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long partyId;
+    private final String partyCode;
+    private final String partyName;
+    private final Long agentId;
+    private final String agentCode;
+    private final BigDecimal amount;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/domain/BatchRun.java

@@ -0,0 +1,122 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.domain;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.List;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+
+/**
+ * One Calculate-then-Post batch run - the deliberate two-step control from the legacy Interest Part
+ * menu (Interest Calculation -> Interest Posting, OD Interest Calculation -> OD Interest Posting,
+ * Commission Calculation -> Commission Posting): a run is generated (rows computed and saved as a
+ * preview, nothing else changes), then posted (a separate, explicit step that applies exactly the
+ * rows that were previewed - never a fresh recalculation, so what gets applied is always what was
+ * seen).
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_batch_run")
+public class BatchRun extends AbstractPersistableCustom<Long> {
+
+    @Column(name = "job_type", length = 40, nullable = false)
+    private String jobType;
+
+    @Column(name = "branch_scope", length = 20, nullable = false)
+    private String branchScope;
+
+    @Column(name = "job_date", nullable = false)
+    private LocalDate jobDate;
+
+    @Column(name = "agent_from", nullable = false)
+    private Long agentFrom;
+
+    @Column(name = "agent_to", nullable = false)
+    private Long agentTo;
+
+    @Column(name = "party_from")
+    private Long partyFrom;
+
+    @Column(name = "party_to")
+    private Long partyTo;
+
+    @Column(name = "status", length = 20, nullable = false)
+    private String status;
+
+    @Column(name = "total_rows", nullable = false)
+    private Integer totalRows;
+
+    @Column(name = "total_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal totalAmount;
+
+    @Column(name = "generated_on_date", nullable = false)
+    private LocalDate generatedOnDate;
+
+    @Column(name = "posted_on_date")
+    private LocalDate postedOnDate;
+
+    @OneToMany(mappedBy = "batchRun", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+    @OrderBy("id")
+    private List<BatchRunRow> rows = new ArrayList<>();
+
+    protected BatchRun() {
+        //
+    }
+
+    public BatchRun(final String jobType, final String branchScope, final LocalDate jobDate, final Long agentFrom,
+            final Long agentTo, final Long partyFrom, final Long partyTo, final LocalDate generatedOnDate) {
+        this.jobType = jobType;
+        this.branchScope = branchScope;
+        this.jobDate = jobDate;
+        this.agentFrom = agentFrom;
+        this.agentTo = agentTo;
+        this.partyFrom = partyFrom;
+        this.partyTo = partyTo;
+        this.status = "CALCULATED";
+        this.totalRows = 0;
+        this.totalAmount = BigDecimal.ZERO;
+        this.generatedOnDate = generatedOnDate;
+    }
+
+    public void addRow(final BatchRunRow row) {
+        row.setBatchRun(this);
+        this.rows.add(row);
+        this.totalRows = this.rows.size();
+        this.totalAmount = this.totalAmount.add(row.getAmount());
+    }
+
+    public boolean isPosted() {
+        return "POSTED".equals(this.status);
+    }
+
+    public void markPosted(final LocalDate postedOnDate) {
+        this.status = "POSTED";
+        this.postedOnDate = postedOnDate;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/domain/BatchRunRow.java

@@ -0,0 +1,65 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+
+/**
+ * One previewed/posted line of a {@link BatchRun}: for an interest job, one Party's accrued interest;
+ * for a commission job, one Agent's commission on their collected volume (partyId is null there).
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_batch_run_row")
+public class BatchRunRow extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "batch_run_id", nullable = false)
+    private BatchRun batchRun;
+
+    @Column(name = "party_id")
+    private Long partyId;
+
+    @Column(name = "agent_id", nullable = false)
+    private Long agentId;
+
+    @Column(name = "amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal amount;
+
+    protected BatchRunRow() {
+        //
+    }
+
+    public BatchRunRow(final Long partyId, final Long agentId, final BigDecimal amount) {
+        this.partyId = partyId;
+        this.agentId = agentId;
+        this.amount = amount;
+    }
+
+    void setBatchRun(final BatchRun batchRun) {
+        this.batchRun = batchRun;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/exception/BatchRunAlreadyPostedException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when Post is attempted on a batch run that has already been posted - a run applies once,
+ * matching the calculate-then-post safety control (never re-post the same preview).
+ */
+public class BatchRunAlreadyPostedException extends AbstractPlatformDomainRuleException {
+
+    public BatchRunAlreadyPostedException(final Long batchRunId) {
+        super("error.msg.ddsbatchrun.already.posted", "DDS batch run " + batchRunId + " has already been posted", batchRunId);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/exception/BatchRunNotFoundException.java

@@ -0,0 +1,28 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+
+public class BatchRunNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public BatchRunNotFoundException(final Long id) {
+        super("error.msg.ddsbatchrun.id.invalid", "DDS batch run with identifier " + id + " does not exist", id);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/data/PartyData.java

@@ -0,0 +1,107 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.Collection;
+import lombok.Builder;
+import lombok.Getter;
+
+/**
+ * Immutable data object representing a DDS Party (customer scheme account), including its nominees.
+ * Built via the Lombok builder rather than a long positional constructor - the field count here makes
+ * positional args unreadable and error-prone to keep in sync.
+ */
+@Getter
+@Builder(toBuilder = true)
+public final class PartyData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long clientId;
+    private final String clientName;
+    private final Long agentId;
+    private final String agentCode;
+    private final String agentName;
+    private final Long savingsAccountId;
+    private final String subType;
+    private final String partyCode;
+    private final String lastAccount;
+    private final Boolean nominal;
+    private final String aadharNo;
+    private final String partyName;
+    private final String partyName1;
+    private final String address1;
+    private final String address2;
+    private final String address3;
+    private final String city;
+    private final String pincode;
+    private final String gender;
+    private final String panCardNo;
+    private final String telephone;
+    private final String mobileNoSms;
+    private final String operation;
+    private final LocalDate birthDate;
+    private final String occupation;
+    private final String risk;
+    private final String ckycId;
+    private final String adultMinor;
+    private final LocalDate minorDate;
+    private final Long guardianClientId;
+    private final String minAccountOpt;
+    private final String relation;
+    private final LocalDate openingDate;
+    private final Integer month;
+    private final LocalDate maturityDate;
+    private final LocalDate reopenDate;
+    private final BigDecimal depositAmount;
+    private final BigDecimal dailyDepositAmount;
+    private final Integer days;
+    private final String ledgerNo;
+    private final BigDecimal maturityAmount;
+    private final BigDecimal interestRate;
+    private final String withdrawType;
+    private final Boolean od1Flag;
+    private final Boolean od2Flag;
+    private final Boolean lien;
+    private final LocalDate payDate;
+    private final BigDecimal paymentAmount;
+    private final BigDecimal currentBalance;
+    private final BigDecimal openingBalance;
+    private final Boolean isSmsActive;
+    private final Boolean isEmailActive;
+    private final BigDecimal interestCalc;
+    private final LocalDate interestDate;
+    private final String spDescription;
+    private final String freezeCode;
+    private final String advCode;
+    private final String creditToBranch;
+    private final String creditToAccountType;
+    private final String creditToAccount;
+    private final Boolean nomineeApplicable;
+    private final String nomineeSplitMode;
+    private final String status;
+    private final LocalDate closeDate;
+    private final Collection<PartyNomineeData> nominees;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/data/PartyNomineeData.java

@@ -0,0 +1,59 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.time.LocalDate;
+import lombok.Getter;
+
+@Getter
+public final class PartyNomineeData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final LocalDate nominationDate;
+    private final String name;
+    private final String mobileNo;
+    private final LocalDate birthDate;
+    private final Boolean minor;
+    private final String relation;
+    private final String gender;
+    private final String guardianName;
+
+    public static PartyNomineeData instance(final Long id, final LocalDate nominationDate, final String name, final String mobileNo,
+            final LocalDate birthDate, final Boolean minor, final String relation, final String gender, final String guardianName) {
+        return new PartyNomineeData(id, nominationDate, name, mobileNo, birthDate, minor, relation, gender, guardianName);
+    }
+
+    private PartyNomineeData(final Long id, final LocalDate nominationDate, final String name, final String mobileNo,
+            final LocalDate birthDate, final Boolean minor, final String relation, final String gender, final String guardianName) {
+        this.id = id;
+        this.nominationDate = nominationDate;
+        this.name = name;
+        this.mobileNo = mobileNo;
+        this.birthDate = birthDate;
+        this.minor = minor;
+        this.relation = relation;
+        this.gender = gender;
+        this.guardianName = guardianName;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/domain/Party.java

@@ -0,0 +1,569 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.domain;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Consumer;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+import org.apache.fineract.organisation.agent.domain.Agent;
+import org.apache.fineract.portfolio.client.domain.Client;
+
+/**
+ * A DDS Party - the customer's daily-deposit scheme account, linked to the Agent who collects for it.
+ * Carries the scheme's KYC, terms and two-stage overdue flags, plus a nominee list.
+ *
+ * The underlying RD (recurring deposit) account this scheme conceptually reuses is not wired up yet -
+ * {@code savingsAccountId} is a nullable placeholder for that future linkage (see the DDS architecture
+ * decision to reuse the RD engine for the deposit half). Until then the scheme/balance fields below
+ * are this record's own, not mirrored from any m_savings_account row.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_party", uniqueConstraints = { @UniqueConstraint(columnNames = { "party_code" }, name = "party_code_UNIQUE") })
+public class Party extends AbstractPersistableCustom<Long> {
+
+    /** DDS accounts carry a flat interest rate unless the officer explicitly overrides it at creation. */
+    private static final BigDecimal DEFAULT_INTEREST_RATE = new BigDecimal("2");
+
+    public static final String STATUS_ACTIVE = "ACTIVE";
+    public static final String STATUS_CLOSED = "CLOSED";
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    @Column(name = "savings_account_id")
+    private Long savingsAccountId;
+
+    @Column(name = "sub_type", length = 60, nullable = false)
+    private String subType;
+
+    @Column(name = "party_code", length = 20, nullable = false)
+    private String partyCode;
+
+    @Column(name = "last_account", length = 50)
+    private String lastAccount;
+
+    @Column(name = "nominal", nullable = false)
+    private boolean nominal;
+
+    @Column(name = "aadhar_no", length = 20)
+    private String aadharNo;
+
+    @Column(name = "party_name", length = 100, nullable = false)
+    private String partyName;
+
+    @Column(name = "party_name1", length = 100)
+    private String partyName1;
+
+    @Column(name = "address1", length = 200, nullable = false)
+    private String address1;
+
+    @Column(name = "address2", length = 200)
+    private String address2;
+
+    @Column(name = "address3", length = 200)
+    private String address3;
+
+    @Column(name = "city", length = 100, nullable = false)
+    private String city;
+
+    @Column(name = "pincode", length = 20, nullable = false)
+    private String pincode;
+
+    @Column(name = "gender", length = 20)
+    private String gender;
+
+    @Column(name = "pan_card_no", length = 20)
+    private String panCardNo;
+
+    @Column(name = "telephone", length = 20)
+    private String telephone;
+
+    @Column(name = "mobile_no_sms", length = 20, nullable = false)
+    private String mobileNoSms;
+
+    @Column(name = "operation", length = 20, nullable = false)
+    private String operation;
+
+    @Column(name = "birth_date")
+    private LocalDate birthDate;
+
+    @Column(name = "occupation", length = 40)
+    private String occupation;
+
+    @Column(name = "risk", length = 20)
+    private String risk;
+
+    @Column(name = "ckyc_id", length = 40)
+    private String ckycId;
+
+    @Column(name = "adult_minor", length = 20, nullable = false)
+    private String adultMinor;
+
+    @Column(name = "minor_date")
+    private LocalDate minorDate;
+
+    @Column(name = "guardian_client_id")
+    private Long guardianClientId;
+
+    @Column(name = "min_account_opt", length = 40)
+    private String minAccountOpt;
+
+    @Column(name = "relation", length = 40)
+    private String relation;
+
+    @Column(name = "opening_date", nullable = false)
+    private LocalDate openingDate;
+
+    @Column(name = "months")
+    private Integer month;
+
+    @Column(name = "maturity_date")
+    private LocalDate maturityDate;
+
+    @Column(name = "reopen_date")
+    private LocalDate reopenDate;
+
+    @Column(name = "deposit_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal depositAmount;
+
+    @Column(name = "daily_deposit_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal dailyDepositAmount;
+
+    @Column(name = "days", nullable = false)
+    private Integer days;
+
+    @Column(name = "ledger_no", length = 40)
+    private String ledgerNo;
+
+    @Column(name = "maturity_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal maturityAmount;
+
+    @Column(name = "interest_rate", scale = 6, precision = 19, nullable = false)
+    private BigDecimal interestRate;
+
+    @Column(name = "withdraw_type", length = 20)
+    private String withdrawType;
+
+    @Column(name = "od1_flag", nullable = false)
+    private boolean od1Flag;
+
+    @Column(name = "od2_flag", nullable = false)
+    private boolean od2Flag;
+
+    @Column(name = "lien", nullable = false)
+    private boolean lien;
+
+    @Column(name = "pay_date")
+    private LocalDate payDate;
+
+    @Column(name = "payment_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal paymentAmount;
+
+    @Column(name = "current_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal currentBalance;
+
+    @Column(name = "opening_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal openingBalance;
+
+    @Column(name = "is_sms_active", nullable = false)
+    private boolean isSmsActive;
+
+    @Column(name = "is_email_active", nullable = false)
+    private boolean isEmailActive;
+
+    @Column(name = "interest_calc", scale = 6, precision = 19, nullable = false)
+    private BigDecimal interestCalc;
+
+    @Column(name = "interest_date")
+    private LocalDate interestDate;
+
+    @Column(name = "sp_description", length = 500)
+    private String spDescription;
+
+    @Column(name = "freeze_code", length = 20, nullable = false)
+    private String freezeCode;
+
+    @Column(name = "adv_code", length = 40, nullable = false)
+    private String advCode;
+
+    @Column(name = "credit_to_branch", length = 100)
+    private String creditToBranch;
+
+    @Column(name = "credit_to_account_type", length = 100)
+    private String creditToAccountType;
+
+    @Column(name = "credit_to_account", length = 50)
+    private String creditToAccount;
+
+    @Column(name = "nominee_applicable", nullable = false)
+    private boolean nomineeApplicable;
+
+    @Column(name = "nominee_split_mode", length = 20)
+    private String nomineeSplitMode;
+
+    @Column(name = "status", length = 20, nullable = false)
+    private String status;
+
+    @Column(name = "close_date")
+    private LocalDate closeDate;
+
+    @OneToMany(mappedBy = "party", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+    @OrderBy("id")
+    private List<PartyNominee> nominees = new ArrayList<>();
+
+    protected Party() {
+        //
+    }
+
+    private Party(final Client client, final Agent agent, final String partyCode, final JsonCommand command) {
+        this.client = client;
+        this.agent = agent;
+        this.partyCode = partyCode;
+        this.subType = command.stringValueOfParameterNamed("subType");
+        this.lastAccount = command.stringValueOfParameterNamedAllowingNull("lastAccount");
+        this.nominal = command.booleanPrimitiveValueOfParameterNamed("nominal");
+        this.aadharNo = command.stringValueOfParameterNamedAllowingNull("aadharNo");
+        this.partyName = command.stringValueOfParameterNamed("partyName");
+        this.partyName1 = command.stringValueOfParameterNamedAllowingNull("partyName1");
+        this.address1 = command.stringValueOfParameterNamed("address1");
+        this.address2 = command.stringValueOfParameterNamedAllowingNull("address2");
+        this.address3 = command.stringValueOfParameterNamedAllowingNull("address3");
+        this.city = command.stringValueOfParameterNamed("city");
+        this.pincode = command.stringValueOfParameterNamed("pincode");
+        this.gender = command.stringValueOfParameterNamedAllowingNull("gender");
+        this.panCardNo = command.stringValueOfParameterNamedAllowingNull("panCardNo");
+        this.telephone = command.stringValueOfParameterNamedAllowingNull("telephone");
+        this.mobileNoSms = command.stringValueOfParameterNamed("mobileNoSms");
+        this.operation = command.stringValueOfParameterNamed("operation");
+        this.birthDate = command.localDateValueOfParameterNamed("birthDate");
+        this.occupation = command.stringValueOfParameterNamedAllowingNull("occupation");
+        this.risk = command.stringValueOfParameterNamedAllowingNull("risk");
+        this.ckycId = command.stringValueOfParameterNamedAllowingNull("ckycId");
+        this.adultMinor = command.stringValueOfParameterNamed("adultMinor");
+        this.minorDate = command.localDateValueOfParameterNamed("minorDate");
+        this.guardianClientId = command.longValueOfParameterNamed("guardianClientId");
+        this.minAccountOpt = command.stringValueOfParameterNamedAllowingNull("minAccountOpt");
+        this.relation = command.stringValueOfParameterNamedAllowingNull("relation");
+        this.openingDate = command.localDateValueOfParameterNamed("openingDate");
+        this.month = command.integerValueOfParameterNamedDefaultToNullIfZero("month");
+        this.maturityDate = command.localDateValueOfParameterNamed("maturityDate");
+        this.reopenDate = command.localDateValueOfParameterNamed("reopenDate");
+        this.depositAmount = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("depositAmount"));
+        this.dailyDepositAmount = command.bigDecimalValueOfParameterNamed("dailyDepositAmount");
+        this.days = command.integerValueOfParameterNamed("days");
+        this.ledgerNo = command.stringValueOfParameterNamedAllowingNull("ledgerNo");
+        this.maturityAmount = BigDecimal.ZERO;
+        this.interestRate = command.parameterExists("interestRate")
+                ? command.bigDecimalValueOfParameterNamed("interestRate")
+                : DEFAULT_INTEREST_RATE;
+        this.withdrawType = command.stringValueOfParameterNamedAllowingNull("withdrawType");
+        this.od1Flag = false;
+        this.od2Flag = false;
+        this.lien = command.booleanPrimitiveValueOfParameterNamed("lien");
+        this.payDate = command.localDateValueOfParameterNamed("payDate");
+        this.paymentAmount = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("paymentAmount"));
+        this.openingBalance = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("openingBalance"));
+        this.currentBalance = this.openingBalance;
+        this.isSmsActive = command.booleanPrimitiveValueOfParameterNamed("isSmsActive");
+        this.isEmailActive = command.booleanPrimitiveValueOfParameterNamed("isEmailActive");
+        this.interestCalc = BigDecimal.ZERO;
+        this.interestDate = command.localDateValueOfParameterNamed("interestDate");
+        this.spDescription = command.stringValueOfParameterNamedAllowingNull("spDescription");
+        this.freezeCode = StringUtils.defaultIfBlank(command.stringValueOfParameterNamedAllowingNull("freezeCode"), "Normal");
+        this.advCode = StringUtils.defaultIfBlank(command.stringValueOfParameterNamedAllowingNull("advCode"), "None");
+        this.creditToBranch = command.stringValueOfParameterNamedAllowingNull("creditToBranch");
+        this.creditToAccountType = command.stringValueOfParameterNamedAllowingNull("creditToAccountType");
+        this.creditToAccount = command.stringValueOfParameterNamedAllowingNull("creditToAccount");
+        this.nomineeApplicable = command.booleanPrimitiveValueOfParameterNamed("nomineeApplicable");
+        this.nomineeSplitMode = StringUtils.defaultIfBlank(command.stringValueOfParameterNamedAllowingNull("nomineeSplitMode"),
+                "Percentage");
+        this.status = STATUS_ACTIVE;
+    }
+
+    public static Party fromJson(final Client client, final Agent agent, final String partyCode, final JsonCommand command) {
+        return new Party(client, agent, partyCode, command);
+    }
+
+    private static BigDecimal orZero(final BigDecimal value) {
+        return value == null ? BigDecimal.ZERO : value;
+    }
+
+    public void addNominee(final PartyNominee nominee) {
+        nominee.setParty(this);
+        this.nominees.add(nominee);
+    }
+
+    public void resetNominees() {
+        this.nominees.clear();
+    }
+
+    public void changeClient(final Client newClient) {
+        this.client = newClient;
+    }
+
+    public void changeAgent(final Agent newAgent) {
+        this.agent = newAgent;
+    }
+
+    /**
+     * Links this Party to an existing real Savings Account, resolved by account number in the write
+     * service. There is no unlink - once a Party's DDS scheme is tied to a real account, it stays
+     * tied.
+     */
+    public void linkSavingsAccount(final Long savingsAccountId) {
+        this.savingsAccountId = savingsAccountId;
+    }
+
+    public BigDecimal credit(final BigDecimal amount) {
+        this.currentBalance = this.currentBalance.add(amount);
+        return this.currentBalance;
+    }
+
+    public BigDecimal debit(final BigDecimal amount) {
+        this.currentBalance = this.currentBalance.subtract(amount);
+        return this.currentBalance;
+    }
+
+    public boolean isClosed() {
+        return STATUS_CLOSED.equals(this.status);
+    }
+
+    /**
+     * Closes this Party's account as of the given date. The balance must already be zero - a Party
+     * is settled to zero (a full Withdraw Deposite/payout) before it is closed, not closed with money
+     * still owed to it.
+     */
+    public void close(final LocalDate closeDate) {
+        this.status = STATUS_CLOSED;
+        this.closeDate = closeDate;
+    }
+
+    /**
+     * Stamps the date interest (regular or OD) was last calculated up to, so the next batch run
+     * accrues only the days since. Set on POST, not on calculate/preview.
+     */
+    public void markInterestCalculatedThrough(final LocalDate date) {
+        this.interestDate = date;
+    }
+
+    public Long clientId() {
+        return this.client.getId();
+    }
+
+    public Long agentId() {
+        return this.agent.getId();
+    }
+
+    public Map<String, Object> update(final JsonCommand command) {
+
+        final Map<String, Object> actualChanges = new LinkedHashMap<>(40);
+
+        if (command.isChangeInLongParameterNamed("clientId", this.client.getId())) {
+            actualChanges.put("clientId", command.longValueOfParameterNamed("clientId"));
+        }
+        if (command.isChangeInLongParameterNamed("agentId", this.agent.getId())) {
+            actualChanges.put("agentId", command.longValueOfParameterNamed("agentId"));
+        }
+
+        stringChange(command, actualChanges, "subType", this.subType, v -> this.subType = v);
+        stringChange(command, actualChanges, "lastAccount", this.lastAccount, v -> this.lastAccount = v);
+
+        if (command.isChangeInBooleanParameterNamed("nominal", this.nominal)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("nominal");
+            actualChanges.put("nominal", newValue);
+            this.nominal = newValue;
+        }
+
+        stringChange(command, actualChanges, "aadharNo", this.aadharNo, v -> this.aadharNo = v);
+        stringChange(command, actualChanges, "partyName", this.partyName, v -> this.partyName = v);
+        stringChange(command, actualChanges, "partyName1", this.partyName1, v -> this.partyName1 = v);
+        stringChange(command, actualChanges, "address1", this.address1, v -> this.address1 = v);
+        stringChange(command, actualChanges, "address2", this.address2, v -> this.address2 = v);
+        stringChange(command, actualChanges, "address3", this.address3, v -> this.address3 = v);
+        stringChange(command, actualChanges, "city", this.city, v -> this.city = v);
+        stringChange(command, actualChanges, "pincode", this.pincode, v -> this.pincode = v);
+        stringChange(command, actualChanges, "gender", this.gender, v -> this.gender = v);
+        stringChange(command, actualChanges, "panCardNo", this.panCardNo, v -> this.panCardNo = v);
+        stringChange(command, actualChanges, "telephone", this.telephone, v -> this.telephone = v);
+        stringChange(command, actualChanges, "mobileNoSms", this.mobileNoSms, v -> this.mobileNoSms = v);
+        stringChange(command, actualChanges, "operation", this.operation, v -> this.operation = v);
+
+        if (command.isChangeInDateParameterNamed("birthDate", this.birthDate)) {
+            actualChanges.put("birthDate", command.stringValueOfParameterNamed("birthDate"));
+            this.birthDate = command.localDateValueOfParameterNamed("birthDate");
+        }
+
+        stringChange(command, actualChanges, "occupation", this.occupation, v -> this.occupation = v);
+        stringChange(command, actualChanges, "risk", this.risk, v -> this.risk = v);
+        stringChange(command, actualChanges, "ckycId", this.ckycId, v -> this.ckycId = v);
+        stringChange(command, actualChanges, "adultMinor", this.adultMinor, v -> this.adultMinor = v);
+
+        if (command.isChangeInDateParameterNamed("minorDate", this.minorDate)) {
+            actualChanges.put("minorDate", command.stringValueOfParameterNamed("minorDate"));
+            this.minorDate = command.localDateValueOfParameterNamed("minorDate");
+        }
+
+        if (command.isChangeInLongParameterNamed("guardianClientId", this.guardianClientId)) {
+            final Long newValue = command.longValueOfParameterNamed("guardianClientId");
+            actualChanges.put("guardianClientId", newValue);
+            this.guardianClientId = newValue;
+        }
+
+        stringChange(command, actualChanges, "minAccountOpt", this.minAccountOpt, v -> this.minAccountOpt = v);
+        stringChange(command, actualChanges, "relation", this.relation, v -> this.relation = v);
+
+        if (command.isChangeInDateParameterNamed("openingDate", this.openingDate)) {
+            actualChanges.put("openingDate", command.stringValueOfParameterNamed("openingDate"));
+            this.openingDate = command.localDateValueOfParameterNamed("openingDate");
+        }
+
+        if (command.isChangeInIntegerParameterNamed("month", this.month)) {
+            final Integer newValue = command.integerValueOfParameterNamed("month");
+            actualChanges.put("month", newValue);
+            this.month = newValue;
+        }
+
+        if (command.isChangeInDateParameterNamed("maturityDate", this.maturityDate)) {
+            actualChanges.put("maturityDate", command.stringValueOfParameterNamed("maturityDate"));
+            this.maturityDate = command.localDateValueOfParameterNamed("maturityDate");
+        }
+
+        if (command.isChangeInDateParameterNamed("reopenDate", this.reopenDate)) {
+            actualChanges.put("reopenDate", command.stringValueOfParameterNamed("reopenDate"));
+            this.reopenDate = command.localDateValueOfParameterNamed("reopenDate");
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("depositAmount", this.depositAmount)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("depositAmount");
+            actualChanges.put("depositAmount", newValue);
+            this.depositAmount = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("dailyDepositAmount", this.dailyDepositAmount)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("dailyDepositAmount");
+            actualChanges.put("dailyDepositAmount", newValue);
+            this.dailyDepositAmount = newValue;
+        }
+
+        if (command.isChangeInIntegerParameterNamed("days", this.days)) {
+            final Integer newValue = command.integerValueOfParameterNamed("days");
+            actualChanges.put("days", newValue);
+            this.days = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("interestRate", this.interestRate)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("interestRate");
+            actualChanges.put("interestRate", newValue);
+            this.interestRate = newValue;
+        }
+
+        stringChange(command, actualChanges, "ledgerNo", this.ledgerNo, v -> this.ledgerNo = v);
+        stringChange(command, actualChanges, "withdrawType", this.withdrawType, v -> this.withdrawType = v);
+
+        if (command.isChangeInBooleanParameterNamed("lien", this.lien)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("lien");
+            actualChanges.put("lien", newValue);
+            this.lien = newValue;
+        }
+
+        if (command.isChangeInDateParameterNamed("payDate", this.payDate)) {
+            actualChanges.put("payDate", command.stringValueOfParameterNamed("payDate"));
+            this.payDate = command.localDateValueOfParameterNamed("payDate");
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("paymentAmount", this.paymentAmount)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("paymentAmount");
+            actualChanges.put("paymentAmount", newValue);
+            this.paymentAmount = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("openingBalance", this.openingBalance)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("openingBalance");
+            actualChanges.put("openingBalance", newValue);
+            this.openingBalance = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("isSmsActive", this.isSmsActive)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("isSmsActive");
+            actualChanges.put("isSmsActive", newValue);
+            this.isSmsActive = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("isEmailActive", this.isEmailActive)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("isEmailActive");
+            actualChanges.put("isEmailActive", newValue);
+            this.isEmailActive = newValue;
+        }
+
+        if (command.isChangeInDateParameterNamed("interestDate", this.interestDate)) {
+            actualChanges.put("interestDate", command.stringValueOfParameterNamed("interestDate"));
+            this.interestDate = command.localDateValueOfParameterNamed("interestDate");
+        }
+
+        stringChange(command, actualChanges, "spDescription", this.spDescription, v -> this.spDescription = v);
+        stringChange(command, actualChanges, "freezeCode", this.freezeCode, v -> this.freezeCode = v);
+        stringChange(command, actualChanges, "advCode", this.advCode, v -> this.advCode = v);
+        stringChange(command, actualChanges, "creditToBranch", this.creditToBranch, v -> this.creditToBranch = v);
+        stringChange(command, actualChanges, "creditToAccountType", this.creditToAccountType, v -> this.creditToAccountType = v);
+        stringChange(command, actualChanges, "creditToAccount", this.creditToAccount, v -> this.creditToAccount = v);
+
+        if (command.isChangeInBooleanParameterNamed("nomineeApplicable", this.nomineeApplicable)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("nomineeApplicable");
+            actualChanges.put("nomineeApplicable", newValue);
+            this.nomineeApplicable = newValue;
+        }
+
+        stringChange(command, actualChanges, "nomineeSplitMode", this.nomineeSplitMode, v -> this.nomineeSplitMode = v);
+
+        return actualChanges;
+    }
+
+    private void stringChange(final JsonCommand command, final Map<String, Object> actualChanges, final String paramName,
+            final String existingValue, final Consumer<String> setter) {
+        if (command.isChangeInStringParameterNamed(paramName, existingValue)) {
+            final String newValue = command.stringValueOfParameterNamed(paramName);
+            actualChanges.put(paramName, newValue);
+            setter.accept(newValue);
+        }
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/domain/PartyNominee.java

@@ -0,0 +1,88 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+
+/**
+ * A single nominee recorded against a {@link Party}. Maker-checker on nominee edits is enforced at
+ * the command layer (the whole Party update goes through the standard maker-checker command flow),
+ * not on this child row individually.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_party_nominee")
+public class PartyNominee extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "party_id", nullable = false)
+    private Party party;
+
+    @Column(name = "nomination_date", nullable = false)
+    private LocalDate nominationDate;
+
+    @Column(name = "name", length = 100, nullable = false)
+    private String name;
+
+    @Column(name = "mobile_no", length = 20)
+    private String mobileNo;
+
+    @Column(name = "birth_date")
+    private LocalDate birthDate;
+
+    @Column(name = "minor", nullable = false)
+    private boolean minor;
+
+    @Column(name = "relation", length = 40, nullable = false)
+    private String relation;
+
+    @Column(name = "gender", length = 20, nullable = false)
+    private String gender;
+
+    @Column(name = "guardian_name", length = 100)
+    private String guardianName;
+
+    protected PartyNominee() {
+        //
+    }
+
+    public PartyNominee(final LocalDate nominationDate, final String name, final String mobileNo, final LocalDate birthDate,
+            final boolean minor, final String relation, final String gender, final String guardianName) {
+        this.nominationDate = nominationDate;
+        this.name = name;
+        this.mobileNo = StringUtils.defaultIfEmpty(mobileNo, null);
+        this.birthDate = birthDate;
+        this.minor = minor;
+        this.relation = relation;
+        this.gender = gender;
+        this.guardianName = StringUtils.defaultIfEmpty(guardianName, null);
+    }
+
+    void setParty(final Party party) {
+        this.party = party;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartyAlreadyClosedException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a Close Party command, or a Party Tran collection, targets a Party that is already
+ * closed.
+ */
+public class PartyAlreadyClosedException extends AbstractPlatformDomainRuleException {
+
+    public PartyAlreadyClosedException(final String partyCode) {
+        super("error.msg.party.already.closed", "Party " + partyCode + " is already closed", partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartyHasBalanceException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a Close Party command is attempted while the Party's balance is still non-zero - the
+ * remaining balance must be paid out (a Withdraw Deposite to zero) before the account can be closed.
+ */
+public class PartyHasBalanceException extends AbstractPlatformDomainRuleException {
+
+    public PartyHasBalanceException(final String partyCode) {
+        super("error.msg.party.has.balance", "Party " + partyCode + " still has a non-zero balance and cannot be closed", partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartyNotFoundException.java

@@ -0,0 +1,40 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+import org.springframework.dao.EmptyResultDataAccessException;
+
+/**
+ * A {@link RuntimeException} thrown when a DDS party resource is not found.
+ */
+public class PartyNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public PartyNotFoundException(final Long id) {
+        super("error.msg.party.id.invalid", "Party with identifier " + id + " does not exist", id);
+    }
+
+    public PartyNotFoundException(final Long id, final EmptyResultDataAccessException e) {
+        super("error.msg.party.id.invalid", "Party with identifier " + id + " does not exist", id, e);
+    }
+
+    public PartyNotFoundException(final String partyCode) {
+        super("error.msg.party.code.invalid", "Party with code " + partyCode + " does not exist", partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartySavingsAccountClientMismatchException.java

@@ -0,0 +1,33 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when the savingsAccountNo given for a Party belongs to a different client than the Party's
+ * own clientId - a Party can only be linked to its own client's savings account.
+ */
+public class PartySavingsAccountClientMismatchException extends AbstractPlatformDomainRuleException {
+
+    public PartySavingsAccountClientMismatchException(final String savingsAccountNo) {
+        super("error.msg.party.savings.account.client.mismatch",
+                "Savings account " + savingsAccountNo + " does not belong to this party's client", savingsAccountNo);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartySavingsAccountNotFoundException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+
+/**
+ * Thrown when a Party's savingsAccountNo does not match any non-closed Savings Account.
+ */
+public class PartySavingsAccountNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public PartySavingsAccountNotFoundException(final String savingsAccountNo) {
+        super("error.msg.party.savings.account.not.found", "No open savings account found with account number " + savingsAccountNo,
+                savingsAccountNo);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/report/data/DdsReportData.java

@@ -0,0 +1,45 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.report.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+import lombok.Builder;
+import lombok.Getter;
+
+/**
+ * A generic tabular result shape shared by every DDS report - one column list plus one row list, both
+ * keyed the same way, so a single report viewer screen can render any of them without a bespoke
+ * result type per report.
+ */
+@Getter
+@Builder
+public final class DdsReportData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final String reportKey;
+    private final boolean available;
+    private final String message;
+    private final List<String> columns;
+    private final List<Map<String, Object>> rows;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/data/PartyTransactionData.java

@@ -0,0 +1,52 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+public final class PartyTransactionData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long partyId;
+    private final String partyCode;
+    private final String partyName;
+    private final Long agentId;
+    private final String agentCode;
+    private final LocalDate transactionDate;
+    private final String transactionType;
+    private final String direction;
+    private final String transactionMode;
+    private final String accountType;
+    private final String accountNo;
+    private final BigDecimal amount;
+    private final String chequeNo;
+    private final String tokenNo;
+    private final String description;
+    private final BigDecimal balanceAfterTransaction;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/domain/PartyTransaction.java

@@ -0,0 +1,110 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+import org.apache.fineract.organisation.agent.domain.Agent;
+import org.apache.fineract.portfolio.dds.party.domain.Party;
+
+/**
+ * A single posted entry on the DDS ledger: a Party's day's collection ("Party Tran", direction
+ * CREDIT), one leg of a "Withdraw Deposite" transfer between two parties (the creditor leg CREDIT,
+ * the debtor leg DEBIT), or an Agent's settlement of collected cash to its branch ("Agent Tran",
+ * direction DEBIT - no {@link Party} involved, so {@code party} is null for this type).
+ * {@code balanceAfterTransaction} holds the Party's balance for Party-linked rows, or the Agent's
+ * balance for an Agent Tran row. Immutable once posted - like any transaction, it is reversed with
+ * an opposing entry, not edited, so there is deliberately no update API for this entity.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_party_transaction")
+public class PartyTransaction extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "party_id")
+    private Party party;
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    @Column(name = "transaction_date", nullable = false)
+    private LocalDate transactionDate;
+
+    @Column(name = "transaction_type", length = 30, nullable = false)
+    private String transactionType;
+
+    @Column(name = "direction", length = 10, nullable = false)
+    private String direction;
+
+    @Column(name = "transaction_mode", length = 20)
+    private String transactionMode;
+
+    @Column(name = "account_type", length = 100)
+    private String accountType;
+
+    @Column(name = "account_no", length = 50)
+    private String accountNo;
+
+    @Column(name = "amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal amount;
+
+    @Column(name = "cheque_no", length = 40)
+    private String chequeNo;
+
+    @Column(name = "token_no", length = 40)
+    private String tokenNo;
+
+    @Column(name = "description", length = 500)
+    private String description;
+
+    @Column(name = "balance_after_transaction", scale = 6, precision = 19, nullable = false)
+    private BigDecimal balanceAfterTransaction;
+
+    protected PartyTransaction() {
+        //
+    }
+
+    public PartyTransaction(final Party party, final Agent agent, final LocalDate transactionDate, final String transactionType,
+            final String direction, final String transactionMode, final String accountType, final String accountNo,
+            final BigDecimal amount, final String chequeNo, final String tokenNo, final String description,
+            final BigDecimal balanceAfterTransaction) {
+        this.party = party;
+        this.agent = agent;
+        this.transactionDate = transactionDate;
+        this.transactionType = transactionType;
+        this.direction = direction;
+        this.transactionMode = transactionMode;
+        this.accountType = accountType;
+        this.accountNo = accountNo;
+        this.amount = amount;
+        this.chequeNo = chequeNo;
+        this.tokenNo = tokenNo;
+        this.description = description;
+        this.balanceAfterTransaction = balanceAfterTransaction;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/exception/InsufficientAgentBalanceException.java

@@ -0,0 +1,33 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an Agent Tran settlement amount exceeds the Agent's current (collected but not yet
+ * settled) balance.
+ */
+public class InsufficientAgentBalanceException extends AbstractPlatformDomainRuleException {
+
+    public InsufficientAgentBalanceException(final String agentCode) {
+        super("error.msg.agent.insufficient.balance",
+                "Agent " + agentCode + " does not have sufficient collected balance for this settlement", agentCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/exception/InsufficientPartyBalanceException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a Withdraw Deposite transfer would take the debtor Party's balance below zero.
+ */
+public class InsufficientPartyBalanceException extends AbstractPlatformDomainRuleException {
+
+    public InsufficientPartyBalanceException(final String partyCode) {
+        super("error.msg.party.insufficient.balance", "Party " + partyCode + " does not have sufficient balance for this transfer",
+                partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/exception/PartyTransactionNotFoundException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+import org.springframework.dao.EmptyResultDataAccessException;
+
+/**
+ * A {@link RuntimeException} thrown when a DDS party transaction resource is not found.
+ */
+public class PartyTransactionNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public PartyTransactionNotFoundException(final Long id, final EmptyResultDataAccessException e) {
+        super("error.msg.partytransaction.id.invalid", "Party transaction with identifier " + id + " does not exist", id, e);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/mobilelookup/domain/MobileLookupLog.java

@@ -24,6 +24,7 @@ import jakarta.persistence.Table;
 import java.time.OffsetDateTime;
 import lombok.Getter;
 import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
 
 /**
  * Activity log for each DIP / MNRL mobile number lookup request.
@@ -64,6 +65,29 @@ public class MobileLookupLog extends AbstractAuditableWithUTCDateTimeCustom<Long
     @Column(name = "looked_up_on", nullable = false)
     private OffsetDateTime lookedUpOn;
 
+    // ── Officer decision on a non-clean result ────────────────────────────────
+    // A DIP hit is a fraud-risk signal rather than a legal bar, so onboarding may continue — but
+    // the officer has to say why in writing, and that reasoning is kept with the lookup.
+
+    /** PROCEEDED | REJECTED. Null while no decision is required or none has been taken. */
+    @Column(name = "override_decision", length = 20)
+    private String overrideDecision;
+
+    @Column(name = "override_reason")
+    private String overrideReason;
+
+    @Column(name = "decided_by")
+    private Long decidedBy;
+
+    @Column(name = "decided_on")
+    private OffsetDateTime decidedOn;
+
+    public static final String STATUS_CLEAN = "CLEAN";
+    public static final String STATUS_ERROR = "ERROR";
+    public static final String STATUS_SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE";
+    public static final String DECISION_PROCEEDED = "PROCEEDED";
+    public static final String DECISION_REJECTED = "REJECTED";
+
     protected MobileLookupLog() {}
 
     public MobileLookupLog(final String mobileNumber, final String lookupStatus,
@@ -78,6 +102,29 @@ public class MobileLookupLog extends AbstractAuditableWithUTCDateTimeCustom<Long
         this.rawResponse = rawResponse;
         this.lookupSource = lookupSource;
         this.clientId = clientId;
-        this.lookedUpOn = OffsetDateTime.now();
+        this.lookedUpOn = DateUtils.getOffsetDateTimeOfTenant();
+    }
+
+    public void recordDecision(final String decision, final String reason, final Long userId) {
+        this.overrideDecision = decision;
+        this.overrideReason = reason;
+        this.decidedBy = userId;
+        this.decidedOn = DateUtils.getOffsetDateTimeOfTenant();
+    }
+
+    /** True when the lookup produced something the officer must consciously decide about. */
+    public boolean requiresDecision() {
+        return this.suspected || this.disconnected;
+    }
+
+    /**
+     * A number may be used only when it came back clean, or when an officer explicitly chose to
+     * proceed. An unreachable DoT service is NOT a pass — it means nothing was checked.
+     */
+    public boolean isUsable() {
+        if (STATUS_CLEAN.equals(this.lookupStatus)) {
+            return true;
+        }
+        return DECISION_PROCEEDED.equals(this.overrideDecision);
     }
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/mobilelookup/domain/MobileLookupLogRepository.java

@@ -19,6 +19,8 @@
 package org.apache.fineract.portfolio.mobilelookup.domain;
 
 import java.util.List;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.query.Param;
@@ -35,4 +37,29 @@ public interface MobileLookupLogRepository extends JpaRepository<MobileLookupLog
 
     @Query("SELECT l FROM MobileLookupLog l WHERE l.lookupStatus = :status ORDER BY l.lookedUpOn DESC")
     List<MobileLookupLog> findByLookupStatus(@Param("status") String status);
+
+    /** Non-clean lookups still waiting for an officer's decision — the DIP review queue. */
+    @Query("SELECT l FROM MobileLookupLog l WHERE (l.suspected = true OR l.disconnected = true) "
+            + "AND l.overrideDecision IS NULL ORDER BY l.lookedUpOn DESC")
+    List<MobileLookupLog> findPendingDecisions();
+
+    /**
+     * Most recent lookup for a number, used by the server-side gate to confirm the browser's
+     * claim that a number was verified.
+     *
+     * <p>
+     * Paged rather than a JPQL {@code LIMIT}, which EclipseLink does not accept — the caller
+     * takes the first row.
+     * </p>
+     */
+    @Query("SELECT l FROM MobileLookupLog l WHERE l.mobileNumber = :mobileNumber ORDER BY l.lookedUpOn DESC")
+    List<MobileLookupLog> findLatestByMobileNumber(@Param("mobileNumber") String mobileNumber, Pageable pageable);
+
+    /**
+     * Earlier rejections of the same number, on any client. A number turned away once is a
+     * standing signal: without this the next officer screens it fresh and sees no history.
+     */
+    @Query("SELECT l FROM MobileLookupLog l WHERE l.mobileNumber = :mobileNumber "
+            + "AND l.overrideDecision = 'REJECTED' ORDER BY l.decidedOn DESC")
+    List<MobileLookupLog> findRejections(@Param("mobileNumber") String mobileNumber, Pageable pageable);
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/sanctions/domain/SanctionsEntryRepository.java

@@ -18,7 +18,9 @@
  */
 package org.apache.fineract.portfolio.sanctions.domain;
 
+import java.time.OffsetDateTime;
 import java.util.List;
+import java.util.Optional;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.query.Param;
@@ -40,4 +42,11 @@ public interface SanctionsEntryRepository extends JpaRepository<SanctionsEntry,
     void deleteAllByActiveTrue();
 
     long countByActiveTrue();
+
+    /**
+     * Timestamp the active sanctions list was last loaded into the database — i.e. the data
+     * currency shown to callers so they know which list snapshot a screening ran against.
+     */
+    @Query("SELECT MAX(s.createdDate) FROM SanctionsEntry s WHERE s.active = true")
+    Optional<OffsetDateTime> findListLastLoadedOn();
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/sanctions/domain/SanctionsScreeningLog.java

@@ -23,6 +23,7 @@ import jakarta.persistence.Entity;
 import jakarta.persistence.Table;
 import java.time.OffsetDateTime;
 import org.apache.fineract.infrastructure.core.domain.AbstractAuditableWithUTCDateTimeCustom;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
 
 /**
  * Activity log for each sanctions screening request.
@@ -60,6 +61,65 @@ public class SanctionsScreeningLog extends AbstractAuditableWithUTCDateTimeCusto
     @Column(name = "screened_on", nullable = false)
     private OffsetDateTime screenedOn;
 
+    // ── Alert disposition ─────────────────────────────────────────────────────
+    // A FLAGGED screening opens a case. It stays PENDING_REVIEW until an officer either
+    // documents it as a different person (FALSE_POSITIVE, effective only once the Principal
+    // Officer approves) or confirms it (CONFIRMED_MATCH, which freezes and gets reported).
+
+    @Column(name = "disposition", length = 30)
+    private String disposition;
+
+    @Column(name = "disposition_reason")
+    private String dispositionReason;
+
+    @Column(name = "reviewed_by")
+    private Long reviewedBy;
+
+    @Column(name = "reviewed_on")
+    private OffsetDateTime reviewedOn;
+
+    @Column(name = "approved_by")
+    private Long approvedBy;
+
+    @Column(name = "approved_on")
+    private OffsetDateTime approvedOn;
+
+    @Column(name = "fiu_str_reference", length = 100)
+    private String fiuStrReference;
+
+    @Column(name = "nodal_officer_informed_on")
+    private OffsetDateTime nodalOfficerInformedOn;
+
+    @Column(name = "frozen_account_ids", length = 1000)
+    private String frozenAccountIds;
+
+    @Column(name = "frozen_on")
+    private OffsetDateTime frozenOn;
+
+    // ── STR tracking ──────────────────────────────────────────────────────────
+    // A confirmed match is reportable to FIU-IND. Tracked here rather than as an AML alert: an
+    // AML alert is built around a monetary transaction, whereas this is triggered by who the
+    // customer is, so the two are surfaced as separate streams on the FIU screen.
+
+    /** NULL until approval; then PENDING_FILING → FILED. */
+    @Column(name = "str_status", length = 30)
+    private String strStatus;
+
+    @Column(name = "str_due_date")
+    private java.time.LocalDate strDueDate;
+
+    @Column(name = "str_raised_on")
+    private OffsetDateTime strRaisedOn;
+
+    public static final String STR_PENDING_FILING = "PENDING_FILING";
+    public static final String STR_FILED = "FILED";
+
+    public static final String RESULT_FLAGGED = "FLAGGED";
+    public static final String RESULT_CLEAR = "CLEAR";
+    public static final String DISPOSITION_PENDING = "PENDING_REVIEW";
+    public static final String DISPOSITION_FALSE_POSITIVE = "FALSE_POSITIVE";
+    public static final String DISPOSITION_CONFIRMED = "CONFIRMED_MATCH";
+
     protected SanctionsScreeningLog() {}
 
     public SanctionsScreeningLog(final String screenedName, final String screeningResult,
@@ -73,9 +133,76 @@ public class SanctionsScreeningLog extends AbstractAuditableWithUTCDateTimeCusto
         this.screeningSource = screeningSource;
         this.clientId = clientId;
         this.ipAddress = ipAddress;
-        this.screenedOn = OffsetDateTime.now();
+        this.screenedOn = DateUtils.getOffsetDateTimeOfTenant();
+        // A hit opens a case; a clear screening has no case to close.
+        this.disposition = RESULT_FLAGGED.equals(screeningResult) ? DISPOSITION_PENDING : null;
     }
 
+    // ── Alert lifecycle ───────────────────────────────────────────────────────
+
+    /**
+     * Records the officer's assessment of the hit. Deliberately does NOT clear the block: a
+     * false positive only takes effect once {@link #approve(Long)} is called by the Principal
+     * Officer, so the person who raised it cannot wave their own match through.
+     */
+    public void recordDisposition(final String newDisposition, final String reason, final Long userId) {
+        this.disposition = newDisposition;
+        this.dispositionReason = reason;
+        this.reviewedBy = userId;
+        this.reviewedOn = DateUtils.getOffsetDateTimeOfTenant();
+        // Re-opening a previously approved alert must drop the old approval with it.
+        this.approvedBy = null;
+        this.approvedOn = null;
+    }
+
+    public void approve(final Long approverId) {
+        this.approvedBy = approverId;
+        this.approvedOn = DateUtils.getOffsetDateTimeOfTenant();
+    }
+
+    /** Records the FIU-IND STR reference and the date the nodal officer was informed. */
+    public void recordReporting(final String strReference, final OffsetDateTime nodalOfficerInformedOn) {
+        if (strReference != null) {
+            this.fiuStrReference = strReference;
+            // Recording the FIU-IND acknowledgement is what closes the filing obligation, so the
+            // case stops appearing as outstanding on the FIU screen.
+            if (!strReference.isBlank()) {
+                this.strStatus = STR_FILED;
+            }
+        }
+        if (nodalOfficerInformedOn != null) {
+            this.nodalOfficerInformedOn = nodalOfficerInformedOn;
+        }
+    }
+
+    public void recordFreeze(final String accountIds) {
+        this.frozenAccountIds = accountIds;
+        this.frozenOn = DateUtils.getOffsetDateTimeOfTenant();
+    }
+
+    /**
+     * Opens the STR obligation on approval of a confirmed match. PMLA allows seven working days
+     * from forming the suspicion; seven calendar days is the stricter reading.
+     */
+    public void raiseStr() {
+        if (this.strStatus != null) {
+            return;
+        }
+        this.strStatus = STR_PENDING_FILING;
+        this.strRaisedOn = DateUtils.getOffsetDateTimeOfTenant();
+        this.strDueDate = DateUtils.getBusinessLocalDate().plusDays(7);
+    }
+
+    public boolean isStrPending() { return STR_PENDING_FILING.equals(this.strStatus); }
+
+    public boolean isFlagged() { return RESULT_FLAGGED.equals(this.screeningResult); }
+
+    public boolean isApprovedFalsePositive() {
+        return DISPOSITION_FALSE_POSITIVE.equals(this.disposition) && this.approvedBy != null;
+    }
+
+    public boolean isConfirmedMatch() { return DISPOSITION_CONFIRMED.equals(this.disposition); }
+
     // ── Accessors ─────────────────────────────────────────────────────────────
 
     public String getScreenedName() { return screenedName; }
@@ -88,4 +215,17 @@ public class SanctionsScreeningLog extends AbstractAuditableWithUTCDateTimeCusto
     public void setClientId(Long clientId) { this.clientId = clientId; }
     public String getIpAddress() { return ipAddress; }
     public OffsetDateTime getScreenedOn() { return screenedOn; }
+    public String getDisposition() { return disposition; }
+    public String getDispositionReason() { return dispositionReason; }
+    public Long getReviewedBy() { return reviewedBy; }
+    public OffsetDateTime getReviewedOn() { return reviewedOn; }
+    public Long getApprovedBy() { return approvedBy; }
+    public OffsetDateTime getApprovedOn() { return approvedOn; }
+    public String getFiuStrReference() { return fiuStrReference; }
+    public OffsetDateTime getNodalOfficerInformedOn() { return nodalOfficerInformedOn; }
+    public String getFrozenAccountIds() { return frozenAccountIds; }
+    public OffsetDateTime getFrozenOn() { return frozenOn; }
+    public String getStrStatus() { return strStatus; }
+    public java.time.LocalDate getStrDueDate() { return strDueDate; }
+    public OffsetDateTime getStrRaisedOn() { return strRaisedOn; }
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/sanctions/domain/SanctionsScreeningLogRepository.java

@@ -39,4 +39,32 @@ public interface SanctionsScreeningLogRepository extends JpaRepository<Sanctions
 
     @Query("SELECT l FROM SanctionsScreeningLog l WHERE LOWER(l.screenedName) LIKE LOWER(CONCAT('%', :name, '%')) ORDER BY l.screenedOn DESC")
     List<SanctionsScreeningLog> findByScreenedNameContaining(@Param("name") String name);
+
+    @Query("SELECT l FROM SanctionsScreeningLog l WHERE l.disposition = :disposition ORDER BY l.screenedOn DESC")
+    List<SanctionsScreeningLog> findByDisposition(@Param("disposition") String disposition);
+
+    /** Every open alert — the Principal Officer's review queue. */
+    @Query("SELECT l FROM SanctionsScreeningLog l WHERE l.disposition IS NOT NULL ORDER BY l.screenedOn DESC")
+    List<SanctionsScreeningLog> findAllAlerts();
+
+    /**
+     * A name is only cleared to onboard once a false positive on that exact name has been
+     * approved by the Principal Officer — the maker's own assessment is not enough.
+     */
+    @Query("SELECT COUNT(l) FROM SanctionsScreeningLog l WHERE LOWER(TRIM(l.screenedName)) = LOWER(TRIM(:name)) "
+            + "AND l.disposition = 'FALSE_POSITIVE' AND l.approvedBy IS NOT NULL")
+    long countApprovedFalsePositives(@Param("name") String name);
+
+    /** Latest alert for a client, used to decide whether their accounts must stay frozen. */
+    @Query("SELECT l FROM SanctionsScreeningLog l WHERE l.clientId = :clientId AND l.screeningResult = 'FLAGGED' "
+            + "ORDER BY l.screenedOn DESC")
+    List<SanctionsScreeningLog> findFlaggedByClientId(@Param("clientId") Long clientId);
+
+    /**
+     * Confirmed matches carrying an STR obligation — the sanctions stream on the FIU-IND screen.
+     * Pass null for every STR regardless of whether it has been filed.
+     */
+    @Query("SELECT l FROM SanctionsScreeningLog l WHERE l.strStatus IS NOT NULL "
+            + "AND (:status IS NULL OR l.strStatus = :status) ORDER BY l.strDueDate ASC, l.strRaisedOn DESC")
+    List<SanctionsScreeningLog> findStrCases(@Param("status") String status);
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/savings/SavingsApiConstants.java

@@ -275,6 +275,7 @@ public class SavingsApiConstants {
     // Additional custom fields
     public static final String balanceFrequencyParamName = "balanceFrequency";
     public static final String accountClosedZeroBalanceInDayClosingParamName = "accountClosedZeroBalanceInDayClosing";
+    public static final String productCategoryParamName = "productCategory";
 
     // Current Product — new UI fields
     public static final String balanceSwapOptionParamName = "balanceSwapOption";

fineract-core/src/main/java/org/apache/fineract/portfolio/savings/data/SavingsProductData.java

@@ -144,6 +144,7 @@ public final class SavingsProductData implements Serializable {
     @Getter @Setter private Boolean enableLockinPeriod;
     @Getter @Setter private String balanceFrequency;
     @Getter @Setter private Boolean accountClosedZeroBalanceInDayClosing;
+    @Getter @Setter private String productCategory;
 
     // New current product fields
     @Getter @Setter private Boolean balanceSwapOption;

fineract-core/src/main/java/org/apache/fineract/portfolio/search/data/SearchConditions.java

@@ -18,6 +18,7 @@
  */
 package org.apache.fineract.portfolio.search.data;
 
+import java.util.Locale;
 import org.apache.fineract.portfolio.search.SearchConstants.SearchSupportedResources;
 
 public class SearchConditions {
@@ -37,17 +38,17 @@ public class SearchConditions {
         this.searchResource = searchResource;
         this.exactMatch = exactMatch;
         this.clientSearch = null == searchResource
-                || searchResource.toLowerCase().contains(SearchSupportedResources.CLIENTS.name().toLowerCase());
+                || searchResource.toLowerCase(Locale.ROOT).contains(SearchSupportedResources.CLIENTS.name().toLowerCase(Locale.ROOT));
         this.groupSearch = null == searchResource
-                || searchResource.toLowerCase().contains(SearchSupportedResources.GROUPS.name().toLowerCase());
+                || searchResource.toLowerCase(Locale.ROOT).contains(SearchSupportedResources.GROUPS.name().toLowerCase(Locale.ROOT));
         this.loanSeach = null == searchResource
-                || searchResource.toLowerCase().contains(SearchSupportedResources.LOANS.name().toLowerCase());
+                || searchResource.toLowerCase(Locale.ROOT).contains(SearchSupportedResources.LOANS.name().toLowerCase(Locale.ROOT));
         this.savingSeach = null == searchResource
-                || searchResource.toLowerCase().contains(SearchSupportedResources.SAVINGS.name().toLowerCase());
+                || searchResource.toLowerCase(Locale.ROOT).contains(SearchSupportedResources.SAVINGS.name().toLowerCase(Locale.ROOT));
         this.shareSeach = null == searchResource
-                || searchResource.toLowerCase().contains(SearchSupportedResources.SHARES.name().toLowerCase());
+                || searchResource.toLowerCase(Locale.ROOT).contains(SearchSupportedResources.SHARES.name().toLowerCase(Locale.ROOT));
         this.clientIdentifierSearch = null == searchResource
-                || searchResource.toLowerCase().contains(SearchSupportedResources.CLIENTIDENTIFIERS.name().toLowerCase());
+                || searchResource.toLowerCase(Locale.ROOT).contains(SearchSupportedResources.CLIENTIDENTIFIERS.name().toLowerCase(Locale.ROOT));
     }
 
     public SearchConditions(final String searchQueryParam, final String searchResource, final Boolean clientSearch,

fineract-core/src/main/java/org/apache/fineract/portfolio/search/service/SearchUtil.java

@@ -321,6 +321,6 @@ public class SearchUtil {
 
     public String camelToSnake(final String camelStr) {
         return camelStr == null ? null
-                : camelStr.replaceAll("([A-Z]+)([A-Z][a-z])", "$1_$2").replaceAll("([a-z])([A-Z])", "$1_$2").toLowerCase();
+                : camelStr.replaceAll("([A-Z]+)([A-Z][a-z])", "$1_$2").replaceAll("([a-z])([A-Z])", "$1_$2").toLowerCase(Locale.ROOT);
     }
 }