System Administrator Guide

As a System Administrator, you ensure the operational readiness, security, and stability of the BiiTrust platform. You manage institutional infrastructure, onboard staff, grant branch access permissions, configure credit products and interest rates, and oversee background processing pipelines.

1. The Administrator Dashboard

Your dashboard (<admin-home>) provides deep visibility into platform operations:

Service Health & Pipeline Gauge

  • Big Number: Number of core platform services currently reporting online and healthy (e.g., 4/4).
  • Nightly Pipeline Pill:
    • Finished X ago (Green): The automated nightly batch run completed cleanly.
    • Failed / Ended X (Red): The nightly run encountered a blocking error and requires investigation.
    • Nightly not run (Red): The cron scheduler did not fire.

Quick Action Buttons

  1. Run (/jobs/pipeline/run): Manually trigger the nightly batch pipeline or run individual stages.
  2. Due (/schedules): Inspect scheduled installments across the entire institution.
  3. Staff (/staff): Manage staff profiles, branch assignments, and role credentials.

Platform Health Metrics

  • Services Up: Live health check of the four foundational services:
    • Database: PostgreSQL connection pool and migration status.
    • Redis: Valkey/Redis cache and BullMQ background queue store.
    • Mail: Outbound SMTP/SES transactional email gateway.
    • SMS: Telecom SMS provider connection for borrower alerts.
  • Failed Jobs: Background worker jobs that encountered unhandled exceptions and await retry.
  • Messages Sent: Delivery count of customer communications (SMS and email).
  • Accounts: Total active staff and client accounts registered on the platform.

Diagnostic Panels

  • Service Health Matrix: Real-time status pills (Online, Unavailable, Needs setup) for each connected service.
  • Last Nightly Run Stepper: A step-by-step breakdown of the previous midnight pipeline execution:
    • Interest accruals.
    • Days Past Due (DPD) recomputation.
    • Overdue penalty assessments.
    • Delinquency band updates.
    • Loan loss provision journals.
    • Non-performing asset (NPA) classifications.
    • Standing instruction auto-debit triggers.
    • Expiring document alerts.
    • Daily statistical snapshot generation.
  • Queue Monitor: Queue depth and failure rates across mail, sms, mpesa, and nightly queues.
  • Recent Data Imports: Status of bulk batch files (e.g., legacy portfolio migrations or bulk loan uploads).
  • Administrator Position Print: Download Morning_Position_Admin.pdf for technical compliance reports.

Bottom Work Feeds

  • Failed jobs: Filtered list of faulted background jobs with error stack traces and one-click retry buttons.
  • All jobs: Real-time log of worker job executions.
  • Imports: Batch data file ingestion pipeline status.
  • Audit trail: Global security and operational event log.

2. Core Administrative Workflows

Onboarding Staff & Granting Access

  1. Create Staff Profile (/staff/new):
    • Enter full legal name, national ID, official phone number, and work email.
    • Assign initial home branch.
  2. Grant Role Access (/access/new):
    • Select the staff account.
    • Choose their operational role: officer, teller, manager, director, accountant, compliance, or admin.
    • Specify the Branch Scope:
      • For branch staff (officer, teller, manager): Select their specific branch. They will only be able to view and manage data belonging to that branch.
      • For executive staff (director, accountant, compliance, admin): Leave branch unassigned (All Branches), granting institution-wide visibility.
  3. Revoking Access (/access/:hex/revoke):
    • When an employee departs or transfers, immediately revoke their active role access. The change takes effect within 60 seconds without requiring a server reboot.

Configuring Credit Products (/products/new)

To launch a new lending product for your branches:

  1. Open Products (/products).
  2. Enter the Product Name (e.g., SME Business Advance).
  3. Choose the Interest Method:
    • Flat: Simple flat rate distributed equally across all installments.
    • Declining Balance: Standard reducing balance amortization where interest is calculated on remaining principal.
  4. Set the Rate Kind: Fixed annual percentage or Floating spread tied to a central bank benchmark rate.
  5. Set the Repayment Interval: daily, weekly, biweekly, monthly, quarterly, or once.
  6. Define Grace Periods: Days before principal or interest repayments begin.
  7. Configure Penalty Rules: Daily late penalty rate and grace days before the penalty begins accruing.
  8. Set Processing Fees: Flat fee plus percentage of principal deducted at disbursement.
  9. Define Eligibility Rules: Minimum and maximum loan ceilings, minimum required KYC tier, and mandatory collateral requirements.

Managing Approval Authority Limits (/settings/authority)

Configure institutional credit delegation bands:

  • Officer Band: Typically KES 0 to KES 50,000 (auto-approves upon officer submission).
  • Branch Manager Band: Typically KES 50,000 to KES 500,000 (requires Level 2 manager signoff).
  • Director Band: Above KES 500,000 (requires Level 3 executive signoff).
  • You can configure custom overrides for specific branches based on their historical loss ratios and manager experience.

Auditing the System (/audits)

To investigate any administrative, operational, or financial change:

  1. Open Audit Trail (/audits).
  2. Search by:
    • Actor: Specific staff member who performed the action.
    • Entity: org.clients, loan.loans, loan.approvals, finance.payments, gl.journals.
    • Action: create, update, approve, disburse, reverse, waive.
    • Date Range: Filter by day or month.
  3. Inspect the Before and After data snapshots to see the exact fields altered.
  4. Export the filtered log to CSV for external auditors.