Real-Time Fraud Detection with Hybrid Rules + Machine Learning
SentinelAI is a real-time fraud detection platform built to analyze financial transactions. By combining deterministic business heuristics with machine learning models, SentinelAI produces a composite risk assessment and streams evaluation results to an interactive monitoring dashboard with human-readable explanations.
🔥 Live Dashboard: https://sentinel-dashboard-zv4v.onrender.com
(Note: As this is hosted on a free Render tier, the backend and AI services may take up to 50 seconds to spin up from sleep if inactive).
| Live Monitoring | Case Management |
|---|---|
![]() |
![]() |
| Rule Engine | Business Impact |
![]() |
![]() |
Financial fraud cannot be stopped by static rules alone, but relying entirely on black-box machine learning can lead to unexplainable false positives. SentinelAI solves this by pairing the speed and determinism of a dynamic rule engine with the adaptability of an ensemble machine learning model. This hybrid approach allows deterministic rules to identify explicit suspicious patterns while ML models contribute probabilistic risk signals for less obvious cases.
- Real-Time Transaction Processing: Evaluates streaming mock transactions with low latency.
- Rule-Based Fraud Detection: Uses Spring Expression Language (SpEL) to run dynamic, on-the-fly heuristic rules without requiring a restart.
- Machine Learning Fraud Prediction: An ensemble of XGBoost, Random Forest, and Logistic Regression models calculate fraud probabilities.
- Composite Risk Scoring: Merges heuristic flags and ML predictions to output a final transaction risk band.
- Explainability (Feature Influence): Provides feature-level explainability (using SHAP) so human analysts know why a transaction was flagged.
- WebSocket Real-Time Updates: Streams live transaction events and system health to the frontend via STOMP/SockJS.
- PostgreSQL Persistence: Reliably stores rules, transaction history, and prediction metadata.
- ML Model Retraining: Support for dynamic, on-the-fly retraining of the machine learning models via the FastAPI service.
- Live Monitoring Dashboard: A stunning Next.js interface for viewing risk trends, rules, and live cases.
- Docker Compose Setup: Completely containerized for a one-click local deployment.
flowchart TD
TS[Transaction Simulator] --> BE[Spring Boot Backend]
subgraph BE_Process[Backend Engine]
RE[Rule Engine / SpEL]
CRE[Composite Risk Engine]
end
BE --> RE
subgraph AI[AI Service]
XGB[XGBoost]
RF[Random Forest]
LR[Logistic Regression]
end
BE --> AI
XGB & RF & LR --> AI
RE --> CRE
AI --> CRE
CRE --> DB[(PostgreSQL)]
CRE --> WS[WebSocket / STOMP]
WS --> FE[Next.js Dashboard]
SentinelAI does not rely solely on machine learning. The detection pipeline is built around three core pillars:
- Rule-Based Detection: Incoming transactions hit a deterministic rules engine first. If a transaction violates a hard business rule (e.g., amount > $10,000 and location is high-risk), it is immediately flagged.
- Machine Learning Prediction: Simultaneously, the transaction is passed to the AI microservice where an ensemble of predictive models evaluates subtle behavioral features (velocity, spending deviation).
- Composite Risk Evaluation: The Composite Risk Engine receives the deterministic rule score and the probabilistic ML score, weighing them together to calculate the final risk band and decide the transaction's fate.
The Python/FastAPI microservice handles the intelligent prediction layer using scikit-learn and xgboost. It loads pre-trained models to evaluate transaction features in real-time. The models include:
- XGBoost: For handling non-linear, high-dimensional tabular data.
- Random Forest: For robust, ensemble-based decision trees.
- Logistic Regression: For highly calibrated baseline probabilities.
- Backend: Java, Spring Boot, Spring Expression Language (SpEL), WebSocket, STOMP
- AI Service: Python, FastAPI, XGBoost, Scikit-Learn, SHAP, Pandas
- Frontend: Next.js, React, Tailwind CSS, SockJS, STOMP
- Database: PostgreSQL
- Infrastructure: Docker, Docker Compose
SentinelAI/
├── ai-service/ # Python, FastAPI, ML models, feature influence
├── backend/ # Java, Spring Boot, SpEL Rule Engine, WebSocket
├── frontend/ # Next.js, React, real-time dashboard
├── docker-compose.yml # Multi-container orchestration
└── README.md # You are here
To run the entire platform locally:
-
Clone the repository:
git clone https://github.com/MAYANK479/SentinelAI.git cd SentinelAI -
Start the containers:
docker compose up -d --build
Once the containers are successfully running, the services will be available at:
- Frontend Dashboard: http://localhost:3000
- Spring Boot Backend:
http://localhost:8080 - AI Service (Swagger UI): http://localhost:8000/docs
Note: The docker-compose.yml file contains default local-only demo credentials for PostgreSQL. For a production deployment, ensure you configure proper environment variables and secrets.
Live Deployed Endpoints (Render):
- Backend WebSocket:
wss://sentinel-backend-d1qo.onrender.com/ws
Local Development Endpoints (Docker Compose):
- AI Service Prediction:
POST http://localhost:8000/api/v1/predict - AI Service Retraining:
POST http://localhost:8000/api/v1/retrain - Backend WebSocket Endpoint:
ws://localhost:8080/ws
A core engineering focus of SentinelAI is model explainability. Black-box models are unacceptable in regulated financial environments. The AI Service uses SHAP (SHapley Additive exPlanations) to calculate the marginal contribution of each feature to the final prediction. This data is bubbled up to the Next.js frontend, allowing human risk analysts to see exactly which features drove the fraud score.
Building SentinelAI required integrating multiple languages and paradigms into a cohesive, low-latency system:
- Real-Time Streaming: Implemented STOMP over WebSockets to establish a continuous, bi-directional connection between the Java backend and Next.js frontend.
- Dynamic Rules Evaluation: Used Spring Expression Language (SpEL) to allow business users to define and update complex rules at runtime without redeploying the backend.
- Microservice Communication: Designed the backend to orchestrate synchronous REST calls to the FastAPI machine learning service while maintaining high throughput on simulated transaction streams.
- Add Kafka for more robust, distributed message streaming.
- Implement more advanced deep learning techniques (e.g., Autoencoders for anomaly detection).
- Expand the frontend dashboard with historical reporting and graphing.
Mayank Pandey GitHub Profile



