eduScout

Full-stack app for aggregating online course catalogs and analyzing them.

• Frontend: React + TypeScript + Vite + Chakra UI
• API: Node.js + Express + TypeScript + MongoDB
• ML/Analytics: Spark jobs (used via the API)

Services & ports

Service	URL / Port	Notes
Frontend (Vite dev server)	http://localhost:5173	React UI
API	http://localhost:3000/api	REST API base
API Docs	http://localhost:3000/api-docs	Swagger UI
MongoDB	localhost:27017	Database
Mongo Express	http://localhost:8081	Admin UI
Spark Master UI	http://localhost:8080	Cluster UI
Spark cluster	spark://localhost:7077	Internal cluster URL in compose

Quick start (Docker Compose)

Prerequisites

• Docker + Docker Compose v2

1) Configure environment

cp .env.example .env

Most setups work with the defaults in .env.example. If you need CORS from a different origin, update CORS_ORIGIN.

2) Start the stack

# N = number of Spark workers (example: 4)
docker compose up -d --scale spark-worker=N

Open:

• Frontend: http://localhost:5173
• Mongo Express: http://localhost:8081

3) View logs / status

docker compose ps
docker compose logs -f api
docker compose logs -f frontend

Repository layout

• api/ Express API (TypeScript)
• frontend/ React UI (Vite)
• spark-jobs/ Spark ML/analytics jobs (Python)
• mongo-init/ MongoDB init scripts

Common development workflows

Run only API + Mongo (no Spark/UI)

docker compose up -d mongodb api

Reset local MongoDB data

This will delete the named volume.

docker compose down -v

Troubleshooting

API container can't talk to Docker daemon

This repo is set up for rootless Docker by default and mounts a user-scoped socket in docker-compose.yml. If your Docker socket is in the standard location, you may need to switch the volume mount to /var/run/docker.sock:/var/run/docker.sock.

Frontend calls the wrong API URL

The compose service sets VITE_API_URL=http://localhost:3000/api. If you're running the API on a different host/port, update that environment variable (or your local .env).

Notes to professors

This setup is not production ready and is generally configured for local development. As such there may be some dependency to local versions of node/npm depending on configuration.

You may also need to run npm install for api and frontend.