🛡️ FraudShield — AI-Powered Fraud Detection Dashboard

A production-grade, real-time fraud detection platform with AI-powered risk scoring, analyst workflows, and live transaction monitoring.

Features · Tech Stack · Architecture · Setup · API Reference

---

📌 Overview

FraudShield is a full-stack MERN application that simulates a real-world payment fraud detection system. Every incoming transaction is analyzed by an AI engine (Groq + Llama 3) that computes a risk score from 0–100, flags suspicious activity, and surfaces actionable alerts for human analysts to review.

The system mirrors workflows used at fintech companies like Razorpay, PayU, and Stripe — where ML-based risk scoring is combined with analyst review queues to minimize false positives while catching genuine fraud.

Built to demonstrate: real-time systems design, AI integration, REST API architecture, MongoDB aggregation pipelines, and production-grade React UI patterns.

---

✨ Features

🤖 AI Fraud Engine

• Risk scoring (0–100) on every transaction using Groq AI (Llama 3)
• Factors analyzed: transaction amount, time of day, merchant reputation, user history, location anomaly, device type, payment method
• Automatic model fallback chain — if one Groq model hits rate limits, the engine silently retries with the next available model
• Rule-based fallback — if AI is unavailable, a deterministic scoring engine kicks in so the system never goes dark

📊 Real-Time Dashboard

• Live transaction feed via Socket.io — zero polling
• 7-day fraud trend (bar chart), risk distribution (pie chart), volume by payment method
• Stats: total transactions, flagged count, pending reviews, confirmed fraud, total volume

🚨 Alert Management

• Prioritized queue of flagged transactions sorted by risk score
• One-click analyst actions: Confirm Fraud, False Positive, Approve
• AI Explain button — asks the AI to explain in plain English why a transaction was flagged
• Real-time badge counter on sidebar updates without page refresh

💳 Transaction Management

• Full CRUD with server-side filtering, search, and pagination
• Review modal with inline risk score breakdown, flagging reasons, and analyst notes
• Audit trail: every decision is stamped with analyst name and timestamp

🏪 Merchant Risk Profiling

• Fraud rate per merchant auto-calculated from transaction history
• Dynamic risk levels (Low / Medium / High / Critical) based on fraud rate thresholds
• Blacklist / unblacklist merchants — blacklisted merchants automatically increase risk score on new transactions

🤖 AI Analyst Chat

• Conversational interface backed by Groq AI with full transaction context injected into every query
• Suggested questions for quick analysis
• Maintains conversation history for multi-turn dialogue

---

🏗️ Tech Stack

Layer	Technology	Reason
Frontend	React 18, React Router v6	Component model, client-side routing
State Management	React Context API	Lightweight — no Redux overhead needed
Charts	Recharts	Composable, React-native charting
Real-Time	Socket.io Client	Bi-directional event streaming
Backend	Node.js + Express.js	Non-blocking I/O, ideal for event-driven systems
Database	MongoDB Atlas + Mongoose	Flexible schema, powerful aggregation pipeline
Authentication	JWT + bcryptjs	Stateless auth, bcrypt salt rounds: 12
AI / LLM	Groq API (Llama 3.1, Llama 3, Mixtral)	Free tier, fastest inference available (~500 tok/s)
Real-Time Server	Socket.io	Push fraud alerts to all connected dashboards instantly
Validation	express-validator	Schema-level request validation

---

🏛️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     React Frontend                       │
│   Dashboard │ Transactions │ Alerts │ Merchants │ AI     │
│                  Socket.io Client                        │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP + WebSocket
┌────────────────────────▼────────────────────────────────┐
│                  Express.js Backend                      │
│                                                          │
│  /api/auth         /api/transactions   /api/merchants   │
│  /api/alerts       /api/ai                              │
│                                                          │
│  ┌──────────────────────────────┐                       │
│  │       Fraud Engine           │                       │
│  │  1. Build transaction prompt │                       │
│  │  2. Call Groq AI (w/fallback)│                       │
│  │  3. Parse risk score 0-100   │                       │
│  │  4. Rule-based fallback      │                       │
│  └──────────────┬───────────────┘                       │
│                 │                                        │
│  Socket.io ─────┤ Emit: new_transaction, fraud_alert    │
└─────────────────┼────────────────────────────────────────┘
                  │
┌─────────────────▼────────────────────────────────────────┐
│               MongoDB Atlas                               │
│   users │ transactions │ merchants                        │
└──────────────────────────────────────────────────────────┘
                  │
┌─────────────────▼────────────────────────────────────────┐
│                  Groq AI API                              │
│   llama-3.1-8b-instant → llama3-8b-8192 → mixtral       │
│                  (fallback chain)                         │
└──────────────────────────────────────────────────────────┘

Key Design Decisions

Why Socket.io over polling? Fraud alerts are time-sensitive. A polling interval of even 5 seconds means an analyst might miss a critical transaction window. Socket.io pushes events the instant a transaction is processed, keeping every connected dashboard in sync.

Why a model fallback chain? Free-tier AI APIs have per-minute and per-day quota limits. Rather than failing with a 429 error, the fraud engine silently retries with the next model in the chain (llama-3.1-8b-instant → llama3-8b-8192 → mixtral-8x7b-32768). If all AI models are exhausted, a deterministic rule-based engine takes over — the system never returns an error to the user.

Why MongoDB aggregation pipelines? Dashboard stats (fraud rates, 7-day trends, category breakdowns) are computed server-side using MongoDB's $group, $match, and $sort stages rather than fetching all documents and calculating in JavaScript. This keeps response times fast even with large datasets.

---

📁 Project Structure

fraud-detection/
│
├── backend/
│   ├── middleware/
│   │   └── auth.js                 # JWT verification middleware
│   ├── models/
│   │   ├── User.js                 # Analyst accounts (bcrypt hashed passwords)
│   │   ├── Transaction.js          # Core transaction schema with risk fields
│   │   └── Merchant.js             # Merchant profiles with fraud rate tracking
│   ├── routes/
│   │   ├── auth.js                 # Register, login, /me
│   │   ├── transactions.js         # CRUD, stats aggregation, analyst review
│   │   ├── merchants.js            # List, blacklist toggle
│   │   ├── alerts.js               # Flagged transaction queue
│   │   └── ai.js                   # Explain transaction, analyst chat
│   ├── services/
│   │   └── fraudEngine.js          # AI scoring logic + model fallback chain
│   ├── seed/
│   │   └── seedData.js             # 200 realistic transactions + demo users
│   ├── server.js                   # Express app + Socket.io setup
│   ├── package.json
│   └── .env.example
│
└── frontend/
    ├── public/
    │   └── index.html
    └── src/
        ├── context/
        │   └── AuthContext.jsx     # Global auth state (login/logout/token)
        ├── utils/
        │   └── api.js              # Axios instance + all API call functions
        ├── components/
        │   └── Layout.jsx          # Sidebar nav + Socket.io live badge updates
        ├── pages/
        │   ├── Login.jsx           # Auth with demo credential shortcut
        │   ├── Register.jsx        # New analyst registration
        │   ├── Dashboard.jsx       # Stats + charts + live feed counter
        │   ├── Transactions.jsx    # Full table with filters, review modal
        │   ├── Alerts.jsx          # Fraud alert queue with AI explain
        │   ├── Merchants.jsx       # Merchant risk grid + blacklist controls
        │   └── AIAnalyst.jsx       # Chat interface with context injection
        ├── App.jsx                 # Router + protected/public route guards
        ├── index.js
        └── index.css               # Full dark-mode design system (no UI lib)

---

⚙️ Setup

Prerequisites

• Node.js 16+
• MongoDB Atlas account (free) — cloud.mongodb.com
• Groq API key — console.groq.com

Step 1 — Clone

git clone https://github.com/yourusername/fraud-detection.git
cd fraud-detection

Step 2 — Backend

cd backend
npm install
cp .env.example .env

Edit .env:

MONGO_URI=mongodb+srv://<user>:<password>@cluster0.xxxxx.mongodb.net/fraud-detection
JWT_SECRET=your_long_random_secret_here_minimum_32_chars
GROQ_API_KEY=gsk_your_groq_key_here
PORT=5000
FRONTEND_URL=http://localhost:3000

Step 3 — Seed the Database

Populates MongoDB with 200 realistic transactions across 10 merchants and 5 users, with a realistic mix of low/medium/high/critical risk scores.

npm run seed

Expected output:

✅ Connected to MongoDB
🗑️  Cleared existing data
✅ Seeded 10 merchants
✅ Seeded 200 transactions
✅ Updated merchant fraud stats
✅ Created demo user: analyst@demo.com / demo1234
🎉 Seed complete!

Step 4 — Start Backend

npm run dev
# ✅ MongoDB connected
# 🚀 Server running on port 5000

Step 5 — Frontend

cd ../frontend
npm install
npm start
# Opens http://localhost:3000

Step 6 — Login

Email:    analyst@demo.com
Password: demo1234

---

📡 API Reference

Authentication

Method	Endpoint	Auth	Description
POST	/api/auth/register	—	Create analyst account
POST	/api/auth/login	—	Login, returns JWT
GET	/api/auth/me	✅	Get current user profile

Transactions

Method	Endpoint	Auth	Description
GET	/api/transactions	✅	List with filters: riskLevel, isFlagged, status, search, page, limit
GET	/api/transactions/stats	✅	Dashboard stats + 7-day trend + risk distribution
GET	/api/transactions/:id	✅	Single transaction detail
POST	/api/transactions	✅	Create transaction — triggers AI fraud scoring
PUT	/api/transactions/:id/review	✅	Submit analyst decision (Approved, Confirmed Fraud, False Positive)

Merchants

Method	Endpoint	Auth	Description
GET	/api/merchants	✅	List with filters: riskLevel, search
GET	/api/merchants/:merchantId	✅	Single merchant profile
PUT	/api/merchants/:merchantId/blacklist	✅	Toggle blacklist status

Alerts

Method	Endpoint	Auth	Description
GET	/api/alerts	✅	Pending flagged transactions, sorted by risk score
GET	/api/alerts/summary	✅	Count by risk level (for sidebar badge)

AI

Method	Endpoint	Auth	Description
POST	/api/ai/explain	✅	Plain-English explanation of why a transaction was flagged
POST	/api/ai/chat	✅	Conversational fraud analyst with transaction context

Socket.io Events

Event	Direction	Payload	Description
new_transaction	Server → Client	Transaction object	Fires on every new transaction
fraud_alert	Server → Client	Transaction object	Fires when isFlagged: true
transaction_reviewed	Server → Client	Updated transaction	Fires after analyst review

---

🔒 Security

• All private routes protected with JWT middleware — unauthenticated requests return 401
• Passwords hashed with bcryptjs at 12 salt rounds
• JWT tokens expire after 30 days
• CORS restricted to FRONTEND_URL environment variable only
• Request body validation on all POST/PUT routes via express-validator
• .env excluded from version control via .gitignore — secrets never committed

---