🎉 This is a hackathon demonstration project!

This application uses an in-memory H2 database for quick setup and demo purposes. Your data will be lost when:

• The server restarts
• After periods of inactivity
• When you close your browser

⚡ Do NOT store important or real financial information!

Traditional credit scoring systems are broken and biased:

❌ Exclude 45% of adults who lack traditional banking history
❌ Penalize freelancers & gig workers for non-traditional income
❌ Ignore real financial behavior like on-time rent & utility payments
❌ Lock out students with no credit cards but responsible spending
❌ Reinforce inequality by treating lack of history as high risk

Result: Millions of financially responsible people are denied loans, housing, and essential services.

ScoreBridge is an AI-powered financial scoring engine that evaluates real-world money habits, not just credit cards and bank loans.

✅ Payment Consistency (35%) - On-time bill payments, rent, utilities
✅ Income Reliability (25%) - Steady income patterns, freelance stability
✅ Transaction Patterns (20%) - Spending habits, financial responsibility
✅ Savings Stability (20%) - Emergency funds, savings growth over time

SBI = 0.35·P + 0.25·I + 0.20·T + 0.20·S

Score Range: 300-850 (like FICO, but fairer)

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│   React SPA     │─────▶│  Spring Boot API │─────▶│  Flask ML API   │
│  (Port 3000)    │◀─────│   (Port 8080)    │◀─────│   (Port 5000)   │
│                 │      │                  │      │                 │
│  • User Auth    │      │  • JWT Auth      │      │  • ML Model     │
│  • Dashboard    │      │  • Data Storage  │      │  • Feature Eng  │
│  • Score View   │      │  • API Gateway   │      │  • Prediction   │
└─────────────────┘      └──────────────────┘      └─────────────────┘
                                   │
                                   ▼
                         ┌──────────────────┐
                         │   H2 Database    │
                         │   (In-Memory)    │
                         └──────────────────┘

• 👤 User Module: Registration, authentication, profile management
• 📥 Data Ingestion Module: Financial profile persistence and validation
• 🎯 Scoring Module: AI-powered score calculation and history tracking
• 🔧 Common Module: Shared utilities, validators, and configurations

• ☕ Java 21 - Modern LTS version with latest features
• 🍃 Spring Boot 3.3.5 - REST API, Security, Data JPA
• 🗄️ H2 Database - In-memory for hackathon demo
• 🔐 Spring Security - JWT authentication with bcrypt
• ✅ Bean Validation - Input validation and sanitization

• ⚛️ React 18.2 - Modern UI with hooks
• ⚡ Vite 5.0 - Lightning-fast build tool
• 🎨 Tailwind CSS 3.3 - Utility-first styling
• 📊 Recharts 2.10 - Beautiful data visualizations
• 🐻 Zustand - Lightweight state management
• 🎯 React Router 6 - Client-side routing

• 🐍 Python 3.11 - ML service runtime
• 🧪 Flask - Lightweight ML API server
• 📈 Scikit-learn - Logistic regression model
• 🔢 Pandas & NumPy - Data processing
• 🎯 Feature Engineering - Custom financial metrics

• 📦 Maven - Java dependency management
• 📦 npm - Frontend package management
• 🐳 Docker-ready - Containerization support

• ☕ Java 21 (Download)
• 📦 Node.js 18+ (Download)
• 🐍 Python 3.11+ (Download)

Terminal 1: ML Service

cd ml_service
pip install -r requirements.txt
python app.py

✅ ML API: http://localhost:5000

Terminal 2: Spring Boot Backend

# Windows
mvnw.cmd spring-boot:run

# Linux/Mac
./mvnw spring-boot:run

✅ Backend API: http://localhost:8080

Terminal 3: React Frontend

cd frontend
npm install
npm run dev

✅ Web App: http://localhost:3000

Open your browser and go to http://localhost:3000 to start using ScoreBridge!

Email: demo@scorebridge.com
Password: Demo123!
Name: John Doe
Phone: +1234567890

Fill out the financial profile form with:

• 💰 Accounts: Bank accounts, credit cards, savings
• 📊 Transactions: Income (salary, freelance), expenses (rent, utilities)
• 📅 History: 3-12 months of data recommended

Click "Calculate Score" and get instant results:

• 🎯 SBI Score (300-850)
• 📊 Component Breakdown with visual progress bars
• 📈 Pie Chart showing weight distribution
• 💡 Personalized Recommendations

• View score history on your dashboard
• See latest score and account summary
• Access all past calculations

Try these scenarios for testing:

• ✅ 6+ months on-time payments
• ✅ Steady income from multiple sources
• ✅ Balanced spending patterns
• ✅ Growing savings balance

• ✅ Most payments on time
• ✅ Regular income with minor gaps
• ✅ Reasonable spending habits
• ⚠️ Modest savings

• ⚠️ Some late payments
• ⚠️ Irregular income patterns
• ⚠️ High expense-to-income ratio
• ❌ Minimal savings

👨‍💻 Freelancers & Gig Workers - Validate non-traditional income streams
🎓 Students - Build credit history without credit cards
🏠 Renters - Leverage on-time rent payments
🌍 Underbanked Communities - Access fair financial opportunities
💼 Small Business Owners - Demonstrate cash flow reliability

• Financial Inclusion: Bridge the gap for 45% of adults without credit history
• Fairness: Reward actual financial behavior, not rigid banking rules
• Transparency: Users understand exactly what impacts their score
• Empowerment: Provide actionable recommendations for improvement

• 🤖 AI scoring model with optimized weights
• 🎨 Full-stack React + Spring Boot application
• 🔐 Secure JWT authentication system
• 📊 Interactive dashboard with visualizations
• 💾 Data persistence and score history
• 📱 Responsive mobile-friendly design
• 🎯 Real-time score calculation
• 💡 Personalized recommendations engine

• 🔗 Integration with real financial data APIs (Plaid, Stripe)
• 📧 Email notifications for score changes
• 📄 PDF score export functionality
• 🧪 A/B testing for model improvements
• 🌐 Multi-language support
• 🗄️ PostgreSQL migration for production
• 🐳 Docker Compose setup
• ☸️ Kubernetes deployment configurations
• 🔍 Advanced analytics dashboard for admins

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

• HackNomics 2025 for the opportunity to build this solution
• Financial inclusion research from the World Bank
• Open-source community for amazing tools and libraries
• All underbanked individuals inspiring us to build fairer systems

• 🌐 GitHub: Omar-Mega-Byte/ScoreBridge
• 📧 Email: omar.tolis2004@gmail.com
• 💬 Issues: Report a bug or request a feature