UIUC Semester Planner

This app is an academic semester planner for UIUC that generates personalized, feasible semester‑by‑semester course plans by reconciling degree requirements, prerequisites, completed coursework, and student constraints; typical use cases include students exploring degree progress and what‑if scenarios, advisors streamlining planning conversations and verifying plan feasibility, and career services mapping skills to course pathways to recommend targeted coursework for specific career outcomes.

Website: https://uiuc-semester-planner.onrender.com/

API: https://uiucsemesterplanner.onrender.com/docs

Tech Stack

Backend

Frontend

Database

Deployment / Tooling

Data / AI (scripts)

Repository Structure

• back-end/ — FastAPI app (main.py, app/ modules, requirements.txt)
• front-end/ — React + Vite app (src/, package.json)
• data/ — Raw/processed datasets and helper scripts under data/db_scripts/
• env.example — Example environment config (copy to .env)
• render.yaml — Render deployment configuration

Prerequisites

• Python 3.10+ (3.11 recommended)
• Node.js 18+ (20+ recommended)
• MongoDB connection string (Atlas or local)
• Firebase project (Web App) for frontend auth

Environment Variables

Copy the example and fill in values:

macOS/Linux (bash)

cp env.example .env

Windows (PowerShell)

Copy-Item env.example .env

Key variables (see env.example for full list):

• Backend
  • SERVER_HOST (default 0.0.0.0)
  • SERVER_PORT or PORT (default 8000)
  • DEBUG (True/False)
  • MONGODB_URL (e.g., mongodb://localhost:27017 or Atlas URI)
  • MONGODB_DB_NAME (default semester_planner)
  • CORS_ORIGINS (comma‑separated, include your Vite dev origin: http://localhost:5173)
  • FIREBASE_CREDENTIALS_PATH (backend only if you later add server‑side Firebase)
• Frontend (Vite reads from repo root via envDir)
  • VITE_API_BASE_URL (e.g., http://localhost:8000/api/v1)
  • VITE_FIREBASE_* (standard Firebase Web SDK fields)

Local Development

1) Backend (FastAPI)

macOS/Linux (bash)

cd back-end
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Option A: run via Python (uses settings from .env)
python main.py

# Option B: run via uvicorn directly
# uvicorn main:app --reload --host 0.0.0.0 --port 8000

Windows (PowerShell)

cd back-end
py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Option A: run via Python (uses settings from .env)
python .\main.py

# Option B: run via uvicorn directly
# uvicorn main:app --reload --host 0.0.0.0 --port 8000

Health check and docs:

• http://localhost:8000/health
• http://localhost:8000/docs (Swagger UI)
• http://localhost:8000/redoc

2) Frontend (React + Vite)

macOS/Linux (bash)

cd front-end
npm install
npm run dev

Windows (PowerShell)

cd front-end
npm install
npm run dev

Vite dev server runs on http://localhost:5173. Ensure VITE_API_BASE_URL in .env points to the backend (e.g., http://localhost:8000/api/v1).

Seeding the Database (optional)

Collections expected by the API:

• courses
• career_paths
• tagged_courses

Helpful scripts live in data/db_scripts/:

• db_import.py — imports courses from data/processed/uiuc_courses_flatten.json into the courses collection.
• generate_pathways.py — tags courses with skills and generates career pathways using OpenAI (requires OPENAI_API_KEY).

Notes:

• db_import.py reads MONGODB_URL and MONGODB_DB_NAME from your root .env. Ensure these are set, then run the script.
• The app defaults to the database name in MONGODB_DB_NAME (e.g., semester_planner). Keep it consistent between import and API usage.

Example (run from repo root):

macOS/Linux (bash)

# Import courses (uses MONGODB_URL and MONGODB_DB_NAME from .env)
python data/db_scripts/db_import.py

# Generate tagged courses + career pathways (requires OPENAI_API_KEY)
export OPENAI_API_KEY="<your key>"
python data/db_scripts/generate_pathways.py

Windows (PowerShell)

# Import courses (uses MONGODB_URL and MONGODB_DB_NAME from .env)
py -3 data\db_scripts\db_import.py

# Generate tagged courses + career pathways (requires OPENAI_API_KEY)
$env:OPENAI_API_KEY = "<your key>"; py -3 data\db_scripts\generate_pathways.py

API Summary

All endpoints are prefixed with /api/v1.

• GET /courses — list courses with filters: department, semester, gen_ed, credit_hours, min_rating, max_difficulty, paging page, limit
• GET /courses/search?q=...&skills=a,b — search by course prefix and/or skills
• GET /courses/{courseId} — course details
• GET /courses/{courseId}/prerequisites — prerequisite summary
• GET /courses/{courseId}/instructors?sort_by=rating|difficulty|avg_gpa
• GET /pathways — list career pathways
• GET /pathways/{pathwayId} — pathway details
• GET /pathways/{pathwayId}/courses?type=core|recommended|optional|all&include_details=false
• POST /pathways/{pathwayId}/recommend — body: { completed_courses: string[], current_semester: string, credits_per_semester?: number, preferences?: object }
• GET /tagged-courses?skills=a,b&page=1&limit=20 — list tagged courses
• GET /tagged-courses/{courseId} — tags for a course

Authentication

• Frontend uses Firebase Web SDK (src/firebase.ts). Provide the VITE_FIREBASE_* values from your Firebase project.
• The backend does not enforce Firebase auth by default. If you plan to add protected API routes, configure verification middleware and set FIREBASE_CREDENTIALS_PATH for server credentials.

CORS

Set CORS_ORIGINS in .env to include your frontend origin(s), e.g. http://localhost:5173. The backend reads this on startup.

Deployment

• Render: render.yaml contains a service definition. Set the same environment variables on Render (including VITE_* for static hosting) and provide a MongoDB URI.

Troubleshooting

• 404s or empty results: verify MongoDB has the courses, career_paths, and tagged_courses collections populated.
• CORS errors: ensure frontend origin is included in CORS_ORIGINS.
• Frontend cannot reach API: confirm VITE_API_BASE_URL and backend port; restart npm run dev after changing .env.