# MICROFINANCE SYSTEM — MODULE ROADMAP EXTENSION

This file extends `MICROFINANCE_DEVELOPMENT_PROMPTS.md` and `MICROFINANCE_SPEC.md`. The same global development rules apply: real database data only, fixed-precision money, backend permissions, branch isolation, database transactions for financial postings, permanent audit history, no silent deletion of financial records, and automated tests before a module is declared complete.

## Module Control Policy

Optional business modules must be centrally configurable under **Administration → System Settings → Modules**.

For every configurable module:

- Super Administrator can turn the module on or off for the whole business.
- Turning a module off must hide its navigation and block its protected routes on the backend.
- Turning a module off must never delete module records, accounting entries, documents, history or audit logs.
- Re-enabling a module must restore access to the existing data exactly as it was.
- Permission checks remain required even when a module is enabled.
- Module settings are business-level settings and must be audit logged.

---

# MODULE 1 — FIXED ASSETS

Purpose: manage company-owned long-term assets and connect them to accounting, depreciation, maintenance and reporting.

Module switch: `Fixed Assets`.

## Asset Register

Every asset must have a permanent system-generated asset number and store at least:

- Business and branch
- Asset name
- Category
- Description
- Serial/registration number
- Supplier
- Purchase reference
- Acquisition source
- Acquisition date
- Acquisition cost
- Residual value
- Depreciation method
- Useful life
- Depreciation start date
- Accumulated depreciation
- Current book value
- Financial account used for purchase, where applicable
- Physical location
- Responsible employee/custodian
- Status
- Next maintenance date
- Notes
- Created/updated user and timestamps

Initial statuses:

- Active
- In Maintenance
- Retired
- Disposed

Financial asset records must not be hard deleted.

## Asset Acquisition Accounting

Support two initial acquisition sources:

### Existing / Opening Asset

Used when an already-owned asset is first introduced into the system.

Accounting:

- Debit Fixed Assets
- Credit Capital / Opening Equity

This must not create false income.

### Purchased From Financial Account

Used when the business buys an asset using Cash, Bank, Mobile Money or another configured financial account.

Posting must atomically:

1. Lock and validate the paying account.
2. Confirm sufficient funds.
3. Reduce the account balance.
4. Create a permanent account transaction.
5. Debit Fixed Assets.
6. Credit the selected financial asset account.
7. Store the asset register record.
8. Audit the event.

## Depreciation

Initial supported method:

- Straight Line
- Do Not Depreciate

Straight-line depreciation must use fixed-precision calculations and allocate rounding differences exactly across the configured useful life.

Each depreciation posting stores:

- Asset
- Period/month
- Depreciation amount
- Accumulated depreciation after posting
- Book value after posting
- Journal number
- Notes
- Posting user/date

Rules:

- The same asset/month cannot be posted twice.
- Depreciation cannot begin before the configured depreciation start month.
- Depreciation cannot reduce book value below residual value.
- A fully depreciated or disposed asset cannot receive additional depreciation.
- Original depreciation history is permanent.

Accounting:

- Debit Depreciation Expense
- Credit Accumulated Depreciation

## Maintenance

Record:

- Maintenance number
- Asset
- Branch
- Date
- Maintenance type
- Description
- Supplier/service provider
- Cost
- Paying financial account where cost exists
- Reference
- Next maintenance date
- Notes
- Recorded by

Maintenance types initially include:

- Preventive Maintenance
- Repair
- Service
- Inspection
- Other

If maintenance has a cost, posting must atomically reduce the selected financial account and create accounting entries:

- Debit Fixed Asset Maintenance Expense
- Credit selected Financial Asset account

Zero-cost inspections/services are allowed and create maintenance history without a cash posting.

## Fixed Asset Reports

Provide:

1. Asset Register Report
2. Depreciation Report
3. Maintenance Report
4. Asset summary by category
5. Acquisition cost
6. Accumulated depreciation
7. Net book value
8. Maintenance cost for selected period

Filters:

- Date range where applicable
- Branch
- Several branches
- Entire accessible company scope

Exports:

- CSV
- Printable browser report

## Permissions

At minimum:

- View Fixed Assets
- Manage Fixed Assets
- Post Depreciation
- Record Maintenance

Accountants and authorized branch management receive operational permissions by default. Auditors receive read-only access.

## Automated Tests

Cover:

- Module enable/disable behavior
- Branch isolation
- Opening asset accounting
- Purchased asset account deduction and balanced journal
- Insufficient funds rejection
- Straight-line depreciation and exact rounding
- Duplicate depreciation prevention
- Residual-value floor
- Maintenance with and without cost
- Maintenance account deduction/accounting
- Reports and exports
- Permissions and audit logging

---

# MODULE 2 — FINANCIAL REPORTS

Purpose: give management and accountants reconciled financial and portfolio reporting from the system’s accounting and loan data.

Module switch: `Financial Reports`.

The module extends the existing reports instead of replacing them.

## Core Financial Reports

Provide:

1. Trial Balance
2. Income Statement / Profit & Loss
3. Statement of Financial Position
4. Cash Flow
5. Financial Account Statements
6. Capital Report
7. Expense Report
8. Payroll Report
9. Collection Report
10. Disbursement Report
11. Portfolio Summary
12. Existing detailed Loan & Branch Reports

## Trial Balance

For every ledger account/category show:

- Opening balance
- Period debit
- Period credit
- Closing debit balance
- Closing credit balance

The report must expose debit/credit totals and accounting difference instead of hiding imbalances.

Company-wide reporting should reconcile to the underlying accounting journal. Branch-only scopes must identify any imbalance caused by cross-branch postings until formal inter-branch clearing accounts are implemented.

## Income Statement

Income must include real earned income such as:

- Interest
- Fees
- Penalties
- Service income
- Write-off recoveries
- Other actual income

Expenses must include:

- Operating expenses
- Payroll
- Write-offs/bad-debt expense
- Depreciation expense
- Fixed-asset maintenance
- Other actual expenses/settlement adjustments as applicable

Loan principal collections must never be counted as revenue.

Show:

- Total income
- Total expenses
- Net profit/loss

## Statement of Financial Position

Show at minimum:

Assets:

- Financial accounts / cash and bank
- Loan principal receivable
- Fixed assets at cost
- Less accumulated depreciation

Equity:

- Owner/business capital
- Cumulative retained profit/loss derived from ledger activity

Liabilities must be shown from real liability ledger data when liability accounting is introduced. Until then the report must state the limitation instead of inventing liability balances.

The statement must display its accounting difference/reconciliation check.

## Cash Flow

Continue transaction-backed cash flow reporting and classify actual money movement including:

- Loan collections
- Loan disbursements
- Operating expenses
- Payroll
- Capital injections
- Transfers
- Fixed asset purchases
- Fixed asset maintenance

Never derive cash flow from income statement figures where real account transactions exist.

## Portfolio Summary

Show management-level lending exposure including:

- Active loans
- Overdue loans
- Written-off loans
- Principal outstanding
- Interest outstanding
- Fees outstanding
- Penalties outstanding
- Total outstanding
- Total overdue
- Portfolio at Risk percentage
- Branch breakdown

Portfolio values must come from loan/accounting data and must never be estimated from package/product configuration.

Current balance snapshots may be used for the initial implementation. Historical as-of portfolio reconstruction requires persistent balance snapshots and must not be falsely presented as historical until that support exists.

## Filters and Exports

Reports must support:

- From / To date
- One branch
- Several branches
- Entire accessible company scope
- Financial account filter where relevant
- CSV export
- Printable report

## Reconciliation Rules

- Trial balance uses accounting entries.
- Cash flow/account statements use financial-account transactions.
- Loan principal is separated from income.
- Fixed assets and accumulated depreciation are ledger-backed.
- Dashboard/report numbers must reconcile with source transactions.
- Any known limitation must be visible in the report instead of silently manufacturing a balancing value.

## Permissions

Financial reporting remains protected by `reports.view` and the Financial Reports module switch.

## Automated Tests

Cover:

- Module enable/disable behavior
- Trial balance debit/credit reconciliation
- Income statement principal exclusion
- Depreciation and maintenance in expenses
- Fixed assets on statement of financial position
- Cash-flow inclusion of asset purchases/maintenance
- Portfolio totals and branch scope
- Branch isolation
- CSV export
- Existing report backward compatibility