Clients & Customer 360

The Clients module (/clients) manages the borrower directory of BiiTrust. It unites personal identity records, credit history, risk ratings, guarantor networks, and account notes into a single unified Customer 360 profile.

1. Key Definitions & Financial Terms

• Borrower / Client (CLX...): The primary legal counterparty entering into a credit contract with BiiTrust. Identified by a unique 15-character hex string (e.g., CLX936F7448BDB3) and an 8-digit client account number.
• KYC (Know Your Customer): The statutory diligence process mandated by banking and anti-money laundering regulations to establish identity, physical residence, and economic activity.
• KYC Tiers:
  • basic: Self-declared identity and mobile phone number verified via SMS OTP. Max lending ceiling: KES 25,000.
  • standard: Physical inspection and upload of original National ID card scan and facial photograph. Max lending ceiling: KES 250,000.
  • enhanced: Full documentary verification including KRA Tax PIN, verified residence utility bill, 6 months M-Pesa/bank statements, and business trade license. Unlocks facilities above KES 250,000.
• Social Collateral & Cross-Guarantees: A microfinance security structure where fellow community or group members legally co-sign and pledge joint liability for an individual’s debt obligations.
• Credit Exposure: Total active principal, accrued interest, fees, and penalties owed by the client across all active facilities.
• Risk Rating: An algorithmic classification (Low, Medium, High, Critical) derived from historical DPD, repayment consistency, and debt-to-income ratio.

2. Navigating the Client Directory

Accessing the Module

• Desktop Sidebar: Click Clients in the left navigation panel (/clients).
• Mobile Bottom Navigation: Tap the Clients icon in the dock.
• Keyboard Shortcut: Press Cmd + K (Mac) or Ctrl + K (Windows) $\to$ Type client: or @ followed by the borrower’s name or national ID.

Directory Views & Filter Chips

The top filter bar provides immediate segmentation across the portfolio:

• Search Box: Type name, phone (07... or 254...), national ID, or hex code. Powered by real-time prefix search ($< 2\text{ms}$).
• Status Filter Chips:
  • All: Complete borrower register.
  • Active: Clients currently servicing one or more live loans.
  • Prospect: Newly registered clients who have not yet originated a loan.
  • Dormant: Historical borrowers with zero active loans.
  • Delinquent: Borrowers currently carrying an overdue installment ($\text{DPD} > 0$).
• Tier Filter Chips: Toggle between Basic, Standard, and Enhanced.
• Branch / Officer Dropdown: For managers and directors, filter by specific operational branch or loan officer book.

3. Client Card Anatomy

Every borrower in list feeds appears in a standardized, high-density card container:

┌────────────────────────────────────────────────────────────────────────┐
│ ● CLX881149919  Grace Wanjiru                     Joined 12 Sep 2026   │
│                                            [ACTIVE] [BASIC TIER]       │
├ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -┤
│ [Avatar]  Grace Wanjiru                                                │
│   (✓)     0712 345 678  •  ID: 29841029                                │
│           Nairobi Central  •  Officer: Peter Kamau                     │
│                                                                        │
│   ┌──────────────────┬──────────────────┬──────────────────┐           │
│   │ OUTSTANDING      │ ACTIVE LOANS     │ KYC TIER         │           │
│   │ KES 35,000       │ 1 loan           │ Basic            │           │
│   └──────────────────┴──────────────────┴──────────────────┘           │
├ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -┤
│                                            [ Note ]  [ Link ]  [ View ]│
│ *(On overdue loans, [ Repay ] replaces [ Link ] on teller screens)*   │
└────────────────────────────────────────────────────────────────────────┘

Key Elements of the Client Card

1. Status Indicator Dot & Reference Number:
   • Green Dot: Active borrower in good standing.
   • Amber Dot: Prospect (registered, but has not taken a loan yet).
   • Red Dot: Defaulter, exited client, or blacklisted individual.
   • Client Number: Monospace code (e.g., #CLX881149919) used on all paper forms.
2. Identity Line:
   • Borrower’s full legal name.
   • Phone number and National ID badge.
   • Home branch and assigned loan officer.
   • Verified checkmark badge over avatar if KYC has been verified by compliance.
3. Metrics Grid:
   • Outstanding: Total active debt (principal, interest, fees). Highlighted in amber/red if debt is overdue.
   • Active Loans: Count of open credit lines.
   • KYC Tier: basic (up to KES 25k), standard (up to KES 250k), or enhanced (unlimited).
4. The Strict 3-Action Bar:
   • View (Accent): Navigates to the borrower’s full Customer 360 profile (/client/:hex).
   • Link (Warn): Opens the guarantor and social connection tool (<link-popup>).
   • Note (Gray): Opens a quick case note window to log phone conversations or field visit remarks.
   • (On teller screens when debt is overdue, Repay takes the place of Link).

4. Borrower Status Lifecycle

Borrower accounts progress through distinct operational stages:

5. Customer 360 Profile (/client/:hex)

Clicking View opens the full borrower profile organized into dedicated working tabs:

1. Overview Tab

• Header Card: Photo, legal name, client account number, verified badge, home branch, and loan officer.
• Financial Scorecard:
  • Lifetime Borrowed: Cumulative principal disbursed across all loans.
  • Lifetime Repaid: Total cash and M-Pesa collected.
  • Current Active Debt: Total balance outstanding.
  • Repayment Score: Percentage of installments settled on or before due date.
• Quick Action Row:
  • New Loan (/applications/new?client=CLX...): Launches the loan origination rail.
  • Take Repayment (/loan/:hex/repay): Opens cashier collection interface.
  • Upload KYC (/kyc/:hex/submit): Add ID scans, tax certificates, or contracts.

2. Loans Tab

Chronological listing of every credit facility ever granted to the borrower:

• Displays loan hex (LOX...), product name, principal, interest rate, issue date, maturity date, balance, and status badge (active, closed, rescheduled, written_off).
• Clicking any loan opens its full installment ledger and repayment schedule.

3. KYC Documents Tab

• Displays all archived files in the client’s electronic file cabinet (org.documents).
• Categorized by kind: national_id_front, national_id_back, portrait, utility_bill, business_permit, signed_contract.
• Each document displays upload timestamp, verifying compliance officer, and document preview thumbnail.

4. Collateral & Security Tab

• Lists all physical, chattel, or cash assets pledged by or behind this client (loan.collaterals).
• Displays description, asset kind, Open Market Value (OMV), Forced Sale Value (FSV), and custody status (held, pledged, released, liquidated).

5. Social Network & Guarantors Tab

• Guaranteed By: People who have pledged social collateral or assets backing this borrower’s facilities.
• Guaranteeing For: Other borrowers whose loans this client has co-signed.
• Risk Guard: If a borrower attempts to exit or clear their account while co-guaranteeing a delinquent loan, the system blocks clearance until the guaranteed debt is cured.

6. Activity & Case Notes Tab

• An append-only, immutable chronological timeline logging:
  • Phone call notes from collection officers.
  • Physical address verification visits.
  • KYC verification decisions and tier upgrades.
  • Loan officer book reassignments.
  • SMS reminders dispatched and delivery receipts.

6. Common Client Workflows

How to Add a Customer Case Note

1. On the client card or profile header, click Note.
2. Type your remark (e.g., “Visited borrower’s grocery shop in Westlands. Business running well; promised to clear installment #3 via M-Pesa today by 4 PM.”).
3. Select Note Tag: Collection, Field Visit, Inquiry, KYC, or Promise to Pay.
4. Click Save Note. The entry stamps into sys.audits with your staff ID and timestamp.

How to Link a Guarantor

1. Click Link on the client card or profile.
2. In the popup modal, search for the guarantor by name or national ID.
3. Select Relationship: Spouse, Business Partner, Parent, Sibling, Group Member, or Employer.
4. Enter Pledged Guarantee Amount (KES).
5. Click Establish Link.