🔖 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.
Goals: Quick API integration and automated billing.
Needs: A Developer API Hub to instantly generate/revoke API keys and manage Stripe subscription tiers.
🌟 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
lifespanevent, 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
Why? XGBoost is the gold standard for tabular fraud data. SHAP provides the mathematical "ground truth" for why a prediction was made, turning a black box into a white box.
3. Frontend - Next.js 14 (App Router)
Why? Server side rendering for the dashboard ensures fast initial loads, while Clerk provides instant, secure authentication.
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
Decision: Built a self-serve portal for API key generation.
Implementation: Integrated Clerk and Stripe webhooks so clients can manage their own API keys and subscription quotas securely.
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
.jsonmodel artifact into memory exactly once at server startup.This architecture ensures that incoming POST requests do not pay the "disk-read tax" for the model, maintaining a strict end-to-end latency of sub-85ms.
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.TreeExplaineron the same feature vector used for the prediction.It returns a structured
risk_factorsobject to the frontend, mapping raw feature names to human-readable insights (e.g., convertingvelocity_1hinto "High transaction frequency").
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.
Secure API Keys: Developed a hashing logic for API keys, allowing users to generate and revoke keys for their own applications via the FraudGuard dashboard.
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/pingendpoint in FastAPI.Configured
cron-job.orgto 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.
