🚀 Hawkins Fraud Detection System - Local Setup Guide

Complete guide to download, setup, and run the Hawkins Fraud Detection System on your local machine.

📦 Project Overview

Hawkins Fraud Detection System is a Next.js TypeScript application with Supabase backend integration featuring:

Real-time fraud detection and analytics
WhatsApp-based transaction approval system
Customer and corporate dashboards
AI-powered fraud reasoning
Secure authentication and authorization

🎯 Prerequisites

Before starting, ensure you have the following installed:

Required Software

Node.js: v18.x or higher (Download)
npm: v9.x or higher (comes with Node.js)
Git: Latest version (Download)
Code Editor: VS Code recommended (Download)

Verify Installation

node --version  # Should show v18.x or higher
npm --version   # Should show v9.x or higher
git --version   # Should show git version

📥 Step 1: Download Project

Option A: Download ZIP (Easiest)

Navigate to your project repository
Click Code → Download ZIP
Extract the ZIP file to your desired location
Open terminal/command prompt in the extracted folder

Option B: Clone via Git

git clone <your-repository-url>
cd hawkins-fraud-detection

🔧 Step 2: Install Dependencies

Navigate to the project root directory and install all required packages:

# Install all npm dependencies
npm install

# This will install:
# - Next.js 14.2.0
# - React 18.2.0
# - TypeScript
# - Tailwind CSS
# - Supabase client
# - All other dependencies from package.json

Expected output:

added 342 packages, and audited 343 packages in 45s

🔐 Step 3: Configure Environment Variables

3.1 Create Environment File

Copy the example environment file:

# Create .env.local file in project root
cp .env .env.local

3.2 Configure Supabase Connection

Get your Supabase credentials:

Go to Supabase Dashboard
Select your project (or create new one)
Navigate to Settings → API
Copy the following values:

Update .env.local file:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

# Optional: Twilio WhatsApp Integration
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886

3.3 Environment Variable Reference

Variable	Required	Description
`NEXT_PUBLIC_SUPABASE_URL`	✅ Yes	Your Supabase project URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	✅ Yes	Supabase anonymous/public key
`TWILIO_ACCOUNT_SID`	❌ No	Twilio Account SID (for WhatsApp)
`TWILIO_AUTH_TOKEN`	❌ No	Twilio Auth Token (for WhatsApp)
`TWILIO_WHATSAPP_NUMBER`	❌ No	Twilio WhatsApp number

Note: WhatsApp integration is optional. The app will work without it, but WhatsApp approval features will be disabled.

🗄️ Step 4: Setup Supabase Database

4.1 Run Database Migrations

The project includes SQL migration files to set up your database schema:

Option A: Via Supabase Dashboard (Recommended)

Go to Supabase Dashboard → SQL Editor
Open supabase/migrations/20251204173053_create_whatsapp_approvals.sql
Copy the entire SQL content
Paste into SQL Editor and click Run

Option B: Via Supabase CLI

# Install Supabase CLI (if not installed)
npm install -g supabase

# Login to Supabase
supabase login

# Link your project
supabase link --project-ref your-project-ref

# Run migrations
supabase db push

4.2 Database Schema Overview

The migration creates the following tables:

whatsapp_approvals - WhatsApp approval tracking
transactions - Transaction records
users - User authentication
fraud_scores - ML fraud detection scores

🚀 Step 5: Run the Application

5.1 Start Development Server

npm run dev

Expected output:

> hawkins-fraud-detection@0.1.0 dev
> next dev

- ready started server on 0.0.0.0:3000, url: http://localhost:3000
- event compiled client and server successfully in 2.5s (502 modules)

5.2 Access the Application

Open your browser and navigate to:

http://localhost:3000

Available Routes:

/login - Login page
/customer-dashboard - Customer view
/corporate-dashboard - Corporate/admin view
/transaction-review - Transaction review interface
/fraud-analytics - Fraud analytics dashboard
/transaction-submission - Submit new transactions

🔒 Step 6: Setup Authentication (Optional)

6.1 Enable Email Authentication in Supabase

Go to Supabase Dashboard → Authentication → Providers
Enable Email provider
Configure email templates (optional)

6.2 Create Test User

-- Run in Supabase SQL Editor
INSERT INTO auth.users (email, encrypted_password, email_confirmed_at)
VALUES (
  'test@example.com',
  crypt('password123', gen_salt('bf')),
  NOW()
);

📱 Step 7: Setup WhatsApp Integration (Optional)

7.1 Prerequisites

Twilio account (Sign up)
WhatsApp Business API access

7.2 Configure Twilio

Follow the detailed guide in TWILIO_SETUP_GUIDE.md

Quick Setup:

Get Twilio credentials from console.twilio.com
Add credentials to .env.local
Deploy Supabase Edge Functions:

supabase functions deploy send-whatsapp-approval
supabase functions deploy check-whatsapp-approval
supabase functions deploy whatsapp-webhook

🛠️ Troubleshooting

Common Issues and Solutions

Issue 1: Port 3000 Already in Use

# Solution 1: Kill the process using port 3000
npx kill-port 3000

# Solution 2: Use a different port
npm run dev -- -p 3001

Issue 2: Supabase Connection Error

Error: Invalid Supabase URL or key

Solution:

Verify .env.local has correct credentials
Check Supabase project is active
Ensure no extra spaces in environment variables
Restart development server after changing .env.local

Issue 3: Module Not Found Errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Issue 4: TypeScript Compilation Errors

# Rebuild TypeScript
npm run build

Issue 5: Tailwind CSS Not Working

# Verify tailwind.config.js exists
# Restart dev server
npm run dev

📂 Project Structure

hawkins-fraud-detection/
├── public/                          # Static assets
│   ├── assets/images/              # Image files
│   └── favicon.ico                 # Site favicon
├── src/
│   ├── app/                        # Next.js app directory
│   │   ├── api/                    # API routes
│   │   ├── login/                  # Login page
│   │   ├── customer-dashboard/     # Customer dashboard
│   │   ├── corporate-dashboard/    # Corporate dashboard
│   │   ├── fraud-analytics/        # Analytics page
│   │   ├── transaction-review/     # Review interface
│   │   └── transaction-submission/ # Transaction form
│   ├── components/                 # Reusable components
│   │   ├── ui/                     # UI components
│   │   └── common/                 # Shared components
│   ├── contexts/                   # React contexts
│   ├── lib/                        # Library configurations
│   ├── styles/                     # Global styles
│   └── utils/                      # Utility functions
├── supabase/
│   ├── functions/                  # Edge functions
│   └── migrations/                 # Database migrations
├── .env.local                      # Environment variables (create this)
├── next.config.mjs                 # Next.js configuration
├── package.json                    # Dependencies
├── tailwind.config.js              # Tailwind configuration
└── tsconfig.json                   # TypeScript configuration

🎨 Available Scripts

# Development
npm run dev          # Start development server on localhost:3000

# Production Build
npm run build        # Create optimized production build
npm run start        # Start production server

# Code Quality
npm run lint         # Run ESLint for code quality checks

# Type Checking
npx tsc --noEmit    # Check TypeScript types without emitting files

🔍 Testing the Application

1. Test Login Flow

Navigate to http://localhost:3000/login
Enter test credentials
Should redirect to dashboard

2. Test Customer Dashboard

Navigate to http://localhost:3000/customer-dashboard
Submit a quick transaction
View transaction history

3. Test WhatsApp Approval (if configured)

Submit transaction requiring approval
Check WhatsApp for approval message
Reply "Yes it's me" to approve

4. Test Analytics Dashboard

Navigate to http://localhost:3000/fraud-analytics
View fraud trend charts
Check model performance metrics

📊 Performance Optimization

Development Mode

Hot Module Replacement (HMR) enabled
Fast Refresh for React components
Source maps for debugging

Production Mode

# Build for production
npm run build

# This will:
# - Optimize JavaScript bundles
# - Minify CSS and HTML
# - Generate static assets
# - Create optimized images

🔐 Security Best Practices

Environment Variables

✅ Never commit .env.local to Git
✅ Use strong Supabase RLS policies
✅ Rotate API keys regularly
✅ Use HTTPS in production

Authentication

✅ Enable email verification
✅ Implement rate limiting
✅ Use secure session management
✅ Enable MFA for admin accounts

📝 Additional Documentation

Twilio Setup: See TWILIO_SETUP_GUIDE.md
API Documentation: See API_REFERENCE.md (if available)
Deployment Guide: See DEPLOYMENT.md (if available)

🆘 Getting Help

Resources

Next.js Documentation: https://nextjs.org/docs
Supabase Documentation: https://supabase.com/docs
TypeScript Documentation: https://www.typescriptlang.org/docs
Tailwind CSS Documentation: https://tailwindcss.com/docs

Common Support Channels

GitHub Issues (if project is on GitHub)
Stack Overflow (tag: nextjs, supabase, typescript)
Supabase Discord Community

✅ Verification Checklist

Before considering setup complete, verify:

🎉 Success!

Your Hawkins Fraud Detection System is now running locally!

Next Steps:

Explore different dashboards and features
Configure WhatsApp integration (optional)
Customize styling and branding
Add custom fraud detection rules
Deploy to production (Vercel recommended)

📦 Creating Production Build

When ready to deploy:

# Create optimized production build
npm run build

# Test production build locally
npm run start

# Deploy to Vercel (recommended)
npm install -g vercel
vercel

🔄 Keeping Updated

To update dependencies:

# Check for outdated packages
npm outdated

# Update all packages to latest compatible versions
npm update

# Update to latest major versions (careful!)
npx npm-check-updates -u
npm install

Last Updated: December 4, 2025 Version: 1.0.0 Minimum Node Version: 18.x

FilesExpand file tree

LOCAL_SETUP_GUIDE.md

Latest commit

History