IIT Mandi Research Scholar Portal 🎓

A comprehensive web-based research scholar management system for IIT Mandi, built with Flask (Python) backend and React frontend.

🌟 Features

For Scholars

• ✅ Progress report submission and tracking
• ✅ Leave application management
• ✅ Meeting scheduling with guides
• ✅ Document requests (certificates, transcripts)
• ✅ Travel grant applications
• ✅ Thesis submission
• ✅ Research milestone tracking
• ✅ Real-time notifications

For Guides/Supervisors

• ✅ Scholar progress monitoring
• ✅ Feedback on progress reports
• ✅ Meeting management
• ✅ Leave application approval
• ✅ Committee participation
• ✅ Multi-scholar management dashboard

For Administrators

• ✅ User management (scholars, guides, admins)
• ✅ Committee management (APC, DC)
• ✅ Document processing and approval
• ✅ Travel grant approval workflow
• ✅ System-wide analytics and reports
• ✅ Email notifications

🛠️ Technology Stack

Backend

• Framework: Flask 3.0.0 (Python)
• Database: PostgreSQL 15+
• ORM: SQLAlchemy
• Authentication: JWT (Flask-JWT-Extended)
• File Handling: Flask file upload with validation
• Email: Flask-Mail
• Migrations: Flask-Migrate
• CORS: Flask-CORS

Frontend

• Framework: React 18+ with Vite
• Styling: Tailwind CSS
• Routing: React Router v6
• State Management: Zustand
• HTTP Client: Axios
• Icons: Lucide React
• Notifications: React Hot Toast

DevOps

• Version Control: Git & GitHub
• Development: Hot reload for both frontend and backend
• Database Migrations: Alembic (via Flask-Migrate)

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.12.3 (exact version recommended)
• PostgreSQL 15+
• Node.js 18+ and npm
• Git

🚀 Quick Start

For Windows Users

1. Clone the repository

   git clone https://github.com/Shrestha-Kumar/research-module.git
   cd research-module

2. Run the automated setup script

   quick_setup_windows.bat

3. Follow the prompts to complete setup

4. Start the application

   Terminal 1 - Backend:

   cd backend
   rp\Scripts\activate
   python run.py

   Terminal 2 - Frontend:

   cd frontend
   npm run dev

5. Open browser: http://localhost:5173

For Mac/Linux Users

See WINDOWS_SETUP_GUIDE.md for detailed manual setup instructions (adapt commands for your OS).

📖 Detailed Setup Guide

For step-by-step instructions, see WINDOWS_SETUP_GUIDE.md

🗄️ Database Schema

The system includes 11 main tables:

1. users - Authentication and user profiles
2. scholars - Scholar-specific information
3. guides - Guide/supervisor information
4. committees - APC and DC committees
5. meetings - Meeting records and schedules
6. progress_reports - Scholar progress submissions
7. exams - Comprehensive exam records
8. travel_grants - Travel grant applications
9. thesis_submissions - Thesis submissions and status
10. leave_applications - Leave requests and approvals
11. student_documents - Document requests (certificates, transcripts)

🔑 Default Test Credentials

After running the seed script, use these credentials to login:

Role	Email	Password
Scholar	scholar@iitmandi.ac.in	scholar123
Guide	guide@iitmandi.ac.in	guide123
Admin	admin@iitmandi.ac.in	admin123

⚠️ Important: Change these passwords in production!

📁 Project Structure

research-module/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── models/          # Database models
│   │   ├── routes/          # API endpoints
│   │   └── utils/           # Helper functions
│   ├── migrations/          # Database migrations
│   ├── uploads/             # File uploads
│   ├── .env                 # Environment variables
│   ├── requirements.txt     # Python dependencies
│   ├── run.py              # Application entry point
│   └── seed.py             # Sample data seeder
│
├── frontend/
│   ├── src/
│   │   ├── components/      # Reusable React components
│   │   ├── pages/          # Page components
│   │   ├── services/       # API service layer
│   │   ├── store/          # State management
│   │   ├── App.jsx         # Root component
│   │   └── main.jsx        # Entry point
│   ├── .env                # Environment variables
│   ├── package.json        # Node dependencies
│   └── vite.config.js      # Vite configuration
│
├── quick_setup_windows.bat  # Automated setup script
├── WINDOWS_SETUP_GUIDE.md   # Detailed setup guide
└── README.md               # This file

🔧 Configuration

Backend (.env)

FLASK_APP=run.py
FLASK_ENV=development
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret
DATABASE_URL=postgresql://postgres:password@localhost:5432/iit_mandi_research
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password

Frontend (.env)

VITE_API_URL=http://localhost:5000/api

🧪 Testing

Test Backend API

# Health check
curl http://localhost:5000/api/health

# Login
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"scholar@iitmandi.ac.in","password":"scholar123"}'

Manual Testing

1. Start both backend and frontend
2. Navigate to http://localhost:5173
3. Login with test credentials
4. Test each feature module

📊 API Documentation

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user

Scholar Endpoints

• GET /api/scholar/dashboard - Scholar dashboard data
• GET /api/scholar/progress-reports - Get all progress reports
• POST /api/scholar/progress-report - Submit progress report
• GET /api/scholar/meetings - Get all meetings
• GET /api/scholar/leave-applications - Get leave applications
• POST /api/scholar/leave - Apply for leave
• POST /api/scholar/travel-grant - Apply for travel grant
• POST /api/scholar/document-request - Request document

Guide Endpoints

• GET /api/guide/dashboard - Guide dashboard data
• GET /api/guide/scholars - Get assigned scholars
• POST /api/guide/feedback - Provide feedback on reports
• GET /api/guide/meetings - Get scheduled meetings
• PUT /api/guide/leave/:id - Approve/reject leave

Admin Endpoints

• GET /api/admin/dashboard - Admin dashboard
• GET /api/admin/scholars - Get all scholars
• GET /api/admin/guides - Get all guides
• POST /api/admin/user - Create new user
• PUT /api/admin/user/:id - Update user
• DELETE /api/admin/user/:id - Delete user

🐛 Troubleshooting

Common Issues

Backend won't start:

• Check PostgreSQL is running
• Verify DATABASE_URL in .env
• Ensure all dependencies are installed
• Check port 5000 isn't in use

Frontend won't start:

• Clear node_modules and reinstall: rm -rf node_modules && npm install
• Check Node.js version: node --version
• Verify .env has correct API URL

Database connection errors:

• Verify PostgreSQL service is running
• Check database exists: psql -U postgres -l
• Verify credentials in .env

Import errors:

• Activate virtual environment
• Reinstall requirements: pip install -r requirements.txt

See WINDOWS_SETUP_GUIDE.md for more detailed troubleshooting.

🔄 Development Workflow

Before Starting Work

git pull origin main
cd backend
rp\Scripts\activate  # or source rp/bin/activate on Mac/Linux
pip install -r requirements.txt
flask db upgrade
cd ../frontend
npm install

Making Changes

1. Create a new branch: git checkout -b feature/your-feature
2. Make your changes
3. Test thoroughly
4. Commit: git commit -m "Description of changes"
5. Push: git push origin feature/your-feature
6. Create Pull Request on GitHub

Updating Database Models

cd backend
rp\Scripts\activate
flask db migrate -m "Description of changes"
flask db upgrade
git add migrations/
git commit -m "Add migration: Description"

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Coding Standards

• Python: Follow PEP 8
• JavaScript/React: Follow Airbnb style guide
• Git Commits: Use conventional commits
• Code Review: All PRs require review

📝 License

This project is proprietary software developed for IIT Mandi.

👥 Team

• Original Developer: Shrestha Kumar
• GitHub: https://github.com/Shrestha-Kumar/research-module
• Institution: IIT Mandi

📞 Support

For issues and questions:

1. Check WINDOWS_SETUP_GUIDE.md
2. Search existing GitHub issues
3. Create a new issue with detailed description
4. Contact the development team

🎉 Acknowledgments

• IIT Mandi for project requirements
• Flask and React communities
• All contributors to this project

---

🚀 Next Steps

After successful setup:

1. Familiarize yourself with the codebase
2. Read the API documentation above
3. Test all features with the test credentials
4. Join the team communication channels
5. Pick up a task from the project board

Happy Coding! 🎓💻