Installation Guide

Setting Up EduPredict Pro

Give yourself about 20 minutes the first time. Most of that is npm downloading things. Follow the order below exactly, because step 3 will fail if you skip step 2.

Prerequisites

1. Python 3.8 or newer. Open a terminal and type python --version. If it says 2.7 or "command not found," go to python.org and install 3.10 or 3.11. On Windows, tick the "Add Python to PATH" checkbox during install - forgetting this causes about half the setup problems we get asked about.
2. Node.js 18 or newer. Check with node --version. If it's missing, grab the LTS build from nodejs.org. npm comes bundled with it, so you don't need to install that separately.
3. A code editor. VS Code is fine and free.

Step 1 - Get the code and install the Python packages

Extract the project folder somewhere sensible. Not inside a OneDrive or Google Drive synced folder, because the sync process locks files mid-write and causes weird errors. Then open a terminal in that folder and run:

cd Student-Performance-Prediction
pip install -r backend/requirements.txt

This pulls in Flask, Flask-SQLAlchemy, Flask-JWT-Extended, Flask-Migrate, Flask-CORS, scikit-learn, pandas and a few others. It'll take a couple of minutes. scikit-learn is the big one.

Step 2 - Train the model

python backend/ml/train_model.py

Watch the terminal. You should see the MAE, RMSE and R-squared printed out, plus the feature importance breakdown. Two files get created in backend/ml/ - rf_model.pkl and scaler.pkl. If you don't see those files afterwards, something went wrong here and there's no point continuing.

Step 3 - Create the database and add sample data

On macOS or Linux:

FLASK_APP=backend.wsgi:app flask db upgrade
python backend/seed.py

On Windows Command Prompt, set the variable separately first:

set FLASK_APP=backend.wsgi:app
flask db upgrade
python backend/seed.py

The seeder creates the four demo accounts along with sample students, subjects, attendance records and marks. Without this you'll have a working app with a completely empty database, which is a confusing way to spend twenty minutes wondering what broke.

Step 4 - Install the frontend packages

cd frontend
npm install
cd ..

Go make chai. This one takes a while.

Step 5 - Run it

You need two terminals open at the same time. Not one after the other. Both, simultaneously.

Terminal 1 - the backend:

python app.py

The API comes up at http://localhost:5001. Leave this terminal alone.

Terminal 2 - the frontend:

cd frontend
npm run dev

Open http://localhost:5173 in your browser and you should see the login screen.

Demo logins

• Admin - admin@spp.com / admin123
• Faculty - faculty1@spp.com / faculty123
• Student - student1@spp.com / student123
• Parent - parent1@spp.com / parent123

Change these before you submit anything, obviously.

Things that usually go wrong

Every API request fails with a CORS or network error. The backend isn't running, or it's on the wrong port. Check Terminal 1 hasn't crashed. On macOS, AirPlay Receiver squats on port 5001 by default - either turn it off in System Settings under General and AirDrop, or change the port inside app.py and update the base URL in frontend/src/api to match.

"No such table" errors when you log in. The migration didn't run. Go back to step 3, make sure FLASK_APP is actually set, and run flask db upgrade again. Then run the seeder.

Prediction button returns a 500 error. The pickle files are missing. Rerun step 2 and confirm rf_model.pkl and scaler.pkl exist in backend/ml/.

How to check everything actually works

1. Log in as admin. The dashboard should load with charts that have actual bars and slices in them, not empty grey boxes.
2. Log out, log in as faculty1. Open a class, mark bulk attendance for today, save it.
3. Still as faculty, pick a student and run a prediction. You should get a score and a category back within a second or two.
4. Log in as student1. The prediction you just ran should be visible on their dashboard.

If all four of those work, the full stack is wired correctly - database, API, auth, model, frontend. You're done.