README.md

metadata

title: EDU Recommender
emoji: 😻
colorFrom: purple
colorTo: indigo
sdk: docker
pinned: false

EduRecommender — HuggingFace Spaces Edition

Premium glassmorphism web app for personalised educational content recommendations. Built with React + Node.js (Express), designed for Docker-based deployment on HuggingFace Spaces.

---

Features

• Glassmorphism UI — dark theme with frosted glass cards, gradient accents, hover lift animations, and backdrop blur.
• Full Recommendation Pipeline — keyword similarity retrieval + rule-based re-ranking (with optional LLM re-ranking when API key is set).
• Preset Learner Profiles — Alice, Bob, Carol with one-click load.
• Interactive Sidebar — tag chips, difficulty selectors, range slider, viewed-ID toggles.
• Pipeline Toasts — animated step-by-step progress feedback.
• Content Browser — expandable catalogue of all 10 courses.
• Sub-millisecond ranking — no Python or ML model dependency in production.
• Docker-ready — multi-stage build, serves on port 7860.

---

Quick Start (Local)

1. Install dependencies

cd huggingface-app

# Server
cd server && npm install && cd ..

# Client
cd client && npm install && cd ..

2. Build the React client

cd client && npm run build && cd ..

3. Start the server

node server/src/index.js

Open http://localhost:7860.

Development mode

Run client and server separately for hot-reload:

# Terminal 1 — server
node server/src/index.js

# Terminal 2 — client (proxies /api to server)
cd client && npm run dev

---

Docker

cd huggingface-app
docker build -t edu-recommender .
docker run -p 7860:7860 edu-recommender

---

Deploy to HuggingFace Spaces

1. Create a new Space with Docker SDK.
2. Push the contents of huggingface-app/ to the Space repo.
3. (Optional) Set HF_TOKEN as a Space secret to enable LLM re-ranking.

---

Project Structure

huggingface-app/
├── client/                      # React frontend (Vite)
│   ├── public/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Header.jsx       # Gradient hero
│   │   │   ├── Sidebar.jsx      # Profile form + presets
│   │   │   ├── RecommendationCard.jsx
│   │   │   ├── RecommendationGrid.jsx
│   │   │   ├── PipelineToast.jsx
│   │   │   └── ContentBrowser.jsx
│   │   ├── hooks/
│   │   │   └── useRecommend.js  # Fetch hook
│   │   ├── styles/
│   │   │   └── global.css       # Design system tokens
│   │   ├── App.jsx              # Root layout
│   │   └── main.jsx             # Entry point
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
├── server/                      # Node.js backend (Express)
│   ├── src/
│   │   ├── index.js             # Server entry
│   │   ├── routes.js            # API endpoints
│   │   ├── data.js              # Content + profiles
│   │   └── recommender.js       # Pipeline (retrieval + ranking)
│   └── package.json
├── Dockerfile                   # Multi-stage build
├── .dockerignore
├── .env.example
├── package.json                 # Root scripts
└── README.md

---

API Endpoints

Method	Path	Description
GET	/api/health	Liveness probe
GET	/api/content	Full content catalogue
GET	/api/users	Mock user profiles
POST	/api/recommend	Top-3 personalised recommendations

---

Environment Variables

Variable	Default	Description
PORT	7860	Server listen port
HF_TOKEN	—	Enables LLM re-ranking
OPENROUTER_API_KEY	—	Alternative LLM key
LLM_MODEL	moonshotai/Kimi-K2.5:novita	Chat-completion model
LLM_BASE_URL	HuggingFace Router	Chat-completion endpoint

---

License

MIT