🕵️ RingNet360!

360° Financial Crime Detection Engine!
Detect money muling fraud rings from bank transaction data using graph theory algorithms, machine learning, and interactive visualization.

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Tech Stack
• Getting Started
• CSV Format
• API Reference
• Project Structure
• Detection Algorithms
• Machine Learning Pipeline
• JSON Output Format
• Contributing
• License

---

🔍 Overview

RingNet360 is a full-stack financial crime detection engine that analyzes bank transaction data to uncover hidden fraud rings, money muling patterns, and shell network structures. Upload a CSV of transactions and instantly get:

• Interactive graph visualizations of money flow
• Suspicion scores for every account
• Detected fraud rings with categorized pattern types
• Timeline animations of transaction activity
• ML-powered anomaly detection with model transparency
• Downloadable HTML investigation reports

---

✨ Features

Feature	Description
🔄 Cycle Detection	Finds circular fund routing (A→B→C→A) with leakage rate analysis
💸 Smurfing Analysis	Detects fan-in/fan-out patterns within 72-hour sliding windows
🏢 Shell Network Detection	Identifies pass-through accounts and layered shell chains
🧩 Community Detection	Louvain algorithm for dense subgroup identification
📊 Suspicion Scoring	Weighted multi-signal scoring (0–100) with false positive filtering
🕸️ Interactive Graph	D3.js force-directed graph with zoom, pan, and ring highlighting
⏱️ Timeline Animation	Chronological transaction replay with play/pause controls
📈 Analytics Dashboard	Recharts-powered charts: pattern distribution, score histogram, ring risk
🤖 ML Analysis	Random Forest classifier with ROC curves, confusion matrix, and feature importance
🧬 Behavioral Similarity	Cosine-similarity based behavioral clustering of accounts
📥 JSON Export	Download or copy-to-clipboard full analysis results
📄 HTML Reports	Generate downloadable investigation reports
✅ CSV Validation	Lightweight pre-upload validation endpoint

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Frontend                              │
│  React 19 + Vite + D3.js + Recharts + Tailwind CSS v4       │
│                                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│  │  Hero    │ │  Graph   │ │ Timeline │ │   Analytics      ││
│  │  Upload  │ │  Viz     │ │  Slider  │ │   Charts         ││
│  └────┬─────┘ └──────────┘ └──────────┘ └──────────────────┘│
│       │                                                      │
│       ▼  Axios (proxy → :8000)                              │
├─────────────────────────────────────────────────────────────┤
│                        Backend                               │
│  FastAPI + Python 3.11+                                      │
│                                                              │
│  ┌──────────────┐  ┌───────────────┐  ┌───────────────────┐ │
│  │ Graph Engine │  │ ML Engine     │  │ Report Generator  │ │
│  │  - Cycles    │  │  - Features   │  │  - HTML Template  │ │
│  │  - Smurfing  │  │  - RandomForest│ │  - PDF-ready     │ │
│  │  - Shells    │  │  - Behavioral │  │                   │ │
│  └──────┬───────┘  └───────┬───────┘  └───────────────────┘ │
│         │                  │                                 │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌───────────────────┐ │
│  │  Community   │  │   Scoring    │  │    Filters        │ │
│  │  Detection   │  │   Engine     │  │  (False Positive) │ │
│  └──────────────┘  └──────────────┘  └───────────────────┘ │
│                                                              │
│  NetworkX + Pandas + scikit-learn + python-louvain           │
└─────────────────────────────────────────────────────────────┘

---

🛠️ Tech Stack

Backend

Technology	Purpose
Python 3.11+	Core runtime
FastAPI	REST API framework
Uvicorn	ASGI server
Pandas	Data manipulation & CSV parsing
NetworkX	Graph construction & traversal
python-louvain	Community detection (Louvain)
scikit-learn	Random Forest ML pipeline

Frontend

Technology	Purpose
React 19	UI framework
Vite 7	Build tool & dev server
D3.js 7	Force-directed graph visualization
Recharts	Analytics charts & histograms
Tailwind CSS 4	Utility-first styling
Lucide React	Icon system
Axios	HTTP client

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• Node.js 18+
• npm

1. Clone the Repository

git clone https://github.com/heckerr404/CICD.git
cd CICD

2. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

The API server will start at http://localhost:8000.

3. Frontend Setup

cd frontend
npm install
npm run dev

The development server will start at http://localhost:5173.

4. Open the App

Navigate to http://localhost:5173 — the frontend proxies API calls to port 8000.

---

📁 CSV Format

Upload a CSV file with these required columns:

Column	Type	Description	Example
transaction_id	string	Unique transaction identifier	TXN001
sender_id	string	Source account ID	ACC_101
receiver_id	string	Destination account ID	ACC_202
amount	number	Transaction amount	4999.00
timestamp	datetime	When the transaction occurred	2024-01-15 10:30:00

A sample test file is provided at test-data/test_transactions.csv.

---

📡 API Reference

Health Check

GET /api/health

Response:

{ "status": "healthy", "service": "RingNet360" }

Analyze Transactions

POST /api/analyze
Content-Type: multipart/form-data
Body: file=<CSV file>

Returns the full analysis JSON (see JSON Output Format).

Validate CSV

POST /api/validate
Content-Type: multipart/form-data
Body: file=<CSV file>

Lightweight pre-upload validation. Returns { valid, errors, warnings }.

Download Report

GET /api/report?analysis_id=<uuid>

Returns a downloadable HTML investigation report.

---

📂 Project Structure

CICD/
├── backend/
│   ├── main.py                  # FastAPI server & API endpoints
│   ├── graph_engine.py          # Cycle, smurfing, shell detection
│   ├── ml_engine.py             # Random Forest ML + behavioral similarity
│   ├── community_detection.py   # Louvain community detection
│   ├── scoring.py               # Weighted suspicion scoring
│   ├── filters.py               # False positive filters
│   ├── validation.py            # CSV validation logic
│   ├── report_generator.py      # HTML report generation
│   ├── models.py                # Pydantic response models
│   ├── requirements.txt         # Python dependencies
│   └── tests/                   # Test suite
│
├── frontend/
│   ├── index.html               # Entry HTML
│   ├── package.json             # NPM dependencies
│   ├── vite.config.js           # Vite configuration
│   ├── src/
│   │   ├── App.jsx              # Root application component
│   │   ├── main.jsx             # React entry point
│   │   ├── index.css            # Global styles (Tailwind)
│   │   ├── components/
│   │   │   ├── LandingPage.jsx         # Landing / marketing page
│   │   │   ├── HeroUpload.jsx          # CSV upload with drag & drop
│   │   │   ├── SummaryCards.jsx        # Key metric cards
│   │   │   ├── GraphVisualization.jsx  # D3.js force-directed graph
│   │   │   ├── TimelineSlider.jsx      # Transaction timeline replay
│   │   │   ├── FraudRingTable.jsx      # Detected rings table
│   │   │   ├── SuspiciousTable.jsx     # Suspicious accounts table
│   │   │   ├── AnalyticsCharts.jsx     # Recharts analytics dashboard
│   │   │   ├── MLAnalysis.jsx          # ML model results viewer
│   │   │   ├── DownloadSection.jsx     # JSON/Report export
│   │   │   ├── NetworkBackground.jsx   # Animated background
│   │   │   └── Tooltip.jsx             # Reusable tooltip
│   │   ├── hooks/
│   │   │   └── useAnalysis.js          # API integration hook
│   │   └── utils/
│   │       └── formatters.js           # Formatting utilities
│   │
│   └── public/                  # Static assets
│
├── test-data/
│   └── test_transactions.csv    # Sample transaction dataset
│
├── docs/                        # Project documentation
├── .gitignore
└── README.md

---

🔬 Detection Algorithms

1. Cycle Detection

Identifies circular fund routing patterns (e.g., A→B→C→A) using DFS-based cycle enumeration on the directed transaction graph. Each cycle is analyzed for:

• Leakage rate: % of funds lost per loop iteration
• Cycle length: Number of participating accounts
• Temporal proximity: Whether transactions occurred within a tight window

2. Smurfing Detection

Detects structuring patterns using a 72-hour sliding window:

• Fan-out: One account distributing to many recipients (splitting large amounts)
• Fan-in: Many accounts converging funds into one account
• Threshold proximity: Amounts consistently near reporting thresholds (e.g., $9,999)

3. Shell Network Detection

Identifies intermediary/pass-through accounts:

• High pass-through ratio: Accounts where inflow ≈ outflow
• Layered chains: Sequential transfers through 3+ intermediaries
• Velocity analysis: Rapid receipt-and-forward patterns

4. Community Detection (Louvain)

Groups densely interconnected accounts into communities using the Louvain modularity optimization algorithm. Accounts in communities with high concentrations of flagged members receive a score boost.

5. Suspicion Scoring

Weighted multi-signal scoring algorithm (0–100):

• Pattern-based signals (cycle, smurfing, shell membership)
• Temporal clustering signals
• Amount-based signals (threshold proximity)
• Community association boost
• False positive filtering (payroll patterns, recurring bills, etc.)

---

🤖 Machine Learning Pipeline

RingNet360 includes a Random Forest classifier (RingHunter ML) that provides:

Component	Details
Model	Random Forest with cross-validation
Features	In/out degree, transaction volume, temporal spread, amount variance, flow ratio
Outputs	Per-account ML confidence scores, ROC curve, confusion matrix, feature importance
Behavioral Analysis	Cosine similarity clustering to find behaviorally similar accounts

The ML layer runs alongside the graph-based detection to provide a second independent signal, improving detection confidence.

---

📊 JSON Output Format

{
  "suspicious_accounts": [
    {
      "account_id": "ACC_101",
      "suspicion_score": 78.5,
      "detected_patterns": ["cycle", "smurfing"],
      "ring_id": "RING_001",
      "ml_confidence": 0.92
    }
  ],
  "fraud_rings": [
    {
      "ring_id": "RING_001",
      "pattern_type": "cycle",
      "member_accounts": ["ACC_101", "ACC_102", "ACC_103"],
      "risk_score": 85.0
    }
  ],
  "summary": {
    "total_accounts_analyzed": 25,
    "suspicious_accounts_flagged": 8,
    "fraud_rings_detected": 3,
    "processing_time_seconds": 0.45
  },
  "graph_data": {
    "nodes": ["..."],
    "edges": ["..."]
  },
  "timeline_data": ["..."],
  "ml_analysis": {
    "model_type": "RandomForest",
    "cross_val_accuracy": 0.94,
    "precision": 0.91,
    "recall": 0.88,
    "f1_score": 0.89,
    "confusion_matrix": {},
    "roc_curve": {},
    "feature_importance": []
  },
  "analysis_id": "uuid"
}

---

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

_{Built with ❤️ for financial crime investigators}