FraudShield-AI
Deployed fraud-risk platform with causal features, hybrid model inference, a Vercel console, Render API, and CI-gated releases.
FraudShield-AI scores payment transactions through a hybrid XGBoost, feedforward neural network, and causal LSTM pipeline served by FastAPI, containerized for Render, and exposed through a Vercel-hosted review console.
Evidence
Case Study Highlights
0.9767
holdout average precision
95.76%
fraud recall
0.051%
false-positive rate
64
CI-validated tests
Context
Problem and ownership
FraudShield-AI is now a deployed transaction-risk system, not only an offline feature pipeline. The public console at fraudai.yusufadamu.dev sends same-origin requests through Vercel functions, which attach the protected backend credential server-side and forward scoring traffic to a Dockerized FastAPI service on Render.
My role
Built the causal feature pipeline, model training and fusion workflow, inference runtime, public review UI, Docker deployment path, and CI release gates.
Constraints
What shaped the solution
- Online scoring has to reproduce the offline causal contract: no future rows, no same-timestamp leakage, and no cross-request mutation of behavioral state.
- The browser must never receive the Render API key, so prediction and feedback calls are proxied through server-side Vercel functions.
- The container needs a compact runtime payload with fitted models, reports, preprocessor, velocity state, and sequence context, while excluding raw CSVs and training matrices.
- Render and Vercel releases need to stay aligned to the same Git commit before production inference is treated as healthy.
Architecture
System design and request flow
The system combines an offline model-building path with an online inference path. Offline jobs create causal features, train-fitted preprocessing, model-data partitions, XGBoost/FNN/LSTM artifacts, a validation-selected hybrid configuration, drift references, and a compact runtime bundle. Online requests load those artifacts once, validate raw transactions, reconstruct static and sequence features, and return component probabilities plus the fused fraud decision.
Request and Data Flow
- 1Chronological CSV streams and digest-bound feature/preprocessing artifacts
- 2Validation-ranked XGBoost, FNN, and causal LSTM model reports
- 3Log-odds hybrid fusion with frozen F2 decision threshold
- 4Compact deployment/runtime bundle with 11 verified files
- 5FastAPI process-lifetime artifact load inside a non-root Docker image
- 6Vercel static console and same-origin API proxy
- 7Render backend release, Vercel frontend release, and routed prediction smoke test
Core Components
- app/api.py exposes health, authenticated predict, and feedback endpoints with CORS, API-key enforcement, bounded batches, and process-lifetime model loading.
- app/scoring.py validates raw transactions, derives event clocks, applies causal velocity state, transforms sparse features, assembles sequence tensors, and returns XGBoost, FNN, LSTM, and fused probabilities.
- web/ contains the Vercel-hosted console, CSV parser, safe DOM rendering, feedback controls, and server-side proxy functions for health, predict, and feedback.
- .github/workflows/deploy.yml runs tests, verifies runtime artifacts, smokes the Docker image, triggers Render and Vercel, checks release identity, and executes a routed authenticated prediction.
Technical decisions
Key choices and why they mattered
Separated browser delivery from model inference
Vercel serves the static console and owns the public custom domain, while Render runs the Dockerized CPU inference service. The browser calls same-origin functions, and only those functions attach the backend API key.
Used a compact integrity-bound runtime bundle
The production image copies only 11 manifest-registered runtime files totaling roughly 2.83 MB, then startup verifies model, preprocessor, velocity, and sequence-context fingerprints before reporting ready.
Fused complementary model families at validation time
XGBoost, static FNN, and causal LSTM probabilities are combined in log-odds space with a frozen validation-selected F2 threshold, then evaluated on the holdout without reselecting parameters.
Trade-offs
What the design optimizes for and gives up
- Render free-tier deployment keeps operating cost low, but feedback persistence is instance-local until a paid persistent disk is attached at /var/lib/fraudshield.
- Running one Uvicorn worker avoids duplicating XGBoost and PyTorch memory, but it places concurrency pressure on a single warm CPU process.
- The public UI makes manual and CSV review easy, but the Vercel proxy intentionally hides backend details and returns bounded generic upstream errors.
Production readiness
Reliability, security, and delivery evidence
- GitHub Actions runs the complete pytest suite, verifies the compact inference payload, loads registered production models, and builds the Docker image before deployment hooks run.
- The container pins Python 3.13 slim by digest, installs CPU inference dependencies in a builder venv, runs as UID/GID 10001, and exposes a health check that requires model readiness.
- Production release health is tied to the Git commit: CI waits until the Render backend and Vercel proxy both expose the expected release before running routed inference.
- Feedback is written through an explicit SQLite ledger and does not retrain, replace, or mutate active model artifacts automatically.
Results
What changed because of the work
- Deployed a live review console showing release c82a2db1, holdout average precision 0.9767, fraud recall 95.76%, and false-positive rate 0.051%.
- Served real-time single and CSV-batch scoring through a FastAPI response contract that returns component scores, final risk, threshold, context depth, and top XGBoost drivers.
- Implemented CI gates that block release reporting unless tests, artifact verification, container smoke inference, backend release identity, frontend release identity, and routed prediction all pass.
Next improvements
Where I would take it next
- Attach a Render persistent disk or external managed store before treating public reviewer feedback as durable production data.
- Add rate limiting and structured request tracing around Vercel proxy functions and FastAPI prediction endpoints.
- Version feedback export and retraining intake so model replacement remains governed by the same artifact and release checks.