GEXP Exchange Mapper

A web application for SUTD CSD students to explore and plan Term 6 exchange options, now split into a Python backend API and a Flutter web frontend.

Features

• Track-based recommendations: Filter by CSD specialization tracks (AI, Security, IoT, etc.)
• Period-aware filtering: Separate Fall/Spring recommendations
• Must-map modules: Only show universities that offer specific required modules
• Viability scoring: Universities ranked by number of mappable modules
• No-track mode: For students who haven't chosen a specialization

Project structure

• backend/
  • Flask API (app.py) and recommendation engine
  • Dependencies in backend/requirements.txt
  • Tests in backend/tests/
• frontend/
  • Flutter web application
  • Built assets in frontend/build/web/ (for GitHub Pages)

Local development

Prerequisites

• Python 3.11+ (CI runs on Python 3.12)
• Flutter (stable channel) with Chrome installed
• make (available by default on macOS/Linux; on Windows use WSL or run the commands manually)

Quick start (recommended)

From the repository root:

# 1. Start the backend (terminal 1)
make deploy-backend

# 2. Start the Flutter web frontend (terminal 2)
make deploy-frontend

By default:

• The backend runs on http://localhost:5001/ and exposes an API at http://localhost:5001/api/meta.
• The frontend runs in Chrome via flutter run -d chrome (Flutter chooses the exact port).

You can change the URLs used by the Makefile with environment variables:

BACKEND_URL=http://localhost:5001/api/meta FRONTEND_URL=http://localhost:8080/ make verify

Backend only

cd backend
python -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .venv\Scripts\activate         # Windows (PowerShell / cmd)

python -m pip install --upgrade pip
pip install -r requirements.txt

# Run the Flask API (port can be overridden with PORT)
PORT=5001 python app.py

The backend should now be reachable at http://localhost:5001/.

Frontend only

Make sure you have Flutter installed and on your PATH, then:

cd frontend
flutter pub get
flutter run -d chrome

This will start a Flutter web dev server and open the app in Chrome.

Testing

Run backend tests

Using the Makefile:

make backend-test

Or directly:

cd backend
python -m pytest tests/ --tb=short -q

Verify local deployment

Once both backend and frontend are running locally, you can sanity‑check connectivity:

make verify

This pings:

• BACKEND_URL (defaults to http://localhost:5001/api/meta)
• FRONTEND_URL (defaults to http://localhost:8080/)

Override these environment variables if your local ports differ.

Deployment

CI/CD with GitHub Actions and GitHub Pages

On every push or pull request to main:

• Test job
  • Sets up Python 3.12
  • Installs backend dependencies from backend/requirements.txt
  • Runs the backend test suite in backend/tests/

On pushes to main:

• Deploy job
  • Checks out the repo
  • Sets up Flutter (stable channel)
  • Builds the Flutter web app from frontend/:
    • flutter pub get
    • flutter build web --release --base-href "/${GITHUB_REPOSITORY#*/}/"
  • Uploads frontend/build/web as a GitHub Pages artifact
  • Deploys the artifact to GitHub Pages

After GitHub Pages is configured for the repository (source: GitHub Actions), your app will be available at:

• https://<github-username>.github.io/<repo-name>/

You can find the exact URL under the repository Settings → Pages.

Backend hosting

The GitHub Pages deployment hosts the frontend only. To expose the backend publicly you can:

• Deploy backend/ to any Python-friendly platform (Render, Railway, etc.)
• Configure the backend URL in the Flutter app (or via environment/config) so that the frontend talks to your deployed API instead of localhost.

Typical production environment variables for the backend:

• PORT – port the Flask app listens on (provided by most platforms)
• Any additional secrets or API keys specific to your deployment platform

Architecture

• Backend: Flask API in backend/app.py with data processing and recommendation logic
• Frontend: Flutter web app in frontend/ for an interactive UI
• Testing: pytest suite under backend/tests/
• CI/CD: GitHub Actions for backend tests and automatic frontend deployment to GitHub Pages