🛡️ Fraud Detection Engine

Real-Time Fraud Detection using Apache Kafka · Redis · Spring Boot · WebSocket

---

What is this?

An enterprise-grade real-time fraud detection system that analyses every financial transaction in under 100ms using a multi-signal scoring engine, Kafka event streaming, Redis velocity checks, and an adaptive feedback loop that gets smarter over time.

Payment arrives → Kafka → Fraud Scorer (5 signals) → Decision Engine → APPROVED / FLAGGED / BLOCKED
                                                                               ↓
                                                               Live WebSocket alert to analyst dashboard
                                                                               ↓
                                                               Analyst feedback → rule weights adapt

---

Tech Stack

Layer	Technology
Language	Java 17
Framework	Spring Boot 3.2
Event Streaming	Apache Kafka 3.7 (KRaft mode)
Cache	Redis 7.2
Database	MySQL 8.0
Real-time	WebSocket + STOMP
Auth	JWT (jjwt 0.11.5)
API Docs	Swagger UI
Infrastructure	Docker Compose

---

Quick Start

1. Start all infrastructure with Docker

docker-compose up -d

This starts MySQL, Redis, and Kafka — all configured and ready.

Verify:

docker-compose ps
# All 3 should show "healthy"

2. Run the Spring Boot app

mvn spring-boot:run

App starts at http://localhost:8081

On first run you will see:

Seeded 5 default rule weights
Seeded default users: admin / analyst1
Started FraudEngineApplication on port 8081

3. Open Swagger UI

http://localhost:8081/swagger-ui

4. Open the live dashboard

http://localhost:8081/dashboard.html

---

Test the System — Step by Step

Step 1 — Login

POST /api/auth/login
{
  "username": "admin",
  "password": "admin123"
}

Copy the JWT token from the response.

Step 2 — Submit a normal transaction (expect: APPROVED)

POST /api/transactions
Authorization: Bearer YOUR_TOKEN
{
  "userId": "user-mandeep",
  "amount": 500,
  "currency": "INR",
  "merchantId": "flipkart",
  "merchantCategory": "ELECTRONICS",
  "userLocation": "Mumbai, IN",
  "ipAddress": "103.21.58.12"
}

Check status: GET /api/transactions/{transactionId}/status

Step 3 — Trigger velocity fraud (expect: BLOCKED)

Send the same request 6 times quickly for the same userId. After the 6th, the score exceeds 70 → auto-blocked.

Step 4 — Trigger geo fraud (expect: FLAGGED/BLOCKED)

# First send from India:
"userLocation": "Mumbai, IN"

# Then immediately send from UK for same userId:
"userLocation": "London, UK"

Step 5 — High risk merchant (expect: FLAGGED)

"merchantCategory": "CRYPTO"
# or: "GAMBLING", "WIRE_TRANSFER", "GIFT_CARDS"

Step 6 — Watch it on the live dashboard

1. Open http://localhost:8081/dashboard.html
2. Paste your JWT token → click Connect
3. Submit transactions in Swagger
4. Watch alerts appear live in the dashboard

Step 7 — Submit analyst feedback

Click "Review" on any flagged/blocked alert in the dashboard. Mark as Confirmed Fraud or False Positive. Then check GET /api/analyst/rule-weights — the weights will have changed.

---

API Endpoints

Auth (public)

Method	Endpoint	Description
POST	/api/auth/login	Login → get JWT token

Transactions (protected)

Method	Endpoint	Description
POST	/api/transactions	Submit payment for fraud analysis
GET	/api/transactions/{id}/status	Check fraud decision
GET	/api/transactions	List all transactions
GET	/api/transactions/pending-review	List flagged + blocked
GET	/api/transactions/user/{userId}	Transactions by user

Analyst (protected)

Method	Endpoint	Description
POST	/api/analyst/feedback	Submit fraud / false positive verdict
GET	/api/analyst/cases	List open fraud cases
GET	/api/analyst/rule-weights	View adaptive scoring weights
GET	/api/analyst/dashboard	Summary statistics

---

Fraud Scoring Signals

Signal	Weight	Triggers when
Velocity check	40 pts	>5 transactions in 60 seconds
Geo anomaly	35 pts	Transaction from different country than usual
Amount anomaly	25 pts	Amount is 3x+ above user's average
High-risk merchant	20 pts	CRYPTO, GAMBLING, WIRE_TRANSFER, GIFT_CARDS
New IP address	15 pts	IP never seen for this user before

Thresholds: Score 0–30 = APPROVED · 31–70 = FLAGGED · 71–100 = BLOCKED

---

Default Credentials

User	Password	Role
admin	admin123	ADMIN
analyst1	analyst123	ANALYST

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Spring Boot App                          │
│                                                             │
│  REST API → TransactionIngestor → Kafka: transactions.raw   │
│                                          ↓                  │
│                              FraudScorer (5 signals)        │
│                              + Redis velocity/baseline       │
│                                          ↓                  │
│                         Kafka: transactions.scored          │
│                                          ↓                  │
│                              DecisionEngine                 │
│                              → MySQL (save result)          │
│                              → WebSocket broadcast          │
│                                          ↓                  │
│                         Analyst Dashboard (live)            │
│                              → Feedback API                 │
│                              → Kafka: feedback.labels       │
│                                          ↓                  │
│                         FeedbackService (adapt weights)     │
└─────────────────────────────────────────────────────────────┘

---

Author

Mandeep Pathak LinkedIn · GitHub