Campus Compass 🎓🧭

Campus Compass is an intelligent college review and information platform designed to help students make informed decisions about their education. It combines a traditional review system with an AI-powered chatbot to provide instant access to college feedback, images, and general inquiries.

---

🌍 Project Domain & Real-World Problem

Domain

EdTech (Educational Technology) / Information Retrieval

The Problem

Choosing a college is one of the most significant decisions in a student's life. However, information is often scattered across various forums, outdated websites, and unstructured social media threads. Students struggle to find:

• Authentic, consolidated student reviews.
• Visual proof of campus facilities (images).
• Quick answers to specific questions without browsing through hundreds of pages.

The Solution

Campus Compass centralizes this experience by offering:

1. A Review Repository: A structured way to submit and read reviews.
2. Visual Insights: A searchable gallery of campus images.
3. AI Assistant: A chatbot that understands natural language to fetch specific reviews or answer general queries using a Large Language Model (LLM).

Target Users

• Prospective Students: Looking for honest feedback and campus photos.
• Current Students/Alumni: Wanting to share their experiences.
• Parents: Seeking information about college facilities and reputation.

---

🚀 High-Level Project Overview

Core Objectives

• Democratize Information: Make college reviews accessible and searchable.
• Enhance User Experience: Use AI to bridge the gap between static data and user queries.
• Visual Verification: Allow users to upload and view real images of colleges.

Key Capabilities

• AI Chatbot: Powered by Gemma 2 (9B) via Ollama, capable of answering general questions and retrieving specific stored reviews.
• Smart Search: Detects user intent (e.g., "Give me a review of X College") to switch between AI generation and database lookup.
• Review Management: Users can submit detailed reviews with images.
• Image Gallery: A dedicated interface to upload and search for college-related images.

---

🏗 System Architecture & Technical Workflow

End-to-End Data Flow

1. User Interaction: The user interacts with the web interface (Chatbot or Image Gallery).
2. Request Handling: The frontend sends HTTP requests (JSON) to the Flask Backend.
3. Intent Recognition:
   • The backend analyzes the message.
   • If it's a Review Query (e.g., "review of MIT"), it searches the local JSON data store.
   • If it's a General Query, it forwards the prompt to the Ollama/Gemma AI model.
4. Response Generation:
   • Database: Returns structured review data.
   • AI: Returns a generated natural language response.
5. Presentation: The frontend renders the response (text or images) to the user.

Major Components

• Client: HTML/JS frontend for chat and image browsing.
• Server: Flask API handling routing, logic, and file management.
• AI Engine: Local Ollama instance running Gemma 2.
• Storage: File-based storage (JSON for text, filesystem for images).

---

🛠 Tech Stack Breakdown

Frontend

• HTML5 / CSS3: For structure and styling.
• JavaScript (Vanilla): Handles API calls (fetch), DOM manipulation, and event listeners.
• Jinja2: Python templating engine for rendering dynamic pages.

Backend

• Python 3.12: Core logic.
• Flask: Lightweight WSGI web application framework.
• Flask-CORS: Handles Cross-Origin Resource Sharing for API security.
• Werkzeug: Utilities for secure file handling.

Data Storage

• JSON (File-Based): Reviews are stored as individual JSON files in data/reviews/. This NoSQL-like approach allows for easy portability and human readability without a heavy database server.
• File System: Images are stored directly in static/uploads/.

AI / ML

• Ollama: A tool for running open-source LLMs locally.
• Gemma 2 (9B): Google's open model, used for generating human-like responses to general queries.

---

⚙️ Core Features

Functional Features

1. Hybrid Chatbot:
   • Context-Aware: Distinguishes between asking for a stored review vs. a general question.
   • Markdown Support: Renders rich text responses from the AI.
2. Review System:
   • Submit reviews with Name, Text, and Images.
   • Auto-timestamping of submissions.
3. Image Search:
   • Upload images with automatic renaming (timestamped).
   • Search images by filename/college name.

Internal System Features

• Intent Extraction: Custom logic (extract_college_and_intent) to parse user messages.
• Secure File Uploads: Uses werkzeug.utils.secure_filename to prevent path traversal attacks.
• Error Handling: Robust try-catch blocks around AI execution and file I/O.

---

🧠 Algorithms & Techniques

1. Intent Recognition (Rule-Based NLP)

• Technique: Keyword matching and heuristic analysis.
• Logic: The system scans for keywords like "review", "feedback", or "rating" combined with the word "college".
• Why: Simple, fast, and effective for this specific domain without needing a heavy NLP classifier.

2. Local LLM Inference

• Model: Gemma 2 (9B).
• Execution: Run via subprocess calls to the Ollama CLI.
• Why: Ensures data privacy (no data sent to external APIs like OpenAI) and allows for offline capability.

3. JSON-Based Indexing

• Technique: Linear search through JSON files.
• Why: For a prototype/small-scale application, file-based storage eliminates the overhead of setting up SQL/Mongo databases while keeping data structured.

---

📥 Installation & Setup

Prerequisites

• Python 3.10+ installed.
• Ollama installed and running.
• Git (optional, for cloning).

Step-by-Step Setup

1. Clone the Repository

   git clone https://github.com/Mithrajith/campus-compass.git
   cd campus-compass

2. Set Up Virtual Environment

   python -m venv env
   source env/bin/activate  # On Windows: env\Scripts\activate

3. Install Dependencies

   pip install -r requirements.txt

4. Setup AI Model Ensure Ollama is installed, then pull the Gemma model:

   ollama pull qwen2.5-coder:1.5b

5. Run the Application

   python backend.py

6. Access the App Open your browser and navigate to: http://127.0.0.1:5000

---

🔍 How It Works (Internals)

Scenario: User asks "Give me a review of Harvard"

1. Input: User types the message in the chat interface.
2. Processing (backend.py):
   • extract_college_and_intent() detects the word "review" and "Harvard".
   • The system skips the AI generation.
   • It calls search_college_by_name(), which iterates through data/reviews/*.json.
3. Output: The system finds review_xyz.json containing "Harvard", formats the text, and sends it back as a JSON response.

Scenario: User asks "What is a good SAT score?"

1. Input: User types the message.
2. Processing:
   • extract_college_and_intent() finds no college name or review keyword.
   • The system calls get_response_from_gemma().
   • A subprocess runs ollama run qwen2.5-coder:1.5b "What is a good SAT score?".
3. Output: The AI generates a general advice response, which is sent back to the frontend.

---

🔮 Future Scope & Improvements

• Database Migration: Move from JSON files to SQLite/PostgreSQL for better scalability and faster querying.
• Vector Search: Implement RAG (Retrieval-Augmented Generation) to let the AI "read" the reviews and answer specific questions based on them (e.g., "Summarize the pros of College X").
• User Authentication: Add login/signup for verified reviews.
• Cloud Deployment: Dockerize the application and deploy it to AWS/GCP.

---

📄 License

This project is open-source and available under the MIT License.