---

📑 Table of Contents

• ✨ Features
• 🏗️ Architecture
• 🛠️ Tech Stack
• 📁 Repository Structure
• 🚀 Quick Start
• 🔀 User Flows
• 📡 API Reference
• 🧠 Model Training
• 🔍 Verification
• 💡 Development Tips
• 🤝 Contributing
• 📄 License

---

✨ Features

🎓	Smart Scholarship Recommendations Neural ranking with rule-based fallback — personalized to each student's profile
📝	Intelligent Exam Matching Eligibility filtering + suitability scoring + neural blending for exam recommendations
🔍	Semantic Search Search scholarships by meaning, not just keywords
⚡	Pre-trained Models Included Trained artefacts (.keras) and preprocessors (.pkl) ship with the repo — no retraining needed
📊	Real-time Stats Dashboard Live scholarship + exam statistics via combined API endpoints

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Diversion 2k26                               │
├──────────────────────────┬──────────────────────────────────────────┤
│   Frontend (React+Vite)  │         Backend (FastAPI+Uvicorn)        │
│   http://localhost:5173  │         http://localhost:8000            │
│                          │                                          │
│  ┌──────────────────┐    │   ┌────────────────────────────────┐    │
│  │  Pages           │    │   │  Model Service                 │    │
│  │  ├─ Home         │    │   │  ├─ Scholarship Recommender    │    │
│  │  ├─ Scholarships │────┼──▶│  ├─ Exam Recommender          │    │
│  │  ├─ Exams        │    │   │  ├─ Text Matcher               │    │
│  │  ├─ Olympiads    │    │   │  └─ Classifier                 │    │
│  │  └─ Dashboard    │    │   └──────────────┬─────────────────┘    │
│  └──────────────────┘    │                  │                      │
│                          │   ┌──────────────▼─────────────────┐    │
│   /api/* ────────────────┼──▶│  Saved Models (.keras)         │    │
│                          │   │  Saved Preprocessors (.pkl)     │    │
│                          │   │  Data Files (JSON / CSV)        │    │
│                          │   └────────────────────────────────┘    │
└──────────────────────────┴──────────────────────────────────────────┘

---

🛠️ Tech Stack

Layer	Technology
Frontend	React 19, Vite 7, Tailwind CSS 4, React Router, Axios
Backend	FastAPI, Uvicorn, Pydantic
ML / Data	TensorFlow / Keras, scikit-learn, pandas, NumPy
Dev Tooling	ESLint, PostCSS, Vite HMR

---

📁 Repository Structure

Click to expand full tree

Diversion2k26/
├── backend/
│   ├── app.py               ← FastAPI server (port 8000)
│   ├── model_service.py     ← Loads models & handles inference
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── pages/           ← Route-level page components
│   │   ├── components/      ← Shared UI components
│   │   └── services/api.js  ← Axios API client
│   ├── vite.config.js       ← /api proxy → localhost:8000
│   └── package.json
├── model/
│   ├── train_models.py      ← Full training pipeline
│   ├── quickstart.py        ← Quick train shortcut
│   ├── saved_models/        ← Pre-trained .keras files
│   └── saved_preprocessors/ ← Serialized .pkl preprocessors
├── data/                    ← Scholarship & exam datasets
├── verify_system.py         ← Project health checker
└── README.md

---

🚀 Quick Start

Prerequisites: Python 3.9+ · Node.js 18+ · npm 9+

1️⃣ Clone the repo

git clone https://github.com/somyadipghosh/Diversion2k26_private.git
cd Diversion2k26

2️⃣ Start the backend

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

URL	Description
http://localhost:8000	API base
http://localhost:8000/docs	Swagger / Interactive docs
http://localhost:8000/health	Health check

3️⃣ Start the frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173 in your browser.

Vite automatically proxies all /api/* requests from the frontend to http://localhost:8000.

---

🔀 User Flows

🎓 Scholarship Flow

User visits /scholarships or /all-scholarships
        ↓
Frontend sends profile → POST /api/recommend
        ↓
Backend model service:
  ├─ [Model loaded]  → Neural recommender scoring
  └─ [Fallback]      → Heuristic rule-based scoring
        ↓
Frontend displays ranked scholarships with match score

📝 Exam Flow

User visits /exams
        ↓
Frontend sends student profile → POST /api/exams/recommend
        ↓
Backend exam pipeline:
  ├─ Step 1: Eligibility filtering
  ├─ Step 2: Rule-based suitability scoring
  └─ Step 3: Neural score blending (if model available)
        ↓
Frontend displays ranked exams + score breakdown

---

📡 API Reference

Core Endpoints

Method	Endpoint	Description
GET	/	Service metadata
GET	/health	Health status (scholarship + exam systems)
GET	/api/combined-stats	Aggregated stats

Scholarship Endpoints

Method	Endpoint	Description
POST	/api/recommend	Personalized scholarship recommendations
POST	/api/search	Semantic scholarship search
GET	/api/search/{query}	Search (GET variant)
POST	/api/classify	Scholarship text classification
GET	/api/stats	Scholarship statistics
GET	/api/categories	All scholarship categories
GET	/api/scholarships/all	Paginated scholarship list

Exam Endpoints

Method	Endpoint	Description
POST	/api/exams/recommend	Personalized exam recommendations
GET	/api/exams/all	Paginated exam list with filters
GET	/api/exams/stats	Exam statistics

📖 Full request/response schemas live in the interactive Swagger docs when the backend is running.

---

🧠 Model Training

Only needed if you want to retrain models from scratch. Pre-trained artefacts are already in the repo.

cd model
pip install -r requirements.txt

# Quick start (recommended)
python quickstart.py

# Full pipeline
python train_models.py

Training output directories

model/
├── saved_models/        ← .keras model files
├── saved_preprocessors/ ← .pkl preprocessors
├── training_logs/       ← JSON training summary
└── plots/               ← Training curves

---

🔍 Verification

Run the built-in project health checker from the repo root:

python verify_system.py

---

💡 Development Tips

Tip	Detail
Backend hot-reload	Uvicorn runs with reload=True — save a file, see changes instantly
Frontend HMR	Vite Hot Module Replacement keeps the browser in sync
API not reachable?	Check backend is on 8000, frontend on 5173, and proxy config in frontend/vite.config.js
Auth pages	/auth and /dashboard are demo-level UI — no real auth service is wired up yet

---

🤝 Contributing

Contributions are welcome! 🎉

1. Fork the repository
2. Create your feature branch  →  git checkout -b feature/your-feature
3. Commit your changes         →  git commit -m "feat: add your feature"
4. Push to the branch          →  git push origin feature/your-feature
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License.

---

_{Built with ❤️ for Diversion 2k26}