tMatch

A Streamlit-based web application for matching students to bachelor projects at HES-SO Valais-Wallis, using the Hungarian algorithm to optimize assignments based on student preferences.

Overview

tMatch streamlines the project assignment process for academic programs (ISC, SYND, LSE, ETE) by:

• Allowing teachers to create and manage project proposals
• Enabling students to rate projects based on their preferences
• Using the Hungarian algorithm to compute optimal student-project assignments
• Sending email notifications for project updates and assignments
• Supporting role-based access for students, teachers, secretaries, and program directors

Features

• Multi-Program Support: Manage projects across different academic programs with program-specific views
• Role-Based Access Control: Four distinct roles (student, teacher, secretary, program director) with tailored permissions
• Hungarian Algorithm: Optimal assignment maximizing student satisfaction using scipy's linear_sum_assignment
• LDAP Authentication: Secure login via FreeIPA integration
• Email Notifications: Automated alerts for project creation, supervision assignments, and algorithm results
• PDF Specifications: Upload and store project specification documents
• Rating System: Students rate projects on a slider; directors can manually adjust ratings

Architecture

• Frontend: Streamlit with Starlette backend for authentication
• Database: PostgreSQL 16 with SQLAlchemy ORM and Alembic migrations
• Authentication: FreeIPA (AlmaLinux 10) via LDAP3
• Deployment: Docker Compose with 3 services (app, database, FreeIPA)
• Package Manager: uv for Python dependency management

Prerequisites

• Docker and Docker Compose
• FreeIPA server (provided via Docker image)
• SMTP server for email notifications (e.g., Infomaniak)

Development Setup

1. Clone the repository:

   git clone https://github.com/ISC-HEI/tMatch
   cd tMatch

2. Configure environment:

   cp .env.example .env
   # Edit .env with your configuration (see Environment Variables below)

3. Start all services:

   docker compose up -d

4. Access the application:

   • Streamlit app: http://localhost:8084
   • FreeIPA admin console: https://localhost:12343
   • PostgreSQL: localhost:3132

5. Initial setup:

   • The database is automatically migrated and seeded on first run
   • Create users in FreeIPA admin console
   • Assign roles via database or admin interface

6. Run tests:

   cd src
   uv sync --frozen
   uv run pytest -v

Production Deployment

1. Configure environment:

   cp .env.example .env
   # Configure all environment variables with production values

2. Deploy with Docker Compose:

   docker compose -f compose.yml up -d --build

3. Verify services:

   docker compose ps
   docker compose logs tmatch_app

Environment Variables

All configuration is managed via environment variables. Copy .env.example to .env and configure:

• Database: POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD
• LDAP: LDAP_HOST, LDAP_PORT, LDAP_USER, LDAP_PASSWORD, LDAP_BASE_DN
• FreeIPA: IPA_SERVER_HOSTNAME, IPA_PASSWORD
• Email: SMTP_SERVER, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD

Project Structure

src/
├── app.py                 # Main Streamlit page routing
├── main.py                # Starlette app entry point
├── config.py              # Configuration from environment
├── models/                # SQLAlchemy ORM models
├── views/                 # Streamlit page views
├── components/            # Reusable UI components
├── services/              # Business logic (auth, LDAP, mail)
├── utils/                 # Utilities (Hungarian algorithm, logger)
├── endpoints/             # HTTP endpoint handlers
├── emails/                # Email templates
├── seeds/                 # Database seed data
└── tests/                 # Unit tests

Algorithm

The Hungarian algorithm (scipy's linear_sum_assignment) optimally assigns students to projects by:

1. Building an n_students × n_projects rating matrix
2. Normalizing ratings per student to [0, 1]
3. Negating the matrix (minimize → maximize)
4. Computing optimal assignment in O(n³) time

Contributing

1. Follow existing code style and conventions
2. Add tests for new functionality