# Production Readiness Checklist

This checklist is the handoff after application implementation, branch isolation, the security/backup review, and the complete integration workflow. It separates production environment work from code correctness already covered by automated tests.

## 1. Production Environment

- [ ] Set `APP_ENV=production`.
- [ ] Generate and securely retain the production `APP_KEY`.
- [ ] Set `APP_DEBUG=false`.
- [ ] Set the final HTTPS `APP_URL`.
- [ ] Keep `APP_TIMEZONE=Africa/Dar_es_Salaam` unless the business explicitly changes its operating timezone.
- [ ] Set `LOG_LEVEL` appropriate for production and configure log retention/rotation.
- [ ] Use production MySQL/MariaDB credentials; do not retain the local SQLite default.
- [ ] Use a dedicated least-privilege database user for the application.

## 2. HTTPS, Sessions, and Web Server

- [ ] Terminate HTTPS with a valid certificate and redirect HTTP to HTTPS.
- [ ] Set `SESSION_SECURE_COOKIE=true` under HTTPS.
- [ ] Keep `SESSION_HTTP_ONLY=true`.
- [ ] Keep the strict SameSite policy unless a documented integration requires another value.
- [ ] Verify Nginx/Apache serves only the Laravel `public` directory.
- [ ] Ensure `.env`, `storage/app/private`, backups, logs, and source files cannot be served directly.
- [ ] Set correct ownership/permissions for `storage` and `bootstrap/cache` without making the whole application writable.

## 3. Database and Migrations

- [ ] Take a pre-deployment database backup.
- [ ] Run production migrations with the application in an appropriate maintenance/deployment window.
- [ ] Run `php artisan branches:repair-user-assignments --dry-run` and review the report.
- [ ] Run `php artisan branches:repair-user-assignments` if the dry run reports legacy inconsistencies.
- [ ] Confirm the primary branch and `branch_user` pivot are consistent for all production staff.
- [ ] Confirm database charset/collation, timezone behavior, and backup credentials on the production server.

## 4. Queues and Scheduler

The repository uses the database queue by default and contains scheduled operational work.

- [ ] Run a supervised queue worker for `QUEUE_CONNECTION=database`.
- [ ] Configure automatic worker restart after deployment.
- [ ] Configure Laravel scheduler execution every minute (`php artisan schedule:run`).
- [ ] Verify reminder, arrears/penalty, recurring-expense, management-work, and backup schedules execute at the intended local time.
- [ ] Confirm long-running workers do not retain branch context between jobs; `BranchContext` callbacks must restore context after each operation.

## 5. Backups and Restore

The example environment exposes `BACKUP_PATH`, `BACKUP_KEEP_DAYS`, `BACKUP_SCHEDULE_ENABLED`, `BACKUP_SCHEDULE_TIME`, and `MYSQLDUMP_BINARY`.

- [ ] Set `BACKUP_PATH` to a protected production destination outside the web root.
- [ ] Enable the scheduled backup only after the destination is verified writable and protected.
- [ ] Confirm `mysqldump` is installed at the configured path.
- [ ] Keep at least one off-server/offsite copy of database and private uploaded files.
- [ ] Encrypt backups at rest and protect transfer credentials.
- [ ] Run a full restore drill into an isolated database/storage location.
- [ ] Verify restored database and private files match backup manifests/integrity checks.
- [ ] Define retention beyond the default `BACKUP_KEEP_DAYS=30` if legal/business policy requires it.

## 6. Mail, SMS, WhatsApp, and External Providers

The example environment uses log/local defaults and empty messaging endpoints/tokens. Production credentials must be supplied deliberately.

- [ ] Configure a real production mail transport instead of `MAIL_MAILER=log` where email delivery is required.
- [ ] Configure the final sender/from address and test password/security emails.
- [ ] Configure approved SMS provider credentials and sender ID.
- [ ] Configure approved WhatsApp provider credentials if the module is enabled.
- [ ] Set provider timeouts and verify failure/retry behavior.
- [ ] Keep provider secrets out of source control and audit logs.
- [ ] Configure and test the production NIN provider/integration if automatic NIN lookup is required by the deployment.
- [ ] Disable optional communication/integration modules that are not configured for production.

## 7. Authentication and Staff Security

- [ ] Replace/rotate any seeded or temporary administrator password before go-live.
- [ ] Verify there is at least one controlled super-administrator account and no unnecessary global administrators.
- [ ] Enable and test two-factor authentication for privileged operators according to business policy.
- [ ] Review staff roles and branch assignments before importing/creating real customer data.
- [ ] Test password reset using the production mail channel.
- [ ] Confirm inactive/terminated staff cannot authenticate.
- [ ] Confirm shared accounts are not used for operational staff.

## 8. Branch Isolation Go-Live Checks

- [ ] Create or identify two safe test branches in staging/pre-production.
- [ ] Verify a Branch A user cannot open a Branch B customer or loan by URL.
- [ ] Verify Branch A cannot submit Branch B IDs for financial accounts, collateral, staff, customer, or loan relationships.
- [ ] Verify Branch A cannot see Branch B totals in dashboard, reports, search, or exports.
- [ ] Verify Branch A cannot download Branch B private documents.
- [ ] Verify a multi-branch user sees exactly the assigned branch union.
- [ ] Verify a no-branch user sees no branch-owned operational data.
- [ ] Verify super-administrator system-wide access remains intentional.

## 9. Financial Go-Live Checks

- [ ] Confirm opening balances for every financial account before real transactions begin.
- [ ] Verify branch/account mapping and account statuses.
- [ ] Verify loan products, interest methods, fees, penalties, and repayment frequencies against approved business rules.
- [ ] Run a staging lifecycle: customer -> collateral -> loan -> approval -> disbursement -> payment -> reports.
- [ ] Reconcile account transactions, accounting entries, customer statement, and dashboard/report totals for the staging lifecycle.
- [ ] Verify maker-checker rules for approvals, expenses, payroll, cash closing, restructuring, and write-off flows.
- [ ] Verify cash reconciliation and daily closing procedures with the actual operational team.

## 10. Documents and Private Storage

- [ ] Configure persistent private storage and include it in backup/restore procedures.
- [ ] Upload and verify production business logo/stamp/contract templates.
- [ ] Generate a sample loan contract and all required print/export documents.
- [ ] Verify private documents are downloadable only by authorized branch users.
- [ ] Confirm executable/unsafe upload types remain blocked.

## 11. Performance and Runtime

- [ ] Run `php artisan config:cache` after production environment values are final.
- [ ] Run `php artisan route:cache` if all production routes support caching.
- [ ] Run `php artisan view:cache`.
- [ ] Build production frontend assets with Node 22.16.0 from `.nvmrc` and `npm ci` from the committed `package-lock.json`.
- [x] Provide an application-specific PHP-FPM pool, aligned Nginx request limit, and fail-closed runtime preflight for upload, memory, and request-timeout limits.
- [ ] Apply the PHP-FPM/Nginx baseline on staging/production, run `php-runtime-preflight.sh`, and verify representative contract/document uploads on the target host.
- [x] Provide targeted reporting composite indexes, `database:performance-check`, MySQL `EXPLAIN` capture, and privacy-safe application slow-query logging.
- [ ] Run the database performance preflight and observe dashboard/report queries with production-like data volume on staging/production; investigate sustained slow queries before go-live.
- [x] Provide a runtime health command for database health, failed queues, scheduler freshness, disk space, and backup freshness, plus the `/up` HTTP health endpoint.
- [ ] Configure the production monitoring/alerting platform to run `operations:health-check`, monitor `/up` externally, and alert on failures.

## 12. Deployment and Rollback

- [ ] Document the exact deployment commands and service restart order.
- [ ] Keep deploys reproducible from a tagged/known Git commit.
- [ ] Back up before schema-changing deployments.
- [ ] Define rollback steps for application code and database migrations/data changes.
- [ ] Perform one staging deployment using the same process planned for production.
- [ ] Record the production commit SHA after every deployment.

## 13. Final Acceptance

Before go-live:

- [ ] `php artisan test` passes on the release commit.
- [ ] Fresh MySQL migrations, seeders, and `database:performance-check --json --explain` pass in CI.
- [ ] Locked frontend `npm ci` and `npm run build` pass in the production-config CI gate.
- [ ] `SecurityBackupReviewTest` passes.
- [ ] `CompleteIntegrationWorkflowTest` passes.
- [ ] Branch isolation regression tests pass, including the zero-legacy-resolver audit and remaining parent-owned scope coverage.
- [ ] A restore drill has succeeded.
- [ ] External providers required at launch have been tested with production/staging credentials.
- [ ] Business owners have reviewed loan products, permissions, reports, document templates, and operational procedures.

## Release Decision

Application correctness can be considered release-candidate quality only when the automated gates are green. Production readiness additionally requires completion of the environment, infrastructure, credentials, backup/restore, monitoring, and operational checks above; those cannot be guaranteed by the repository test suite alone.
