Skip to content

PROJECT_REPORT.md

Latest commit

 

History

History
533 lines (443 loc) · 15.6 KB

PROJECT_REPORT.md

File metadata and controls

533 lines (443 loc) · 15.6 KB

CrediGig - Full Project Report

Generated: January 25, 2026 Repository: Disumakadiya/DU_Hacks
Branch: urval

📊 PROJECT OVERVIEW

CrediGig is a modern credit scoring platform for gig economy workers with ML-powered risk assessment, loan management, and real-time performance tracking.

🏗️ ARCHITECTURE

Technology Stack

Frontend  → React 18 + Vite + Tailwind CSS + Lucide Icons
Backend   → Node.js + Express + PostgreSQL (Neon DB)
ML        → Python + Flask + scikit-learn + pandas

Port Configuration

  • Frontend: Port 5173 (Vite dev server)
  • Backend: Port 3000 (Express API)
  • ML Service: Port 5001 (Flask API)
  • Database: Neon PostgreSQL (cloud-hosted)

📁 PROJECT STRUCTURE

Root Directory

DU_Hacks/
├── client/                    # React Frontend Application
├── server/                    # Node.js Backend API
├── ml_service/               # Python ML Service
├── README.md                 # Project documentation
└── .gitignore               # Git ignore rules

🎨 FRONTEND (client/)

Framework & Build

  • React 19.2.0 with Vite 7.2.4
  • Tailwind CSS 4.1.18 for styling
  • React Router DOM 7.13.0 for navigation
  • Lucide React for icons

Project Structure

client/
├── src/
│   ├── pages/                      # Page Components (11 pages)
│   │   ├── LoginPage.jsx          # User authentication
│   │   ├── RegisterPage.jsx       # User registration
│   │   ├── DashboardPage.jsx      # Worker dashboard
│   │   ├── EarningsPage.jsx       # Earnings tracking
│   │   ├── ProfilePage.jsx        # User profile
│   │   ├── LoanEligibilityPage.jsx
│   │   ├── LoanEligibilityInputPage.jsx
│   │   ├── LoanApplicationPage.jsx
│   │   ├── AdminDashboardPage.jsx  # Admin overview
│   │   ├── AdminLoansPage.jsx      # Loan management
│   │   └── AdminWorkersPage.jsx    # Worker management
│   │
│   ├── components/                  # Reusable Components
│   │   ├── common/                 # Common UI Components
│   │   │   ├── Badge.jsx          # Status badges
│   │   │   ├── Button.jsx         # Reusable buttons
│   │   │   ├── Card.jsx           # Card containers
│   │   │   ├── Header.jsx         # Page headers
│   │   │   ├── Input.jsx          # Form inputs
│   │   │   ├── Layout.jsx         # Page layout wrapper
│   │   │   ├── Modal.jsx          # Modal dialogs
│   │   │   ├── Navbar.jsx         # Navigation bar
│   │   │   ├── ProtectedRoute.jsx # Route protection
│   │   │   ├── ScoreCard.jsx      # Score display
│   │   │   └── Sidebar.jsx        # Sidebar navigation
│   │   │
│   │   ├── worker/                 # Worker-specific Components
│   │   │   ├── EarningsSummary.jsx
│   │   │   ├── LoanEligibilityCard.jsx
│   │   │   ├── PerformanceCard.jsx
│   │   │   └── ScoreBreakdown.jsx
│   │   │
│   │   ├── admin/                  # Admin-specific Components
│   │   │   ├── AdminStatsGrid.jsx
│   │   │   └── WorkerList.jsx
│   │   │
│   │   ├── AdminDashboard.jsx      # Admin dashboard logic
│   │   ├── AdminLogin.jsx          # Admin login form
│   │   ├── Dashboard.jsx           # Worker dashboard logic
│   │   ├── InputForm.jsx           # Risk assessment form
│   │   ├── InputForm_new.jsx       # Alternative form version
│   │   └── RoleSelection.jsx       # Role selector
│   │
│   ├── context/                     # React Context
│   │   ├── AuthContext.jsx         # Authentication state
│   │   └── ThemeContext.jsx        # Theme (dark/light mode)
│   │
│   ├── hooks/                       # Custom React Hooks
│   │   ├── useAuth.js              # Authentication hook
│   │   └── useTheme.js             # Theme management hook
│   │
│   ├── data/                        # Mock Data & Utilities
│   │   └── mockData.js             # localStorage integration
│   │
│   ├── services/                    # API Services
│   │   └── api.js                  # API client
│   │
│   ├── utils/                       # Utility Functions
│   │   └── helpers.js              # Helper functions
│   │
│   ├── __tests__/                   # Test Files
│   │   ├── Dashboard.test.jsx
│   │   └── InputForm.test.jsx
│   │
│   ├── App.jsx                      # Main App component
│   ├── App.css                      # App styles
│   ├── main.jsx                     # Entry point
│   └── index.css                    # Global styles
│
├── public/                          # Static assets
├── index.html                       # HTML template
├── vite.config.js                   # Vite configuration
├── tailwind.config.js               # Tailwind configuration
├── postcss.config.js                # PostCSS configuration
├── eslint.config.js                 # ESLint configuration
└── package.json                     # Dependencies & scripts

Key Features

  1. Worker Portal

    • Real-time credit score dashboard
    • Earnings tracking and management
    • Loan eligibility checker
    • Loan application system
    • Profile management

  2. Admin Portal

    • Loan application review system
    • Worker directory and search
    • Statistics and analytics
    • Approve/reject loan applications

  3. UI/UX Features

    • Dark/Light mode toggle
    • Responsive design (mobile-first)
    • Loading states and error handling
    • Form validation
    • Toast notifications

Dependencies

"dependencies": {
  "axios": "^1.13.2",           # HTTP client
  "lucide-react": "^0.563.0",   # Icon library
  "react": "^19.2.0",           # React framework
  "react-dom": "^19.2.0",       # React DOM
  "react-router-dom": "^7.13.0" # Routing
}

⚙️ BACKEND (server/)

Framework & Database

  • Express 5.2.1 (Node.js framework)
  • PostgreSQL (Neon cloud database)
  • CORS enabled for cross-origin requests
  • dotenv for environment variables

Project Structure

server/
├── index.js                    # Main Express server
├── db.js                       # PostgreSQL connection pool
├── neon_setup.js              # Database schema setup
├── .env                        # Environment variables (DATABASE_URL)
├── package.json               # Dependencies & scripts
├── migrations/                 # Database migrations
│   └── 001_rename_rating_add_debt_ratio.js
├── __tests__/                  # Backend tests
│   └── api.test.js
└── test_db_schema.js          # Schema testing utility

API Endpoints

POST   /api/assess-risk              # Submit worker data for ML assessment
GET    /api/applications              # Get all loan applications (admin)
PUT    /api/applications/:id/status  # Update loan application status
GET    /api/history                  # Get assessment history
GET    /api/assessment/:id           # Get single assessment
GET    /api/statistics               # Get assessment statistics
GET    /api/risk-distribution        # Get risk category distribution
GET    /api/health                   # Health check endpoint

Database Schema (PostgreSQL)

Tables

1. workers

id            UUID PRIMARY KEY
name          TEXT NOT NULL
role          TEXT DEFAULT 'worker'
created_at    TIMESTAMP DEFAULT NOW()

2. assessments (Core ML data)

id                      UUID PRIMARY KEY
worker_id               UUID → workers(id)
daily_upi_earnings      NUMERIC
delivery_frequency      INTEGER
system_derived_rating   NUMERIC      # ⭐ System-computed (NOT user input)
work_consistency        INTEGER
debt_ratio             NUMERIC      # ⭐ Debt-to-income ratio
credit_score           INTEGER      # From ML model
risk_category          TEXT         # Low/Medium/High Risk
default_probability    NUMERIC      # From ML model
created_at             TIMESTAMP DEFAULT NOW()

3. loan_applications

id                UUID PRIMARY KEY
assessment_id     UUID → assessments(id)
loan_status       TEXT DEFAULT 'pending'  # pending/approved/rejected
interest_rate     TEXT
approved_amount   NUMERIC
reviewed_by       TEXT
reviewed_at       TIMESTAMP
created_at        TIMESTAMP DEFAULT NOW()

Key Backend Features

  1. Input Validation

    • Worker name, earnings, delivery frequency, work consistency
    • REMOVED: User input for customer_rating (now system-computed)

  2. System-Derived Rating

    • Auto-computed based on:
      • Earnings score (earnings / 1200 * 1.5)
      • Frequency score (deliveries / 25 * 1.5)
      • Consistency score (days worked / 7 * 2)
    • Rating scale: 1-5 (rounded to 1 decimal)

  3. Debt Ratio Calculation

    • Formula: existing_debt / monthly_income
    • Optional field (defaults to 0)

  4. ML Integration

    • Calls ML service at http://127.0.0.1:5001/predict
    • Sends: earnings, frequency, system_rating, consistency
    • Receives: risk_category, credit_score, default_probability

Dependencies

"dependencies": {
  "axios": "^1.13.2",       # HTTP client for ML service
  "cors": "^2.8.6",         # Cross-origin resource sharing
  "dotenv": "^17.2.3",      # Environment variables
  "express": "^5.2.1",      # Web framework
  "pg": "^8.17.2"           # PostgreSQL client
}

Environment Variables (.env)

DATABASE_URL=postgresql://...  # Neon PostgreSQL connection string

🤖 ML SERVICE (ml_service/)

Framework & Libraries

  • Flask (Python web framework)
  • Flask-CORS (Cross-origin support)
  • scikit-learn (Machine learning)
  • pandas (Data manipulation)
  • numpy (Numerical operations)

Project Structure

ml_service/
├── app.py                    # Flask API server
├── train_model.py           # Model training script
├── test_model.py            # Model testing script
├── test_ml_local.py         # Local ML testing
├── requirements.txt         # Python dependencies
├── credit_risk_model.pkl    # Trained model (generated)
└── __pycache__/             # Python cache

ML Model Details

Model Type: RandomForestClassifier (100 estimators)

Input Features (4):

  1. upi_earnings - Daily UPI earnings (₹)
  2. delivery_frequency - Deliveries per day
  3. customer_rating - System-derived rating (1-5)
  4. work_consistency - Days worked per week (0-7)

Output:

  • risk_category - Low Risk / Medium Risk / High Risk
  • credit_score - 300-900 (computed heuristically)

Credit Score Formula:

base_score = 300
earnings_score = min(upi_earnings / 1500 * 200, 200)    # Max 200
freq_score = min(delivery_frequency / 30 * 150, 150)    # Max 150
rating_score = (customer_rating / 5) * 150              # Max 150
consistency_score = (work_consistency / 7) * 100        # Max 100
total = base_score + earnings_score + freq_score + rating_score + consistency_score
credit_score = min(total, 900)

Risk Classification Logic:

Low Risk:    earnings > 900 AND rating > 4.5 AND consistency >= 6
High Risk:   earnings < 600 OR rating < 3.5 OR consistency <= 3
Medium Risk: Everything else

API Endpoints

POST /predict
  Request:  { upi_earnings, delivery_frequency, customer_rating, work_consistency }
  Response: { risk_category, credit_score }

Training Data

  • Synthetic data generation (2000 samples)
  • Features: Normal distributions with realistic means/std
  • Train/Test split: 80/20

🔑 KEY IMPROVEMENTS MADE

1. Database Schema Updates

✅ Renamed customer_rating → system_derived_rating ✅ Added debt_ratio column ✅ Added comments for documentation ✅ Migration script created

2. Backend Logic Updates

✅ Auto-compute rating (NOT user input) ✅ Calculate debt ratio from optional existing_debt ✅ Removed customer_rating from user input validation ✅ Send computed rating to ML service

3. Frontend Updates

✅ Removed customer_rating input field ✅ Added existing_debt optional field ✅ Updated admin dashboard to show system_derived_rating ✅ Display debt_ratio when available ✅ Updated tests

4. Documentation

✅ Created migration script with clear instructions ✅ Added inline comments explaining system-derived logic

📋 RULES ENFORCED

Rule Status
User manually enters rating ❌ NEVER
Backend computes rating ✅ YES
DB stores rating ✅ YES (as system_derived_rating)
Admin can edit rating ❌ NO
Rating used for ML ✅ YES
Debt ratio stored ✅ YES

🚀 SETUP & RUN

Prerequisites

  • Node.js >= 16.x
  • Python >= 3.8
  • PostgreSQL (Neon DB)

Installation

1. Clone Repository

git clone https://github.com/Disumakadiya/DU_Hacks.git
cd DU_Hacks

2. Setup Database

# Add DATABASE_URL to server/.env
echo "DATABASE_URL=your_neon_connection_string" > server/.env

# Run schema setup
cd server
node neon_setup.js

# Run migration
node migrations/001_rename_rating_add_debt_ratio.js

3. Install Backend Dependencies

cd server
npm install

4. Install Frontend Dependencies

cd ../client
npm install

5. Install ML Service Dependencies

cd ../ml_service
pip install -r requirements.txt

Running the Application

Terminal 1 - ML Service (Port 5001)

cd ml_service
python app.py

Terminal 2 - Backend (Port 3000)

cd server
npm start

Terminal 3 - Frontend (Port 5173)

cd client
npm run dev

Access: http://localhost:5173

🧪 TESTING

Frontend Tests

cd client
npm test

Backend Tests

cd server
npm test

Database Schema Test

cd server
node test_db_schema.js

ML Model Test

cd ml_service
python test_model.py

📊 DATABASE STATUS

Connection: ✅ Connected to Neon PostgreSQL Tables: 3 (workers, assessments, loan_applications) Migration Status: ✅ Applied (system_derived_rating, debt_ratio) Total Assessments: 0 (empty database - ready for use)

🎯 CURRENT BRANCH STATUS

Repository: Disumakadiya/DU_Hacks Current Branch: urval Status: 12 commits ahead of origin/urval Last Commit: "Merge main into urval - resolved AdminDashboard conflict"

📦 DEPENDENCIES SUMMARY

Frontend (client/)

  • React 19.2.0
  • Vite 7.2.4
  • Tailwind CSS 4.1.18
  • React Router DOM 7.13.0
  • Axios 1.13.2
  • Lucide React 0.563.0

Backend (server/)

  • Express 5.2.1
  • PostgreSQL (pg) 8.17.2
  • Axios 1.13.2
  • CORS 2.8.6
  • dotenv 17.2.3

ML Service (ml_service/)

  • Flask
  • Flask-CORS
  • pandas
  • scikit-learn
  • numpy

Report Generated: January 25, 2026 Project Status: ✅ Fully Configured & Ready to Run