# MICROFINANCE MANAGEMENT SYSTEM — AUTHORITATIVE SPECIFICATION

This document is the product-level source of truth for the Microfinance Management System. The detailed executable requirements and acceptance criteria are defined phase-by-phase in `MICROFINANCE_DEVELOPMENT_PROMPTS.md` and, for configurable optional modules, in `MICROFINANCE_MODULE_ROADMAP.md`. These files are normative: no requirement may be skipped, mocked, hard-coded, or replaced with a non-working placeholder.

## Product objective

Build a production-ready, responsive, multi-branch microfinance business management platform that connects customers, KYC and documents, loans, loan products, approvals, contracts, disbursements, repayment schedules, collections, reminders, arrears, penalties, collateral/dhamana custody, top-ups, early settlement, restructuring, write-offs and recoveries, financial accounts, transfers, reconciliation, expenses, recurring costs, payroll, capital, fixed assets, accounting, audit trails, tasks, calendar, notifications, branch reporting, consolidated reporting, trial balance, financial statements, profit/loss, cash flow, dashboards, security, backups and future customer/mobile channels.

## Mandatory business principles

1. Every shilling entering or leaving the business must be traceable to a business event, account, branch, user and source record.
2. Loan principal recovery is not revenue. Interest, fees and penalties must be separated from principal in accounting and reporting.
3. Approval and disbursement are separate events.
4. Financial records are never silently deleted. Use reversal, cancellation, write-off, status transitions and audit history.
5. Every loan keeps a permanent lifecycle and history, including top-ups, restructures, arrears, write-offs and later recoveries.
6. Every collateral item has a unique identity, custody history, storage location and release history.
7. Branch data isolation and permissions must be enforced on the backend, not only hidden in the UI.
8. Financial operations must use fixed-precision money types and database transactions.
9. Critical operations must be idempotent and protected from duplicate posting and concurrency errors.
10. Dashboard and report totals must come from real database transactions and reconcile with account histories and customer/loan statements.
11. Optional modules must be centrally switchable without deleting or corrupting existing module data. Disabled modules must be hidden from navigation and blocked on the backend.
12. Known accounting/reporting limitations must be displayed explicitly; the system must never manufacture balancing figures or silently invent missing ledger categories.

## Business configuration

Support business name, logo, registration number, TIN, licence details, physical and postal addresses, region, district, country, phones, email, website, currency, currency symbol, number formatting, financial year, accounting period, default interest calculation method, default penalty settings, company stamp and document templates.

Interest methods must include flat interest, reducing balance and fixed interest amount.

System Settings must include business-wide optional module controls. Turning a module off changes availability only; records, accounting entries, files, history and audit logs remain preserved for later reactivation.

## Branches and staff

Support unlimited branches with unique codes, location/contact details, manager, opening date and status. Every relevant transaction belongs to a branch. Staff records include full name, employee number, phone, email, NIN, position, username/login credentials, profile photo, employment date, status and one or more branch assignments.

Default roles: Super Administrator, Branch Manager, Loan Officer, Loan Inspector/Approver, Cashier, Accountant, Debt Collector, HR/Payroll Officer and Auditor. Permissions are customizable.

## Customers

Support customers with NIN and without NIN. NIN integration must be optional so manual registration always works. Store full profile, address/GPS, next of kin, guarantors, documents, expiry dates, customer photo, duplicate detection, blacklist/watchlist, risk profile and permanent loan history.

## Loans

Loan products define amount limits, duration, interest, calculation method, repayment frequency, grace period, penalties, processing/insurance/other fees, collateral requirement and guarantor requirement.

Loan application lifecycle:

Customer Registration -> KYC/Documents -> Application -> Collateral -> Assessment -> Contract Generation -> Customer Signature -> Signed Contract Upload -> Approval -> Ready for Disbursement -> Disbursement -> Repayment Schedule -> Reminders -> Repayments -> Completion -> Collateral Release -> Archive.

Support approval-required and authorized auto-approval modes, optional maker-checker controls, signed-contract-before-disbursement enforcement, unique loan numbers, printable contracts and valid status transitions.

## Collateral / Dhamana

Support configurable collateral categories, unique collateral numbers, QR/barcode labels, photos, documents, values, condition, branch, storage location, receiving staff and statuses including pending inspection, accepted, in custody, released, repossessed, scheduled for sale, sold and returned. Preserve complete custody history and generate receipts/release acknowledgement.

## Repayments and reminders

Generate schedules for daily, weekly, biweekly, monthly, custom and lump-sum repayment. Store installment principal, interest, fees, penalties, due amount, paid amount, remaining amount, due date and status.

Office payments and approved remote payments must update account balances, payment allocations, loan balance, schedule, statement, ledger, collections and receipt atomically. Support partial and multi-installment payments.

Automated reminders include configurable pre-due, due-date and overdue notifications via SMS, WhatsApp, email and in-system channels with delivery logs and retry-safe scheduling.

## Arrears and advanced loan operations

Provide arrears buckets (1–7, 8–30, 31–60, 61–90, 90+ days), collection actions, promise-to-pay history and configurable penalties.

Top-up must preserve the old loan, internally settle the old balance from the new principal, disburse only the net cash to the customer, keep the new principal obligation intact and record the relationship/audit trail. Support configurable eligibility thresholds and authorized overrides.

Support early settlement, restructuring with preserved old schedules, write-off with approval/supporting documents, and recovery of written-off loans without deleting history.

## Financial accounts and accounting

Support cash, mobile-money, bank, petty-cash, safe, collection and other accounts. Store opening/current balance and transaction history. Account transfers create linked debit/credit entries and do not change total company funds or profit.

Support cash reconciliation, owner capital injections, expenses, recurring expenses, payroll and payslips.

Maintain an accounting ledger for loan disbursement, principal repayment, interest, fees, penalties, expenses, salaries, capital, transfers, fixed-asset acquisitions, depreciation, maintenance, reversals, write-offs and write-off recoveries.

## Fixed Assets

Fixed Assets is an optional business module controlled from System Settings.

Maintain a permanent register of company-owned assets with unique asset number, branch, category, serial/registration number, acquisition date/cost, residual value, depreciation basis, location, custodian, condition/status, supplier/reference, maintenance dates and notes.

Support opening/existing assets without creating false income and newly purchased assets funded from a real financial account. Purchased assets must reduce the selected account and create balanced accounting entries atomically.

Support straight-line depreciation using fixed-precision calculations. Prevent duplicate depreciation for the same asset/month, preserve the original depreciation schedule/history, never depreciate below residual value, and post depreciation expense against accumulated depreciation.

Record preventive maintenance, repair, service, inspection and other maintenance. Paid maintenance reduces the selected financial account and posts maintenance expense; zero-cost maintenance/inspection remains valid operational history.

Provide asset register, depreciation and maintenance reports with branch/date filters, category summaries, acquisition cost, accumulated depreciation, net book value and maintenance cost.

## Reporting

Financial Reports is an optional business module controlled from System Settings.

Provide daily dashboards, portfolio reports, branch reports, consolidated company reports, trial balance, income statement/profit and loss, statement of financial position, cash flow, account statements, capital/expense/payroll reports, collection/disbursement reports, officer performance, collateral reports, fixed-asset reports, end-of-day closing, automated daily management reports and monthly management reports.

Trial balance must be derived from accounting entries and show opening balances, period debits/credits, closing debit/credit balances and any accounting difference. The system must expose rather than hide an imbalance.

Income statements must distinguish principal from revenue and include genuine income/expense categories such as interest, fees, penalties, service income, write-off recoveries, operating expenses, payroll, depreciation and asset maintenance.

Statement of financial position must use real ledger values for financial assets, principal receivable, fixed assets, accumulated depreciation, capital and cumulative result. Liabilities must come from real liability ledger data when liability accounting is introduced; no fictitious balancing liability may be generated.

Portfolio reporting must show active/overdue/written-off loan counts, principal/interest/fees/penalties outstanding, total outstanding, total overdue, portfolio-at-risk percentage and branch breakdown. If only current balance snapshots are available, the report must identify them as current snapshots rather than pretending they are historical as-of balances.

The owner must always be able to answer:

- How much money does the company have and where is it?
- How much principal is currently loaned out?
- How much income has been earned?
- How much has been spent?
- What is the current profit/loss?
- What is due and overdue?
- What fixed assets does the company own and what are they worth in the books?
- What collateral is in custody?
- How is each branch performing?

## Security, audit and operations

Require secure authentication, password hashing, optional 2FA support, login monitoring, session security, device/IP history where appropriate, role/permission enforcement, branch isolation, secure private file storage, upload validation, rate limiting, audit logs, protected financial history and automated backups stored separately from the primary server.

## Execution rule

Development must follow `MICROFINANCE_DEVELOPMENT_PROMPTS.md` and `MICROFINANCE_MODULE_ROADMAP.md` one phase/module at a time. After each phase, run migrations, seeders and automated tests, audit every requirement, fix failures, and only then proceed. The current implementation phase must not silently implement or weaken later-phase business rules.