Spaces:
Configuration error
Configuration error
| # 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. | |