# Back-end guide: how NCA works day to day

## 1. Who does what

| Role | Signs in at | Daily work |
|---|---|---|
| Verifier | `/login` then `/admin` | Members > **To review**: open an application, view documents (opens in a new tab, link expires in 5 minutes), read **Automatic checks**, then **Approve**, **Request info** or **Reject**. If any check is flagged, approval asks for a reason that is logged |
| Finance | `/admin` | **Payments** (filters; fix *Needs finance review* and *Unmatched* with **Allocate to member**), **Reconciliation** (check pending prompts, import statement), **Reports**, mark agent commissions paid |
| Admin | `/admin` | Everything above except staff accounts, plus Tiers/fees, Events, News, Announcements, Impact figures, Partners, Deletion requests |
| Super admin | `/admin` | Staff accounts (create logins, reset someone's 2FA), Audit log |
| Agent / café | `/agent` | Uses the registration link with their code; sees their own registrations and commission |
| Partner | `/partner` | Anonymised totals only |

## 2. Member lifecycle

`submitted` (form received) > `pending_payment` (phone verified) > `pending_review` (fee paid, automatic checks run) > `active` (approved), or `needs_info` (verifier asked for a fix; the member re-uploads and goes back to review) or `rejected`. Active members can become `suspended` (by an admin) or `lapsed` (contribution more than 14 days overdue; paying reactivates automatically).

## 3. Money

- Fees are set in Back office > **Tiers**. Changing a fee affects new payments only.
- A payment is **Paid** only after Safaricom's callback (or a status query, or a statement import). Wrong amount or a reused receipt becomes **Needs finance review**.
- Registration paid + approval creates the monthly subscription (due one month later). Each month: SMS reminder, M-Pesa prompt on the due date, lapse after 14 days.
- Agent commission (default 10 percent of the registration fee, editable per agent) accrues when the registration fee is paid.

## 4. Content

- **News articles:** Back office > News articles. Leave "published at" empty for a draft; a future date schedules it. Needs `php artisan storage:link` for uploaded pictures.
- **Impact figures:** shown on the public Impact page and the partner dashboard.
- **Events:** published events show on the website and in member portals; members register (free) or pay by M-Pesa and get a QR ticket.
- **Announcements:** pick an audience (all, active, or one county), optionally SMS, press **Send**. It cannot be unsent.

## 5. Privacy tools

- Members: **Profile > Download my data** (JSON) and **Request account deletion**.
- Admin: Deletion requests > **Erase personal data** removes name, phone, email, ID number, documents and messages and disables the login; payment records stay (financial law) but are no longer linked to a person.
- Every opening of a member record, every ID document view and every export is in the audit log.

## 6. Where things live (for your developer)

| Thing | File |
|---|---|
| Payment settlement (idempotent) | `app/Services/Payments/PaymentSettler.php` |
| Daraja client / fake client | `app/Services/Payments/DarajaClient.php`, `FakeMpesaClient.php` |
| Callback endpoint | `app/Http/Controllers/MpesaCallbackController.php`, `routes/api.php` |
| Registration | `RegisterController`, `RegisterRequest`, `app/Actions/RegisterMember.php` |
| Approval / rejection | `app/Actions/*Member.php`, `RequestMoreInfo.php` |
| Automatic checks | `app/Services/Verification/RulesVerifier.php` |
| Renewals and lapsing | `app/Services/Membership/SubscriptionService.php` |
| Screens shown to views | `app/Support/Presenters.php` |
| Back office | `app/Filament/` |
| Settings / switches | `config/nca.php` and `.env` |
| Tests | `tests/` |