🔖 Introduction
About the project
FraudGuard AI is a high-performance B2B SaaS fraud detection engine designed for modern FinTech. The project addresses the "Black Box" problem in AI by providing sub-85ms transaction scoring coupled with human readable SHAP explanations. Built using FastAPI and XGBoost, it allows businesses to stop fraud without alienating legitimate customers through unexplained declines.
Dashboard view showing a real-time feed of Threat analysis, Transaction volume charts and amount of fraud prevented.
Analysis view showing a real time feed of transaction analysis, Moving beyond "black box" AI, utilizing SHAP (SHapley Additive exPlanations) to provide analysts with granular, per-factor driver breakdowns for every risk score.
Developer API Hub: A self-serve portal for generating API keys, enabling clients to integrate the REST endpoint directly into their checkout flow.
Bulk CSV Auditing: Dedicated tooling for risk teams to backtest rules by auditing up to 10,000 legacy transaction rows simultaneously.
Global Threat Map: Real-time geospatial tracking of high-risk IPs and merchant location mismatches using custom Leaflet cartography.
🤔 Problem space
Problems to solve/Requirements to Create
Fraud teams currently face a "transparency tax" they either use simple, easy to beat rules or complex AI models that provide no reasoning for their decisions.
👉 Problem 1: The "Black Box" Decline
Legacy AI models provide a risk score (e.g., 0.95) but no context. When a legitimate high value customer is blocked, support teams cannot explain why, leading to permanent churn.
Current solution: Manual review queues where analysts guess why a model triggered, often taking hours to resolve a single customer complaint.
Evidence: Industry data shows that "False Positives" cost merchants more in lost lifetime value than actual fraud losses.
👉 Problem 2: Friction in B2B API Integration & Threat Tracking Developers lack a self serve way to integrate fraud endpoints, and risk teams lack real-time visual tracking of spatial anomalies.
Current solution: Manual API key generation via email requests and reading raw IP logs instead of using visual maps.
How do we know it is a problem: Delayed onboarding for B2B clients and delayed response times to coordinated regional fraud attacks.
Goals
Company objective 🎯
To provide a transparent, developer first fraud prevention API that maximizes merchant revenue by reducing false positives and streamlining B2B integrations.
Project goals
Project goal: Achieve sub-85ms end-to-end inference latency using XGBoost.
Project goal: Implement SHAP (SHapley Additive exPlanations) for human readable risk factors.
Project goal: Build a self serve Developer API Hub, a Global Threat Map, and Bulk CSV Auditing tools for enterprise usability.
User Stories
Fraud Analyst The Analyst needs to verify why a specific transaction was flagged to decide whether to override the block.
Goals: Reduce time-to-decision for flagged transactions.
Needs: Clear, granular feature contribution charts (SHAP factors).
Developer (B2B Client) The developer needs to integrate the FraudGuard REST endpoint into their company's checkout flow.
🌟 Design space
UI Design
The interface follows a "Cyberpunk Enterprise" aesthetic: dark mode with high-contrast neon accents (Teal for safe, Red for fraud) to help analysts quickly scan data.
Low-fidelity Wireframe
High-fidelity design
Design system 🎨
Utilized ShadCN UI and Tailwind CSS. This allowed for rapid development of complex data tables and accessible modal components, ensuring the dashboard felt like a professional enterprise tool rather than a prototype.
Development Phase
Technology Stack Selection
1. Backend - FastAPI (Python)
Why? High performance with asynchronous support. It allows for the lifespan event, which ensures the XGBoost model is loaded into RAM before the server starts accepting requests, eliminating per-request load times.
2. ML Model - XGBoost & SHAP
3. Frontend - Next.js 14 (App Router)
High-Level Architecture Diagram
Built a unified inference service where FastAPI acts as the orchestrator, pulling raw data from the frontend, transforming features in-memory, and logging results to Supabase for persistence.
XGBoost Workflow and Decision Pipeline
Key Features of the Software
1. XGBoost Inference & SHAP Explainability
Decision: Chose XGBoost over deep learning for faster CPU execution, paired with SHAP to convert raw scores into actionable insights (e.g., "Velocity", "Geo-distance").
2. Developer API Hub
3. Bulk CSV Auditing & Global Threat Map
Decision: Needed enterprise tools for risk teams to backtest rules and visualize attacks.
Implementation: Engineered a CSV processing pipeline that audits up to 10,000 legacy rows simultaneously. Integrated custom Leaflet cartography for real-time geospatial tracking of IP/merchant mismatches.
4. High-Performance ML Inference Engine (FastAPI & XGBoost)
Decision: Chose a combination of FastAPI and XGBoost to handle high-frequency transaction scoring. While deep learning models are popular, XGBoost is mathematically superior for the tabular, structured data found in financial transactions and runs significantly faster on standard CPUs.
Implementation: * Utilized the FastAPI Lifespan event to load the .json model artifact into memory exactly once at server startup.
5. Explainable AI (XAI) Integration (SHAP)
Decision: Integrated SHAP (SHapley Additive Explanations) to solve the "Black Box" problem. Most fraud systems provide a score but no justification; SHAP allows us to provide a legally auditable reason for every decline.
Implementation: * The backend runs a shap.TreeExplainer on the same feature vector used for the prediction.
6. Multi-Tenant API Management & Monetization (Stripe & Clerk)
Decision: Implemented a self-serve Developer Hub using Clerk for identity and Stripe for usage-based monetization. This transforms the project from a simple script into a viable B2B SaaS product.
Implementation: * Stripe Webhooks: Integrated real-time webhooks to automatically update user quotas and "Pro" tier permissions in the Supabase (PostgreSQL) database.
Challenges Faced and Solutions
Problem:
Hosting the Python/XGBoost backend on Render's free tier meant the instance would sleep after 15 minutes of inactivity. Booting up the ML model upon waking caused unacceptable latency (ruining the sub-85ms SLA).
Solution:
Implemented a Keep-Awake Heartbeat:
Implemented a zero-logic /api/v1/ping endpoint in FastAPI.
Configured cron-job.org to ping this endpoint every 14 minutes.
Result: The Render instance stays warm 24/7, keeping the XGBoost model loaded in memory and ensuring instantaneous, sub-85ms inference for all requests.
Future Vision / next steps
Long-term vision
V2: Implementation of custom "Rules Engine" UI where users can override ML decisions with hard-coded logic.
V3: Real-time WebSocket alerts for Analysts when high-value fraud spikes occur.
UI Activities: Add a "Dark Web" monitoring tab that alerts users if their customers' emails appear in recent data breaches.
Get visibility from recruiters & peers