Topic Allocator

Summary

The goal of the application is streamlining the process of allocating multiple topics between students, taking into account certain constraints, such as the preference of the students, or the capacity of the instructors. (The problem is very similar to the college admissions problem, researched by Gale and Shapley.)

The application is designed to be embedded into e-learning platforms such as Moodle via implementing the LTI standard. This way most of the authentication and authorization is not the concern of the application.

Development

The project can be broken into four modules, a client and a server, the solver, and finally a module for e2e tests.

Client and Server

The server is an Azure Functions application, running on Node. The ORM used is Prisma. The client is a React SPA, using Vite as a bundler. The two modules are under an npm workspace, making it possible for code sharing between the two.

IMPORTANT: Make sure to only import code from the server to the client, and not the other way around. Importing client code on the server would make the client a runtime dependency of the server (since there is no "build" step on the server).

Starting locally

1. Install dependencies, in the root of the project run:

npm install

(This will install dependencies for both the client and the server.)

2. Put a local.settings.json at the root of the server folder (check local.settings.example.json for help)

3. Put the connection string of your MsSQL database on your path, its name should be LTI_DATABASE_URL. (Normally env variables should go into the local.settings.json, however, prisma, for some, reason is not able to read it from there.)

4. Start the dev servers

npm run dev -w client

and

npm run dev -w server

4. Navigate to the address of the client and set a cookie with key jwt and the value of the JWT that was produced as the result of an LTI launch. (Setting it manually is only required during development. Check lti.ts for more details.)

Solver

The solver is also an Azure Functions application this time written in python. The mixed integer programming model is mostly based on this publication.

Starting locally

0. Optional: set up a virtual environment

1. Install dependencies, in the root of the project run:

pip install -r solver/requirements.txt

2. In the root of the solver folder run:

func start

(For this you will need the Azure Functions Core Tools.)

Considering that you will probably run this together with the server, the default port, 7071 will be taken. You can specify a different port like this:

func start -p 7072

E2E tests

Playwright is used for e2e tests.

Running tests locally

1. Install dependencies, in the e2e folder run:

npm install && npx playwright install

2. Start the other modules locally

docker compose up

(You can also spin up the dev servers individually, however, in this case make sure to build the client and put the bundle under server/static.)

3. Make sure the database is in the right state

npx ts-node server/src/seed/ci-seed.ts

4. Run the tests

npm run test

Running with ui:

npm run test -- --ui

(Quick tip for writing tests: Check Playwright codegen.)

Deployment

Deployment happens through GitHub Actions. See the specified workflows for more details.

IMPORTANT: Workflows responsible for deployment do not cover database migrations (yet). In the event of a schema change npx prisma migrate deploy must be manually run against the production database.

E2E and unit tests are also automatically run through GitHub Actions.