# Install and run the NCA platform (front end + back end)

This takes you from nothing to the full Nova Community Alliance platform on your own computer: public website, registration with SMS code and M-Pesa payment, member portal, agent and partner portals, and the staff back office at `/admin`.

On your own computer **nothing real happens**: SMS go to a log file and M-Pesa is simulated (`MPESA_DRIVER=fake`). Real services are connected later with `CONNECT-SERVICES.md`.

---

## 1. Install the tools (one time)

| Tool | Version | Check |
|---|---|---|
| PHP | 8.2 or newer (8.3 recommended) | `php -v` |
| Composer | 2.x | `composer --version` |
| Node.js + npm | Node 20 or newer | `node -v` |

**PHP extensions that must be switched on.** Filament (the back office) needs `intl`. Laravel needs the usual set.

### Windows with XAMPP
1. Install PHP 8.3 separately if XAMPP's PHP is older than 8.2 (check `C:\xampp\php\php.exe -v`). Add the PHP folder to your Windows PATH.
2. Open `C:\xampp\php\php.ini` in Notepad and remove the `;` at the start of these lines, then save:
   ```
   extension=curl
   extension=fileinfo
   extension=gd
   extension=intl
   extension=mbstring
   extension=openssl
   extension=pdo_sqlite
   extension=sqlite3
   extension=zip
   ```
3. Install **Composer** (getcomposer.org) and **Node.js** (nodejs.org). Open a **new** Command Prompt and run the three checks above.
4. Check the extensions: `php -m` should list `intl`, `gd`, `mbstring`, `pdo_sqlite`, `zip`.

**Laravel Herd** or **Laragon** are easier alternatives: they install everything with the right extensions.

### macOS / Linux
`brew install php composer node` (macOS). On Ubuntu: `sudo apt install php php-cli php-mbstring php-xml php-curl php-zip php-sqlite3 php-mysql php-gd php-intl unzip curl`, then install Composer and Node.

---

## 2. Run the setup script

Unzip `nca-platform.zip` to a path **without spaces**, for example `C:\XAMPP\htdocs\nca-platform`. Open Command Prompt **in that folder** and run the script, giving it a **new, empty** folder name for the finished project:

**Windows**
```bat
install.bat C:\XAMPP\htdocs\nca-app
```
**macOS, Linux, Git Bash**
```bash
bash install.sh ../nca-app
```

The script does eight things and prints each step: creates a fresh Laravel project, installs the packages (Filament, roles, audit log, QR, 2FA), copies the NCA platform in, sets safe local settings in `.env`, creates the database and starter data (47 counties, sectors, tiers, roles, sample logins), installs and builds the CSS/JS, runs the automatic tests, and prints a requirements report. It needs internet and takes several minutes the first time.

> The folder you pass must not exist yet. The unzipped `nca-platform` folder is **not** a Laravel project by itself; the script builds the real project in the new folder.

---

## 3. Run it

```bat
cd /d C:\XAMPP\htdocs\nca-app
php artisan serve
```
Open **http://127.0.0.1:8000**. Back office: **http://127.0.0.1:8000/admin**.

You do not need Apache or MySQL running for local testing (it uses a SQLite file).

---

## 4. Sample logins (local only, password `password`)

| Who | Email | Opens |
|---|---|---|
| Super admin | super@nca.test | `/admin` (asks you to set up 2FA the first time) |
| Admin | admin@nca.test | `/admin` |
| Verifier | verifier@nca.test | `/admin` (review queue) |
| Finance | finance@nca.test | `/admin` (payments, reconciliation) |
| Agent | agent@nca.test | `/agent` |
| Partner | partner@nca.test | `/partner` |
| Active member | member0@nca.test | `/member` |

**Two-factor for staff:** the first login shows a QR code. Scan it with Google Authenticator, Microsoft Authenticator or Authy, then type the 6-digit code. Phone-less shortcut for local testing only: `php artisan nca:env NCA_STAFF_2FA=false`.

Make your own real super admin (do this on the live server too):
```bat
php artisan nca:make-staff you@example.com super_admin --name="Erick Odhiambo"
```

---

## 5. Try the whole journey (about 5 minutes)

1. Go to `/register`, fill the four steps (any small photos work), tick consent, submit.
2. The SMS code is shown on screen in demo mode (`NCA_DEMO=true`); it is also in `storage/logs/laravel.log`.
3. Press **Pay with M-Pesa**. The simulated customer approves after about 3 polls, through the real payment code.
4. Log in as **verifier@nca.test** at `/login`, finish 2FA, open **Members**, **To review**, open the new person, check **Documents** and **Automatic checks**, press **Approve**.
5. Log in as the new member (the email you used, your password): you now have a Member Number, a QR card, and a monthly subscription.
6. Scan or open the QR link `/verify/<token>`: it shows the public verification page.
7. Run `php artisan nca:check` to see what is still in development mode.

---

## 6. Commands you will use

| Command | What it does |
|---|---|
| `php artisan nca:check` | Requirements report: PASS / WARN / FAIL (add `--live` for production rules) |
| `php artisan test` | Runs the automated tests (payments, callbacks, approvals, access control, data rights) |
| `php artisan nca:make-staff EMAIL ROLE` | Create a staff, agent or partner login |
| `php artisan nca:env KEY=value` | Safely edit `.env` |
| `php artisan nca:fake-pay` | Dev only: pretend the newest pending M-Pesa prompt was paid (or `--fail`) |
| `php artisan nca:reconcile` | Ask Safaricom about payments that never got a callback |
| `php artisan nca:renewals` | Send reminders, M-Pesa prompts for due dates, lapse overdue members |
| `php artisan nca:housekeeping` | Delete old OTPs, anonymise old rejected applications |
| `php artisan schedule:list` | Shows when each of those runs automatically |

---

## 7. Troubleshooting

**`install.bat` stops at "composer require ... intl".** Enable `extension=intl` in `php.ini` (step 1), open a new Command Prompt, run the script again with a **new** folder name.

**"Could not open input file: artisan".** You are in the wrong folder. Use `cd /d C:\XAMPP\htdocs\nca-app` (the folder the script created), not the unzipped overlay.

**Unstyled page / "Vite manifest not found".** Run `npm run build` in the project folder.

**"could not find driver".** Enable `pdo_sqlite` and `sqlite3` in `php.ini`.

**Staff login says "403".** The account has no staff role. Use `nca:make-staff`.

**QR scanner gives a wrong address.** Set `APP_URL` in `.env` to the real address (on a phone test, your computer's LAN address), then `php artisan config:clear`.

**Photos from iPhone are rejected.** HEIC photos are not accepted; use JPG or PNG (camera settings: "Most Compatible").

**Changes not showing.** `php artisan optimize:clear`, hard refresh (Ctrl+F5).

**Start again from scratch.** Delete the project folder and run the script again with a new folder name.

---

## 8. What is real now and what is simulated

| Feature | Locally | Live |
|---|---|---|
| Registration, documents, consent | Real, stored in the database and private storage | Same |
| SMS | Written to `storage/logs/laravel.log` | Africa's Talking (`SMS_DRIVER=africastalking`) |
| M-Pesa | Simulated | Safaricom Daraja (`MPESA_DRIVER=daraja`) |
| Email | Written to log | SMTP |
| Everything else (approvals, roles, 2FA, cards, reports, audit log, data-rights tools) | Real | Real |

See **CONNECT-SERVICES.md** to switch the simulated parts to the real services, and **REQUIREMENTS-CHECKLIST.md** to confirm every part of the Build Plan.