# Usage Guide — Banking Fraud Detection System

A walkthrough for a real, logged-in person to exercise every feature of the system: officer console and client app, every page, every action. For install/run commands see [RUN.md](RUN.md); for API/schema reference see [README.md](README.md).

## 1. Get the seed officer credentials

There is exactly one officer account created automatically, from your own `.env`:

```
SEED_OFFICER_EMAIL=...
SEED_OFFICER_PASSWORD=...
```

**I can't put the actual values in this file for you** — printing a live secret to a file/terminal is blocked by this environment's permission guardrails, even on your own request. Open your `.env` yourself (`cat .env` or your editor) and copy the two values from there. Every other account in the system (every client, and any additional officer) is created *through the app itself* using the flow below — those you can freely put in this doc since you choose them.

Start the server if it isn't already running (see RUN.md), then open:

```
http://localhost:8811/login          (or your own APP_PORT)
```

## 2. Log in as the officer

Sign in with `SEED_OFFICER_EMAIL` / `SEED_OFFICER_PASSWORD`. You land on `/officer`.

### 2a. Dashboard (`/officer`)
- Confirms: total clients, total transactions, overall fraud rate, open alerts by tier, recent cross-client activity table.
- On a brand-new database this will show all zeros/"No activity yet." — that's correct; it's not stuck (see step 3 to populate it).

### 2b. Create a client (`/officer/clients`)
1. Click **+ Create client**.
2. Fill in:
   - Full name: `Alice Uwase`
   - Email: `alice.demo@fakebankmail.com`
   - Starting balance (RWF): `100000`
   - Account type: `Checking`
   - Temporary password: `ClientDemo123!` (min 8 characters — pick your own, this is just an example)
3. Click **Create client**. A one-time confirmation shows the email + temp password — **copy it now, it's never shown again**.
4. Close the modal — the new client appears in the table with their starting balance.
5. Try creating a second client (e.g. `Bob Habimana`, `bob.demo@fakebankmail.com`, RWF 50,000) — you'll want two clients later to test alert isolation.
6. Try creating a client with a duplicate email — confirms the 409 "already exists" error banner.

### 2c. Client detail (`/officer/clients/{id}`)
Click **View →** next to Alice. You'll see her balance, account type, and two tabs (Transactions / Alerts) — both empty until step 3.

### 2d. EDA Insights (`/officer/insights`)
Charts and captions describing the PaySim training data: class imbalance, fraud rate by transaction type/hour, amount distribution. Read-only, no interaction needed — just confirm the charts render.

### 2e. Model Performance (`/officer/model`)
Precision/recall/F1 at different thresholds, PR curve, and why accuracy alone would be misleading at this fraud rate. Read-only.

### 2f. Alerts Queue (`/officer/alerts`)
Empty for now — filter chips (All / Low / Medium / High / Open / Reviewed / Dismissed) are visible but there's nothing to show yet. Come back after step 3.

## 3. Log in as the client and trigger every outcome

Log out (button in the sidebar), then log back in with `alice.demo@fakebankmail.com` / `ClientDemo123!`. You land on `/client`.

### 3a. Client dashboard (`/client`)
Balance card (RWF 100,000), no notices yet, "No transactions yet."

### 3b. A normal, low-risk transaction
`/client/transactions/new`:
- Type: **Payment**
- Amount: `5000`
- To account: `MSHOP001`
- Date/time: leave as-is (defaults to now)
- Submit.

Expected: green "Approved" result card. Balance drops to RWF 95,000.

### 3c. A deposit (cash-in) — balance should increase
- Type: **Cash in**
- Amount: `20000`
- To account: `MAGENT01`
- Submit.

Expected: "Approved", and balance **increases** to RWF 115,000 (not decreases — this was a bug that's now fixed; use this step to confirm it stays fixed).

### 3d. The fraud-triggering pattern — full balance drain
This is the model's actual learned signature: a `Transfer` or `Cash out` that empties the account to exactly zero.
- Check your current balance on `/client` first (should be RWF 115,000 after steps 3b–3c).
- Type: **Transfer**
- Amount: **exactly your current balance** (`115000`)
- To account: `C_MULE_1`
- Submit.

Expected: red "Being reviewed for your security" result card, risk tier **high**, probability near 100%. Balance goes to RWF 0.

(See [fraud-example.md](fraud-example.md) for more example amounts and the raw-API version of this test.)

### 3e. Transaction history (`/client/transactions`)
All three transactions from 3b–3d, newest first, with amount and Approved/Under review status.

### 3f. My alerts (`/client/alerts`)
The high-risk transfer from 3d shows up here, plain-language, read-only — no admin controls available to a client (confirms role boundary).

### 3g. Try to overdraw (should fail)
Back on `/client/transactions/new`, submit a **Transfer** for `999999` (far more than your RWF 0 balance). Expected: a red error banner, transaction rejected (422) — balance untouched.

## 4. Back to the officer — review the alert and confirm isolation

Log out, log back in as the officer.

### 4a. Dashboard now has data
`/officer` — clients: 2, transactions: 4 (or however many you submitted), a nonzero fraud rate, 1 open alert, and Alice's drain transaction in "Recent activity."

### 4b. Alerts Queue (`/officer/alerts`)
Alice's alert appears. Click **Review** to expand it — you'll see the SHAP feature breakdown (a horizontal bar per feature, red = pushes toward fraud, green = pushes away). This is the explainability piece: don't just trust the score, see *why*.

Three actions:
- **Approve** — confirms the transaction is legitimate. Alert closes, balance untouched.
- **Reject & reverse** — confirms it's actually fraud. Asks for confirmation, then reverses the transaction: it's excluded from the client's balance going forward (check `/client` as Alice afterward — her balance is back to what it was before the drain).
- **Dismiss** — closes the alert without a fraud/legitimate determination either way (e.g. a duplicate or a false alarm not worth tracking as reviewed).

The row updates immediately either way, and filter chip counts (including a new "Rejected" chip) update.

### 4c. Client detail confirms it landed on the right client
`/officer/clients/{Alice's id}` → Transactions tab shows all 4 rows with risk tier + probability per row; Alerts tab shows the one alert, now marked reviewed/dismissed.

### 4d. Confirm data isolation (Bob never sees Alice's stuff)
Log out, log in as Bob (`bob.demo@fakebankmail.com`), check `/client/alerts` — should be empty, since only Alice transacted. This is the client-isolation guarantee: a client only ever sees their own account, and there's no `client_id` parameter anywhere in their own routes to guess around.

## 5. Officer-only raw scoring (optional, for API exploration)

While logged in as the officer, open **`/docs`** (Swagger UI, linked from the sidebar as "API Reference"). Try `POST /api/predict` directly with a raw PaySim-shaped transaction — useful for testing the model in isolation from the account-balance flow. Example fraud-triggering payload:

```json
{
  "step": 5,
  "type": "TRANSFER",
  "amount": 181.0,
  "nameOrig": "CTEST_ORIG",
  "oldbalanceOrg": 181.0,
  "newbalanceOrig": 0.0,
  "nameDest": "CTEST_DEST",
  "oldbalanceDest": 0.0,
  "newbalanceDest": 0.0
}
```

More payloads (fraud-triggering and legit-contrast) are in [fraud-example.md](fraud-example.md).

## 6. Automated coverage (if you don't want to click through by hand)

```bash
pytest                          # unit + integration — 63 tests, covers every endpoint and role boundary
python -m scripts.test_live --base-url http://127.0.0.1:8811   # live smoke test: full officer→client→officer loop against the running server
```

## 7. Mobile / responsive check

Resize the browser below ~900px width (or open on a phone):
- Officer console: sidebar collapses behind a hamburger button (top-left) — tap it to open the drawer, tap any link to navigate and auto-close.
- Client app: the pill nav (Home/History/Alerts) becomes horizontally scrollable if the screen is very narrow.

## 8. Clean-up

Everything above except the seed officer is safe to delete once you're done demoing — see the cleanup snippet under "Live smoke test" in [TESTING.md](TESTING.md) for a copy-pasteable script that removes all client/transaction/alert data while keeping the seed officer intact.