# NewKipp Microfinance Solution

A Laravel 12 multi-tenant SaaS Microfinance Management System optimized for MySQL and Namecheap/cPanel shared hosting.

## Built In

- Central super admin panel for tenant approvals, plans, billing, revenue, support tickets, and settings.
- Tenant dashboards with isolated members, KYC, savings, loans, repayments, accounting, reports, staff, branches, member notifications, settings, alerts, and support.
- Branded public tenant links at `/t/{tenant-slug}` where members can sign up, log in, save, apply for loans, view schedules, and repay loans.
- Role-based access for Super Admin, Tenant Admin, Manager, Loan Officer, Accountant, and Member.
- Dedicated virtual account support for member savings deposits, including tenant gateway setup and webhook-based crediting.
- Tenant Data Import for existing microfinance companies using CSV templates for branches, members, savings accounts, savings transactions, loans, and loan payments.
- Offline/online Sync Center for XAMPP or branch-office installations to export JSON packages, import packages into the hosted copy, or push directly to an online receiver token.
- Member KYC includes middle name, DOB-based age display, BVN, NIN, masked identity display, and automatic KYC verification when required identity data is complete.
- Tenant payment gateway choices include Paystack, Monnify, Flutterwave, Providus Bank, and Wema Bank. Hosted checkout is wired for Paystack, Monnify, and Flutterwave; direct bank adapters store credentials for bank-issued integrations.
- Single MySQL database tenancy using `tenant_id` scoped models and tenant-active middleware.
- SaaS billing with 14-day automatic trials, plan limits, manual payment proof uploads, gateway checkout, approval workflow, subscription expiry, auto-renewal settings, and invoice records.
- Loan workflow: application, approval, rejection, disbursement, flat-interest schedule generation, penalties, partial repayments, and receipts.
- Accounting: chart of accounts, ledger entries, cashbook, income, expenses, trial balance, and profit/loss.
- PDF report export using DOMPDF. No browser automation or Node build is needed in production.
- Bootstrap 5 Blade UI with no Vite build requirement.
- Merchant portal for onboarding and referral partners, with merchant self-signup, personalized landing pages, tenant assignment, onboarding commission, referral commission, and commission payout tracking.
- Installable PWA mobile app shell with manifest, service worker, offline screen, browser-aware install prompt/help modal, slide-out menu, and phone bottom navigation.

## Local Setup

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate:fresh --seed
php artisan serve
```

Default seeded users:

- Super Admin: `admin@microfinance.test` / `password`
- Tenant Admin: `owner@demo.test` / `password`
- Manager: `manager@demo.test` / `password`
- Loan Officer: `loan@demo.test` / `password`
- Accountant: `accountant@demo.test` / `password`
- Merchant: `agent@microfinance.test` / `password`

## Shared Hosting Install

Use [deployment/namecheap-cpanel.md](deployment/namecheap-cpanel.md).

For no-terminal deployment:

1. Upload the prepared app folder with `vendor`.
2. Configure `.env`.
3. Import [database/database.sql](database/database.sql) through phpMyAdmin.
4. Point your domain to `public`, or use [deployment/public_html-index.php](deployment/public_html-index.php).

## Important Paths

- Routes: `routes/web.php`
- User manual: `USER_MANUAL.md`, `/user-manual`, guided `/video-manual`, and `/mobile-app`
- Migrations: `database/migrations`
- Seed data: `database/seeders/DatabaseSeeder.php`
- SQL import: `database/database.sql`
- Models: `app/Models`
- Controllers: `app/Http/Controllers`
- Tenant isolation: `app/Models/Concerns/BelongsToTenant.php`
- Middleware: `app/Http/Middleware`
- Services: `app/Services`
- Blade views: `resources/views`

## Production Notes

- Use PHP 8.2+ and MySQL 5.7+/8.0.
- Use `SESSION_DRIVER=file`, `CACHE_STORE=file`, and `QUEUE_CONNECTION=sync` on shared hosting.
- Keep `.env` and application source outside `public_html` when possible.
- Only `public`, or copied public assets plus `deployment/public_html-index.php`, should be web-accessible.
- Change the seeded super admin password immediately after import.
- Configure email, SMS, WhatsApp, and Paystack from Super Admin > Settings after login. Tenants can also configure their own email, SMS, WhatsApp, and payment gateway from Company Settings. `.env` is now only a fallback for first install defaults.
- Existing companies can start from Tenant Settings > Data Import. Download the CSV template for each data type, import branches first, then members, savings/loan accounts, and finally transaction/payment history.
- Offline branches can use Tenant Settings > Sync Center. Create a receiver token on the online copy, paste the online URL and token into the offline copy, then use Push to online now. Manual export/import works when outbound HTTP is unavailable.
- Merchants can register from `/merchants/register`, get personalized onboarding/referral links, and earn the commission rate assigned by Super Admin.
- For member virtual accounts, enable Paystack in Tenant Settings > Payment Gateway, add the tenant Paystack secret key, optionally set a preferred bank slug such as `wema-bank` or `titan-paystack`, and copy the displayed Paystack webhook URL into the Paystack dashboard.
- Monnify reserved virtual accounts require API key, secret key, contract code, and a member BVN or NIN. Providus/Wema direct bank integrations require credentials and endpoint documentation issued by the bank.
- For online payments and automatic subscription renewal, store only gateway references or bank mandate references. Enable Paystack in Settings, then run `php artisan billing:process-auto-renewals` from cPanel Cron.
- Super Admin > Settings > Homepage edits the public SaaS homepage. Super Admin > Settings > Auto Notifications controls email, SMS, WhatsApp, and system alerts for tenant registration, payments, trial reminders, and overdue reminders.
- Run `php artisan notifications:tenant-lifecycle-reminders` daily from cPanel Cron to send trial reminders every 3 days and overdue reminders weekly.
- Run `php artisan notifications:member-reminders` daily from cPanel Cron to send tenant-controlled member reminders for due loans, overdue loans, savings contributions, savings maturity, investment maturity, and pending KYC.

## Mobile App / PWA

The first mobile version is included as an installable Progressive Web App:

- Manifest: `public/manifest.webmanifest`
- Service worker: `public/sw.js`
- Offline page: `public/offline.html`
- App icons: `public/pwa/icon.svg` and `public/pwa/maskable-icon.svg`
- Mobile behavior script: `public/js/pwa.js`

After hosting with HTTPS, Android users can open the site in Chrome and choose **Install app** or **Add to Home screen**. The same web app can later be wrapped with Capacitor for Play Store distribution.
