System Terms & Security Architecture

This chapter defines the system architecture, entity identifiers, security tiers, and role permissions governing the BiiTrust core banking platform.

1. Hexadecimal Entity Identifiers

Every record created across BiiTrust is assigned an immutable, collision-resistant 15-character uppercase hexadecimal identifier. The first three letters denote the operational domain, followed by 12 pseudo-random uppercase hex characters:

Hex Prefix	Domain Name	Database Table	Purpose & Description
`CLX…`	Clients	`org.clients`	Individual or business borrower records and profiles.
`LOX…`	Loans	`loan.loans`	Active, closed, or written-off credit facilities.
`APX…`	Applications	`loan.applications`	Credit origination requests undergoing underwriting.
`PMX…`	Payments	`loan.payments`	Inbound cash, bank, or M-Pesa repayment transactions.
`BRX…`	Branches	`org.branches`	Physical branch offices and regional hubs.
`STF…`	Staff	`org.staff`	Employee identity records, system users, and officers.
`ACX…`	Accounts	`gl.accounts`	General Ledger chart of accounts and sub-accounts.
`COL…`	Collateral	`loan.collaterals`	Physical pledged assets, logbooks, and chattel liens.
`DOC…`	Documents	`org.documents`	Uploaded KYC files, National ID scans, and contracts.
`MAN…`	Mandates	`loan.mandates`	Standing orders, direct debit mandates, and group guarantees.
`PRD…`	Products	`loan.products`	Loan product configurations, rates, tenors, and calculation rules.
`AUD…`	Audits	`sys.audits`	Immutable security audit logs recording every action, IP, and payload.
`CMS…`	Comms	`sys.comms`	Outbound SMS notifications, email statements, and delivery states.

Hex Resolution Rules

Case Insensitive in Search: Searching clx936 or CLX936 immediately resolves to the target client.
Universal Links: Typing or clicking any hex code across the UI navigates directly to that entity’s profile page (e.g., clicking LOX44A1B903 opens the loan ledger).

2. Client Onboarding Tiers

To comply with statutory Anti-Money Laundering (AML) and Proceeds of Crime regulations while ensuring financial inclusion, BiiTrust structures customer profiles into three progressive tiers:

Tier	Required Credentials	Maximum Credit Ceiling	Verification Level
`basic`	Mobile phone number, self-declared name, National ID number.	KES 25,000	Automated SMS OTP verification. Prospect status.
`standard`	Verified original National ID card scan, passport portrait, physical residence details, next of kin.	KES 250,000	Reviewed and approved by Compliance Officer.
`enhanced`	KRA Tax PIN Certificate, 6 months bank/M-Pesa statements, utility bill, business registration / permit.	Unlimited (Up to product maximum)	Full Enhanced Due Diligence (EDD), field visit verification, and Credit Committee clearance.

3. Entity Lifecycle States

Client States

prospect: Registered prospect; KYC incomplete; cannot borrow.
active: Fully verified KYC; eligible for loan origination.
dormant: No transactions or active credit facilities in 180+ days.
blacklisted: Barred from future lending due to fraud, forgery, or malicious default.
exited: Formally closed membership; all liabilities discharged.

Application Stages

draft: Created by Loan Officer; pending document attachment or guarantor assignment.
submitted: Forwarded to Branch Manager or Credit Committee queue for review.
appraised: Credit evaluation, affordability scoring, and field visit report completed.
approved: Formally authorized for funding; awaiting borrower acceptance and disbursement.
rejected: Application denied; reason documented and archived in audit trail.
disbursed: Funds released to borrower’s account/phone; converted into active LOX loan.

Loan States

pending: Approved but funds not yet transferred.
active: Disbursed and currently amortizing according to schedule.
closed: Outstanding balance reaches exactly KES 0.00; collateral released.
rescheduled: Original facility superseded by restructured terms.
written_off: Uncollectible debt removed from balance sheet; recovery ongoing.

4. Cryptographic Scoped Search Keys

BiiTrust uses an enterprise search security model powered by Typesense Scoped Search Keys. Rather than relying on client-side filtering or slow SQL database scans, the system validates user permissions cryptographically:

Session-Driven Identity: When an employee signs into the web application, their JWT session establishes their Role, Staff Identity (identity), and Assigned Branch (branch).
Cryptographic Signing (HMAC-SHA256): The backend generates an ephemeral, short-lived search key embedded with non-negotiable security filters:
- For an Officer: branch:=[BRX1001] && officer:=805303613
- For a Branch Manager: branch:=[BRX1001]
- For an Executive Director / Admin: branch:=* (no isolation)
Hardware-Enforced Isolation: The search engine validates the HMAC signature before executing any query. Even if a user attempts to manually forge a search query, Typesense physically restricts the search results to records matching their signed token.
Sensitive Field Masking: Scoped keys automatically strip protected fields (password, pin, risk_score, national_id_raw) from search results before network transmission.

5. Role Hierarchy & Operational Privileges

System Role	Scope of Access	Core Responsibilities	Gated Actions
`owner` / `admin`	Organization-wide	System health, staff onboarding, branch creation, product setup, database sync.	Can manage all configurations, credentials, and settings.
`director`	Organization-wide	High-value loan approvals ($\ge \text{KES } 500,000$), write-offs, financial statements.	Cannot disburse cash directly across a branch counter.
`manager`	Single Branch	Operational oversight, staff management, loan approvals ($< \text{KES } 500,000$), rescheduling.	Confined strictly to branch loans, clients, and cash drawers.
`officer`	Own Portfolio Book	Client prospecting, loan application origination, group collection sheets.	Confined strictly to assigned clients; cannot approve loans.
`teller`	Branch Cash Counter	Cash receipts, manual M-Pesa entry, STK pushes, cash drawer balancing.	Cannot originate loans or alter repayment schedules.
`accountant`	General Ledger	Chart of accounts, journal entries, bank reconciliations, fiscal closures.	Cannot approve credit or originate borrower files.
`compliance`	Risk & Legal	KYC document verification, sanction checks, CRB reporting, AML audit.	Independent oversight; cannot handle cash or approve loans.
`auditor`	Read-only Org-wide	Inspection of audit trails (`AUD`), general ledger balances, and portfolio health.	Read-only across all modules; cannot perform updates.

BiiTrust User Manual