Enterprise-grade ML system achieving 94.16% accuracy in credit risk assessment with explainable AI

An end-to-end production-ready credit risk assessment platform that combines Random Forest machine learning with traditional financial risk metrics to automate loan approval decisions and monitor portfolio health. This system processes ₹67+ Crores in loan disbursements across 1,500+ applications with real-time risk scoring and SHAP-based explainability.

• Project Overview
• Key Features
• System Architecture
• Technology Stack
• ML Model Performance
• Installation
• Usage
• API Documentation
• Project Structure
• Design Decisions
• Future Enhancements
• Author

This system addresses the critical challenge of manual loan underwriting in financial institutions—a process that is slow, inconsistent, and vulnerable to human bias. Traditional credit assessment methods can take 3-5 business days and suffer from subjective decision-making, leading to both missed opportunities and increased default rates.

This automated solution delivers:

• 95% reduction in processing time: From days to seconds for loan decisions
• 94.16% prediction accuracy: Validated on stress-test scenarios with 1,500+ applications
• 91.38% recall rate: Catches 91 out of 100 high-risk borrowers before default
• Real-time portfolio monitoring: Tracks ₹67+ Crores in disbursed loans with NPA ratio alerts
• Regulatory compliance: SHAP-based explanations for every rejection decision

Rather than using randomly generated data, this system employs causal synthetic data where financial risk factors (Debt-to-Income ratio, Loan-to-Income ratio) directly determine default outcomes. This design choice ensures the ML model learns genuine financial patterns rather than spurious correlations—a critical validation that the #1 feature importance is indeed debt_to_income_ratio (32.99%), matching real-world banking theory.

• Random Forest classifier trained on 28 financial features (1,285 samples)
• 94.16% test accuracy, 95.77% ROC-AUC score
• Real-time risk probability calculation (0-100%)
• SHAP integration for model explainability—satisfies regulatory requirements for decision transparency
• Credit score generation on industry-standard 300-850 scale

• NPA (Non-Performing Asset) tracking: Automatically flags loans overdue 90+ days
• Debt-to-Income (DTI) ratio: Calculates monthly debt burden vs. income
• Loan-to-Income (LTI) ratio: Assesses total loan size relative to annual income
• EMI calculation: Computes Equated Monthly Installments using compound interest formula
• Portfolio concentration risk: Monitors exposure by loan purpose, geography, and customer segment

• 11 production-ready endpoints following REST principles
• Customer registration and KYC data management
• Loan application submission with instant ML predictions
• Portfolio analytics API (NPA analysis, repayment statistics, risk distribution)
• Comprehensive error handling with HTTP status codes and validation

• Loan application interface with real-time ML predictions and SHAP explanations
• Admin dashboard with Plotly visualizations (portfolio health, default trends, approval rates)
• Real-time alerts for regulatory thresholds (NPA ratio > 5%, default rate > 10%)
• Repayment performance tracking with on-time payment percentages

• 9 normalized tables (3NF compliance): Customers, Employment, Applications, Loans, Disbursements, Repayments, Collateral, Guarantors, NPA Tracking
• Foreign key constraints ensuring referential integrity
• Indexes on search columns (customer_id, loan_status, application_date)
• ACID transactions for financial data consistency
• Designed for horizontal scaling with connection pooling

┌─────────────────────────────────────────────────────────────────┐
│                       STREAMLIT FRONTEND                        │
│         (Loan Application Form + Admin Dashboard)               │
│   • Real-time ML Predictions  • SHAP Visualizations             │
│   • Portfolio Analytics       • Risk Alert Monitoring           │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP/REST API
                            ↓
┌─────────────────────────────────────────────────────────────────┐
│                        FLASK API LAYER                          │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐      │
│  │  Customer    │  │  Loan        │  │  Portfolio      │      │
│  │  Routes      │  │  Routes      │  │  Routes         │      │
│  │              │  │              │  │                 │      │
│  │ • Register   │  │ • Apply      │  │ • Summary       │      │
│  │ • Retrieve   │  │ • Approve    │  │ • NPA Analysis  │      │
│  └──────────────┘  └──────────────┘  └─────────────────┘      │
└─────────────┬──────────────────────────┬────────────────────────┘
              │                          │
              ↓                          ↓
┌──────────────────────────────┐   ┌──────────────────────────────┐
│   ML PREDICTION MODULE       │   │   POSTGRESQL DATABASE        │
│                              │   │                              │
│  ┌────────────────────────┐ │   │  ┌────────────────────────┐ │
│  │  Random Forest Model   │ │   │  │  9 Normalized Tables:  │ │
│  │  • 28 Features         │ │   │  │  • customers           │ │
│  │  • 94.16% Accuracy     │ │   │  │  • employment          │ │
│  │  • 95.77% ROC-AUC      │ │   │  │  • applications        │ │
│  │                        │ │   │  │  • loans               │ │
│  │  SHAP Explainer        │ │   │  │  • disbursements       │ │
│  │  • Feature Impact      │ │   │  │  • repayments          │ │
│  │  • Decision Trans.     │ │   │  │  • collateral          │ │
│  └────────────────────────┘ │   │  │  • guarantors          │ │
│                              │   │  │  • npa_tracking        │ │
│  Feature Engineering:        │   │  └────────────────────────┘ │
│  • DTI Calculation           │   │                              │
│  • LTI Ratio                 │   │  ACID Transactions           │
│  • Risk Flags                │   │  Foreign Key Constraints     │
│  • One-Hot Encoding          │   │  Connection Pooling          │
└──────────────────────────────┘   └──────────────────────────────┘

Data Flow:

1. User submits loan application via Streamlit UI
2. Flask API validates input and fetches customer data from PostgreSQL
3. ML module engineers 28 features and generates risk probability
4. SHAP explainer calculates feature contributions for decision transparency
5. System returns credit score, approval decision, and risk factors
6. Dashboard displays real-time portfolio health metrics

• Flask 3.1.0 - Microframework for RESTful API development
• SQLAlchemy 2.0.36 - ORM for database operations with connection pooling
• psycopg2-binary 2.9.10 - PostgreSQL database adapter
• Flask-CORS - Cross-Origin Resource Sharing support

• PostgreSQL 18.1 - Production-grade RDBMS
  • 9 normalized tables with referential integrity
  • B-tree indexes on foreign keys and search columns
  • ACID compliance for transaction safety

• scikit-learn 1.6.0 - Random Forest Classifier, metrics, preprocessing
• SHAP 0.44.0 - Model explainability (TreeExplainer for Random Forest)
• pandas 2.2.3 - Data manipulation and feature engineering
• numpy 2.2.1 - Numerical computations and array operations

• Streamlit 1.41.1 - Interactive web application framework
• Plotly 5.24.1 - Professional data visualizations (bar charts, line graphs, pie charts)
• Matplotlib - SHAP waterfall plots and feature importance charts

• Python 3.13 - Core programming language
• Git - Version control
• pytest 8.3.4 - Unit testing framework (future implementation)

The model was trained on a stress-test dataset simulating high-risk economic scenarios:

Dataset Size: 1,500 loan applications (₹67+ Crores disbursed)
Training Set: 1,028 samples (80%)
Test Set: 257 samples (20%)
Features: 28 (after removing data leakage variables)
Target Distribution: 
  • Low Risk (0): 707 samples (54.9%)
  • High Risk (1): 581 samples (45.1%)
Algorithm: Random Forest
  • n_estimators: 100 trees
  • max_depth: 10
  • class_weight: 'balanced' (handles imbalanced classes)
  • random_state: 42

Mean Accuracy: 92.61% ± 2.19%
Mean ROC-AUC: 95.15% ± 2.08%
Overfitting Check: Train-Test Gap = 0.98% (excellent generalization)

Ranked by Gini importance—validates that the model learned genuine financial risk factors:

Key Insight: The model correctly prioritized debt_to_income_ratio as the #1 feature (32.99% importance), validating that it learned the causal relationship embedded in the synthetic data. This mirrors real-world credit risk models used by FICO and major banks.

To justify the architectural choice of Random Forest, I conducted a head-to-head comparison against Logistic Regression—the traditional industry standard for credit scoring:

Decision Rationale:

1. Precision Advantage: Random Forest achieved 95.5% precision vs. 90.4% for Logistic Regression—this 5% improvement means 40% fewer false alarms (wrongly rejected good borrowers), significantly reducing operational costs and improving customer experience.

2. Robustness: Logistic Regression failed to converge on unscaled financial data (DTI ratios, income values vary by orders of magnitude). Random Forest handled the raw data natively without requiring StandardScaler or MinMaxScaler preprocessing.

3. Explainability: While neural networks might achieve slightly higher accuracy, Random Forest provides feature importance rankings and integrates with SHAP for regulatory compliance—critical in banking where every rejection must be explainable.

                Predicted
              Low Risk  High Risk
Actual Low    136        5         (True Negatives: 136)
Risk          (96.5%)    (3.5%)    (False Positives: 5)

Actual High   10         106       (False Negatives: 10)
Risk          (8.6%)     (91.4%)   (True Positives: 106)

Key Metrics:

• True Positives (106): Successfully caught high-risk borrowers before default
• False Negatives (10): Missed 10 risky borrowers—acceptable trade-off for 95.5% precision
• False Positives (5): Only 5 good borrowers wrongly rejected out of 141—minimal customer friction

Ensure the following are installed on your system:

• Python 3.9+ (Download)
• PostgreSQL 12+ (Download)
• Git (Download)

git clone https://github.com/rakshanrk/credit-risk-system.git
cd credit-risk-system

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt

Key dependencies installed:

• Flask, SQLAlchemy, psycopg2-binary
• scikit-learn, pandas, numpy, shap
• Streamlit, Plotly

# Start PostgreSQL service
# Windows: Ensure PostgreSQL service is running via Services app
# macOS: brew services start postgresql
# Linux: sudo systemctl start postgresql

# Create database
psql -U postgres
CREATE DATABASE credit_risk_db;
\q

# Run schema to create 9 tables
psql -U postgres -d credit_risk_db -f database/schema.sql

# Create Docker container
docker run --name credit-risk-postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=credit_risk_db \
  -p 5432:5432 \
  -d postgres:18.1

# Import schema
docker exec -i credit-risk-postgres psql -U postgres -d credit_risk_db < database/schema.sql

Edit config.py and set your PostgreSQL credentials:

# Database Configuration
DB_HOST = 'localhost'
DB_PORT = 5432
DB_NAME = 'credit_risk_db'
DB_USER = 'postgres'
DB_PASSWORD = 'your_password_here'  # Change this!

python database/seed_data.py

When prompted, type yes to confirm. This script generates:

• 1,000 customers with realistic demographics (age, income, employment)
• 1,500 loan applications with causal default logic (High DTI → Default)
• Repayment histories and NPA tracking records

Expected output:

✓ Created 1000 customers
✓ Created 1500 applications (Approved: 785, Rejected: 500, Pending: 215)
✓ Created 785 loans (80 defaulted based on risk probability)
✓ Created 12,954 repayment records

python ml/train_model.py

This script:

1. Fetches loan data from PostgreSQL
2. Engineers 28 features (DTI, LTI, EMI, etc.)
3. Trains Random Forest classifier (100 trees, max_depth=10)
4. Performs 5-fold cross-validation
5. Saves model to ml/models/credit_model.pkl (810 KB)

Expected output:

✓ Training set: 1,028 samples
✓ Test Accuracy: 94.16%
✓ Test ROC-AUC: 95.77%
✓ Model saved successfully

python backend/app.py

The Flask API will start on http://localhost:5000. You should see:

============================================================
🚀 CREDIT RISK ASSESSMENT API STARTING
============================================================
📍 API running at: http://127.0.0.1:5000
📊 Database: credit_risk_db
🔍 Debug mode: True
============================================================

Health Check:

curl http://localhost:5000/health
# Response: {"status":"healthy","database":"connected"}

Open a new terminal (keep Flask running) and execute:

streamlit run frontend/app.py

Streamlit will open automatically in your browser at http://localhost:8501.

Dashboard Features:

• Loan Application Page: Submit applications with instant ML predictions
• Admin Dashboard: View portfolio health (NPA ratio, default rate, approval rate)
• SHAP Explanations: See which features drove each approval/rejection decision

curl -X POST http://localhost:5000/api/loans/apply \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 1101,
    "loan_amount": 3500000,
    "loan_tenure_months": 36,
    "interest_rate": 9.5,
    "loan_purpose": "Home Renovation"
  }'

Response:

{
  "application_id": 1662,
  "credit_score": 330.45,
  "risk_probability": 0.9456,
  "status": "Rejected",
  "recommendation": "High risk - Debt-to-Income ratio exceeds threshold",
  "contributors": [
    {"feature": "debt_to_income_ratio", "impact": 0.45},
    {"feature": "loan_to_income_ratio", "impact": 0.22},
    {"feature": "estimated_emi", "impact": 0.18}
  ]
}

http://localhost:5000/api

Currently, the API is open for development. Production deployment should implement JWT token authentication.

Retrieve all customers with pagination.

Query Parameters:

• limit (int, default=100): Number of records to return
• offset (int, default=0): Starting position for pagination

Example Request:

curl "http://localhost:5000/api/customers/?limit=50&offset=0"

Response:

{
  "customers": [
    {
      "customer_id": 1101,
      "full_name": "Ravi Reddy",
      "email": "[email protected]",
      "phone": "+91-9876543210",
      "city": "Bangalore",
      "state": "Karnataka",
      "created_at": "2025-01-10"
    }
  ],
  "total": 1000,
  "limit": 50,
  "offset": 0
}

Get detailed customer information including employment data.

Example Request:

curl "http://localhost:5000/api/customers/1101"

Response:

{
  "customer_id": 1101,
  "full_name": "Ravi Reddy",
  "email": "[email protected]",
  "date_of_birth": "1985-03-15",
  "employment": {
    "employer_name": "Infosys",
    "employment_type": "Salaried",
    "monthly_income": 75000.0,
    "years_of_experience": 8.5
  }
}

Submit a new loan application. This endpoint triggers real-time ML prediction and returns credit score, risk probability, and SHAP-based feature contributions.

Request Body:

{
  "customer_id": 1101,
  "loan_amount": 3500000,
  "loan_tenure_months": 36,
  "interest_rate": 9.5,
  "loan_purpose": "Home Renovation"
}

Response (Rejection Example):

{
  "application_id": 1662,
  "customer_id": 1101,
  "credit_score": 330.45,
  "risk_probability": 0.9456,
  "risk_level": "High",
  "status": "Rejected",
  "recommendation": "High risk - Debt-to-Income ratio (48.72%) exceeds threshold (40%)",
  "model_confidence": 0.9456,
  "contributors": [
    {"feature": "debt_to_income_ratio", "impact": 0.45},
    {"feature": "loan_to_income_ratio", "impact": 0.22},
    {"feature": "estimated_emi", "impact": 0.18},
    {"feature": "monthly_income", "impact": -0.12},
    {"feature": "years_of_experience", "impact": -0.08}
  ],
  "factors": {
    "debt_to_income_ratio": 48.72,
    "loan_to_income_ratio": 29.23,
    "monthly_income": 34209.0
  }
}

Response (Approval Example):

{
  "application_id": 1663,
  "customer_id": 1102,
  "credit_score": 745.20,
  "risk_probability": 0.1895,
  "risk_level": "Low",
  "status": "Approved",
  "recommendation": "Low risk - Strong financial profile",
  "contributors": [
    {"feature": "monthly_income", "impact": -0.35},
    {"feature": "years_of_experience", "impact": -0.18},
    {"feature": "debt_to_income_ratio", "impact": 0.12}
  ]
}

SHAP Explanation Interpretation:

• Positive impact: Feature pushes decision toward "High Risk" (rejection)
• Negative impact: Feature pushes decision toward "Low Risk" (approval)
• Impact magnitude: Larger absolute values = more influential features

Retrieve all loan applications with filtering options.

Query Parameters:

• status (string): Filter by status (Approved, Rejected, Pending)
• customer_id (int): Filter by customer

Example Request:

curl "http://localhost:5000/api/loans/applications?status=Approved&limit=10"

Retrieve all disbursed loans.

Get comprehensive portfolio health metrics—critical for risk management dashboards.

Example Request:

curl "http://localhost:5000/api/portfolio/summary"

Response:

{
  "loan_statistics": {
    "total_applications": 1500,
    "total_loans": 785,
    "active_loans": 705,
    "defaulted_loans": 80,
    "approval_rate": 52.33
  },
  "financial_metrics": {
    "total_disbursed": 6762340000.0,
    "total_outstanding": 4538920000.0,
    "total_repaid": 2223420000.0,
    "total_npa_amount": 890560000.0
  },
  "risk_metrics": {
    "npa_ratio": 19.61,
    "default_rate": 10.19,
    "average_emi_payment_rate": 78.5
  }
}

Critical Metrics Explained:

• NPA Ratio: Percentage of loans overdue 90+ days (regulatory threshold: 5%)
• Default Rate: Percentage of loans that defaulted (industry average: 2-3%)
• Approval Rate: Percentage of applications approved

Get detailed NPA classification breakdown.

Response:

{
  "npa_classification": {
    "Standard": {"count": 705, "percentage": 89.81},
    "Sub-Standard": {"count": 45, "percentage": 5.73},
    "Doubtful": {"count": 25, "percentage": 3.18},
    "Loss": {"count": 10, "percentage": 1.27}
  }
}

Get repayment performance metrics.

credit-risk-system/
│
├── backend/                          # Flask REST API
│   ├── app.py                       # Application entry point (Flask routes)
│   ├── database.py                  # SQLAlchemy connection & session management
│   ├── models.py                    # ORM models for 9 database tables
│   ├── routes/
│   │   ├── customer_routes.py       # Customer CRUD endpoints
│   │   ├── loan_routes.py           # Loan application & approval logic
│   │   └── portfolio_routes.py      # Portfolio analytics endpoints
│   └── utils/
│       └── calculations.py          # Financial formulas (EMI, NPA, DTI, LTV)
│
├── database/
│   ├── schema.sql                   # PostgreSQL schema (9 normalized tables)
│   └── seed_data.py                 # Causal synthetic data generator
│
├── ml/                               # Machine Learning Pipeline
│   ├── data_prep.py                 # Feature engineering (28 features)
│   ├── train_model.py               # Random Forest training pipeline
│   ├── predict.py                   # Real-time prediction with SHAP
│   ├── compare_models.py            # Benchmarking (RF vs Logistic Regression)
│   └── models/
│       └── credit_model.pkl         # Trained model (810 KB)
│
├── frontend/                         # Streamlit UI
│   ├── app.py                       # Home page & navigation
│   └── pages/
│       ├── 1_loan_application.py    # Loan submission form with ML predictions
│       └── 2_admin_dashboard.py     # Portfolio analytics dashboard
│
├── config.py                         # Configuration (DB credentials, API settings)
├── requirements.txt                  # Python dependencies
├── README.md                         # This file
└── .gitignore                       # Git exclusions (venv, pycache, *.pkl)

Decision: Flask 3.1.0

Rationale:

1. Microservices-Friendly: Flask's minimalist design is ideal for REST APIs that focus on a single responsibility (credit risk assessment). Django's monolithic structure (admin panel, ORM, template engine) introduces unnecessary overhead for a stateless API.

2. Flexibility: Flask doesn't enforce an ORM—I chose SQLAlchemy separately for connection pooling and complex queries, which Django's ORM would have made more rigid.

3. Industry Standard: Flask is the microframework of choice for data science APIs at Netflix, Airbnb, and LinkedIn. Its lightweight nature makes it perfect for ML model serving.

4. Integration with ML: Flask seamlessly integrates with scikit-learn models via simple function calls, whereas Django requires additional middleware layers.

Decision: PostgreSQL 18.1

Rationale:

1. ACID Compliance: PostgreSQL offers stricter transactional guarantees critical for financial data. In banking, a failed loan disbursement transaction must roll back completely—PostgreSQL's MVCC (Multi-Version Concurrency Control) handles this more reliably than MySQL's InnoDB.

2. Advanced Data Types: PostgreSQL supports JSON columns, arrays, and custom types—useful for storing SHAP explanation arrays and complex risk metrics without serialization overhead.

3. Concurrency: PostgreSQL handles concurrent writes better than MySQL, which is essential when multiple loan officers submit applications simultaneously.

4. Fintech Adoption: PostgreSQL is the database of choice for Stripe, Robinhood, and Square—companies that require transaction integrity and complex query capabilities.

Decision: Random Forest Classifier (100 trees, max_depth=10)

Rationale:

1. Explainability (Regulatory Requirement): Banking regulations (e.g., ECOA in the US, GDPR in EU) mandate that loan rejections must be explainable. Random Forest provides:

   • Feature Importance: Identifies which factors (DTI, income) drove the decision
   • SHAP Integration: Generates per-prediction explanations (e.g., "Rejected because DTI ratio is 48%, exceeding 40% threshold")

   Neural networks are "black boxes"—while they might achieve 96% accuracy, explaining why a borrower was rejected is nearly impossible, exposing the bank to regulatory fines.

2. Precision Advantage: Benchmark results showed Random Forest achieved 95.5% precision vs. 90.4% for Logistic Regression. In banking terms, this means:

   • 40% fewer false alarms (good borrowers wrongly rejected)
   • Improved customer experience (fewer complaints about unfair rejections)
   • Lower operational costs (fewer manual reviews required)

3. Robustness to Unscaled Data: Logistic Regression failed to converge on the unscaled financial data (DTI ratios, income values vary by orders of magnitude). Random Forest handles heterogeneous feature scales natively—no need for StandardScaler or complex preprocessing pipelines.

4. Small Data Performance: Random Forest works well with 1,000-2,000 samples, whereas neural networks require 10,000+ samples to avoid overfitting. Training on our 1,285-sample dataset, Random Forest achieved 94.16% accuracy with only 0.98% overfitting gap.

Decision: Causal data where High DTI → Default (not random generation)

Rationale:

1. Model Validation: Randomly generated data creates noise—the model might learn spurious correlations (e.g., "customers from Karnataka default more"). With causal data, I embedded the rule: If DTI > 50% OR Income < ₹30,000, then Default = True. The fact that the trained model identified debt_to_income_ratio as the #1 feature (32.99% importance) proves the model learned the correct financial logic, not random patterns.

2. Stress Testing: Real bank portfolios have 2-3% default rates. I simulated a 45% default rate (stress-test scenario) to ensure the classifier has enough "High Risk" examples to learn from. This is critical—training on a 95% Low Risk / 5% High Risk dataset would produce a model that simply predicts "Low Risk" for everyone and achieves 95% accuracy while being useless.

3. Privacy & Scalability: Real loan data contains PII (Personally Identifiable Information) that cannot be shared publicly on GitHub. Synthetic data allows me to demonstrate the system's capabilities without GDPR/compliance concerns while easily generating 10,000+ samples for future experiments.

4. Reproducibility: The seed data script uses random_state=42, ensuring anyone cloning the repository gets identical results for benchmarking.

• ✅ XGBoost Integration: Benchmark against gradient boosting for potential 2-3% accuracy gain
• ✅ SHAP Waterfall Plots: Visualize cumulative feature contributions in the UI
• ✅ Ensemble Model: Combine Random Forest + Logistic Regression via soft voting
• ✅ Online Learning: Retrain model monthly on new loan data to capture market trends

• ✅ JWT Authentication: Secure API endpoints with role-based access control (admin vs. loan officer)
• ✅ Rate Limiting: Implement Redis-backed rate limiting (100 requests/hour per IP)
• ✅ Caching Layer: Cache portfolio metrics for 5 minutes to reduce database load
• ✅ Docker Deployment: Multi-container setup (Flask + PostgreSQL + Nginx reverse proxy)
• ✅ CI/CD Pipeline: GitHub Actions for automated testing and deployment

• ✅ What-If Analysis: "What if income increases by 20%? How does credit score change?"
• ✅ Cohort Analysis: Track default rates by origination month (e.g., "Q1 2025 loans have 8% default rate")
• ✅ Stress Testing: Simulate portfolio performance under recession scenarios (unemployment spike, interest rate hikes)
• ✅ Early Warning System: Flag loans with 3 consecutive late payments before they become NPA

• ✅ Webhook Integration: Notify external systems when loan status changes (Approved → Disbursed)
• ✅ Audit Logging: Track all API calls and model predictions for compliance (GDPR, SOC 2)
• ✅ A/B Testing Framework: Test Random Forest vs. XGBoost in production (champion/challenger approach)
• ✅ Automated Retraining Pipeline: Airflow DAG to retrain model monthly and deploy if test accuracy > 94%

Rakshan R K
Data Science Graduate | Machine Learning Engineer

📧 Email: [email protected]
💼 LinkedIn: linkedin.com/in/rakshanrk
🐙 GitHub: @rakshanrk
📍 Location: Bangalore, India

This system was built as a portfolio project to demonstrate end-to-end ML engineering skills for roles in fintech and consulting (JPMorgan Chase, Deloitte, McKinsey). It showcases:

• Production-grade software architecture (Flask API, PostgreSQL, Docker)
• Financial domain expertise (NPA tracking, DTI calculations, EMI formulas)
• Machine learning best practices (feature engineering, hyperparameter tuning, cross-validation)
• Explainable AI (SHAP integration for regulatory compliance)

If you're a recruiter or hiring manager, feel free to reach out for a demo call or technical deep-dive!

This project is licensed under the MIT License—free to use, modify, and distribute with attribution.

MIT License

Copyright (c) 2025 Rakshan R K

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

• scikit-learn for the robust Random Forest implementation and comprehensive documentation
• SHAP for making machine learning interpretable and regulation-compliant
• Flask & Streamlit communities for excellent tutorials and responsive forums
• PostgreSQL for providing a production-grade database that never lets you down
• Finance domain experts whose credit risk assessment research papers informed the feature engineering strategy

Contributions are welcome! If you'd like to improve this project:

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

• Implement XGBoost model and compare with Random Forest
• Add JWT authentication to API endpoints
• Create Docker Compose configuration for one-command deployment
• Build unit tests using pytest (target: 80% code coverage)
• Add support for additional financial metrics (LTV ratio, FOIR)
• Implement real-time dashboard auto-refresh using WebSockets

• Open a GitHub Issue for bugs or feature requests
• Email me directly for consulting inquiries or collaboration opportunities
• Check the API Documentation section above for integration guides

If you found this project useful or have suggestions for improvement:

• ⭐ Give it a star on GitHub
• 👍 Share it with your network on LinkedIn
• 💬 Leave a comment about what you'd like to see next

Press the 'thumbs down' button below any response to provide feedback to the development team.

If you're interested in building similar systems, here are recommended resources:

• "Credit Risk Modeling Using Excel and VBA" by Gunter Löffler
• Andrew Ng's Machine Learning Course (Coursera)
• Kaggle: Home Credit Default Risk Competition

• "Designing Machine Learning Systems" by Chip Huyen
• Flask Mega-Tutorial by Miguel Grinberg
• MLOps Community (YouTube channel)

• Basel III Capital Requirements (Bank for International Settlements)
• FICO Score Methodology (myFICO.com documentation)
• RBI Guidelines on Income Recognition and Asset Classification

• CPU: 2 cores, 2.0 GHz
• RAM: 4 GB
• Storage: 2 GB free space
• OS: Windows 10, macOS 10.14+, or Linux (Ubuntu 18.04+)

• CPU: 4 cores, 3.0 GHz
• RAM: 16 GB
• Storage: 20 GB SSD
• OS: Ubuntu 22.04 LTS or Docker container
• Database: PostgreSQL 12+ with connection pooling (pgBouncer)

1. Environment Variables: Never commit credentials to Git. Use .env files:

   # .env file
   DB_PASSWORD=your_secure_password
   SECRET_KEY=your_flask_secret_key

2. API Authentication: Implement JWT tokens for all endpoints:

   from flask_jwt_extended import jwt_required
   
   @app.route('/api/loans/apply', methods=['POST'])
   @jwt_required()
   def apply_loan():
       # Protected endpoint

3. Input Validation: Sanitize all user inputs to prevent SQL injection

4. HTTPS Only: Deploy behind Nginx with SSL/TLS certificates (Let's Encrypt)

5. Rate Limiting: Use Flask-Limiter to prevent abuse:

   from flask_limiter import Limiter
   limiter = Limiter(app, default_limits=["100 per hour"])

• GET /customers/: 45ms (100 records)
• POST /loans/apply: 120ms (includes ML prediction)
• GET /portfolio/summary: 200ms (aggregates 1,500 records)

• Customer lookup: 5ms (indexed on customer_id)
• Loan history retrieval: 15ms (indexed on application_date)
• Portfolio aggregation: 180ms (1,500 records with JOINs)

• Inference time: 8ms per prediction (28 features)
• Model loading time: 150ms (810 KB pickle file)
• SHAP explanation: 45ms (TreeExplainer)

If this project helped you, consider giving it a star! ⭐

• ✅ Initial release with Random Forest classifier
• ✅ 9-table PostgreSQL database schema
• ✅ Flask REST API with 11 endpoints
• ✅ Streamlit dashboard with SHAP visualizations
• ✅ 94.16% test accuracy on stress-test dataset
• ✅ Causal synthetic data generator

• v1.1.0: XGBoost integration and model comparison dashboard
• v1.2.0: JWT authentication and API rate limiting
• v2.0.0: Docker Compose deployment and Kubernetes manifests

• Credit Risk Modeling Toolkit - GitHub topic for similar projects
• Lending Club Loan Analysis - Kaggle notebook
• FICO Explainable ML - Industry standard

This system can be adapted for:

1. Microfinance Institutions: Assess creditworthiness of unbanked populations
2. P2P Lending Platforms: Automate borrower risk scoring for investors
3. NBFC (Non-Banking Financial Companies): Replace manual underwriting processes
4. Fintech Startups: White-label credit risk API for embedded lending
5. Banking Consultancies: Template for building custom credit risk models

1. Synthetic Data: Model trained on simulated data—requires retraining on real loan portfolios for production use
2. Single Currency: Currently supports INR only—needs internationalization for multi-currency support
3. No External Data: Doesn't integrate with credit bureaus (CIBIL, Experian) for historical credit scores
4. Batch Processing: No support for bulk loan application uploads (CSV import)
5. Mobile App: No native iOS/Android app—only web interface

Monthly:  Retrain on last 3 months of loan data
Quarterly: Benchmark against XGBoost/LightGBM
Annually:  Review feature importance and add new features

• Model Drift: Alert if test accuracy drops below 90%
• Data Drift: Alert if DTI mean shifts by > 10%
• System Health: Track API latency and database connection pool usage

Built with ❤️ by Rakshan R K | Last Updated: January 2025

For professional inquiries, consulting, or collaboration opportunities:
📧 [email protected] | 💼 LinkedIn | 🐙 GitHub