# Foundation setup and review

## Install

Use PHP 8.2+, Composer, MySQL and the required PHP extensions (PDO MySQL, mbstring, XML, intl). Run `composer install`, then `php init --env=Development --overwrite=All`. Set LEND_DB_DSN, LEND_DB_USER and LEND_DB_PASSWORD in the runtime environment or edit the generated ignored common/config/main-local.php. Use a dedicated database account and database named lendford. Run `php yii migrate`.

Create bootstrap accounts using the console. Set LEND_USER_PASSWORD in the process environment to a unique password of at least 12 characters; do not put it in command arguments, source files or the repository. Run:

```sh
php yii staff/create support support@example.com adminSuperuser "Support Administrator"
php yii staff/create chief chief@example.com ceo "Chief Executive"
```

Set a different password before each command and remove the environment variable afterwards. Replace example identity values with real approved staff details. There are no default passwords. The CEO account is created through the console; the web support form cannot create or edit CEO accounts. A CEO needing support administration can explicitly receive both roles through controlled console configuration.

Point the staff virtual host at backend/web. The frontend is reserved and exposes no signup or login routes. Enforce HTTPS in production and set LEND_SECURE_COOKIES=1. Configure the web server to reject direct access to project files. No borrower uploads or live data are included.

## Foundation workflows

Sign in as support to add/deactivate branches and create staff accounts. Open a staff profile to add a branch, transfer all current assignments to a new branch, appoint a manager or end an assignment. Histories use Africa/Lusaka display time. Assigning a manager ends the prior manager's branch assignment; other assignments remain intact. Administrators can edit roles except CEO. An account or assignment change invalidates existing staff sessions. At least one active administrative superuser is retained by the web workflow.

Staff without a branch assignment see no branches. CEO and administrative support have organisation-wide branch visibility. Support does not receive financial approval. Branch Manager and Finance Officer are preparer roles; CEO retains financial authorisation. Lending modules are placeholders in this phase, with no live financial data or actions.

## Verification

`php tests/foundation.php` runs integration tests against a disposable MySQL database (set LEND_TEST_DSN, LEND_DB_USER and LEND_DB_PASSWORD; never use an existing database) for permission separation, branch scoping, transfer history, inactive branches, duplicates, password hashing, session revocation keys, last-superuser protection and audit. The GitHub workflow installs dependencies and runs these checks plus PHP syntax validation. CI additionally applies the migrations on MySQL and runs HTTP smoke checks for staff login, role guards, branch creation, CSRF and output escaping. Deployment browser checks remain necessary.

Browser checklist: guest requests redirect to sign-in; officer cannot access branch/staff administration URLs; admin can create branch and staff; transfer ends historical assignment and changes visible branch scope; deactivate a staff account and verify its old session cannot proceed; test invalid passwords and login throttle; change own password and sign in again; logout must reject GET. Verify CSRF rejects state changes without a token and all displayed names/addresses are escaped. CEO can read audit but cannot obtain support administration unless explicitly assigned that role.

Current limitations: module workflows and CEO business approval inbox are scheduled for later phases. A designation as branch manager does not grant financial approval. No MFA, public registration, email reset workflow, impersonation, accounting or financial postings are enabled. Login throttling uses the application file cache; multi-server production deployment will need shared cache storage. All financial screens show unavailable states instead of fabricated loan totals.