# Microfinance Management System

A Laravel 12 application for managing microfinance operations including branches, staff, customers, loan products, collateral, loan applications, approvals, repayment schedules, collections, penalties, write-offs, expenses, fixed assets, accounting, financial reporting, and management workflows.

## Requirements

- PHP 8.2+
- Composer
- Node.js 22.16.0 for the locked frontend build (`.nvmrc`)
- npm with the committed `package-lock.json`
- SQLite for quick local setup, or MySQL/MariaDB for production

## Installation

```bash
git clone https://github.com/skymantz10/microfinance.git
cd microfinance
composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
npm ci
npm run build
php artisan serve
```

The application will be available at `http://127.0.0.1:8000` by default.

`package-lock.json` is committed and is the dependency-resolution source of truth. Use `npm ci` for clean development, CI, staging, and production builds. Change frontend dependency declarations deliberately and commit the resulting lockfile change in the same pull request.

## Product specification and roadmap

- `MICROFINANCE_SPEC.md` — authoritative product specification.
- `MICROFINANCE_DEVELOPMENT_PROMPTS.md` — primary step-by-step development roadmap.
- `MICROFINANCE_MODULE_ROADMAP.md` — normative roadmap extension for configurable modules, including Fixed Assets and advanced Financial Reports.
- `docs/BRANCH_ISOLATION_PLAN.md` — original branch-isolation design and phased implementation plan.
- `docs/BRANCH_ISOLATION_COMPLETION.md` — implemented branch-isolation end state and regression guarantees.
- `docs/PRODUCTION_READINESS_CHECKLIST.md` — environment, deployment, backup/restore, provider, monitoring, and go-live checklist.
- `docs/DATABASE_PERFORMANCE.md` — reporting-index, slow-query logging, MySQL EXPLAIN, and production-like performance observation runbook.
- `deploy/README.md` — Ubuntu/Nginx/PHP-FPM/Supervisor deployment, release verification, smoke-check, restore-drill, and rollback runbook.

## Stack

- Laravel 12
- PHP 8.2+
- Vite
- Tailwind CSS

## Development

```bash
composer run dev
```

## Testing

```bash
php artisan test
```

## Production readiness

Start from `.env.production.example`, replace all placeholders on the target server, then run the blocking configuration gate before deployment:

```bash
php artisan production:check
```

The command rejects unsafe production defaults such as debug mode, non-HTTPS application URLs, SQLite, sync queues, insecure session cookies, and backup paths exposed under the public web root. Runtime/provider items that require infrastructure verification remain warnings or checklist items.

After production migrations, verify the reporting indexes and capture representative MySQL query plans:

```bash
php artisan database:performance-check --json --explain
```

Production enables privacy-safe slow-query logging through `DB_SLOW_QUERY_MS`; query bindings are not logged. Use `docs/DATABASE_PERFORMANCE.md` for the staging/production-like observation procedure.

After the queue worker and scheduler are running and a verified pre-release backup exists, the final internal acceptance gate is:

```bash
RELEASE_GIT_SHA="$(git rev-parse HEAD)" php artisan release:verify --require-backup
```

`release:verify` proves database/queue/scheduler runtime health, executes a real queued probe, verifies the latest backup, and writes a non-secret release manifest tied to the deployed Git SHA. External HTTPS smoke checks and the guarded isolated MySQL restore drill are maintained under `deploy/scripts/` and documented in `deploy/README.md`.

The Laravel health endpoint is available at `/up`.
