FraudShield

FraudShield is a mobile-first web app for detecting fraud in mobile-money transactions. It is designed as a final-year project with a polished analyst dashboard, FastAPI backend, SQLite demo database, and an offline machine-learning training pipeline for the PaySim dataset.

What Is Built

• Dark fintech React dashboard for an admin fraud analyst.
• Receipt screenshot upload/check workflow for Nigerian fintech and bank receipts.
• Student-facing link and payment-prompt verification page.
• Admin fraud-signature database for suspicious domains, keywords, and patterns.
• FastAPI backend with seeded demo transactions and seeded fraud signatures.
• Single-transaction fraud prediction.
• CSV upload with row-level validation errors.
• Review queue for marking transactions as fraud, legitimate, or needs review.
• Analytics for transaction risk, receipt checks, link checks, student reports, signatures, and real trained model metrics.
• Offline training script for PaySim with temporal split, class imbalance handling, PR-AUC, F2-score, and leakage-aware feature comparisons.

Project Structure

FraudShield/
  backend/
    app/
      main.py
      database.py
      model_service.py
      link_service.py
      ocr_service.py
      receipt_service.py
      schemas.py
    ml/
      train_model.py
    models/
    data/
    requirements.txt
  frontend/
    src/
      components/
      pages/
      lib/
      styles.css
    package.json
  sample_transactions.csv

Run The Backend

cd FraudShield/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The API will seed SQLite automatically on first startup.

Health check:

curl http://localhost:8000/health

Run The Frontend

cd FraudShield/frontend
npm install
npm run dev

Open:

http://localhost:5173

If the backend is hosted elsewhere, set:

VITE_API_BASE_URL=https://your-api-url npm run dev

Train With PaySim

Download the PaySim mobile-money fraud dataset and run the training script from the FraudShield directory:

cd FraudShield
python backend/ml/train_model.py --input /path/to/paysim.csv

The script saves:

backend/models/fraud_model.joblib
backend/models/model_metrics.json

The FastAPI service automatically uses fraud_model.joblib when it exists. Without it, the API uses a clearly labeled demo fallback scorer so the app remains runnable.

ML Methodology Notes

• PaySim is simulated mobile-money data.
• Fraud labels appear only in TRANSFER and CASH_OUT.
• Balance fields can leak simulated fraud behavior.
• The training script compares a full feature set against a no-balance feature set.
• Train/test split is temporal using the step column.
• Model selection uses PR-AUC, F2-score, precision, recall, ROC-AUC, and confusion matrix.
• The final report should discuss leakage and class imbalance directly.

API Endpoints

• GET /health
• POST /predict
• POST /receipts/upload
• GET /receipts
• GET /receipts/{id}
• GET /receipts/{id}/image
• PATCH /receipts/{id}/review
• POST /verify-link
• POST /reports
• GET /reports
• GET /link-checks
• GET /fraud-signatures
• POST /fraud-signatures
• PATCH /fraud-signatures/{id}
• DELETE /fraud-signatures/{id}
• POST /transactions/upload
• GET /transactions
• GET /transactions/{id}
• PATCH /transactions/{id}/review
• GET /analytics

Demo CSV

Use sample_transactions.csv from this folder on the Upload page.

Evaluation Objectives

Recommended Chapter One objectives are available in docs/evaluation-objectives.md. They align the written project with the implemented React/FastAPI/SQLite stack and the combined transaction plus link-verification functionality.

Receipt OCR Setup

Receipt upload works without OCR installed, but records will be flagged with low OCR quality. For real text extraction install Tesseract and Python OCR dependencies:

sudo apt-get install -y tesseract-ocr
cd FraudShield/backend
pip install -r requirements.txt

The receipt module extracts provider, amount, status, reference, sender, receiver, and date when OCR text is available.