RecMind - AI-Powered Learning Resource Recommendation Platform

RecMind is a modern full-stack application that provides AI-powered personalized learning resource recommendations combining semantic search and collaborative filtering.

Prerequisites

To run this project, you need to have the following installed:

• Docker and Docker Compose OR
• Node.js (v18+)
• Python (3.10+)
• MongoDB (If running manually)

Quick Start (with Docker Compose)

The easiest way to get the entire stack (Frontend, Backend, Recommender, and MongoDB) up and running is using Docker Compose.

1. Setup Environment Variables

First, create the necessary .env files for the backend and recommender services.

Backend Environment: Create a file at backend/.env with the following contents:

MONGO_URI=mongodb://mongodb:27017/recmind
JWT_SECRET=recmind_jwt_secret_change_in_production
GEMINI_API_KEY=your_gemini_api_key_here
PORT=5000
RECOMMENDER_URL=http://recommender:8000

(Note: If running the backend manually instead of docker, use localhost for MONGO_URI and RECOMMENDER_URL).

Recommender Environment: Create a file at recommender/.env with the following contents:

GITHUB_TOKEN=your_github_personal_access_token_here
YOUTUBE_API_KEY=your_youtube_api_key_here

2. Prepare Seed Data for Recommender

Before starting the recommender service, you need to fetch initial learning resources using your API keys.

1. Navigate to the recommender directory:

   cd recommender

2. Install Python dependencies:

   pip install -r requirements.txt

3. Run the data ingestion script:

   python scripts/fetch_resources.py

   This will create a seed_resources.json file in recommender/data/.

3. Start the Application

Once the seed data is prepared and environment variables are set up, go back to the root directory and start the services using Docker Compose:

cd ..
docker-compose up --build -d

4. Access the Application

• Frontend Web App: http://localhost:5173
• Backend API: http://localhost:5000/health
• Recommender API: http://localhost:8000/health

---

Full System Working & Architecture

RecMind is a decentralized, microservice-based application. Its core strength lies in combining static learning resources with dynamic, AI-generated learning paths and collaborative recommendations.

Here is the step-by-step working of the entire system:

1. Data Ingestion & Seeding (Offline Phase)

Before the system serves recommendations, the Recommender microservice needs seed data.

• The Python script (fetch_resources.py) uses the GitHub API and YouTube Data API to scrape thousands of high-quality courses, tutorials, and repositories across diverse topics (e.g., React, Machine Learning, System Design).
• This rich, domain-specific data is cleaned and stored locally in seed_resources.json.

2. Semantic Embedding & Indexing (App Startup)

When the Recommender FastAPI service starts:

• It securely constructs high-dimensional vector embeddings of the metadata (titles, descriptions, tags, etc.) using a local SentenceTransformers model (e.g., all-MiniLM-L6-v2).
• These embeddings are stored and indexed within a FAISS (Facebook AI Similarity Search) vector database for rapid retrieval.
• TF-IDF Fallback: A traditional TF-IDF index is built in the background to serve as a fault-tolerant fallback algorithm in case dense FAISS indices fail, rebuild, or are temporarily unavailable.
• These dense embeddings allow the system to perform profound Semantic Search. When a user queries for "beginner python tutorials", the system calculates the mathematical similarity between the query context and all resources in the FAISS index to find the most conceptually relevant—not just keyword-matching—results.

3. User Interaction & The Frontend (React + Vite)

When a user visits the application via the browser:

• The Frontend (React, TailwindCSS, Framer Motion) provides an intuitive, gamified UI.
• Users can create profiles, explore topics, and click on resources.
• These user interactions (clicks, views, saves, completions) are sent to the Node.js backend to track progress and update the collaborative filtering model.

4. Personalization via Hybrid Recommendation Engine

When a recommendation is requested, the system uses a Hybrid Approach:

1. Semantic Search (SentenceTransformers + FAISS): Retrieves candidates based on mathematical similarity to the search query or course topic. (Falls back to TF-IDF if FAISS is unavailable).
2. Collaborative Filtering: The Recommender service dynamically builds an interaction matrix using implicit user feedback (e.g., clicks, views). It finds similar users and calculates a collaborative score.
3. Scoring & Ranking: The final ranking is determined by combining the Semantic Score (relevance), Collaborative Score (user similarity), Popularity Score (GitHub stars, YouTube views), and Recency Score (how new the content is). The resulting top N list is served to the UI.

5. AI Learning Paths (Gemini Integration)

For long-term learning, users can request an AI Learning Path:

• The User specifies a goal (e.g., "Learn Rust in 3 months") on the frontend.
• The Node.js Express Backend intercepts this request, injects structured context, and orchestrates a prompt to the Google Gemini API.
• Gemini generates a structured, step-by-step curriculum which the backend parses, saves to MongoDB, and serves back to the user interface.

6. Persistence & State Management

• MongoDB acts as the single source of truth for all dynamic user data.
• It securely handles user authentication (passwords, JWT tokens), user profiles, generated learning paths, and raw interaction logs.
• The Microservices efficiently query MongoDB when updating user state or serving the dashboard.

Stopping the Application

To shut down the Docker containers, run:

docker-compose down

To also remove the MongoDB data volume, use:

docker-compose down -v