CreditScore SA - Alternative Credit Scoring Platform

An alternative credit scoring application specifically designed for the South African market. This platform helps assess creditworthiness using non-traditional factors, making financial services more accessible to underbanked populations.

Features

Alternative Credit Assessment: Uses non-traditional factors like utility payments, rent history, mobile money usage, and employment stability
User Authentication: Secure registration and login system
Real-time Scoring: Instant credit score calculation (300-850 range)
Application History: Track all credit assessments over time
Risk Categorization: Clear risk categories from Very Low to Very High Risk
Loan Amount Calculation: Personalized maximum loan amount based on income and credit score
Mobile Responsive: Works on desktop and mobile devices

Technology Stack

Backend

Node.js with Express.js
JSON-based database (lightweight file storage)
JWT authentication
bcryptjs for password hashing

Frontend

Vanilla JavaScript (ES6+)
HTML5 & CSS3
Responsive design with CSS Grid & Flexbox

Credit Scoring Algorithm

The scoring algorithm evaluates applicants based on six key factors:

Income Assessment (20%): Monthly income, debt-to-income ratio, and dependents
Employment Stability (15%): Employment status and duration
Expense Management (15%): Monthly obligations relative to income
Banking Relationship (15%): Bank account presence, age, savings, and mobile money usage
Alternative Payment History (20%): Utility and rent payment history
Overall Stability (15%): Housing status, education level, and employment duration

Score Ranges

750-850: Very Low Risk
650-749: Low Risk
550-649: Medium Risk
450-549: High Risk
300-449: Very High Risk (typically not approved)

Quick Start (Demo)

The backend is already running! You can start testing immediately:

Demo Credentials:

Email: demo@creditscore.co.za
Password: demo123

Simply open frontend/index.html in your browser and login with these credentials. The demo user already has a credit application with a score of 672 (Low Risk).

Installation

Prerequisites

Node.js (v14 or higher)
npm (comes with Node.js)

Setup Instructions

Clone or download the repository
```
cd credit-score-mvp
```
Install backend dependencies
```
cd backend
npm install
```
Configure environment variables

The .env file is already created with development settings. For production, update:
```
PORT=3000
JWT_SECRET=your-secure-secret-key-here
NODE_ENV=production
```
Start the backend server
```
npm start
```
Or for development with auto-reload:
```
npm run dev
```
The API will be running at http://localhost:3000

Open the frontend

Open frontend/index.html in your web browser, or serve it using a simple HTTP server:

cd ../frontend
# Using Python 3
python3 -m http.server 8000

# Or using Node.js http-server (install first: npm install -g http-server)
http-server -p 8000

Then visit http://localhost:8000

Usage Guide

1. User Registration

Click "Register" tab
Fill in your details:
- Full Name
- 13-digit SA ID Number
- Email
- Password
- Phone (optional)
Click "Register"

2. Apply for Credit Assessment

After logging in, click "Apply for Credit Assessment"
Complete all sections of the application form:
- Income & Employment: Monthly income, employment status, duration
- Living Situation: Housing status, expenses, debt, dependents
- Banking & Savings: Bank account details, savings, mobile money
- Payment History: Utility and rent payment track record
- Education: Highest education level
Submit the application

3. View Results

Receive instant credit score and risk assessment
See your maximum approved loan amount
Review detailed score breakdown

4. Track History

View all previous applications
Monitor credit score changes over time

API Documentation

Authentication Endpoints

Register User

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword",
  "full_name": "John Doe",
  "id_number": "9001015009087",
  "phone_number": "0821234567"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword"
}

Credit Application Endpoints

Submit Application

POST /api/credit/apply
Authorization: Bearer <token>
Content-Type: application/json

{
  "monthly_income": 15000,
  "employment_status": "full-time",
  "employment_duration_months": 24,
  "rent_or_own": "rent",
  "monthly_expenses": 8000,
  "existing_debt": 2000,
  "has_bank_account": true,
  "bank_account_age_months": 36,
  "has_savings": true,
  "savings_amount": 5000,
  "utility_payment_history": "good",
  "rent_payment_history": "excellent",
  "mobile_money_usage": true,
  "education_level": "university",
  "dependents": 1
}

Get User Score

GET /api/credit/score
Authorization: Bearer <token>

Get All Applications

GET /api/credit/applications
Authorization: Bearer <token>

Get Specific Application

GET /api/credit/applications/:id
Authorization: Bearer <token>

Database Schema

Users Table

id: Primary key
email: Unique email address
password: Hashed password
full_name: User's full name
id_number: SA ID number (unique)
phone_number: Contact number
created_at: Registration timestamp

Credit Applications Table

id: Primary key
user_id: Foreign key to users
All application fields (income, employment, etc.)
credit_score: Calculated score
risk_category: Risk assessment
approved: Boolean approval status
max_loan_amount: Maximum approved loan
created_at: Application timestamp

South African Market Considerations

This application is specifically tailored for South Africa:

ID Validation: Uses 13-digit SA ID number format
Currency: All amounts in South African Rand (ZAR)
Alternative Data: Recognizes the importance of utility payments, rent history, and mobile money
Income Ranges: Calibrated for SA income distribution
Employment Categories: Includes self-employment and informal work common in SA
Education Levels: Aligned with SA education system (Matric, etc.)

Security Features

Password hashing with bcrypt
JWT token-based authentication
SQL injection prevention with prepared statements
Input validation on both frontend and backend
Secure token storage in localStorage
CORS enabled for API protection

Future Enhancements

Integration with TransUnion or Experian for traditional credit data
Mobile app version (React Native or Flutter)
SMS notifications for application status
Admin dashboard for loan officers
Document upload for income verification
Credit education resources
Payment reminders and financial tips
Multi-language support (Zulu, Xhosa, Afrikaans)
USSD integration for feature phone users

Development

File Structure

credit-score-mvp/
├── backend/
│   ├── server.js          # Express server & API routes
│   ├── database.js        # Database schema & initialization
│   ├── creditScoring.js   # Credit scoring algorithm
│   ├── package.json       # Backend dependencies
│   ├── .env              # Environment variables
│   └── credit_score.db   # SQLite database (auto-generated)
├── frontend/
│   ├── index.html        # Main HTML file
│   ├── styles.css        # Styling
│   └── app.js           # Frontend JavaScript
└── README.md            # This file

Adding New Features

Backend: Add routes in server.js, update schema in database.js
Frontend: Add UI in index.html, styles in styles.css, logic in app.js
Scoring: Modify algorithm in creditScoring.js

Troubleshooting

Backend won't start

Ensure Node.js is installed: node --version
Check if port 3000 is available
Verify all dependencies are installed: npm install

Frontend can't connect to backend

Ensure backend is running on port 3000
Check API_BASE_URL in frontend/app.js
Verify CORS is enabled in backend

Database errors

Delete credit_score.db and restart server to recreate
Check file permissions in backend directory

License

This is a demonstration project for educational purposes.

Contributing

This is an MVP. Contributions and suggestions for improvements are welcome!

Contact

For questions or support, please create an issue in the repository.

Built for the South African market to promote financial inclusion and accessibility.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md

Itsdex47/credit-score-mvp

Folders and files

Latest commit

History

Repository files navigation