Credit module — staff operations guide (Task 10.1)

Status: ✅ Complete

Plan reference: Task 10.1 in the Credit module implementation plan (operations workspace root)

The Credit module lets staff originate and service AAOIFI-compliant financing facilities: Murabaha (cost-plus sale), Ijarah (lease-to-own), and Diminishing Musharakah (declining co-ownership). It is a separate product from the NAV-fund flows and the existing Mudarabah investments. This page is the how — the day-to-day staff walkthrough. For the what (data model, API, math) see the technical credit docs; for how it fits see the credit architecture docs.

All screens described here live under /u/credit in the ERP.

What the three products mean (plain terms)

Murabaha — cost-plus sale. Ethica buys an asset and sells it to the customer at cost + an agreed profit that is fixed at signing. The profit is a flat naira amount locked into the contract; it never changes, no matter how fast or slow the customer pays. This fixed-at-signing profit is the heart of the AAOIFI no-riba rule for Murabaha.
Ijarah — lease-to-own. Ethica owns the asset and leases it to the customer; rent is charged on the outstanding (un-bought-out) value, and ownership transfers at the end.
Diminishing Musharakah (DM) — declining co-ownership. Ethica and the customer co-own the asset. Each period the customer buys out a slice of Ethica's share (principal) and pays rent on the share Ethica still holds. Ethica's ownership winds down to zero; the customer's rises to 100%.

DM and Ijarah share one declining-balance engine (rent on the shrinking balance). Murabaha uses a separate fixed-profit engine.

Roles and permissions

Access is permission-based; your administrator maps these to roles:

Permission	Lets you
`credit:view`	View facilities, schedules, payments, reports
`credit:create`	Create a facility (draft) and submit it for review
`credit:review`	Perform the maker-checker review (approve to Shariah / reject)
`credit:approve`	Shariah/credit approval, mark asset owned, activate, record non-accrual; approve or reject an ibra' rebate request
`credit:record_payment`	Record customer payments and early settlements; initiate or withdraw an ibra' rebate request
`credit:config_manage`	Edit the CFO posting account-map

End-to-end lifecycle (what staff do, in order)

1. Create a facility

Open Credit → New facility (/u/credit). Choose the product type, pick the customer, and enter the deal terms:

Asset cost, down payment, and the resulting facility amount (cost − down payment). All money fields show the ₦ symbol with thousands separators.
Rate (annual profit/rent rate) and term (number of periods × periods/year).
For Murabaha only: fixedTotalProfit — the flat naira profit, agreed and entered at signing. This field is required for Murabaha and is what the contract locks in. It is never derived from the rate after the fact. (DM/Ijarah leave it blank — their rent is rate-derived on the declining balance.)

On save the system assigns a facility reference in the form CF-YYYYMMDD-XXXX and the facility enters draft. You can preview the full repayment schedule before submitting (View schedule) — the engine generates every period line (principal, profit/rent, total, ending balance, ownership %).

2. Submit for review (maker-checker)

When the draft is correct, Submit for review moves it to pending_review. The creator (maker) cannot approve their own facility — a different user with credit:review acts as the checker.

3. Maker-checker: approve or reject

A reviewer opens the facility and either:

Approve → moves to shariah_review (the deal terms are sound; hand off to Shariah).
Reject → moves to rejected with a reason. Rejection is allowed from both pending_review and shariah_review.

4. Shariah review and approval

The Shariah/credit approver confirms the structure is compliant (correct product, profit fixed for Murabaha, ownership plan sound) and Approves → the facility moves to approved. From here the asset must be acquired before anything else can happen.

5. Acquire the asset and mark it owned

This is the AAOIFI "no sale before ownership" step. The asset record (credit_assets) starts as pending_acquisition. Once Ethica has actually bought the asset, staff use Mark asset owned to set its ownership status:

Murabaha / Ijarah → owned_by_ethica
Diminishing Musharakah → co_owned

The acquisition date is stamped. You cannot skip this step.

6. Activate — the VR-001 gate

Activate is the moment the financing goes live. The system enforces gate VR-001: a facility can only be activated once its asset is in the required ownership state (owned_by_ethica for Murabaha/Ijarah, co_owned for DM). If the asset is still pending acquisition, activation is blocked — this is "no sale before ownership," enforced in software.

On a successful activation the system atomically posts the origination journal and moves the facility to active:

DM / Ijarah: Dr financing-asset / investment Cr cash for the facility amount.
Murabaha: Dr Receivable (cost + profit) Cr cash (cost) Cr Deferred Profit (profit) — the profit sits in Deferred Profit and is recognised as the customer pays.

If activation fails (gate not met, or an account is unmapped) nothing is posted — the journal and the status change roll back together.

7. Record payments

Open the active facility and use Record payment (credit:record_payment). Enter the amount, payment date, and a reference. The system matches the payment to the due schedule line(s) and posts the servicing journal:

DM / Ijarah payment: Dr cash (total) Cr rental-income (rent portion) Cr investment (principal portion).
Murabaha payment: Dr cash (total) Cr Receivable (total) plus Dr Deferred Profit (profit portion) Cr Income (profit portion) — profit is recognised only as instalments are paid.

Schedule lines update their status to paid or partially_paid, and the paidAmount is tracked. For Murabaha, the profit recognised is invariant to how fast the customer pays — paying early does not increase profit. This is the anti-riba guarantee; see the engine doc.

Partial payments and extra / early payments

A payment smaller than the due amount marks the line partially_paid and leaves the remainder outstanding.
An extra payment (more than the period due) is flagged on the payment record and reduces the outstanding balance faster.

Early settlement

Use the early-settlement flow when a customer wants to close the facility ahead of schedule:

DM / Ijarah: future rent is waived — the customer pays the remaining principal (buy-out) only. They never pay rent on time they didn't use.
Murabaha: the customer settles the outstanding principal plus any profit not already rebated. The staff member opening the settlement can grant a discretionary ibra' rebate — see below.

Early settlement with an ibra' rebate (Murabaha only)

What ibra' is. Ibra' is a voluntary, discretionary rebate of some or all of the remaining unearned deferred profit when a customer closes a Murabaha facility early. DM and Ijarah already waive future rent on early settlement, so this flow applies only to Murabaha.

Maker (fund accountant — credit:record_payment). Open the facility, choose Early settlement. The screen shows:

Outstanding principal — what the customer still owes on the asset cost.
Remaining unearned profit — the deferred profit not yet recognised.
Rebate amount — enter any amount from ₦0 up to the full remaining unearned profit.

As you type, the screen updates live to show the resulting profit recognised (remaining profit − rebate) and the settlement amount the customer must pay (outstanding principal + profit recognised).

A rebate of ₦0 posts immediately — no approval required.
A rebate greater than ₦0 is submitted for CFO approval. The facility is locked from the moment you submit: no further payments or settlements can be recorded while a request is pending. You (the initiator) can Withdraw your own pending request at any time before a decision is made, which unlocks the facility.

(Screenshots TBD once the UI is captured.)

Checker (CFO — credit:approve). A different staff member from the initiator reviews the request (maker ≠ checker is enforced — you cannot approve your own submission). The checker sees the proposed rebate amount, the profit that would be recognised, and the resulting settlement figure, and then either:

Approve — posts the settlement immediately.
Reject (with a reason) — unlocks the facility; the fund accountant can amend and resubmit.

No new permissions are needed: the existing credit:record_payment covers initiating and withdrawing; credit:approve covers approving and rejecting.

What posts on approval.

Dr cash Cr Receivable for the full settlement amount (principal + recognised profit).
Dr Deferred Profit Cr Income for the (remaining profit − rebate) — only the non-rebated portion is recognised as income.
Dr Deferred Profit Cr Receivable for the forgiven rebate — the waived amount is released from deferred profit against the receivable and is never booked as income.
The facility moves to completed.

On a non-accrual facility no further profit is recognised regardless of rebate — the non-accrual rule takes precedence.

8. Overdue handling

A daily job flips any unpaid, past-due schedule line to overdue. Per AAOIFI there is no compounding and no penalty interest — an overdue line simply carries its original amount until paid. Staff can see overdue lines on the facility and in the portfolio report. Marking a line overdue does not change what the customer owes; it is a status flag for follow-up.

Marking a facility non-accrual

When a facility is impaired and income should no longer be recognised, an approver uses Mark non-accrual (records nonAccrual, nonAccrualAt, and a nonAccrualReason). After this:

Payments post Dr cash Cr principal only — no income/rent/profit is recognised while non-accrual is in force.
Principal recovery continues normally.

CFO posting account-map (config)

Credit → Account map (credit:config_manage) is where the CFO maps each product type × event type × side to a specific GL account. The posting engine resolves accounts from this map at posting time — accounts are never hardcoded. If a required mapping is missing, posting fails closed (the journal will not post) rather than guessing an account. Keep this map complete before going live with a new product.

Reports

Credit → Reports provides three views:

Portfolio — outstanding balances broken down by product and status.
Income contribution — income recognised by the credit book.
Shari'ah-compliance summary — a compliance overview (e.g. fixed-profit integrity, ownership-before-sale adherence).

Open / gated items (pending Shari'ah & finance confirmation)

Delivered

Early-settlement rebate (ibra') — ✅ built. The maker-checker ibra' flow for Murabaha is live; see the section above.

Still pending build

Late-payment penalty — CFO has ruled: build as a configurable, dormant add-on (all three calculation bases are acceptable). Formula/config details are confirmed; not yet built. Call out to customers/auditors as pending.
Ijarah / DM asset depreciation — CFO has confirmed the DM case (depreciate over useful life; the depreciable amount declines as the customer redeems ownership). Three product-scope and formula specifics are still being confirmed with the Shari'ah board; not yet built.

Credit technical docs — data model, API, the repayment-engine math.
Credit architecture — lifecycle state machine, posting flow, AAOIFI rationale.
Finance module — the GL / posting engine the credit module posts through.
People and access — how credit:* permissions map to roles.