Loans & Portfolio Management

The Loans module (/loans) is the core engine of BiiTrust. It tracks active credit facilities, generates dynamic amortization schedules, accrues contractual interest and late penalties, manages aging arrears, and enforces portfolio risk policies.

1. Key Definitions & Financial Terms

Credit Facility / Loan (LOX...): An active, approved, or closed lending agreement between BiiTrust and a borrower, uniquely identified by a 15-character hex code (e.g., LOX44A1B903).
Principal ($P$): The gross capital amount disbursed to the borrower (or net after upfront fee deductions).
Amortization: The structured schedule of periodic installment payments that gradually liquidates principal debt and recognizes earned interest over the loan tenor.
Days Past Due (DPD): The consecutive calendar count of days elapsed since the oldest unpaid installment’s maturity date. Governs aging buckets and provisioning stages.
Portfolio at Risk (PAR): The percentage of the gross loan book where installments are overdue beyond a specified threshold ($\text{PAR } 30$, $\text{PAR } 60$, $\text{PAR } 90$).
Waterfall Allocation: The strict institutional payment priority order: $$\text{Payment} \longrightarrow \text{Penalties} \longrightarrow \text{Fees} \longrightarrow \text{Interest} \longrightarrow \text{Principal}$$
Effective Interest Rate (EIR): The internal rate of return reflecting the real borrowing cost including upfront fees and compounding frequency.
Accrual Accounting: Contractual interest and daily late penalties are recognized as receivables as they fall due, before cash is received.

2. Navigating the Loans Directory (`/loans`)

Accessing the Module

Desktop Sidebar: Click Loans in the left navigation menu (/loans).
Mobile Bottom Navigation: Tap Loans in the dock.
Global Search: Press Cmd + K $\to$ Type loan: followed by loan hex, borrower name, or account number.

Filter Chips & Portfolio Views

The top bar provides instant segmentation across the book:

Status Filters:
- All: Complete historical registry of facilities.
- Active: Currently amortizing facilities with an open balance.
- Overdue: Facilities carrying an overdue installment ($\text{DPD} > 0$).
- Closed: Loans where outstanding balance is exactly KES 0.00.
- Rescheduled: Restructured loans operating under revised terms.
- Written Off: Facilities charged off to the impairment reserve.
Aging Band Chips: Filter specifically by delinquency tier (Current, 1-30 DPD, 31-60 DPD, 61-90 DPD, 90+ DPD).
Product Filter: Filter by loan product (e.g., Biashara Fast, Asset Finance, Salary Advance).
Branch / Officer Filter: Restrict list to specific regional offices or officer books.

3. The Loan Lifecycle

Every loan moves through distinct operational states from origination to final closure:

[ Draft Application ]
         │ (Officer submits)
         ▼
[ In Review (Manager / Director) ]
         │ (Credit Committee approves)
         ▼
[ Approved (Awaiting Disbursement) ]
         │ (Disbursed via M-Pesa B2C / Bank)
         ▼
[ Active / Disbursed ] ◄─────────────────────────┐
         │                                       │ (Borrower pays arrears)
         ├───────────► [ Overdue (1–29 DPD) ] ───┘
         │
         ├───────────► [ In Default (30–89 DPD) ]
         │
         ├───────────► [ Non-Performing / NPA (90+ DPD) ]
         │                     │
         │ (Restructured)      │ (All recovery exhausted)
         ▼                     ▼
[ Restructured ]        [ Written Off ]
         │
         ▼ (Final payment clears all legs)
[ Fully Paid / Closed ]

4. Interest Calculation Models

BiiTrust supports two standardized calculation models configured per product:

1. Flat Rate Method

Interest is computed once on the initial principal and distributed evenly across all installments:

$$\text{Total Interest} = P \times \left(\frac{\text{Annual Rate %}}{100}\right) \times \left(\frac{\text{Tenor Months}}{12}\right)$$ $$\text{Periodic Installment} = \frac{P + \text{Total Interest}}{n}$$

Installment Composition: Fixed principal portion and fixed interest portion on every schedule row.
Usage: Standard for micro-enterprise, biashara loans, and weekly market group lending.

2. Declining / Reducing Balance Method

Interest is computed strictly on the remaining unpaid principal at each repayment cycle:

$$\text{Interest Portion}k = \text{Remaining Balance}{k-1} \times \left(\frac{\text{Annual Rate}}{m}\right)$$

Installment Composition: Interest is front-loaded; as principal amortizes, the interest portion of each installment decreases while the principal repayment portion increases.
Early Settlement Benefit: Borrowers who liquidate debt early save money on future unaccrued interest.

5. The Repayment Schedule Inspector (`/loans/:hex/schedule`)

Clicking on any loan opens its full installment ledger:

#	Due Date	Principal	Interest	Fees	Penalty	Total Due	Status
1	15 Oct 2026	KES 10,000	KES 1,500	KES 0	KES 0	KES 11,500	`paid`
2	15 Nov 2026	KES 10,000	KES 1,500	KES 0	KES 0	KES 11,500	`partial`
3	15 Dec 2026	KES 10,000	KES 1,500	KES 0	KES 150	KES 11,650	`overdue`
4	15 Jan 2027	KES 10,000	KES 1,500	KES 0	KES 0	KES 11,500	`due`

Schedule Status Badges

paid: All installment legs (penalty, fees, interest, principal) fully satisfied.
due: Current installment within contractual window; not yet overdue.
partial: Some funds received, but balance remains open.
overdue: Due date has passed and grace window has expired. DPD counter active.
defaulted: Unpaid for 90+ days. Facility classified as non-performing.

6. The Loan Detail Page (`/loan/:hex`)

The loan profile provides comprehensive operational controls:

Working Tabs

Schedule: The complete interactive repayment schedule table, showing remaining balance, paid amounts, and next installment countdown.
Payments: Complete ledger of all inbound transactions credited to this loan, showing receipt numbers, channels (Cash/M-Pesa), and allocation splits.
Security / Collateral: Pledged logbooks, title deeds, and chattels backing this facility, with current LTV coverage ratio.
Statement: Official loan statement showing debits, credits, and running balance. Click Download PDF to export Loan_Statement_LOX....pdf.
Notes & Audit: Chronological log of officer collection calls, guarantor contacts, and restructures.

Repay (/loan/:hex/repay): Takes an immediate repayment across the counter or triggers an M-Pesa STK push.
Reschedule (/loan/:hex/reschedule): Extends tenor, adjusts interest rate, or pauses installments.
Pledge Security (/loan/:hex/pledge): Attach additional collateral to improve loan coverage.
Write Off (/loan/:hex/writeoff): For directors/accountants; charge off uncollectible debt.
Reassign (/loans/reassign?loan=LOX...): Transfer portfolio ownership to another loan officer.

BiiTrust User Manual