Neo-bank Fraud Detection and Transaction Categorisation System

LedgerGuard

LedgerGuard is a production-minded fraud detection and transaction categorisation system for a neo-bank setting, delivering an end-to-end ML pipeline that auto-labels merchant transactions and assigns a fraud risk score, surfaced through an Ops Dashboard for ingestion, scoring, review, and feedback, alongside a read-only Customer Dashboard for safe end-user visibility.

Highlights

• CSV ingestion with validation and schema coercion
• Baseline category prediction (TF-IDF + Logistic Regression)
• Baseline fraud risk scoring (Isolation Forest)
• Unified scoring pipeline with category, confidence, fraud risk, and flagged state
• Ops Dashboard for uploads, KPIs, filtering, and review
• Analyst feedback loop with stable row IDs and exportable edits
• Rules overlay to override model category with audit tags
• Customer Dashboard with minimal exposure and customer flag capture
• Model performance page powered by model_registry.json
• Docker-ready deployment with healthcheck endpoint

Technologies Used

• Language: Python 3.11
• Web framework: Django 5 (Django Templates for server-rendered UI)
• Frontend: HTML, CSS, Vanilla JavaScript
• API tooling dependency: Django REST Framework
• Database: PostgreSQL
• Data and ML: pandas, NumPy, scikit-learn, imbalanced-learn
• Advanced modeling: XGBoost, LightGBM
• NLP/Embeddings: sentence-transformers, transformers, PyTorch
• Model/runtime utilities: joblib, gunicorn, WhiteNoise, python-dotenv
• Visualisation: Matplotlib, Seaborn
• Testing: pytest, pytest-django, factory_boy, coverage/pytest-cov
• Code quality: Black, isort, Flake8, mypy, pre-commit
• DevOps/Deployment: Docker, Docker Compose, Render, GitHub Actions (CI)

Quick Start

1. Install dependencies and set env vars:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

2. Demo users are not pre-seeded (no fixture or migration ships with accounts). If you want to use demo credentials, create them manually:

Ops admin:

• username: admin
• email: admin@neobank.com
• password: admin

Customer user:

• username: customer1
• password: pass1234

python manage.py migrate
python manage.py createsuperuser

Create a customer user via Django admin or your normal signup flow. Avoid a username that collides with a customer_id in your CSVs to prevent confusion when filtering or selecting a customer dashboard.

3. If you want to create your own admin + customer users, follow the same steps but pick your own credentials.

4. Start the server and upload demo data:

python manage.py runserver

Use demo data: data/sample_transactions.csv

Screens and Docs

• Screenshots and notes: docs/screenshots
• Model registry: model_registry.json
• Rules configuration: rules/category_overrides.json

Architecture Overview

• dashboard/ Ops workflows, ingestion services, scoring orchestration, UI
• customer_site/ Customer views and templates
• ml/ Training and inference for baseline models
• rules/ Category override definitions
• artefacts/ Model artefacts and metrics
• data/ Sample datasets
• tests/ Unit and integration-style tests

Repository Structure

Neo-Bank-Fraud-Detection-Project/
├── dashboard/               # Ops dashboard app (views, services, templates, static assets)
├── customer_site/           # Customer-facing app (read-only dashboard and auth views)
├── neobank_site/            # Django project config (settings, URLs, WSGI/ASGI)
├── ml/
│   ├── inference/           # Scoring and prediction entry points
│   ├── training/            # Model training pipelines and utilities
│   ├── metrics/             # Metrics rendering and plotting helpers
│   ├── scripts/             # ML operational scripts (state refresh, preload)
│   └── reporting/           # Reporting/visualisation helpers
├── tests/                   # Unit/integration tests
├── docs/                    # Project docs, model cards, screenshots
├── data/                    # Sample input datasets
├── artefacts/               # Trained model artefacts
├── reports/                 # Metrics and threshold outputs
├── rules/                   # Rule-based category override config
├── requirements/            # Split requirement files (base/dev/ml/all)
├── scripts/                 # Utility scripts (e.g., registry validation)
├── docker-compose.yml       # Local multi-service orchestration
├── Dockerfile               # Production image build
├── manage.py                # Django management entry point
├── model_registry.json      # Model run metadata and registry
├── pyproject.toml           # Project tooling configuration
├── pytest.ini               # Pytest configuration
└── render.yaml              # Render deployment configuration

Data Contract

Expected CSV columns:

• timestamp
• amount
• customer_id
• merchant
• description

Contract guarantees:

• Required columns must be present
• Amounts are coerced to numeric
• Text fields are normalized
• customer_id must be non-empty

Local Development (Python)

Prerequisites:

• Python 3.11
• PostgreSQL

Setup:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Update .env with your local database values, then run:

python manage.py migrate
python manage.py runserver

Ops Dashboard: http://127.0.0.1:8000/ops/

Customer Dashboard: http://127.0.0.1:8000/customer/

Local Development (Docker)

docker compose up --build

The Docker setup includes Postgres and runs Django on port 8000.

Environment Variables

Core settings (see .env.example):

• DEBUG
• SECRET_KEY
• ALLOWED_HOSTS
• DATABASE_URL

PostgreSQL settings (when not using DATABASE_URL):

• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_HOST
• POSTGRES_PORT

Optional integrations (present in .env.example):

• REDIS_URL
• CELERY_BROKER_URL
• CELERY_RESULT_BACKEND
• EMAIL_HOST
• EMAIL_PORT

Ops Dashboard Workflow

1. Upload a CSV file.
2. Set a fraud threshold.
3. Review KPIs and scored results.
4. Filter rows by flags, customer, merchant, category, or fraud risk.
5. Edit categories and export feedback.

Category provenance is explicit:

• model for model output
• rule for rule-based override
• edit for analyst override

Precedence: edit > rule > model.

Customer Dashboard

The customer site is a read-only surface that exposes a limited transaction view and allows customers to flag a transaction with an optional note. It deliberately hides any fraud scores, thresholds, or model output.

Rules Overlay

Rules are stored in rules/category_overrides.json and applied using case-insensitive substring matching against merchant and description. This keeps overrides auditable and fast to change.

Healthcheck

• GET /health/
• Returns { "ok": true }

Testing

Run the test suite:

pytest -q

Coverage:

coverage run -m pytest -q
coverage report

CI enforces an 80% minimum coverage threshold.

Deployment

The project ships with a production Dockerfile and a gunicorn entrypoint. For a container platform:

• Set DEBUG=False
• Configure ALLOWED_HOSTS
• Provide DATABASE_URL
• Run database migrations

Example gunicorn start command:

gunicorn neobank_site.wsgi:application --bind 0.0.0.0:$PORT

Render Deployment

Render is supported out of the box via the existing render.yaml.

High-level flow:

1. Create a new Render service from this repo.
2. Add a managed PostgreSQL database and set DATABASE_URL.
3. Set DEBUG=False and configure ALLOWED_HOSTS.
4. Trigger a deploy and run migrations if needed.

License

MIT. See LICENSE.

Maintainer

Adrian Adewunmi

Repository

https://github.com/AAdewunmi/Neo-Bank-Fraud-Detection-Project