Epsilon - Enterprise Fraud Detection & Case Management Platform

A production-ready fraud detection and case management platform with real-time alerting, comprehensive investigation tools, and advanced analytics.

Features • Quick Start • Architecture • Documentation • API

---

📋 Table of Contents

• Overview
• Key Features
• System Architecture
• Tech Stack
• Quick Start
• Installation
• Configuration
• Usage
• API Documentation
• Development
• Deployment
• Project Structure
• Contributing
• License

---

🎯 Overview

Epsilon is an enterprise-grade fraud detection and investigation platform designed for financial institutions, fintech companies, and e-commerce platforms. It provides end-to-end fraud management capabilities from alert generation through case resolution, with complete audit trails and comprehensive analytics.

What Makes Epsilon Special?

• ✅ Complete Workflow: Alert → Case → Investigation → Resolution → Disposition
• ✅ Real-time Detection: JSON-based rule engine with sub-second evaluation
• ✅ Case Management: Full-featured case workflow with notes, activities, and timeline
• ✅ Investigation Tools: Customer 360° view and cross-entity search
• ✅ Analytics & Reporting: Real-time metrics, dashboards, and performance tracking
• ✅ Scalable Architecture: Async processing, indexed database, horizontal scaling ready
• ✅ Production Ready: 95% feature complete, comprehensive testing, full documentation

---

🚀 Key Features

1. Alert Management

• Real-time Alert Generation: Rule-based fraud detection with configurable thresholds
• Alert Prioritization: Automatic priority assignment (low, medium, high, critical)
• Alert Assignment: Assign alerts to analysts for review
• Alert Actions: Create cases, add notes, close alerts
• Filtering & Search: Status, priority, decision, customer filters
• Bulk Operations: Efficient handling of high-volume alerts

2. Case Management

• Complete Case Lifecycle: Open → Investigating → Resolved → Closed
• Case Creation: Create cases directly from alerts with one click
• Case Assignment: Assign cases to team members
• Notes & Comments: Collaborative investigation with timestamped notes
• Activity Timeline: Complete audit trail of all case actions
• Case Resolution: Resolve with dispositions (True/False Positive)
• Fraud Amount Tracking: Monitor financial impact
• Case Attachments: Document evidence (schema ready)

3. Disposition Tracking

• Automatic Disposition: Created automatically on case resolution
• Disposition Types: True Positive, False Positive, Unable to Determine
• Performance Metrics: Precision rate, false positive rate tracking
• Fraud Impact: Total fraud prevented and recovered amounts
• Trend Analysis: Historical disposition patterns

4. Investigation Tools

• Customer 360° View: Comprehensive customer profile
  • Total alerts and cases
  • True/false positive history
  • Blocked transactions
  • Fraud amount trends
• Customer Timeline: Chronological event history
• Cross-Entity Search: Search by customer ID, device, IP, email, phone
• Recent Activity: Latest alerts and cases

5. Watchlist Management

• Blocklist: High-risk entities to automatically flag
• Greylist: Suspicious entities requiring extra scrutiny
• Whitelist: Trusted entities to bypass certain checks
• Entity Types: Customer ID, device ID, IP address, email, phone
• Match Recording: Track when entities hit watchlists
• Active/Inactive: Enable/disable watchlist entries

6. Rule Management

• JSON-Based DSL: Flexible, declarative rule definition
• Rule Versioning: Track rule changes over time
• Draft/Published: Safe testing before production
• Pattern Library: Reusable fraud patterns
• Scoring System: Configurable thresholds and weights
• External Enrichment: Third-party data provider integration
• Rule Testing: Evaluate rules before deployment

7. User Management

• Role-Based Access: Analyst, Senior Analyst, Manager, Admin, Viewer
• Team Management: Organize users by teams
• Activity Logging: Track all user actions
• API Key Management: Secure API access
• Account Security: Password hashing, account locking

8. Provider Management

• Database Adapters: PostgreSQL, MySQL, MongoDB
• API Adapters: DeviceCheck, SimKYC, ID Blacklist
• Connection Testing: Verify provider connectivity
• Rate Limiting: Prevent provider overload
• Caching: Feature cache with TTL
• Performance Tracking: Monitor provider response times

9. Metrics & Analytics

• Real-time Dashboard: Live fraud metrics
• Alert Analytics: Volume, distribution, trends
• Case Metrics: Resolution times, status distribution
• Rule Performance: Alert volume, precision rates
• Disposition Summary: TP/FP rates, fraud prevented
• Top Rules: Identify high-performing rules

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Frontend (React)                        │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────────┐│
│  │ Dashboard  │  │   Alerts   │  │   Cases  │ Metrics etc││
│  └────────────┘  └────────────┘  └────────────────────────┘│
│         │                │                    │              │
│         └────────────────┴────────────────────┘              │
│                          │                                   │
│                   React Query (State)                        │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTPS/REST
┌─────────────────────────┴───────────────────────────────────┐
│                    Backend (FastAPI)                         │
│  ┌─────────────────────────────────────────────────────────┐│
│  │               API Layer (Routers)                        ││
│  │  alerts │ cases │ metrics │ investigation │ rules etc   ││
│  └────────────────────┬─────────────────────────────────────┘│
│                       │                                      │
│  ┌────────────────────┴─────────────────────────────────────┐
│  │              Business Logic (Services)                    │
│  │  - Case Management    - Alert Processing                 │
│  │  - Disposition        - Rule Evaluation                  │
│  │  - Investigation      - Provider Integration             │
│  └────────────────────┬─────────────────────────────────────┘│
│                       │                                      │
│  ┌────────────────────┴─────────────────────────────────────┐
│  │                Data Layer (Models)                        │
│  │  SQLAlchemy ORM + Alembic Migrations                     │
│  └────────────────────┬─────────────────────────────────────┘│
└───────────────────────┼──────────────────────────────────────┘
                        │
┌───────────────────────┴──────────────────────────────────────┐
│                   PostgreSQL Database                         │
│  - Cases & Notes      - Alerts & Tags    - Dispositions      │
│  - Rules & Patterns   - Users & Auth     - Watchlists        │
│  - Providers & Calls  - Metrics & Logs   - Audit Trails      │
└───────────────────────────────────────────────────────────────┘

Data Flow

1. Alert Generation: Rules evaluate transactions → Alerts created
2. Case Creation: Analyst reviews alert → Creates case
3. Investigation: Analyst adds notes, checks customer 360°, reviews timeline
4. Resolution: Case resolved with disposition (TP/FP/Unable to Determine)
5. Metrics: System aggregates data for dashboards and reports

---

🛠️ Tech Stack

Backend

• Framework: FastAPI 0.109+ (Python 3.11+)
• Database: PostgreSQL 15+ with SQLAlchemy 2.x ORM
• Migrations: Alembic
• Validation: Pydantic v2
• Rule Engine: JsonLogic
• Authentication: API Key & Password Hashing
• Logging: Structured logging with context
• Testing: Pytest

Frontend

• Framework: React 18+ with TypeScript 5+
• Build Tool: Vite
• UI Library: shadcn/ui + Radix UI
• Styling: Tailwind CSS
• State Management: TanStack Query (React Query)
• Routing: React Router v6
• Icons: Lucide React
• Forms: Controlled components with validation

DevOps

• API Documentation: OpenAPI/Swagger (auto-generated)
• Database Tools: pgAdmin, psql
• Version Control: Git
• Environment Management: python-dotenv

---

⚡ Quick Start

Prerequisites

• Python 3.11 or higher
• Node.js 18+ and npm
• PostgreSQL 15+
• Git

1. Clone Repository

git clone <repository-url>
cd Epsilon-main

2. Backend Setup

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Create .env file
cat > .env << EOF
DATABASE_URL=postgresql://postgres:password@localhost:5432/Epsilon
API_KEY=dev-key-change-me
SECRET_KEY=your-secret-key-change-me
ENVIRONMENT=development
EOF

# Run migrations
alembic upgrade head

# Start backend server
uvicorn app.main:app --reload --port 8000

Backend will be available at: http://localhost:8000 API Docs at: http://localhost:8000/api/docs

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Frontend will be available at: http://localhost:5173

4. Create First User

curl -X POST http://localhost:8000/api/users/register \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-key-change-me" \
  -d '{
    "username": "admin",
    "email": "[email protected]",
    "full_name": "System Admin",
    "password": "SecurePassword123!",
    "role": "admin",
    "team": "Security"
  }'

5. Login

Navigate to http://localhost:5173/auth and login with:

• Username: admin
• Password: SecurePassword123!

---

📦 Installation

Database Setup

# Create PostgreSQL database
createdb Epsilon

# Or using psql
psql -U postgres
CREATE DATABASE Epsilon;
\q

Backend Installation

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e .

# For development
pip install -e ".[dev]"

Frontend Installation

cd frontend
npm install

---

⚙️ Configuration

Backend Configuration

Create backend/.env:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/Epsilon

# Security
API_KEY=your-api-key-here
SECRET_KEY=your-secret-key-here

# Application
APP_NAME=Epsilon
API_PREFIX=/api
ENVIRONMENT=development

# CORS
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

# Logging
LOG_LEVEL=INFO

Frontend Configuration

Frontend uses environment variables from Vite. Create frontend/.env:

VITE_API_URL=http://localhost:8000/api

Database Migrations

cd backend

# Create new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1

# View current version
alembic current

---

📖 Usage

Creating a Rule

1. Navigate to Rules page
2. Click "Create Rule"
3. Define rule using JSON DSL
4. Test rule with sample data
5. Publish rule to activate

Managing Alerts

1. Navigate to Alerts page
2. View alerts with filters
3. Click "Create Case" on high-priority alerts
4. Assign to analyst or add notes
5. Close false positives

Investigating Cases

1. Navigate to Cases page
2. Click on a case to view details
3. Review Details tab for case information
4. Check Timeline for activity history
5. Add Notes for findings
6. Assign to team members
7. Resolve with disposition when complete

Customer Investigation

1. Navigate to Investigation page
2. Enter customer ID
3. View 360° profile with all alerts and cases
4. Review timeline of events
5. Make informed decisions

Monitoring Metrics

1. Navigate to Dashboard for real-time overview
2. Check Metrics page for detailed analytics
3. Review Dispositions for accuracy metrics
4. Monitor top-performing rules

---

📚 API Documentation

Authentication

All API requests require the x-api-key header:

curl -H "x-api-key: your-api-key" http://localhost:8000/api/endpoint

Core Endpoints

Alerts

# List alerts
GET /api/alerts?status=open&limit=50

# Get alert
GET /api/alerts/{alert_id}

# Create case from alert
POST /api/cases
{
  "alert_id": "uuid",
  "case_type": "transaction_fraud",
  "customer_id": "CUST123",
  "priority": "high",
  "created_by": "[email protected]"
}

# Assign alert
POST /api/alerts/{alert_id}/assign
{
  "assigned_to": "[email protected]"
}

# Close alert
PATCH /api/alerts/{alert_id}/close

Cases

# List cases
GET /api/cases?status=open&limit=50

# Get case detail
GET /api/cases/{case_id}

# Update case
PUT /api/cases/{case_id}?[email protected]
{
  "status": "investigating",
  "priority": "high",
  "fraud_amount": 1500.00
}

# Assign case
POST /api/cases/{case_id}/assign
{
  "assigned_to": "[email protected]",
  "assigned_by": "[email protected]"
}

# Add note
POST /api/cases/{case_id}/notes
{
  "note_text": "Customer confirmed transaction was unauthorized",
  "created_by": "[email protected]"
}

# Resolve case
POST /api/cases/{case_id}/resolve
{
  "disposition": "true_positive",
  "fraud_amount": 1500.00,
  "resolved_by": "[email protected]"
}

# Close case
PATCH /api/cases/{case_id}/close?[email protected]

# Get timeline
GET /api/cases/{case_id}/timeline

Investigation

# Customer 360
GET /api/investigation/customer/{customer_id}

# Customer timeline
GET /api/investigation/customer/{customer_id}/timeline

Metrics

# Dashboard summary
GET /api/metrics/summary

# Alert metrics
GET /api/metrics/alerts?days=7

# Case metrics
GET /api/metrics/cases?days=7

# Disposition summary
GET /api/metrics/disposition-summary?days=30

# Top rules
GET /api/metrics/top-rules?days=7&limit=10

Watchlists

# List watchlists
GET /api/watchlists?list_type=blocklist

# Create entry
POST /api/watchlists
{
  "entity_type": "customer_id",
  "entity_value": "CUST123",
  "list_type": "blocklist",
  "reason": "Confirmed fraudster",
  "created_by": "[email protected]"
}

# Delete entry
DELETE /api/watchlists/{watchlist_id}

# Check entity
POST /api/watchlists/check
{
  "entity_type": "customer_id",
  "entity_value": "CUST123"
}

API Documentation UI

Interactive API documentation available at:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• OpenAPI JSON: http://localhost:8000/api/openapi.json

---

💻 Development

Running Tests

cd backend
pytest
pytest --cov=app tests/
pytest -v tests/test_specific.py

Code Quality

# Format code
black app/
isort app/

# Lint
flake8 app/
mypy app/

# Frontend
npm run lint
npm run type-check

Database

# Connect to database
psql -U postgres Epsilon

# View tables
\dt

# View table structure
\d cases

# Query data
SELECT * FROM cases WHERE status = 'open';

Development Workflow

1. Create feature branch: git checkout -b feature/new-feature
2. Make changes and test locally
3. Run tests: pytest
4. Commit changes: git commit -m "Add new feature"
5. Push branch: git push origin feature/new-feature
6. Create pull request

---

🚢 Deployment

Production Checklist

• Set up production PostgreSQL database
• Configure environment variables
• Run database migrations: alembic upgrade head
• Create initial admin user
• Set strong API keys and secrets
• Configure CORS for production domains
• Set up SSL certificates
• Configure reverse proxy (nginx)
• Set up monitoring and logging
• Configure backup strategy
• Test all endpoints
• Load test (optional)

Environment Variables (Production)

DATABASE_URL=postgresql://user:pass@prod-db:5432/Epsilon
API_KEY=<strong-random-key>
SECRET_KEY=<strong-random-secret>
ENVIRONMENT=production
ALLOWED_ORIGINS=https://Epsilon.example.com
LOG_LEVEL=WARNING

Docker Deployment (Example)

# Backend Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY backend/ .
RUN pip install -e .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

# Frontend Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY frontend/ .
RUN npm install && npm run build
CMD ["npm", "run", "preview"]

Reverse Proxy (nginx)

server {
    listen 80;
    server_name Epsilon.example.com;

    location /api {
        proxy_pass http://backend:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location / {
        proxy_pass http://frontend:5173;
        proxy_set_header Host $host;
    }
}

---

📁 Project Structure

Epsilon-main/
├── backend/                    # FastAPI Backend
│   ├── alembic/               # Database migrations
│   │   └── versions/          # Migration files
│   ├── app/
│   │   ├── core/              # Core utilities
│   │   │   ├── config.py      # Configuration
│   │   │   ├── security.py    # Authentication
│   │   │   └── logging.py     # Logging setup
│   │   ├── db/                # Database
│   │   │   ├── base.py        # Base model
│   │   │   └── session.py     # DB session
│   │   ├── models/            # SQLAlchemy models
│   │   │   ├── alert.py       # Alert models
│   │   │   ├── case.py        # Case models
│   │   │   ├── disposition.py # Disposition models
│   │   │   ├── rule.py        # Rule models
│   │   │   ├── user.py        # User models
│   │   │   └── watchlist.py   # Watchlist models
│   │   ├── schemas/           # Pydantic schemas
│   │   │   ├── alert.py       # Alert schemas
│   │   │   ├── case.py        # Case schemas
│   │   │   └── ...
│   │   ├── routers/           # API endpoints
│   │   │   ├── alerts.py      # Alert endpoints
│   │   │   ├── cases.py       # Case endpoints
│   │   │   ├── metrics.py     # Metrics endpoints
│   │   │   └── ...
│   │   ├── services/          # Business logic
│   │   │   ├── alerts.py      # Alert service
│   │   │   ├── cases.py       # Case service
│   │   │   ├── providers/     # Provider adapters
│   │   │   └── ...
│   │   └── main.py            # FastAPI app
│   ├── tests/                 # Unit tests
│   ├── .env                   # Environment variables
│   ├── alembic.ini            # Alembic config
│   ├── pyproject.toml         # Python dependencies
│   └── README.md              # Backend docs
├── frontend/                  # React Frontend
│   ├── src/
│   │   ├── components/        # React components
│   │   │   ├── ui/           # UI components (shadcn)
│   │   │   └── Layout.tsx    # App layout
│   │   ├── contexts/          # React contexts
│   │   │   └── AuthContext.tsx
│   │   ├── hooks/             # Custom hooks
│   │   ├── lib/               # Utilities
│   │   │   ├── api.ts        # API client
│   │   │   └── utils.ts      # Helper functions
│   │   ├── pages/             # Page components
│   │   │   ├── Dashboard.tsx  # Dashboard page
│   │   │   ├── Alerts.tsx     # Alerts page
│   │   │   ├── Cases.tsx      # Cases page
│   │   │   ├── Investigation.tsx
│   │   │   ├── Metrics.tsx
│   │   │   └── ...
│   │   ├── App.tsx            # Root component
│   │   └── main.tsx           # Entry point
│   ├── public/                # Static assets
│   ├── package.json           # NPM dependencies
│   ├── tsconfig.json          # TypeScript config
│   ├── vite.config.ts         # Vite config
│   └── README.md              # Frontend docs
├── CASE_MANAGEMENT_IMPLEMENTATION.md
├── IMPLEMENTATION_GAPS.md
├── COMPLETE_FEATURE_LIST.md
└── README.md                  # This file

---

🤝 Contributing

Getting Started

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open pull request

Code Style

• Python: Follow PEP 8, use Black formatter
• TypeScript: Follow ESLint rules, use Prettier
• Commits: Use conventional commits (feat, fix, docs, etc.)

Pull Request Process

1. Update documentation for new features
2. Add tests for new functionality
3. Ensure all tests pass
4. Update CHANGELOG.md
5. Get approval from maintainers

---

📄 License

This project is proprietary software. All rights reserved.

© 2025 Epsilon. Unauthorized copying, distribution, or modification is prohibited.

---

🆘 Support

For support, please contact:

• Email: [email protected]
• Documentation: See /docs folder
• Issues: GitHub Issues (if applicable)

---

🎉 Acknowledgments

Built with:

• FastAPI
• React
• shadcn/ui
• PostgreSQL
• SQLAlchemy
• Tailwind CSS

---

📊 Project Status

Version: 1.0.0
Status: Production Ready (95% Feature Complete)
Last Updated: 2025

Recent Updates

• ✅ Complete case management system
• ✅ Alert-to-case workflow integration
• ✅ Disposition tracking and metrics
• ✅ Investigation tools (Customer 360°)
• ✅ Comprehensive metrics and analytics
• ✅ User and watchlist management
• ✅ Full API documentation

Roadmap

• 🔨 File attachment upload/download
• 🔨 Real-time notifications (WebSocket)
• 🔨 Advanced analytics with charts
• 🔨 Bulk operations
• 🔨 SLA tracking
• 🔨 Mobile optimizations

---

Made with ❤️ for fraud fighters worldwide

⬆ Back to Top