AI-Powered Alternative Credit Scoring Platform

Hybrid ML + Rule-Based scoring · Explainable AI (SHAP) · Dockerized Microservices

AltCred is a production-grade fintech platform that uses machine learning to generate credit scores for individuals with little to no traditional credit history. It analyzes alternative data points — employment stability, income patterns, financial discipline — and combines a rule-based engine with a Random Forest ML model using a hybrid scoring architecture.

Every prediction is accompanied by SHAP-based explanations, telling users why they received their score.

graph TD
    A[👤 User] --> B[Next.js Frontend]
    B --> C[Express Backend]
    C --> D{Scoring Engine}
    D --> E[Rule-Based Engine<br/>Weight: 40%]
    D --> F[FastAPI ML Service<br/>Weight: 60%]
    F --> G[Random Forest Model]
    F --> H[SHAP Explainer]
    F --> I[Model Registry]
    F --> J[Feature Service]
    C --> K[(Supabase PostgreSQL)]
    C --> L[Analytics API]
    L --> M[Monitoring Dashboard]

graph LR
    A[Kaggle Dataset] --> B[Feature Pipeline]
    B --> C[Training Script]
    C --> D[Model Evaluation]
    D --> E[Model Registry]
    E --> F[FastAPI Inference]
    F --> G[SHAP Explanations]

• Node.js 18+
• Python 3.11+
• Docker & Docker Compose (for containerized setup)
• A Supabase project

git clone https://github.com/Archisman-NC/AltCred.git
cd AltCred

Copy the example file and fill in your credentials:

cp .env.example backend/.env

Create frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1

# Backend
cd backend && npm install && npm run dev

# Frontend (new terminal)
cd frontend && npm install && npm run dev

# ML Service (new terminal)
cd ml && pip install -r requirements.txt
uvicorn ml.inference.app:app --host 0.0.0.0 --port 8000

The entire platform can be started with a single command:

make run

Or directly:

docker-compose up --build

The backend automatically waits for the ML service to be healthy before starting.

curl -X POST http://localhost:8000/predict-credit-score \
  -H "Content-Type: application/json" \
  -d '{
    "age": 28,
    "annual_income": 65000,
    "monthly_inhand_salary": 5200,
    "num_bank_accounts": 2,
    "num_credit_card": 1,
    "interest_rate": 8.5,
    "num_of_delayed_payment": 0,
    "outstanding_debt": 2500,
    "credit_utilization_ratio": 15.5,
    "total_emi_per_month": 450,
    "monthly_balance": 2200,
    "occupation": "Software Engineer",
    "credit_mix": "Good",
    "payment_of_min_amount": "Yes",
    "payment_behaviour": "Low_spent_Small_value_payments"
  }'

{
  "credit_score_category": "Good",
  "confidence": 0.87,
  "model_version": "credit_model_v1",
  "explanation": [
    {"feature": "outstanding_debt", "impact": -0.18},
    {"feature": "annual_income", "impact": 0.15},
    {"feature": "num_of_delayed_payment", "impact": -0.12}
  ],
  "latency_ms": 34.2
}

Every prediction includes a SHAP-based explanation showing the top 3 features that influenced the score.

graph LR
    A[User Input] --> B[Feature Service]
    B --> C[Random Forest]
    C --> D[Prediction]
    C --> E[SHAP TreeExplainer]
    E --> F[Top 3 Feature Impacts]
    D --> G[API Response]
    F --> G

This enables transparency and regulatory compliance for credit scoring decisions.

• Algorithm: Random Forest Classifier (100 estimators)
• Accuracy: ~78.3% (3-class classification)
• Target: Credit_Score → Poor (0), Standard (1), Good (2)
• Features: 15 financial attributes (income, debt, payment history, etc.)
• Registry: ml/registry/model_registry.json for version tracking
• Hot-swap: Models can be reloaded via POST /reload-model without restarting

The /analytics page provides real-time visibility into:

• 📈 Prediction Volume — Total and daily prediction counts
• ⚡ Latency Tracking — Average ML inference response time
• 🎯 Risk Distribution — Breakdown of Good / Standard / Poor scores
• 🏥 System Health — Active model version and service status

AltCred uses a hybrid scoring architecture:

Final Score = (Rule Score × 0.4) + (ML Base Score × 0.6)

If the ML service is unavailable, the system gracefully degrades to 100% rule-based scoring.

AltCred/
├── frontend/              # Next.js application
│   ├── src/pages/         # Pages (Home, Dashboard, Analytics)
│   └── Dockerfile         # Multi-stage production build
├── backend/               # Express.js API server
│   ├── src/modules/       # auth, intake, credit-score, analytics
│   ├── src/services/      # mlService.js (ML client)
│   └── Dockerfile
├── ml/                    # Python ML workspace
│   ├── inference/         # FastAPI app, Feature Service
│   ├── registry/          # Model registry (JSON)
│   ├── models/            # Serialized models & encoders
│   └── Dockerfile
├── docker-compose.yml     # Orchestration with health checks
├── Makefile               # Dev CLI (make run, make stop)
├── .env.example           # Environment variable template
└── LICENSE                # MIT License

To deploy backend and ML services on Render, simply connect your GitHub repository and Render will automatically detect the render.yaml Blueprint file and provision both services. Ensure all environment variables from .env.example are configured in your deployment platform.

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License — see the LICENSE file for details.

_{Built with ❤️ by Archisman Nath Choudhury}