User Manual — WatuKopesha

1. Getting Started

WatuKopesha is a complete loan management system (LMS) built for Tanzanian microfinance providers (MSPs). It has four main areas: a public website for new clients, a client portal for existing borrowers, an admin area for staff, and an owner portal for read-only oversight.

2. User Roles & Portals

Staff Roles

• Super Admin — all permissions, full system access
• Branch Manager — manages a branch, approves loans
• Loan Officer — creates applications, records repayments
• Accountant — accounting, financial reports, BoT submissions
• HR Officer — employees and payroll
• Data Entry Clerk — data entry only, no approvals

3. Logging In

Staff Login

1. Go to /admin/login.php
2. Enter username and password
3. If 2FA enabled, enter OTP sent to your phone

Client Login

1. Go to /portal/login.php
2. Enter phone number and membership number
3. Receive an OTP by SMS and verify

4. Navigation

The admin sidebar groups every module into five logical buckets:

Click a group header to expand or collapse. The group containing the current page auto-opens.

5. Borrowers

Registering a New Borrower

1. Click Borrowers → + New Borrower
2. Fill in basic info: name, phone, NIDA ID, address
3. Select branch and economic sector
4. Save — a membership number is auto-generated
5. A welcome SMS is sent automatically to the borrower

KYC (Know Your Customer)

Ensure each borrower has complete data before approving any loan: identity number, date of birth, address, and gender. Use the KYC Compliance Audit report to find gaps.

6. Groups (Solidarity Lending)

Groups enable solidarity lending where members guarantee each other. Create a group at Groups → New Group, add members, then when creating a loan choose "group loan" instead of "individual".

This module can be turned off at Settings → Modules → Group Loans.

7. Loan Products

Before lending, create loan products that define interest, term, min/max amount, and repayment cycle. Go to Loans → Products → + Add Product.

8. Loan Workflow (Application → Closure)

The full lifecycle has six stages, all visible on Loans → View loan:

1. Submitted — Loan officer creates the application
2. Under Review — Manager reviews the file
3. Approved — A loan record is created and the repayment schedule generated
4. Disbursed — Funds released via bank/M-Pesa, posted to the GL
5. Active — Borrower repays each cycle
6. Closed — Outstanding hits zero; loan is closed

Each stage triggers an automatic SMS to the borrower.

Approve or Reject

Open the application at Loans → Applications. Click "Approve" to spawn the loan, or "Reject" with a reason — the reason is sent to the borrower by SMS.

Disbursement

An approved loan sits in pending_disbursement status. Click "Disburse", pick the source account (cash/bank/M-Pesa), date and reference. The system posts the payment to the GL and sends an SMS confirming the loan amount and first installment date.

9. Repayments

Recording a Payment

1. Repayment → + New Repayment
2. Search the loan (by number or borrower name)
3. Enter amount, method (cash/bank/M-Pesa…), and the receiving account
4. Click Submit — the system allocates: penalty → fees → interest → principal
5. A receipt is generated and the borrower gets an SMS with the new balance

10. Restructure & Write-off

Restructure

When a borrower can no longer meet the schedule, change the term and/or rate. The remaining balance becomes the new principal. Go to Loan view → Restructure.

Write-off

Truly uncollectible loans are written off. The system posts the balance to bad-debt expense (5300) and reduces loans receivable (1300).

11. Savings

1. Create a savings product at Savings → Products
2. Open an account for a borrower at Savings → + New Account
3. Post deposits, withdrawals, interest credits, or fees

Every transaction sends an SMS to the customer and posts a journal entry to the GL.

12. Accounting

The accounting suite includes:

• Chart of Accounts — all GL accounts grouped by type
• Journal Entries — double-entry postings; auto-generated by loans, savings, payroll, etc.
• Trial Balance, Balance Sheet, Income Statement, Cash Flow
• Receivables & Payables — outstanding from clients and to suppliers
• Bank Reconciliation — match imported bank statements with GL

Cash/bank/M-Pesa accounts are linked to GL accounts at Accounting → Cash Accounts.

13. Fixed Assets

Register vehicles, furniture, computers, etc. under Fixed Assets. Run "Depreciation" monthly — the system reduces book value and posts depreciation expense (5200) automatically.

14. HR & Payroll

HR (Employees)

• Departments / Positions / Employees — master data
• Leave Requests / Attendance
• Staff Loans — advances to staff (separate from client loans)

Payroll

Run payroll monthly via Payroll → New Run. The system calculates PAYE, NSSF, NHIF, SDL, and WCF using current Tanzanian rates (Settings → Accounting). Pay slips are generated per employee and can be printed.

Statutory reports available: PAYE Report, NSSF Report, NHIF Report, SDL/WCF Report, Statutory Tax Summary.

15. Inventory

Track office supplies (stationery, IT consumables, branded merchandise). Configure warehouses, categories, items. The system tracks current quantities and every movement.

16. Procurement

Full procure-to-pay flow:

1. Suppliers — register vendors
2. Purchase Requisition (PR) — department request
3. Purchase Order (PO) — after approval
4. Goods Received Note (GRN) — receive delivery
5. Supplier Invoice — log the invoice
6. Supplier Payment — pay from any cash/bank account

17. Complaints

Log client complaints received by phone, email, in-person, or through the portal. This feeds the BoT MSP2-06 quarterly return automatically.

18. Reports & Analytics

A library of 100+ reports across 10 categories:

• Loan Reports (35) — active, arrears, PAR, top borrowers, sector breakdown, etc.
• Repayment Reports (10) — daily/weekly/by-method collections, voided, day-of-week patterns
• Savings (10), Borrowers (10), Financial Statements (13)
• HR & Payroll (9), Fixed Assets (5), Inventory & Procurement (7)
• Regulatory & Compliance (6), Operational (6)

Analytics — a separate page with 12 trend charts for executive insight.

19. 🤖 AI Skilled Agents

The system ships with 60 OpenAI-powered assistants: 40 for admin staff and 20 for the owner. Each one reads MFI data straight from the database, then produces expert-level analysis — from scoring a borrower to drafting the next BoT MSP2 return.

Initial setup

1. Get an OpenAI API key from platform.openai.com/api-keys
2. Open Settings → AI
3. Paste the key, pick a model (recommended: gpt-4o-mini), click Save

Pricing (Tsh)

AI usage is billed in credits on a flat per-credit rate:

Token usage is shown below every AI result and is recorded in the Audit Log so admins can track spend per user, per day, per agent.

Admin agents — 40 (/admin/ai/)

Owner agents — 20 (/owner/ai/)

How to run an agent

1. Go to Insights → 🤖 AI Assistants (or Owner → 🤖 AI)
2. Click the card of the agent you want
3. Fill the form — most agents use search dropdowns (type a borrower name, loan number, etc.)
4. Click ▶ Run agent
5. Result appears within 2-5 seconds on the right side

🔒 Privacy & Security

• API key stored in DB, never written to logs or audit trail (recorded as ••• redacted •••)
• OpenAI does not train models on data sent via the API (per their data-policy)
• Every agent run is logged in the Audit Log (token count only, never the prompt content)
• To disable AI: clear the OPENAI_API_KEY field in Settings → AI

Disclaimer

AI suggestions are guidance, not final decisions. A human MFI staffer must always verify before taking a financial action (approving a loan, writing off debt, etc.). The model computes from your data; verification is your responsibility.

20. BoT MSP2 Quarterly Return

This is the regulatory return submitted to the Bank of Tanzania every quarter. It contains 10 sections:

1. Go to Reports → BoT MSP2
2. Select the year and quarter
3. Review the figures — they're computed from the GL and loan tables
4. Click "Export CSV" to feed into the official BoT spreadsheet
5. Click "Save snapshot" to archive the values for internal audit

21. SMS & Reminders

SMS notifications fire automatically on these events:

For reminders to fire, add a daily cPanel cron at 9 AM running cron/sms_reminders.php.

To silence all notifications (e.g. testing), set setting('sms_notifications_enabled') = '0'.

Pricing

SMS volume and cost are visible at Reports → Operational → SMS Outbox.

22. 📲 Install as an App (PWA)

All three surfaces — Admin, Client Portal, and Owner Portal — can be installed as an "app" on a phone, tablet or desktop. They use Progressive Web App (PWA) technology: no Play Store or App Store needed, and they continue to work even when offline.

What you get

• Icon on the home screen (mobile) or desktop / Start menu (computer)
• Opens without a browser bar — looks and feels like a native app
• Faster (CSS/JS assets are cached locally)
• Shows a friendly offline page when the connection drops
• Mobile bottom navigation with icons (Home, Loans, Statement, Profile)
• Long-press shortcuts on the icon (e.g. "+ New Loan", "+ Repayment", "AI Assistants")

What installs where

How to install — Chrome (Desktop)

1. Open the surface you want in Chrome (e.g. https://hbs.watukopesha.com/admin/)
2. Look at the right side of the address bar — you'll see a 📲 install icon (or open the 3-dot menu → "Install [App name]")
3. Or click the 📲 Install button at the top-right of the admin bar
4. Confirm "Install" in the dialog
5. The app appears in your Start Menu / Dock — opens without a browser bar

How to install — Android (Chrome)

1. Open https://hbs.watukopesha.com/portal/ in Chrome on your phone
2. Tap the floating "📲 Install App" button at the bottom-right, OR open the 3-dot menu → "Add to Home screen"
3. The icon appears on your home screen — tap to launch

How to install — iPhone / iPad (Safari)

1. Open the surface in Safari (not Chrome — iOS only allows Safari to install PWAs)
2. Tap the Share button ⎋ at the bottom-center
3. Tap "Add to Home Screen"
4. Give it a name (e.g. "WK Client") and tap "Add"

Mobile Bottom Navigation

The Client Portal and Owner Portal show an icon-based bottom navigation bar on phones and tablets (under 1024px wide). It's hidden on large desktop screens where the top nav is enough.

Offline Mode

When the connection drops, the app shows a friendly offline page (portal/offline.html / owner/offline.html / admin/offline.html). The service worker caches CSS, JS, and logos so the app loads instantly even on weak 3G.

📲 Shortcuts (Long-press the icon)

After installing, long-press the app icon to jump straight into common actions:

23. Client Portal

Borrowers can log in to /portal/ to see:

• All their loans (active, closed)
• Outstanding balance and next payment due
• Repayment statement
• Their profile

New clients can self-register at /portal/register.php — a 4-step mobile-friendly form.

24. System Administration

Settings

These tabs live under Settings:

• Company — Name, address, phone, TIN, MSP code, and logo upload
• Currency — Currency, timezone, default locale
• Modules — Toggle features on/off
• SMS — Provider, sender ID, simulate mode
• Security — Session timeouts, lockout policy, OTP length
• Numbering — Prefixes for loan #, receipt #, etc.
• Accounting — Fiscal year, statutory rates (PAYE/NSSF/NHIF/SDL/WCF)
• Theme — Pick from 20 color palettes for the public site + portal

Users & Roles

Create users at Users → + New User. Each user has a role that determines their permissions. Edit roles and toggle individual permissions at Users → Roles.

Audit Log

Every important action (logins, loan approvals, user creations, etc.) is recorded to the Audit Log and is searchable by user, action, or date.

25. Security

• Passwords must be at least 8 characters (configurable)
• Accounts auto-lock after 5 failed attempts
• 2FA via phone OTP can be enforced
• All data flows over HTTPS in production
• Database is backed up daily by cPanel

26. Glossary

27. Troubleshooting

Cannot log in

Verify the username is correct. The account may be locked — check the Failed Login Attempts report or ask an admin to unlock.

SMS not being sent

• Verify Settings → SMS → Provider = "Wanzago" (not "log")
• Verify SMS_USER + SMS_PASS in .env are correct
• Check SMS Outbox for the error reason

Reports show Tsh 0 everywhere

Reports compute from the GL. Make sure journal entries exist — they're auto-created by every disbursement, repayment, and savings transaction. For demo data, import bot_demo_data.sql.

PAR > 30 is unrealistically high

Usually a demo-data artifact. In production with current activity, 2-7% is typical. Remove demo_data.sql before going live.