authentication
user-dashboard_3
user-dashboard_2
institution-network-page
institution-dashbord-page
institution-dashbord-page_2
user-dashboard
database-setup

SurakshaFlow — Project Story

About the Project

SurakshaFlow is a real-time intelligence platform that fuses Security Operations Center (SOC) signals with Anti-Money Laundering (AML) monitoring to detect and disrupt money mule networks and financial scams. The name "SurakshaFlow" combines the Hindi word "Suraksha" (security) with "Flow" (representing transaction flows), embodying our mission to secure financial transactions through intelligent monitoring.

What Inspired Us

The inspiration came from the alarming rise in digital financial fraud in India and globally. With the rapid adoption of UPI, digital wallets, and online banking, cybercriminals have evolved sophisticated money mule networks that exploit the gap between traditional cybersecurity monitoring and financial fraud detection systems.

Key Motivating Factors

Fragmented detection systems: Banks typically monitor financial transactions separately from cyber signals (logins, device fingerprints, IP geolocation), missing the correlation that reveals mule networks
Delayed response times: Traditional fraud detection often acts post-facto, after funds have already been laundered through multiple accounts
Lack of explainability: Compliance officers receive alerts without clear explanations, leading to investigation delays
The human cost: Behind every fraud statistic are real victims—elderly individuals scammed out of life savings, small business owners deceived by phishing attacks

What We Learned

Building SurakshaFlow taught us invaluable lessons across multiple domains:

1. Graph Theory & Network Analysis

How to model financial transactions as directed graphs using NetworkX
Applying centrality metrics (PageRank, betweenness, degree centrality) to identify key nodes in mule networks
Community detection using the Louvain algorithm to uncover organized fraud rings

2. Machine Learning for Fraud Detection

Feature engineering for temporal graph data (extracting 20+ node-level features)
Training gradient boosting classifiers on synthetic graph topologies (star graphs for kingpins, chain structures for mules)
The challenge of achieving realistic accuracy—intentionally adding label noise (~3%) to avoid overfitting

3. Multi-Modal Risk Scoring

$$\text{Unified Score} = 0.30 \times \text{Cyber} + 0.25 \times \text{Financial} + 0.20 \times \text{Graph} + 0.25 \times \text{ML}$$

This weighted fusion formula balances traditional rule-based scoring with modern ML predictions.

4. Explainable AI

Prompt engineering for Gemini AI to generate actionable compliance explanations
Building fallback rule-based systems when AI APIs are unavailable
Rate limiting strategies (5 calls/minute) to manage API quotas

5. Real-Time Systems

Implementing live simulation with 5-second polling intervals
Managing in-memory state for dynamic graph updates
Structured logging with timing metrics for all API calls

How We Built the Project

Architecture Overview

┌─────────────────┐       /api proxy        ┌──────────────────┐
│  React Frontend │ ──────────────────────── │  FastAPI Backend  │
│  localhost:3000  │                          │  localhost:8000   │
└─────────────────┘                          └──────────────────┘
        │                                            │
        │                                   ┌────────┴────────┐
        │                                   │  Risk Engines   │
        ▼                                   │  • Cyber        │
   Firebase Auth                            │  • Financial    │
   Firebase Firestore                       │  • Graph (NX)   │
   Gemini AI (client)                       │  • Unified      │
                                            └─────────────────┘

Development Journey

Phase 1: Foundation (Backend Core)

Set up FastAPI with structured logging middleware
Built the data generator with realistic attack chain scenarios
Implemented the three risk engines:
- Cyber Engine: Detects impossible travel, phishing, new device logins, device reuse across accounts
- Financial Engine: Flags rapid layering, high-velocity transactions, circular fund flows
- Graph Engine: Constructs transaction graphs, labels nodes (victim/mule/kingpin), computes risk scores

Phase 2: ML Integration

Created TemporalGraphFeatureExtractor with 20 features per node
Generated synthetic training data simulating different fraud topologies
Built TemporalGNNClassifier using Gradient Boosting as a practical GNN equivalent
Implemented incremental retraining with graph hash-based deduplication

Phase 3: Frontend Development

React 19 with TypeScript for type safety
Tailwind CSS 4 for the dark-themed cyber-aesthetic UI
D3.js for interactive network graph visualization
Recharts for risk trend visualization
Real-time simulation hook polling every 5 seconds

Phase 4: AI & Explainability

Gemini AI integration for natural language explanations
SMS scam detection for end-user protection
Email phishing analysis with urgency detection, link analysis, and impersonation patterns
STR (Suspicious Transaction Report) PDF generation using fpdf2

Phase 5: Digital Twin Simulation

"What-if" freeze scenarios to find optimal intervention points
BFS-based downstream exposure calculation
Prevention metrics showing money saved by SurakshaFlow

Challenges We Faced

1. Balancing ML Complexity with Practicality

Aspect	Description
Initial Plan	Full PyTorch Geometric GNN with message passing
Reality	Heavy dependencies, complex deployment
Solution	Graph-aware classifier using NetworkX features + sklearn GradientBoosting—equivalent detection with simpler deployment

2. Achieving Realistic Model Accuracy

Aspect	Description
Problem	Synthetic data produced near-perfect training accuracy (>99%)
Solution	Added Gaussian noise (5% scale) and flipped ~3% of labels to simulate real-world uncertainty
Result	Honest test accuracy of ~85-92%

3. Managing Gemini API Rate Limits

Aspect	Description
Constraint	5 calls per minute on free tier
Solutions	• Implemented sliding window rate limiter • Cached explanations by SHA-256 hash of prompt • Built comprehensive rule-based fallbacks

4. Dynamic Graph Updates

Aspect	Description
Challenge	Rebuilding the transaction graph on every live event without performance degradation
Solution	Bounded transaction lists (keep last 400), hash-based deduplication for retraining

5. Type Safety Across Full Stack

Aspect	Description
Challenge	Maintaining consistent types between Python backend and TypeScript frontend
Solution	Pydantic models with `model_dump(mode="json")` for serialization, mirrored TypeScript interfaces

6. Firebase Configuration Graceful Degradation

Aspect	Description
Challenge	Application should work in demo mode without Firebase credentials
Solution	Demo-mode fallback with generated profiles, conditional Firebase initialization

Key Technical Achievements

Component	Technology	Innovation
Graph Analysis	NetworkX + Louvain	Automatic mule/kingpin labeling via structural heuristics
ML Classifier	sklearn GradientBoosting	20-feature node embedding with synthetic augmentation
Unified Scoring	Custom weighted fusion	Dynamic ML weight adjustment (25% when available)
Live Simulation	5-second polling	Real-time dashboard updates with ML/non-ML scenarios
Explainability	Gemini 2.5 Flash Lite	JSON-structured AI explanations with confidence scores
STR Generation	fpdf2	Auto-generated compliance reports with risk breakdowns

Technologies Used

Languages

TypeScript — Frontend application logic
Python — Backend API and ML models

Frontend Frameworks & Libraries

React 19 — UI component framework
React Router DOM 7 — Client-side routing
Tailwind CSS 4 — Utility-first styling
Lucide Icons — Icon library
Motion — Animation library
D3.js 7 — Network graph visualization
Recharts 3 — Charts and data visualization

Backend Frameworks

FastAPI — REST API framework
Uvicorn — ASGI server

Database & Cloud Services

Firebase Authentication — User authentication
Firebase Firestore — NoSQL database
Firebase Storage — File storage

AI & Machine Learning

Google Gemini API (gemini-2.5-flash-lite) — Explainable AI, SMS/email scam detection
scikit-learn — GradientBoostingClassifier, StandardScaler
NetworkX 3.4.2 — Graph construction and analysis
python-louvain 0.16 — Community detection

Data Processing & Utilities

NumPy 1.26.4 — Numerical computations
Pydantic 2.10.4 — Data validation and serialization
fpdf2 2.8.3 — PDF report generation
httpx 0.28.1 — HTTP client
python-dotenv 1.0.1 — Environment configuration

Build & Development Tools

Vite 6 — Frontend build tool
TypeScript 5.8 — Type safety
@vitejs/plugin-react — React HMR
@tailwindcss/vite — Tailwind integration

API Endpoints

Method	Endpoint	Description
`GET`	`/api/health`	Health check
`GET`	`/api/dashboard/bank/summary`	Bank dashboard summary stats
`GET`	`/api/dashboard/bank/alerts`	List alerts (filterable)
`GET`	`/api/dashboard/bank/alert/{id}`	Single alert detail
`POST`	`/api/dashboard/bank/alert/{id}/action`	Act on alert (freeze/monitor/escalate)
`GET`	`/api/dashboard/user/{uid}/risk`	User risk score breakdown
`GET`	`/api/dashboard/user/{uid}/events`	User cyber + financial events
`GET`	`/api/graph/network`	Full transaction graph
`GET`	`/api/graph/cluster/{id}`	Subgraph around account
`POST`	`/api/gemini/explain`	AI explanation for alert
`POST`	`/api/gemini/analyze-sms`	SMS scam detection
`POST`	`/api/str/generate/{id}`	Generate STR report PDF
`GET`	`/api/str/download/{id}`	Download STR report
`POST`	`/api/simulation/digital-twin`	Run digital twin simulation
`POST`	`/api/demo/seed`	Re-seed demo data
`POST`	`/api/demo/run-scenario`	Load attack chain scenario

Project Impact

SurakshaFlow demonstrates how unified cyber-financial intelligence can proactively detect and disrupt fraud networks before victims suffer irreversible losses. By combining graph analytics, machine learning, and explainable AI, we bridge the gap between traditional SOC monitoring and AML compliance—creating a platform that is both powerful and actionable for financial institutions.