USAGE.md

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; for API/schema reference see 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 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:

{
  "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.

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

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 for a copy-pasteable script that removes all client/transaction/alert data while keeping the seed officer intact.