Fraud Radar

Real-time transaction fraud scoring: Isolation Forest anomaly model, FastAPI scoring service, Kafka replay pipeline.

Project status. This is a learning/portfolio project, not a production fraud system. It scores synthetic transactions with a single unsupervised model and no persistence layer. See ROADMAP.md for what's built versus planned, and CONTEXT.md for the non-goals. Anyone evaluating this repo should read that distinction before the architecture diagram — the diagram describes an aspiration.

---

What this actually does today

1. Generates a synthetic dataset shaped like the Kaggle Credit Card Fraud dataset (28 PCA features, Amount, Time, Class).
2. Trains an IsolationForest on legitimate transactions only (semi-supervised — no fraud labels used at fit time).
3. Serves POST /score and POST /score/batch over FastAPI, returning a calibrated [0, 1] risk score, a LOW/MEDIUM/HIGH/CRITICAL bucket, and a flag decision.
4. Replays transactions through Kafka (transactions → scored by a consumer → scored-transactions, with a fraud-dlq for malformed messages) to simulate a live stream.
5. Pushes every scored transaction to WebSocket clients on /ws/live.

There is no database. Scores live in an in-memory rolling window and are lost on restart. There is no rule engine, no behavioral/velocity features, no authentication, and no test suite yet. This is intentional at this stage — see ARCHITECTURE.md for what's deliberately deferred and why.

Architecture

data/generate_data.py → transactions.csv
                              │
                        ml/train.py
                              │
              ml/artifacts/ (model, scaler, calibration.json)
                              │
                   api/main.py (FastAPI, loads artifacts)
                              │
        ┌─────────────────────┴─────────────────────┐
        │                                           │
  kafka/producer.py → Kafka `transactions`   direct HTTP clients
        │
  kafka/consumer.py → scores via api/scorer.py → `scored-transactions`
                                                → `fraud-dlq` (on failure)

Full detail, including the target-state diagram and what's proposed vs. shipped: ARCHITECTURE.md.

Repository layout

fraud-radar/
├── data/     synthetic data generator
├── ml/       Isolation Forest training + calibration + artifacts
├── api/      FastAPI service: schemas, scorer, routes, WebSocket
├── kafka/    producer (replay) and consumer (score + republish)
├── docs/
│   └── rfc/  design proposals before they become code
├── ARCHITECTURE.md
├── CONTEXT.md
├── AGENTS.md
├── SECURITY.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── ROADMAP.md
└── docker-compose.yml

Running it

Prerequisites: Docker + Docker Compose v2.

docker compose up --build -d

This brings up Zookeeper → Kafka → topic creation → the API (which generates data and trains the model on first boot if ml/artifacts/ is empty) → the producer and consumer, in that dependency order.

Watch the consumer score transactions in real time:

docker compose logs -f consumer

Local dev without Docker

pip install -r requirements.txt
python -m data.generate_data
python -m ml.train
uvicorn api.main:app --reload

API

curl http://localhost:8000/health
curl http://localhost:8000/stats

curl -s -X POST http://localhost:8000/score \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 8420.00, "Time": 86400,
    "V1": -3.5, "V2": 2.8,  "V3": -5.2, "V4": 4.1,
    "V5": -2.9, "V6": 1.7,  "V7": -4.3, "V8": 3.6,
    "V9":  2.1, "V10": -1.8,"V11": 3.3, "V12": -2.6,
    "V13": 4.7, "V14": -3.1,"V15": 2.4, "V16": -0.9,
    "V17": 1.2, "V18": -4.5,"V19": 3.8, "V20": -2.2,
    "V21": 4.0, "V22": -3.7,"V23": 2.7, "V24": -1.5,
    "V25": 3.1, "V26": -2.8,"V27": 1.9, "V28": -3.4,
    "merchant_id": "merch_0042", "payment_method": "CARD", "country": "US"
  }'

Swagger UI: http://localhost:8000/docs Live feed: ws://localhost:8000/ws/live (send "ping", server replies "pong")

Where this is going

See ROADMAP.md for the sequenced plan and docs/rfc/0001-decisioning-platform-v2.md for the design of the next concrete increment (behavioral state in Redis, a transparent rule layer on top of the ML score, an audit trail in Postgres, and idempotent Kafka processing).

Contributing

See CONTRIBUTING.md. See AGENTS.md if you're working in this repo with an AI coding assistant — it documents conventions the codebase already assumes.

Security

This project processes only synthetic data and has no auth layer. Do not point it at real payment data. See SECURITY.md for the vulnerability reporting process and the specific reasons this is not production-ready as-is.

License

Apache-2.0. See LICENSE.