# Lendford Management System

System design v1.2 — 1 October 2026

Design coverage includes the complete planned management system. Delivery will proceed module by module. Later-phase modules below are part of the architecture, with unspecified business policies clearly marked as open decisions.

## 1. Decisions and scope

Technology: Yii2, MySQL, server-rendered views and Bootstrap. One application with separate business services for applications, loan calculations, repayments, collateral and reporting. Interface: approved Concept C, navy top navigation, white panels, broad tables and restrained green accents.

Initial release: authentication, staff and branches, clients, applications, assessments, agreements, disbursements, custom repayment schedules, payment verification, collateral custody, recovery sales, surplus returns, follow-ups, reports and audit history. Include a small linked expense facility for surplus returns. General expenses, payroll, commissions, referrals, independent asset selling and car-clearance workflows are later scope.

Branches: Oasis Mall, Royal Lutanda and Leeds Complex are separate. Administrators can create, edit and deactivate branches, assign managers, and assign or reassign staff. Preserve effective-dated assignment history. Transfers do not change the branch on historical transactions. Moving servicing responsibility for an existing loan is a separate authorised action with an audit trail.

All pledged collateral is held by Lendford at a recorded branch and storage location. A loan may have multiple collateral items. Instalment dates and amounts are configurable per loan for the client. Single-payment loans use the same schedule model with one instalment.

Payment allocation is configurable; default interest, late fees, principal. Store the actual allocation and policy used on each posted payment. Existing allocations do not change when settings change.

Late fees follow the workbook: K50 per day after the final loan due date, capped at three chargeable days. Both settings are configurable. Intermediate missed instalments create collection arrears but do not create separate late charges.

Sales are recorded at actual amounts and dates. Record gross price, selling costs, net proceeds, amount applied to debt, surplus and shortfall separately. A surplus return is an expense-category payment named Surplus Return, linked to the client, loan and sale. Track outstanding surplus until paid or resolved through an explicitly authorised decision. Do not automatically treat unpaid surplus as income.

## 2. Source basis and unresolved rules

Sources: Lendford OS v2.1 - MANAGEMENT MASTER.xlsx; Lendford_Xpress_Loans_Application_Form.pdf; supplied branding and service images; decisions in this conversation. No borrower personal data is copied into this design.

Workbook term rates: one week 10%, two weeks 15%, three weeks 25%, four weeks 35%. Expected interest is principal multiplied by the selected term rate. Due date is disbursement date plus term weeks multiplied by seven. Loan-to-value warning threshold is 70%. These are starting configurations rather than assumed rules for other products or terms.

The workbook late-day formula uses today while principal or expected interest remains outstanding, and otherwise uses Last Payment Date. Implementation must explicitly determine how backdated verified payments and later fee-only payments affect that date. Before production, reconcile these cases against workbook examples. Preserve the three-day cap and avoid duplicate charges.

Early-settlement columns exist, but the inspected rows do not establish a complete reduction policy. Support an approved settlement quote with an explicit interest adjustment; do not silently infer an automatic discount.

Still to confirm: financial approval limits; early-settlement calculation; shortfall closure versus continuing debt; permissible schedule dates beyond the agreed term; treatment of excess ordinary repayments; whether product settings changed mid-loan apply to existing contracts. Proposed default: snapshot terms on disbursement and require a separate approved amendment for an existing loan.

## 3. Navigation and screens

Top navigation: Dashboard, Clients, Applications, Loans, Repayments, Collateral, Collections, Reports. Administration and personal account options appear in menus. Branch selector only lists authorised branches. On small screens navigation collapses, metrics wrap and tables scroll horizontally.

Palette: navy #1E2D5C, brand green #8BC53F, white #FFFFFF, neutral canvas #F5F7FA. Use darker green for small text and buttons where needed for contrast. Pending statuses amber, completed statuses green, errors and overdue warnings red, review statuses blue. Always include text labels alongside colour.

| Screen | Content and actions |
| --- | --- |
| Dashboard | Portfolio balance as of date, verified cash collected in period, active loans, arrears; pending approvals and payment verification; due and overdue work queues |
| Client directory | Search by name, client reference, identity number or phone; branch filters; create client |
| Client profile | Identity, contacts, employment, documents, applications, loans and follow-ups |
| Application editor | Applicant; affordability; requested terms; collateral; next of kin and guarantor; declaration; review and submit |
| Application assessment | Requested versus approved terms, verification checklist, disposable income, valuation, LTV, assessment notes and decision |
| Loan details | Balance breakdown, approved terms, schedule, payments, collateral, follow-ups, agreements and full history |
| Disbursement | Approved amount, actual date, method, reference, signed agreement and custody checklist |
| Repayment entry | Existing loan selection, amount, actual payment date, method, reference and proof; allocation preview |
| Verification queue | Loan and payment evidence; approve or reject with reason; flag duplicate references |
| Collateral register | Item ID, linked loan, type, serial, value, branch, storage and custody state |
| Collateral details | Photos, ownership evidence, condition, valuation and custody events; authorised transfer, release or sale |
| Recovery sale | Actual date and buyer, items sold, gross amount, costs, evidence, debt application, surplus and shortfall |
| Surplus return | Available surplus, return amount, actual date, payment method, reference, proof and approval |
| Collections | Missed instalments, final maturity arrears, promises, assigned officer and next action |
| Administration | Branches, assignment history, roles, permissions, lending settings and document templates |

Application affordability: monthly income plus other income minus living expenses and existing repayments. It is an assessment input, not an automatic approval rule. Store an application snapshot so later client edits do not rewrite the assessment.

## 4. Permissions

Proposed roles: System Administrator, Management, Branch Manager, Loan Officer, Finance Officer and Auditor. Use Yii2 RBAC permissions with branch and assignment checks on every request, including exports and file downloads.

| Action | Default responsibility |
| --- | --- |
| Create branches, assign staff and permissions | System Administrator |
| Create clients, applications, follow-ups and payment submissions | Loan Officer or authorised branch staff |
| Assess applications | Branch Manager or designated assessor |
| Approve loans and contract amendments | Management or explicitly delegated approver |
| Record disbursement | Finance Officer with disbursement permission |
| Verify payments | Finance Officer or Management, separate from submitter |
| Approve release, recovery sale, write-off or reversal | Explicitly authorised approver |
| Read audit history | Management and Auditor within permitted scope |

Technical administrator access does not automatically confer financial approval. Delegated limits remain configurable. Prevent self-verification and self-approval for controlled financial actions. Every decision includes actor, time and reason.

## 5. Domain relationships and database

Each table has an internal primary key. Business records also have a unique human-readable reference. Use foreign keys, indexed relationship columns, fixed-precision decimal amounts and string phone/identity numbers. Financial records are not hard-deleted.

| Table | Key fields and relationships |
| --- | --- |
| branch | code, name, address, active status |
| user | name, email, password hash, account status |
| staff_branch_assignment | user, branch, primary flag, role context, effective dates, assigned by |
| branch_manager_assignment | branch, manager, effective dates |
| auth_item / auth_item_child / auth_assignment / auth_rule | Yii2 RBAC |
| client | reference, legal name, NRC/passport, birth date, nationality, gender, marital status, phones, email, address, housing |
| client_contact | client, contact type, name, relationship, address, phone |
| client_employment | client, employer/business, activity, address, work phone, duration |
| loan_product_version | product, version, effective dates, charging rules and allocation policy |
| loan_product_term | product version, term days, rate |
| loan_application | client, branch, officer, requested amount, purpose, term, status, submission date |
| application_assessment | application, income/expense snapshot, checks, approved terms, notes, assessor |
| application_guarantor | application, identity and contact snapshot |
| application_consent | application, declaration version, accepted date, signature document |
| loan | application, client, originating branch, servicing branch, officer, principal, rate, term, maturity, rule snapshot, lifecycle state |
| loan_agreement | loan, document version, generated document, signed document, signing date |
| loan_disbursement | loan, amount, actual date, method, reference, recorded/authorised by |
| repayment_schedule_version | loan, version, effective date, amendment reason and authorisation |
| repayment_instalment | schedule version, sequence, due date, principal due, interest due |
| repayment | loan, branch, amount, actual date, method, reference, proof, submitter, verification state |
| repayment_allocation | repayment, component, amount, applicable instalment or charge, allocation-policy snapshot |
| loan_charge | loan, type, charge date, amount, rule basis, reversal link |
| loan_adjustment | loan, component, amount, reason, decision and evidence |
| loan_transaction | loan, component, signed amount, source record, posting time, effective date, reversal link |
| collateral_item | client/owner, item reference, type, brand, model, serial, description, condition |
| collateral_pledge | item, application, loan when issued, pledge state, ownership confirmation |
| collateral_valuation | item, applicant value, assessed value, valuation date, assessor |
| collateral_custody_event | item, source/destination branch and storage, event type, actor, date, evidence |
| collateral_sale | loan, branch, buyer, actual date, method, reference, decision, posting status |
| collateral_sale_item | sale, pledged item, gross price, allocated selling cost |
| recovery_allocation | sale, loan component, amount, linked financial posting |
| surplus_return | sale, client, amount, method, date, reference, proof, linked expense record |
| expense | category, branch, amount, date, payment reference, source sale/return and approval |
| collection_follow_up | loan, officer, contact method, outcome, promised amount/date, next action |
| document | storage key, file type, owner record, version, uploader, checksum |
| approval_event | controlled action, record reference, decision, actor, reason, timestamp |
| audit_event | actor, record, action, changed fields, time and request correlation |
| system_setting_version | setting, value, effective time, author and reason |

Key relationships: one client has many applications and loans; one approved application creates at most one loan; one loan has many instalments, repayments and pledged assets; a sale has multiple sold items and one loan recovery context; a sale has zero or more partial surplus returns. Document links use explicit attachment relationships where foreign-key integrity is needed.

## 6. Lending and payment behaviour

Application states: Draft, Submitted, Under Assessment, More Information Required, Approved, Declined, Withdrawn. Approval creates agreed terms but no cash movement. Disbursement requires approval, signed agreement evidence and recorded collateral custody.

Loan lifecycle: Awaiting Disbursement, Active, Closed. Closure reason is separate: Paid, Early Settlement, Collateral Recovery, Approved Write-off. Recovery stage is separate from lifecycle. Due Today, Instalment Arrears and Past Maturity are derived indicators.

Schedule generation offers equal weekly instalments and editable custom schedules as proposed convenience options. Staff must confirm all dates and amounts. Sum of scheduled principal equals disbursed principal; sum of scheduled interest equals agreed interest. Put any rounding remainder in the final instalment. Default final schedule date equals contractual maturity; differing dates require an explicit approved term amendment.

Allocation preview uses the selected component order. Proposed within-component rule: oldest outstanding obligation first. A verified payment may partially pay an obligation. Store each allocation, rather than recalculating old payments from current settings. Excess remains unapplied credit pending an authorised refund or allocation decision; it is not additional interest income.

Loan balance is derived from posted obligations, charges, allocations and approved adjustments. Use one authoritative posting source per movement. Recovery proceeds must not be counted again as ordinary cash repayments. Maintain separate cash, recovery, adjustment and credit totals.

Verification transaction: lock loan and repayment; recheck permission, status, source uniqueness and current debt; calculate allocation; insert postings; set verification metadata; commit. Receipt generation happens after commit and can be retried without duplicating the financial posting. Reversal posts compensating entries with a reason and approval, never edits the original payment.

## 7. Collateral and surplus

Custody events: Received, Transferred, Released, Sold. A branch transfer records handover and receipt. Prevent the same active item being pledged to two loans. Normalise serial/IMEI where available; missing serials require a generated item ID and description/photos.

Release requires an authorised decision and debt clearance or an explicitly approved exception. A recovery sale records actual proceeds even when below the debt. Net proceeds equal gross less selling costs. Amount applied cannot exceed both non-negative available net proceeds and the debt at posting. Surplus equals positive net proceeds less debt applied. Shortfall equals remaining debt after recovery. A below-cost sale requires explicit review and must not create negative debt allocation.

Shortfall is not silently written off: retain the balance unless an authorised closure adjustment is approved. Sale evidence and debt before recovery are retained. Receipt/reference uniqueness and posting state prevent duplicate recoveries.

Surplus Return records the actual client payment once, with a linked expense-category record for the requested business workflow. Reports show it as return of sale surplus separately from operating expenses. Available surplus reduces after posted returns. Reject payments above the remaining surplus and duplicate return references. This management treatment does not assert statutory accounting classification.

## 8. Reports and dashboard definitions

Reports: loan portfolio; principal outstanding; interest and fees outstanding; verified cash collections; instalment arrears; past-maturity loans; client statements; collateral custody; collateral sales and recovery; unpaid and paid surplus; branch performance; audit history.

Portfolio balance is principal plus interest plus fees remaining at the selected as-of date. Arrears are amounts due by that date less allocations to those obligations, not every future obligation on a delinquent loan. Active loan count counts disbursed loans with remaining obligations. Collections show verified cash effective in the selected period, excluding recovery postings and non-cash adjustments. Revenue and recovery gains are distinct management measures.

Filters: branch, officer, period/as-of date, product, status and payment method. PDF and spreadsheet exports enforce the same permissions as screens. Include report definitions, generated time and filters. Historical reporting uses effective dates and original branch attribution.

## 9. Yii2 architecture and operational controls

Modules: administration, clients, lending, payments, collateral, collections and reporting. Thin controllers handle requests; form models validate inputs; domain services perform controlled transitions and calculations; ActiveRecord models handle persistence. Shared services handle document generation, audit writing, reference generation and file access.

Services: ApplicationService, DisbursementService, ScheduleService, PaymentAllocationService, PaymentVerificationService, LateFeeService, SettlementService, CollateralCustodyService, RecoveryService and SurplusReturnService. Calculation services accept explicit amounts, policy and effective dates to support deterministic testing.

Use authenticated sessions, CSRF protection for mutations, output escaping, password hashing, login throttling, session expiry and protected file downloads. Store documents outside the public web directory. Configure database credentials outside committed source. Keep an audit trail for access changes and financial decisions. Schedule daily fee/collection refresh with idempotent charge keys. Backups include database and documents, with a verified restore procedure.

## 10. Migration and verification

Import workbook data into staging first. Retain original references and dates, preserve source provenance, map branch aliases deliberately, identify duplicate client identities and validate every loan/collateral/payment relationship. Do not copy cached balances as independent posted transactions. Reconcile principal, verified payments, charges, recovery and adjustments before accepting opening balances. Keep pending/rejected payments distinct.

Minimum acceptance scenarios:

1. Add a branch, transfer a staff member and verify historical branch reports stay unchanged.
2. Create a custom schedule and reject inconsistent totals or dates.
3. Verify a partial payment using interest, fees, principal; change the configured order and confirm old allocations remain unchanged.
4. Reject self-verification, cross-branch unauthorised requests and duplicate financial posting.
5. Confirm intermediate arrears do not incur fees; after maturity, charge K50, K100, K150 and stop at the cap.
6. Reconcile a backdated payment and settled-loan fee treatment against approved workbook examples.
7. Record a recovery sale below debt without automatic write-off, and above debt with surplus tracked.
8. Record partial surplus returns and reject an excess return.
9. Reverse a verified payment and preserve both original and reversal history.
10. Generate a client statement and reconcile every balance to posted source movements.

Implementation sequence: foundation and Concept C shell; clients/applications; lending and schedules; repayment verification; custody/recovery/surplus; reporting and staged workbook migration. Financial-policy questions above must be resolved before the affected feature is used in production.

## 11. General expenses and branch cash control

Expense workflow: Draft, Submitted, Approved, Rejected, Paid, Reversed. Record category, vendor/payee, amount, currency, incurred date, branch, evidence, payment method, reference, submitter and decision. Approval and actual payment are separate facts. Include recurring-expense templates without automatically marking future expenses paid. Surplus returns use their dedicated link and cannot be counted twice as both an independent expense and a return.

Cash control: branch cash/bank/mobile-money accounts, opening float, receipts, disbursements, expenses, branch transfers and closing reconciliations. Record book balance, counted balance, variance, explanation and reviewer. Paired branch transfers have one source transfer reference and separate dispatch/receipt states. Unreceived transfers remain visible. Approved expenses must not be deducted from a cash account until paid.

Tables: expense_category, expense, expense_payment, financial_account, account_movement, branch_fund_transfer, reconciliation_session, reconciliation_item. Loan payments and sales generate linked account movements exactly once; users do not manually recreate those movements.

Screens: expense register, expense detail/approval, pay-expense form, account register, transfer form and daily reconciliation. Reports: expenses by category/branch, unpaid approved expenses, account balances and reconciliation variances. No automatic bank or mobile-money integration is assumed.

## 12. Staff, commissions, targets and payroll

Staff profile combines user account, employment status, start/end dates, effective-dated branch assignment and pay profile. Deactivating a user ends login access but preserves employment and transaction history. Keep salary access separate from ordinary staff-directory access.

Commission design follows the workbook's 10% on interest as a starting rate, but earning eligibility, verified collection basis, recovery inclusion and reversal treatment require confirmation. Store commission accruals linked to source payments and rule versions. A reversal creates an offset. Prevent the same commission being included in two payroll runs. Expected commission and actually earned commission are distinct measures.

Targets are per officer, branch and month: disbursement amount, loans count and collection amount. Version revisions and retain their author. Actuals derive from approved/disbursed loans and verified collections using an explicit recognition policy. Loan reassignment must not silently rewrite historical target attribution.

Payroll workflow: Draft, Calculated, Submitted, Approved, Partially Paid, Paid, Reversed. Inputs: basic salary, fixed allowances, earned commission, communal commission, incentives, employee deductions and employer costs. Gross pay equals basic plus allowances plus commissions/incentives. Net pay equals gross less employee deductions. Employer cost equals gross plus employer contributions, not net pay plus contributions. PAYE, NAPSA and NHIMA calculation rules and effective dates require separate validated configuration before automated calculation; no rates are inferred here. Manual reviewed entries can be retained with provenance.

Tables: employee_profile, employee_pay_profile_version, commission_rule_version, commission_accrual, officer_target, payroll_run, payroll_item, payroll_component, payroll_payment and statutory_rule_version. Branch allocation is snapshotted for each pay period. Payroll-generated expenses link to payroll payments; do not double-count salaries already recorded as standalone imported expenses.

Screens/reports: staff profile, assignment history, targets, commission register, payroll preparation, approval, payment and payslip; payroll totals by period/branch, outstanding salaries and commission reconciliation. Restrict individual payslips to the employee and authorised payroll staff.

## 13. Referral programme

Record referrer separately from staff commission. A referral links to a prospective client and resulting application, with campaign and source. Rules specify the qualifying event, reward amount/formula, eligibility and effective dates; these are open business decisions. States: Recorded, Qualified, Approved, Paid, Cancelled. Disallow self-referral and duplicate reward claims under the agreed policy. Reward reversal retains history.

Tables: referrer, referral, referral_rule_version, referral_reward, referral_reward_payment. Screens: referral register, qualification/reward queue and payment evidence. Reports: referred applications, conversion, rewards payable and paid. Rewards link to an expense category and cash movement once. Do not assume a public referral portal in the first release.

## 14. Asset selling on behalf of clients

This is a consignment service distinct from pledged collateral recovery. Intake records owner, item, condition, evidence, custody branch, agreed minimum price, commission/fee, mandate dates and signed agreement. A consigned item cannot simultaneously be actively pledged without an explicit approved change of purpose and agreement.

Workflow: Intake, Available for Sale, Sale Agreed, Sold, Owner Settlement Pending, Settled; alternatives Withdrawn/Returned. Actual sale records buyer, proceeds, selling costs and agreed business fee. Owner proceeds remain payable until settled. Report sale proceeds, business fee and owner liability separately. Pricing authority, selling-cost responsibility, fee rules and settlement deadlines are open decisions.

Tables: asset_sale_mandate, consignment_item, consignment_sale, consignment_sale_item, owner_settlement and owner_settlement_payment. Reuse client, document, custody event, account movement and audit infrastructure. Screens: intake, inventory, mandate, sale and owner settlement. Reports: held consignment assets, fees earned and unsettled owner proceeds.

## 15. Car clearance and business lending extensions

Business lending reuses applications, assessments, versioned products, agreements, schedules and repayments. Add business ownership, registration documents, business cash-flow assessment and product-specific checks only when confirmed. Existing short-term rate bands must not automatically apply to a new product.

Car clearance applications add vehicle VIN/chassis number, registration where available, import documents, supplier, purchase price, clearance-cost estimate, verified costs and expected clearance dates. Funding may involve payments to third parties rather than cash to the client. Store each approved disbursement recipient and supporting invoice. Define how costs enter the financed principal before implementation. Do not treat each supplier payment as another loan.

Tables: business_profile, business_assessment, vehicle_clearance_case, clearance_cost_item, clearance_document_link and disbursement_recipient. Reuse core loan records. Screens: product-specific application sections, clearance checklist/cost sheet and supplier-payment evidence. Open decisions: qualifying collateral, ownership/custody, repayment term, rates, fee financing, insurance and authorisation limits.

## 16. Accounting integration, reporting and governance

The initial application provides loan subledger and management cash controls. Full statutory accounting is a separate module or integration decision. Prepare mappings between source movements and accounting categories, with export batches, unique source IDs and reversal links. Optional later tables: chart_of_account, accounting_period, journal_entry, journal_line and accounting_export_batch. If implemented, journals must balance and closed periods require controlled reopening. No claim of statutory financial statements is made without an approved accounting policy.

Cross-module report catalogue: organisation and branch performance; loan balances/arrears; cash and recovery collections; custody and sales; client/owner payables; expenses; staff targets; commissions; payroll; referrals; cash reconciliation; audit and data quality. Period-end processes check unreconciled payments, unapproved recoveries, unpaid surplus/owner proceeds, incomplete transfers and pending adjustments. Dashboards link every total to its detailed register.

Global configuration covers company identity, branches, currency, timezone, versioned product terms, late-fee amount/cap, payment allocation, approval permissions/limits, categories, reference formats, document templates and optional notification templates. Financial rule changes retain author, effective date and reason. Settings are not a mechanism to overwrite posted history.

Documents include application, agreement, repayment receipt, custody intake/handover/release form, sale record, surplus-return acknowledgement, payslip and consignment mandate. Retain generated versions and signed evidence separately. Notifications can later cover upcoming dues, missed instalments, approval tasks and follow-up reminders. Provider selection and consent rules are open; recording a reminder is distinct from sending it successfully.

Operations: separate development/test/production configuration; schema migrations; synthetic demo data; scheduled jobs with run logs and retry policies; file retention settings; access reviews; backup/restore; incident logs and exception queues. Imported data reconciliation and production cutover have signed-off totals and a rollback plan. Hosting, repository and deployment destination remain to be chosen.

## 17. Step-by-step implementation plan

| Step | Deliverable | Completion evidence |
| --- | --- | --- |
| 1 | Yii2 foundation, MySQL migrations, Concept C shell, login and RBAC | Role and branch access checks pass; layout usable on desktop/mobile |
| 2 | Branches, staff and effective-dated assignments | Add/deactivate branch; staff transfer preserves history |
| 3 | Clients, documents and application/assessment forms | Supplied application fields captured; decisions and consent retained |
| 4 | Products, agreements, disbursement and custom schedules | Principal/interest reconcile; custody and signing prerequisites enforced |
| 5 | Repayments, allocation, verification, late fees and reversals | Partial/duplicate/backdated/concurrent payment scenarios reconciled |
| 6 | Collateral transfers, release, recovery sale and surplus return | Custody traceable; sale/return totals and outstanding surplus reconcile |
| 7 | Collections, core reports and workbook migration | Client statements and branch totals reconcile to imported sources |
| 8 | Expenses, financial accounts and cash reconciliation | Payment timing and transfers reconcile without duplicate costs |
| 9 | Targets and commissions | Actuals trace to eligible source transactions; reversal offsets work |
| 10 | Payroll and staff financial reporting | Approved calculations and payments reconcile; access controls verified |
| 11 | Referrals and client consignment sales | Rewards and owner payables reconcile to source records |
| 12 | Car clearance/business product extensions | Product-specific rules confirmed and scenario checks pass |
| 13 | Optional accounting integration, notifications and advanced automation | Export/send retries do not duplicate postings or communications |

Each step includes its database changes, screens, permissions, business services, relevant scenario checks and operator notes. Review the completed step before moving to the next. No deployment or production-data import is implied by this design document.


## 18. Confirmed policy updates: settlement, replacement loans and authority

This section supersedes conflicting proposed rules earlier in this document.

### Early settlement

Apply the interest rate for the actual period in which the client settles, instead of retaining the original longer-term rate. Example: a four-week loan settled within one week uses the one-week rate. Existing configured bands are 10%, 15%, 25% and 35% for weeks one through four. Store the settlement quote, effective payment date, elapsed period, selected band, revised interest, previous interest, reduction, remaining debt and CEO approval. Reconcile prior verified interest payments without rewriting their allocations. Excess funds become a recorded credit pending CEO disposition.

Boundary rules remain to be confirmed before coding: how same-day settlement, exact seven-day boundaries, time-of-day and periods beyond four weeks are classified. Proposed interpretation is elapsed calendar days from disbursement with inclusive upper band limits, subject to confirmation.

### Partial repayments and replacement loans

A partial repayment closes the original loan and creates a linked replacement loan whose principal is the remaining balance, as instructed by the CEO. Preserve the original principal, contractual terms, approved repayment and all transaction history. Do not edit the original loan principal to represent the new agreement.

The closing transaction must separately identify actual cash received and debt transferred. Transferring a balance is not a cash repayment, a write-off or a new cash disbursement. The original closes with reason Replaced after partial repayment; the replacement references the original and the approved rollover action. CEO approval is required for the repayment and replacement loan. Commit the related postings and loan transition atomically only when both authorisations and required new terms are complete. Prevent duplicate replacement loans from retries.

Tables/extensions: loan.predecessor_loan_id, loan_rollover, loan_rollover_component, settlement_quote and settlement_quote_component. Capture transferred principal, interest and fees separately even when their approved sum becomes replacement principal. Collateral pledge links move through an audited successor event without recording a physical release; custody stays at the Lendford branch.

Replacement loans require an agreed start date, new term/rate, schedule and agreement or approved amendment evidence. Whether remaining balance includes unpaid interest and fees, and how interest is adjusted for a partial repayment, still requires explicit confirmation. No component is silently capitalised or waived. Instalment schedules remain supported, but their interaction with this instruction needs clarification: whether each scheduled partial instalment triggers replacement or only an explicitly selected reloan action. Do not implement ordinary instalment processing in a way that contradicts the confirmed replacement policy.

Reporting distinguishes cash collections, debt transferred, new money advanced and replacement principal. Count replacement loans separately from original originations so portfolio turnover and staff performance are not inflated. Loan statements show a continuous chain of predecessor and successor records.

### CEO approvals and exception authority

The CEO approves all activities including loans, reloans, repayments, sales, expenses, reversals, waivers and recovery sales. Loan officers capture and submit records; they never independently approve them. Earlier suggestions allowing finance staff or branch managers to approve financial actions are superseded. They may prepare assessments or reconciliation evidence, but final authorisation rests with the CEO.

Provide a central approval inbox by action type, branch, submitter and age. Show source evidence, balance impact, linked records and dependencies before approval. Approve, reject or request correction with a reason. A modification after submission invalidates approval of the changed payload and requires resubmission. An approved decision refers to the exact record version. CEO-approved posting can run automatically without giving the service account independent discretionary approval authority.

CEO exception tools cover repayment allocation corrections, backdating, sale corrections, fees/interest waivers, reversals, custody exceptions and supported loan resolutions. Record reason, evidence, original state, resulting state and authorisation. Exceptions use explicit compensating entries or approved transitions and preserve the audit trail. The CEO may determine policy exceptions; financial reconciliation and history must still remain traceable.

Interpret all activities broadly for the approval workflow; clarify which routine nonfinancial edits, such as contact corrections or staff assignments, require CEO approval before implementation. Until clarified, use a CEO review path for business-record changes rather than silently delegating approval.

### Administrative superuser

Create a distinct Admin Superuser role for system configuration, account management, access recovery and user support. CEO business authority and administrative system access are separate permissions. This role does not automatically approve or override transactions on the CEO's behalf. The CEO account can hold both roles when explicitly assigned.

Provide audited user activation/deactivation, role and branch assignment, session revocation and secure reset assistance. Never display existing passwords. If support impersonation is later requested, require a restricted, time-limited, prominently indicated session and prohibit financial approvals during impersonation. No impersonation capability is assumed in the initial implementation.

Acceptance checks add: one-week settlement of a four-week loan; previous interest exceeding revised interest; partial repayment with linked transfer and zero duplicated cash; collateral continuity; duplicate rollover rejection; CEO-only approvals; changes after approval requiring resubmission; superuser support access without CEO approval permission; traceable approved exceptions.


## 19. Confirmed repayment policy updates — 1 October 2026

Scheduled instalments reduce the existing loan balance and keep it active until settled. An explicit CEO-approved reloan transfers all remaining principal, unpaid interest and accrued fees; ordinary instalments do not trigger replacement loans. This supersedes the automatic-replacement wording in section 18. Explicit reloan origination and collateral continuity will be implemented as a separate workflow.

Early settlement uses elapsed calendar days from disbursement: days 0–7 use week one, 8–14 week two, 15–21 week three, and day 22 onwards week four. Revised interest never exceeds original contractual interest. The CEO approves the resulting reduction, and prior allocations remain immutable; excess interest already paid becomes recorded credit pending disposition.


Explicit reloans now require a verified partial repayment, a signed replacement agreement, and a separate CEO approval. Source debt and payment history are snapshotted and rechecked at posting. The transfer creates no cash disbursement, retains original repayment allocations, and carries collateral custody into the successor. Source payment reversals are blocked once a successor exists; reloan reversal is a separate controlled resolution workflow.