🎓 EduNavigator

EduNavigator is a Flask-based college recommendation and counselling web application designed to help students shortlist Tamil Nadu engineering colleges using their TNEA cutoff score and personal preferences.

The application filters and ranks colleges based on factors such as course, branch, city, college type, and fee range, then explains why a college was recommended and provides detailed information about its facilities and available programmes.

---

🌐 Live Demo

🚀 Launch EduNavigator

The application is hosted on Render. The free instance may take a few seconds to wake up after inactivity.

✨ Features

• 🎯 TNEA Cutoff-Based Recommendations

  • Shortlist colleges based on a student's cutoff score.

• 🔍 Preference-Based Filtering

  • Course
  • Branch
  • City
  • College type
  • Fee range

• 📊 Recommendation Ranking

  • Processes college and course data using Pandas to generate ranked recommendations.

• 💡 Recommendation Explanation

  • Shows why a college was recommended based on the selected preferences.

• 🏫 College Details

  • View college information, facilities, and available programmes.

• 💾 SQLite Database

  • Uses Flask-SQLAlchemy with SQLite for local application data.

• 🧪 Automated Testing

  • Includes automated tests for application and recommendation functionality.

• 🐳 Docker Support

  • The application can be built and run using Docker Compose.

---

🧠 Recommendation Workflow

EduNavigator follows a preference-driven recommendation workflow:

Student Preferences
        │
        ▼
TNEA Cutoff + Preference Input
        │
        ▼
College & Course Filtering
        │
        ▼
Recommendation Ranking
        │
        ▼
Ranked College Recommendations
        │
        ▼
Recommendation Explanation
        │
        ▼
Detailed College Information

The recommendation workflow uses Pandas to process the college dataset and perform the ranking and filtering operations.

---

🛠️ Technology Stack

Backend

• Python
• Flask
• Flask-SQLAlchemy

Data & Database

• Pandas
• SQLite
• CSV

Frontend

• Jinja Templates
• Bootstrap
• CSS

Testing & Deployment

• Pytest
• Docker
• Docker Compose

---

📁 Project Structure

EduNavigator/
├── app.py
├── config.py
├── extensions.py
├── models.py
├── data_service.py
├── recommendation.py
├── import_data.py
├── requirements.txt
├── .env.example
├── .gitignore
├── README.md
│
├── data/
│   └── final.csv
│
├── templates/
├── static/
│
├── tests/
│   ├── test_app.py
│   └── test_recommendation.py
│
├── docs/
│   └── EDUNAVIGATOR_REPORT.docx
│
└── instance/

instance/ contains local runtime/database data and is ignored by Git.

---

📊 Data & Recommendation System

The application uses a CSV-based college dataset as its primary source of college and programme information.

The data is processed using Pandas and imported into the application's local SQLite database.

The recommendation process uses student inputs such as:

• TNEA cutoff score
• Course
• Branch
• City
• College type
• Fee range

These preferences are used to filter and rank suitable colleges before presenting the results to the student.

---

🖥️ Application Screenshots

🏠 Home

📝 Recommendation Form

🎯 Recommendation Results

🏫 College Details

---

🚀 Getting Started

Prerequisites

• Python 3.10 or newer
• Git

1. Clone the repository

git clone <your-repository-url>
cd EduNavigator

2. Create a virtual environment

Windows PowerShell

python -m venv venv
.\venv\Scripts\Activate.ps1

3. Install dependencies

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

4. Import the dataset

python import_data.py

5. Start the application

python app.py

Open the application in your browser:

http://127.0.0.1:5000

These steps are based on the existing local setup documented in the project.

---

🔄 Recreate the Database

To recreate the local SQLite database from data/final.csv:

python import_data.py --replace

---

🧪 Testing

Run the automated test suite with:

python -m pytest -q

Tests are located in:

tests/
├── test_app.py
└── test_recommendation.py

---

🐳 Run with Docker

Make sure Docker Desktop is installed.

Set the application's secret key:

$env:SECRET_KEY = "replace-with-a-long-random-value"

Build and start the application:

docker compose up --build

Then open:

http://127.0.0.1:5000

On the first start, Docker creates the SQLite database and imports data/final.csv. The database is stored in a named Docker volume so it persists across container restarts.

---

🔐 Configuration

Create a .env file from the provided example:

copy .env.example .env

Set a strong SECRET_KEY before deployment.

SECRET_KEY=your-long-random-secret-key

Do not commit .env or the generated SQLite database to GitHub.

The project already excludes local runtime database data through Git configuration.

---

🔮 Future Improvements

Potential areas for further development include:

• Machine-learning-based recommendation models
• More advanced personalized ranking
• Historical TNEA admission data integration
• User accounts and saved recommendations
• Improved recommendation explanations
• Cloud database integration
• Production deployment

---

👨‍💻 Author

Mithilesh A

Software Developer

⭐ Project

If you find EduNavigator useful or interesting, consider giving the repository a ⭐ on GitHub.

EduNavigator — helping students make better-informed engineering college choices through data-driven recommendations.