Decentralized Scholarship Allocation System

A decentralized application that combines rule-based AI matching with blockchain transparency for scholarship allocation. Students apply through a web interface, get matched using intelligent algorithms, and have their allocations recorded immutably on the blockchain.

---

Features

• Rule-Based AI Matching: Scholarship matching based on GPA, major, community service, financial need, and diversity factors.
• Blockchain Transparency: Allocations recorded on Ethereum blockchain for complete transparency.
• MetaMask Integration: Wallet connection for blockchain transactions.
• Privacy-Preserving: Student data hashed using HMAC-SHA256 before blockchain storage.
• Real-Time Processing: Instant application scoring and matching.
• Local Development: Fully functional local blockchain environment with test accounts.

---

Architecture

Components

1. Backend (FastAPI) – Rule-based matching engine and API
2. Frontend (React + Tailwind) – Student application interface
3. Smart Contract (Solidity) – Blockchain record storage
4. Local Blockchain (Hardhat) – Development environment

Technology Stack

• Backend: FastAPI, Python, Web3.py
• Frontend: React, Vite, Tailwind CSS, ethers.js
• Blockchain: Hardhat, Solidity, MetaMask
• Deployment: PowerShell automation

---

Quick Start

Prerequisites

• Node.js (v18 or higher)
• Python 3.8+
• MetaMask browser extension
• PowerShell (Windows) or Bash (Linux/Mac)

One-Command Setup (Windows)

cd "C:\Users\Jayesh\DEC AI\ScholarshipChain"
.\start-system.ps1

This script will:

• Install all dependencies
• Start local blockchain
• Deploy smart contracts
• Launch backend API
• Start frontend development server
• Open your browser automatically

Manual Setup

1. Install Dependencies

# Frontend
cd frontend
npm install

# Backend
cd ../backend
pip install -r requirements.txt

# Contracts
cd ../contracts
npm install

2. Start Services

# Terminal 1: Blockchain
cd contracts
npx hardhat node

# Terminal 2: Deploy contract
npx hardhat run scripts/deploy.js --network localhost

# Terminal 3: Backend
cd ../backend
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 4: Frontend
cd ../frontend
npm run dev

3. Access the Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• Blockchain RPC: http://localhost:8545

---

Usage Guide

For Students

1. Fill out application form: personal info, GPA, major, community service hours, financial need, family income, and underrepresented status.
2. Get instant scholarship matches and score breakdown.
3. Optionally record results on blockchain using MetaMask.

For Administrators

1. Monitor applications through the backend API at /docs.
2. Verify allocations using blockchain logs and immutable records.

---

Scholarship Criteria

The system includes four mock scholarships:

1. Academic Excellence Scholarship ($5,000)

   • Min GPA: 3.8
   • Required majors: CS, Engineering, Mathematics
   • Min community hours: 50

2. Financial Need Scholarship ($8,000)

   • Min GPA: 3.0
   • Max family income: $60,000
   • Financial need required

3. Community Leadership Award ($3,000)

   • Min GPA: 3.2
   • Min community hours: 100
   • Any major

4. STEM Diversity Scholarship ($6,000)

   • Min GPA: 3.5
   • STEM majors only
   • Underrepresented status preferred
   • Min community hours: 25

---

AI Matching Algorithm

• GPA (30%)
• Major Match (25%)
• Community Service (20%)
• Financial Need (15%)
• Diversity (10%)

Minimum Score: 60/100 for approval.

---

Security & Privacy

• Student data never stored on-chain.
• HMAC-SHA256 used for anonymized identifiers.
• Access-controlled smart contracts.
• Duplicate allocation prevention and event logging.

---

Development

Project Structure

ScholarshipChain/
├── backend/                  # FastAPI server
│   ├── main.py               # Main API app
│   ├── requirements.txt      # Python dependencies
│   └── .env.example          # Environment template
├── frontend/                 # React app
│   ├── src/components/       # Components
│   ├── src/hooks/            # Custom hooks
│   └── App.jsx               # Main app
├── contracts/                # Smart contracts
│   ├── contracts/            # Solidity files
│   ├── scripts/              # Deployment scripts
│   └── hardhat.config.js     # Hardhat config
└── start-system.ps1          # Startup automation

Environment Variables

Backend (.env)

SERVER_SECRET=your-secret-key
BLOCKCHAIN_RPC_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x...
PRIVATE_KEY=0x...

Frontend (.env)

VITE_BACKEND_URL=http://localhost:8000
VITE_BLOCKCHAIN_RPC_URL=http://localhost:8545
VITE_CONTRACT_ADDRESS=0x...

---

Testing

Example Student Data

High-Achieving CS Student

• GPA: 3.9
• Major: Computer Science
• Community Hours: 75
• Financial Need: No

Financial Need Candidate

• GPA: 3.4
• Major: Biology
• Income: $45,000
• Community Hours: 30
• Financial Need: Yes

MetaMask Setup

• Import Hardhat test account using provided private key.
• Add local Hardhat network (http://127.0.0.1:8545, Chain ID: 31337).

---

Monitoring & Analytics

API Endpoints

• GET / – System status
• GET /scholarships – Available scholarships
• POST /allocate – Process application
• POST /submit-to-blockchain – Record allocation
• GET /blockchain-status – Blockchain info

Blockchain Analytics

• getAllocationsCount() – Total allocations
• getAllocation(index) – Individual record
• ScholarshipAllocated event logs

---

Contributing

1. Fork repository
2. Create feature branch
3. Commit changes
4. Push branch
5. Open Pull Request

---

License

Licensed under the MIT License. See LICENSE for details.

---

Troubleshooting

Port Already in Use

npx kill-port 8545
npx kill-port 8000
npx kill-port 5173

MetaMask Connection Failed

• Ensure Hardhat node is running
• Check contract deployment
• Verify correct local network setup

Backend API Errors

• Confirm dependencies installed
• Check environment variables
• Validate blockchain connection

---

Made for Transparent Scholarship Allocation

---

?