Realmonitoring: Real-Time Fraud Monitoring Reference Project

This repository is a runnable reference implementation of a real-time fraud monitoring pipeline for financial transactions.

It demonstrates:

• Streaming transaction ingestion (simulated stream)
• Online behavioral feature computation
• Millisecond-style model inference (lightweight ensemble)
• Action decisioning: APPROVE, STEP_UP, BLOCK
• HTTP scoring via FastAPI
• Streaming adapter for Kafka consumer/producer

1) Streaming Data Pipeline

Conceptual flow:

[Live Transaction] -> [Kafka Stream] -> [Feature Store] -> [ML Model Inference] -> [Action: Approve/Block]

Reference implementation mapping:

• simulator = streaming source (Kafka substitute for local demo)
• FeatureEngineer = online feature store + stream computation
• ModelEnsemble = model inference layer
• FraudMonitoringPipeline = decision engine

2) Real-Time Behavioral Features

The pipeline computes these features per transaction:

1. Velocity metrics

   • tx_count_5m: number of transactions for a card in the last 5 minutes
   • amount_sum_5m: total amount in the last 5 minutes

2. Geographic impossibility

   • Computes Haversine distance between consecutive transactions for the same card
   • Derives required speed in km/h
   • Flags impossible_travel = 1 when speed exceeds threshold (900 km/h)

3. Amount deviation

   • Rolling 30-day card spending baseline
   • amount_zscore_30d
   • amount_ratio_to_avg_30d

3) Model Strategy

The reference ModelEnsemble includes fast approximations of:

• Isolation Forest-like anomaly score
• XGBoost-like supervised score
• Autoencoder-like reconstruction error score
• Graph-risk proxy score

Final risk is a weighted aggregate in [0, 1] and mapped to actions by thresholds:

• < 0.35 -> APPROVE
• 0.35 to <0.70 -> STEP_UP
• >= 0.70 -> BLOCK

Project Structure

• src/realmonitoring/types.py — transaction, feature, score, and decision data models
• src/realmonitoring/features.py — streaming feature computation
• src/realmonitoring/models.py — ensemble scoring and risk aggregation
• src/realmonitoring/pipeline.py — end-to-end process + action decision
• src/realmonitoring/contracts.py — shared API contracts
• src/realmonitoring/transforms.py — shared payload/domain transformers
• src/realmonitoring/simulator.py — deterministic transaction stream generator
• src/realmonitoring/main.py — tiny runner for local demo
• src/realmonitoring/api.py — FastAPI app with /health and /score
• src/realmonitoring/kafka_adapter.py — Kafka adapter (consume transactions, publish decisions)
• src/realmonitoring/kafka_worker.py — CLI entrypoint for Kafka loop
• tests/test_pipeline.py — unit tests (happy path + anomaly edge cases)
• tests/test_api.py — API endpoint tests
• tests/test_kafka_adapter.py — Kafka adapter unit tests
• ARCHITECTURE.md — module boundaries and extension points
• CONTRIBUTING.md — development and contribution workflow

Modularity Notes

This codebase separates concerns by layer:

• Domain layer: types.py
• Core logic: features.py, models.py, pipeline.py
• Transport contracts: contracts.py
• Shared adapters/mappers: transforms.py
• Delivery channels: api.py, kafka_adapter.py

This structure lets HTTP and Kafka paths reuse the same fraud scoring core.

Quick Start

Prerequisites

• Python 3.10+

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run demo

PYTHONPATH=src python -m realmonitoring.main

Run tests

pytest

Run the FastAPI service

PYTHONPATH=src uvicorn realmonitoring.api:app --host 0.0.0.0 --port 8000

Example scoring request

curl -X POST http://127.0.0.1:8000/score \
   -H "Content-Type: application/json" \
   -d '{
      "transaction_id": "tx_api_001",
      "card_id": "card_abc",
      "user_id": "user_abc",
      "amount": 129.95,
      "merchant_id": "m_101",
      "merchant_category": "grocery",
      "latitude": 39.9612,
      "longitude": -82.9988,
      "timestamp": "2026-07-08T12:00:00"
   }'

Run the Kafka adapter

By default the adapter consumes from transactions.raw and produces to transactions.decision.

PYTHONPATH=src python -m realmonitoring.kafka_worker

If Kafka isn't running, you can still unit-test adapter logic with tests/test_kafka_adapter.py.

Git setup and publish

Initialize and push to your personal Git account:

git init
git add .
git commit -m "feat: modular real-time fraud monitoring reference project"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main

Expected Demo Behavior

You should see:

• Early low-risk transactions mostly APPROVE
• Later burst/high-amount/impossible-travel events becoming STEP_UP or BLOCK
• A summary with action counts and average latency

Troubleshooting

• ModuleNotFoundError: realmonitoring

  • Ensure you run with PYTHONPATH=src or install package in editable mode.

• No suspicious events in output

  • The simulator is deterministic by default, but scores may vary if you change thresholds or generator logic.

Next Extensions (Optional)

• Replace simulator with Kafka consumer/producer
• Add Redis/Feast-backed online feature store
• Serve real models via FastAPI or gRPC
• Add drift monitoring and champion/challenger model routing