Skip to content

README.md

Latest commit

 

History

History
301 lines (240 loc) · 12.3 KB

README.md

File metadata and controls

301 lines (240 loc) · 12.3 KB

RISKOFF - Complete Implementation Walkthrough

Project: RISKOFF - A Fintech Platform for Risk Assessment and Loan Management

RISKOFF is an AI-powered smart lending platform that automates loan processing, risk assessment, and financial management. It integrates machine learning for risk scoring, parses financial documents for verification, and provides user-friendly interfaces for customers and admins. This README provides a comprehensive overview of the implementation, building upon the previous RISKON + VisualPe framework with enhanced features, security, and integrations.

🌟 Features

Customer-Facing Features

  • 📊 Financial Dashboard: Visualize income, expenses, investments, and spending patterns.
  • 📄 Bank Statement Upload: Auto-parse and categorize transactions from CSV uploads with identity verification.
  • 🎯 Customer Score: AI-calculated creditworthiness score (0-900) based on DTI, expenses, and risk rules.
  • 💰 Loan Application: Apply for Personal, Home, Car, Education, or Business loans with instant AI assessment.
  • 📋 Loan Tracking: Real-time status updates and history.
  • ❓ Grievance System: AI-generated explanations for approvals/rejections.
  • 🤖 AI Chat Agent: Contextual responses for loan queries.
  • 🎙️ Voice-to-Text Engine: Users can apply for loans using voice notes. The system uses Gemini 1.5 Flash to transcribe audio directly into structured loan queries.
  • 📤 File Uploads: Support for receipts (images), bank statements (CSV), and audio transcription.

Admin-Facing Features

  • 📈 Dashboard: Overview stats (loans by status, total volume).
  • 🤖 Auto-Processing: Auto-approve low-risk, auto-reject high-risk loans.
  • 🔍 Risk Analysis: Detailed ML-based assessment with fraud detection.
  • 🚨 Fraud Detection: Flags mismatches in expenses or identities.
  • 💬 AI Responses: Automated grievance explanations and notifications.
  • 👨‍💼 Role-Based Access: Admin-only endpoints for loan review and updates.

Core Capabilities

  • AI-Powered Risk Engine: EMI calculation and rule-based scoring.
  • Document Parsing: AI extraction for receipts, statements, and audio.
  • Notifications: Email alerts via Gmail SMTP.
  • Audit Logging: Track all actions for compliance.
  • Security: JWT auth, rate limiting, CORS, and headers.

📦 Technology Stack

Component Technology/Framework
Backend FastAPI (Python)
Frontend React.js, TailwindCSS, Recharts
Database Supabase (PostgreSQL)
AI/LLM Google Gemini 1.5 Flash
ML Model Scikit-learn (Random Forest)
Authentication Supabase Auth (JWT + OTP)
Email Gmail SMTP
Containerization Docker
Other Libraries Pandas (parsing), Fuzzywuzzy (verification), SlowAPI (rate limiting)

📁 Project Structure

riskoff/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py          # FastAPI entry point + middleware
│   │   ├── config.py        # Supabase + Gemini initialization
│   │   ├── schemas.py       # Pydantic models for validation
│   │   ├── routers/
│   │   │   ├── auth.py      # Authentication endpoints
│   │   │   ├── loans.py     # Loan application endpoints
│   │   │   ├── upload.py    # File upload (CSV, images, audio)
│   │   │   ├── admin.py     # Admin panel endpoints
│   │   │   └── agent.py     # AI chat agent
│   │   ├── services/
│   │   │   ├── risk_engine.py # EMI + Risk score calculation
│   │   │   ├── parser.py    # CSV/Image/Audio parsing + identity verification
│   │   │   ├── llm.py       # Gemini AI text generation
│   │   │   ├── notification.py # Email notifications (SMTP/Mock)
│   │   │   └── audit.py     # Audit logging
│   │   └── utils/
│   │       └── security.py  # JWT verification, auth dependencies
│   ├── tests/               # Test files
│   ├── requirements.txt     # Python dependencies
│   ├── Dockerfile           # Production Docker setup
│   ├── .dockerignore        # Docker build exclusions
│   └── .env                 # Environment secrets
├── frontend/
│   ├── src/                 # React source code
│   ├── public/              # Public assets
│   ├── package.json         # Node dependencies
│   └── ...                  # Other frontend files
├── .gitignore
└── README.md                # This file

🌐 API Endpoints Reference

🔐 Authentication (/auth)

Method Endpoint Auth Required Description
POST /auth/signup ❌ Register new user
POST /auth/login ❌ Login → returns JWT tokens
POST /auth/login/form ❌ OAuth2 login for Swagger
POST /auth/logout ✅ Sign out current user
POST /auth/refresh ❌ Refresh access token
GET /auth/me ✅ Get current user profile

💰 Loans (/loans)

Method Endpoint Auth Required Description
POST /loans/apply ✅ Submit loan application with AI assessment
GET /loans/my-loans ✅ Get user's loan history
GET /loans/ ❌ (Admin) Get all loans (admin view)
GET /loans/{loan_id} ❌ (Admin) Get specific loan

Loan Application Flow:

  1. User submits amount, tenure, income, expenses, purpose.
  2. Risk Engine calculates EMI and risk score.
  3. Gemini AI generates approval/rejection message.
  4. Loan saved to Supabase loans table.
  5. Action logged to audit_logs.

📤 Uploads (/upload)

Method Endpoint Auth Required Description
POST /upload/receipt Optional Upload receipt image → AI extracts data
POST /upload/bank-statement ✅ Upload CSV → parses with verification
POST /upload/receipt/save ✅ Save verified receipt to database
POST /upload/audio/transcribe ✅ Transcribe voice notes to text using Gemini

Features:

  • Receipt Parsing: Gemini Vision extracts merchant, amount, date, category.
  • Bank Statement Parsing: Pandas-based auto-categorization (Food, Transport, etc.).
  • Identity Verification: Fuzzy name matching (60% threshold).
  • Audio Transcription: Gemini for voice input on loan queries.

👨‍💼 Admin (/admin)

Method Endpoint Auth Required Description
GET /admin/stats Admin Dashboard stats (loans, volume)
GET /admin/loans Admin Get all loans for review
PATCH /admin/loans/{loan_id}/status Admin Update loan status + email notification

Admin Features:

  • Role-based access (profiles.role = 'admin').
  • Email notifications on status changes.
  • Audit logging for actions.

🤖 AI Agent (/agent)

Method Endpoint Auth Required Description
POST /agent/chat ✅ Chat with AI Bank Manager

What it does:

  • Fetches user's loan data.
  • Generates contextual responses using Gemini.

🏠 System Endpoints

Method Endpoint Description
GET / API status
GET /health Health check (API + DB)

⚙️ Core Services

  1. Risk Engine (risk_engine.py):

    • EMI Calculation: EMI = P × r × (1+r)^n / ((1+r)^n - 1).
    • Risk Scoring Rules:
      • DTI > 40%: +30 points.
      • DTI > 60%: +50 points (replaces 30).
      • Expenses > 70% of income: +20 points.
      • DTI > 50% AND Expenses > 80%: ×1.5 multiplier.
    • Result: Score > 50 = REJECTED, else APPROVED.

  2. Parser Service (parser.py):

    • Bank Statement: Pandas parsing, auto-categorization.
    • Receipts: Gemini Vision extraction.
    • Audio: Gemini transcription.
    • Identity: Fuzzy matching (60% threshold).

  3. LLM Service (llm.py):

    • Functions: Loan summaries, rejection/approval messages, chat responses, spending analysis.
    • Singleton for unified imports.

  4. Notification Service (notification.py):

    • Gmail SMTP (mock mode for dev).
    • Status update emails.

  5. Audit Service (audit.py):

    • Logs to audit_logs table.
    • Non-blocking design.

🔒 Security Implementation

Feature Implementation
Authentication Supabase Auth + JWT + OTP
Rate Limiting SlowAPI (60/min)
Security Headers X-Content-Type-Options, X-Frame-Options, HSTS
CORS Configured (allow all origins)
Role-Based Access Admin dependency checks
Identity Verification Fuzzy name matching for uploads

🗄️ Database Schema (Supabase)

Table Purpose
loans Loan applications (status, score, EMI)
profiles User profiles (name, phone, role)
transactions Parsed financial transactions
bank_statements Uploaded statement records
audit_logs Action audit trail

🐳 Docker Setup

Dockerfile (for backend):

FROM python:3.11-slim
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

.dockerignore:

__pycache__
*.pyc
venv/
.env
.git
.pytest_cache
tests/

Build & Run (for backend):

# Build image
docker build -t riskoff-backend .
# Run container
docker run -d -p 8000:8000 --env-file .env --name riskoff-api riskoff-backend

🚀 Running Locally

Backend Setup

  1. Navigate to backend: cd backend
  2. Create virtual environment: python -m venv venv
    • Activate: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows)
  3. Install dependencies: pip install -r requirements.txt
  4. Set up .env with: 
    SUPABASE_URL=your_url
SUPABASE_KEY=your_key
GEMINI_API_KEY=your_key
SMTP_EMAIL=your_email
SMTP_PASSWORD=your_password
  5. Run server: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

  1. Navigate to frontend: cd frontend
  2. Install dependencies: npm install
  3. Run: npm start

Access:

🔐 Demo Accounts

Role Email Password
Admin admin@riskoff.com admin123
User user@test.com user123

✅ Implementation Summary

All components (FastAPI backend, React frontend, Supabase, Auth, Risk Engine, AI, Parsing, Admin, Agent, Notifications, Audit, Docker, Security) are complete and tested.

ARCHITECTURE DIAGRAM

image

VIMEO LINK

https://vimeo.com/1152642038?fl=ip&fe=ec https://vimeo.com/1152642490?fl=ip&fe=ec

📄 License

MIT License