End-to-End Operational Lifecycle

This guide details the complete 7-phase operational journey of a borrower in BiiTrust, from initial field registration through compliance KYC verification, credit origination, multi-tier committee approval, loan disbursement, servicing repayments, and final accounting settlement.

The 7-Phase Journey Map

┌────────────────────────────────────────────────────────────────────────┐
│ Phase 1: Client Onboarding & Registration                              │
│   Identity capture (National ID 'hex' + Display 'number')             │
│   Registration Fee payment (STK / Paybill 4050329 / Cash)              │
│   Status moves 'prospect' -> 'active' (Dr 1103 / Cr 4200)              │
├────────────────────────────────────────────────────────────────────────┤
│ Phase 2: Compliance Due Diligence & KYC Verification                   │
│   Document preview & fact verification rail                            │
│   Compliance approval & tier ceiling assignment (basic/std/enhanced)  │
│   Real-time Typesense search sync (live.client)                       │
├────────────────────────────────────────────────────────────────────────┤
│ Phase 3: Loan Origination & Pre-Flight Eligibility Gates               │
│   Hard pre-flight gates: Active registration + Verified KYC           │
│   Eligibility check (GET /kyc/:client/eligibility) & Collateral LTV   │
│   Product selection & instant amortization schedule preview            │
├────────────────────────────────────────────────────────────────────────┤
│ Phase 4: Multi-Tier Underwriting & Approval Hierarchy                  │
│   Loan Officer -> Branch Manager -> COO -> Managing Director           │
│   Enforced four-eyes policy & authority delegation limits             │
├────────────────────────────────────────────────────────────────────────┤
│ Phase 5: Disbursement Pipeline & Automated Accounting                  │
│   Amortization schedule generation & calendar holiday shift            │
│   Balanced GL journal: Dr 1200 / Cr 1103 / Cr 4200                     │
│   Automated Safaricom M-Pesa B2C payout                                │
├────────────────────────────────────────────────────────────────────────┤
│ Phase 6: Servicing, Repayments & Liquidation Waterfall                 │
│   C2B Paybill 4050329 with prefix stripping ('3907#')                   │
│   Waterfall: Penalties (4300) -> Fees (4200) -> Interest (4100) ->    │
│              Principal (1200) -> Savings (2200)                        │
│   Suspense ledger safety net (Dr 1103 / Cr 2105) for unmatched receipts│
├────────────────────────────────────────────────────────────────────────┤
│ Phase 7: Delinquency, Provisioning & Final Settlement                  │
│   Daily DPD aging calculation & PAR buckets                           │
│   Automated provisioning: Normal (1%), Watch (5%), Substandard (25%), │
│                           Doubtful (50%), Loss/NPA (100%)              │
│   Zero balance -> 'settled' -> Cycle increment & credit score upgrade  │
└────────────────────────────────────────────────────────────────────────┘

Master End-to-End Borrower Lifecycle Journey Map Figure 1.1: Complete borrower operational lifecycle across all 7 operational phases in BiiTrust.

Phase 1: Client Onboarding & Registration

  1. Intake: Loan Officer navigates to /clients/register and inputs:
    • Branch office and assigned loan officer.
    • Legal names, date of birth (min 18 years), gender, and mobile phone.
    • National ID number (org_clients.hex / auth_accounts.identity).
    • Physical residence address and next-of-kin contacts.
    • Digital photo portrait, ID front/back scans, and touchscreen signature.
  2. Account Creation: Submitting the form creates the client record in prospect status.
  3. Registration Fee Settlement:
    • Institutional fee (e.g., KES 300) must be paid before the client can borrow.
    • Settled via on-demand M-Pesa STK push, Paybill 4050329 with account 3907#REG-<NATIONAL_ID>, or branch counter cash.
    • General Ledger Entry: Dr 1103 (M-Pesa Float) / Cr 4200 (Fee Income).
    • Client status advances from prospect → active.

Phase 2: Compliance KYC Verification

  1. Compliance Feed: The KYC dossier appears in the compliance review queue (/kyc/feed).
  2. 3-Step Rail:
    • Step 1 (Facts): Compliance officer verifies name, National ID, phone, and PEP screening.
    • Step 2 (Documents): Inspector views each uploaded scan using the mandatory preview viewer.
    • Step 3 (Decision): Approves verification, assigns approved borrowing tier (basic up to KES 50k, standard up to KES 500k, enhanced unlimited), and sets expiration horizon.
  3. Live Search Indexing: System immediately triggers app/search/live.client to update Typesense with { verified: true, kyc: 'verified', number: 'HQ-...' }.

Client Onboarding and Real-Time KYC Compliance Verification Figure 1.2: Client profile displaying both the active registration fee badge and verified KYC tier ceiling.

Phase 3: Loan Origination & Pre-Flight Eligibility Gates

  1. Borrower Lookup: Officer opens /applications/new and searches by National ID or account number.
  2. Hard Pre-Flight Gates (Step 0):
    • Client registration must be active (Registration Fee paid).
    • Client KYC verification must be verified and unexpired.
    • If either check fails, the application is blocked with actionable links.
  3. Eligibility & Product Matching:
    • Platform calls GET /kyc/:client/eligibility?principal=&product= to confirm requested principal does not exceed tier ceiling.
    • Verifies collateral security against product max_ltv_ratio.
    • Generates instant installment schedule preview.
    • Officer attaches capacity evidence (M-Pesa 6-month statement) and submits to manager.

Phase 4: Underwriting & Approval Hierarchy

  1. Dossier Evaluation: Branch Manager opens /application/:hex/decide.
  2. Four-Eyes Enforcement: Creator cannot approve; approver of level $N$ cannot approve level $N+1$.
  3. Decision Options:
    • Approve: If within authority limit (e.g. $\le$ KES 250k), advances to approved. If exceeding limit, escalates to COO or Managing Director.
    • Return: Sends back to officer desk with mandatory correction notes.
    • Reject: Declines application with statutory grounds and formal explanation.

Phase 5: Disbursement Pipeline & Automated Accounting

  1. Disbursement Authorization: Authorized manager clicks Disburse Funds on approved application.
  2. Schedule Generation: Amortization engine (utils/amortize.js) generates binding repayment schedules, shifting holiday collisions forward.
  3. Double-Entry General Ledger Post:
    • Debit 1200: Gross Loan Portfolio Asset (Full Principal).
    • Credit 1103: M-Pesa Float Asset / Cash (Net Payout).
    • Credit 4200: Processing Fee Income (Withheld Fee).
  4. Mobile Money Payout: System automatically enqueues mpesa.b2c background job, transferring net funds directly to borrower’s phone via Safaricom Daraja API.

Phase 6: Servicing, Repayments & Liquidation Waterfall

  1. Inbound Collections:
    • Borrower pays via Paybill 4050329 with account 3907#<NATIONAL_ID>.
    • Webhook callback strips 3907# prefix and matches active loan facility.
  2. Accounting Liquidation Waterfall:
    • Priority 1: Penalties → Cr 4300 (Penalty Income)
    • Priority 2: Fees → Cr 4200 (Fee Income)
    • Priority 3: Interest → Cr 4100 (Interest Income)
    • Priority 4: Principal → Cr 1200 (Gross Loan Asset)
    • Priority 5: Surplus Overpayment → Cr 2200 (Client Savings Liability)
  3. Suspense Protection: Misspelled references are booked to Dr 1103 / Cr 2105 (Suspense) and surfaced in /payments/suspense for 1-click matching.

Phase 7: Delinquency, Provisioning & Final Settlement

  1. Nightly Delinquency Evaluation: Scheduled worker scans active loans, computing dpd (Days Past Due) and portfolio aging buckets (PAR 1, PAR 30, PAR 60, PAR 90).
  2. Loan Loss Provisioning:
    • Normal (0–30 DPD): 1% → Dr 5100 / Cr 1205
    • Watch (31–60 DPD): 5% → Dr 5100 / Cr 1205
    • Substandard (61–90 DPD): 25% → Dr 5100 / Cr 1205
    • Doubtful (91–180 DPD): 50% → Dr 5100 / Cr 1205
    • Loss / NPA (>180 DPD): 100% → Dr 5100 / Cr 1205
  3. Settlement: When all obligations reach zero:
    • Loan status transitions to settled.
    • Completed loan cycle increments (loan_cycles.number + 1), raising borrowing ladder.
    • Credit score is recomputed (POST /scores/:client/recompute), recording clean repayment history in kyc_scores.

Disbursement Payout, Repayment Waterfall Servicing, and Settlement Figure 1.3: Active loan facility view displaying the amortization repayment schedule, automated liquidation waterfall, and cycle progression.