Skip to content

Commit

Permalink
Docs: Add more detail
Browse files Browse the repository at this point in the history
  • Loading branch information
@phnagy
phnagy committed Sep 2, 2024
1 parent eb7447f commit d7c1a4c
Showing 1 changed file with 72 additions and 29 deletions.
101 changes: 72 additions & 29 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,29 +78,56 @@ Bob,Johnson,[email protected],Male,002,5,Bachelor,Information Systems,Interm
Carol,Lee,[email protected],Male,003,7,Bachelor,Computer Science,Expert,Native,C1/C2,DE,1,0,Intermediate,Intermediate,true,true,false,false
```

- **Gender**: Female, Male, Other, Prefer not to say
- **Project preference**: 0, 1, 2, ... (0 is the highest Priority)
- **Skill proficiency**: Novice, Intermediate, Advanced, Expert
- **Language Proficency**: A1/A2, B1/B2, C1/C2, Native
- **Nationality Format**: ISO 3166-1 alpha-2
- **Language Format**: ISO 639-1
- **Device**: true, false
- **Supported Devices**: IPhone, Mac, IPad, Watch
- **Skill Names**: Any name is allowed
- **Project Team Names**: Any name is allowed
#### Mandatory Header Fields:

- firstName
- lastName
- email
- gender
- id
- semester
- studyDegree
- studyProgram
- skillLevel
- nationality
- device
- device[IPhone]
- device[Mac]
- device[IPad]
- device[Watch]

#### Dynamic Header Fields

- language[X] (where X is the language format (ISO 639-1), currently required: **de** & **en**)
- projectPreference[X] (where X is the project team name)
- skill[X] (where X is the skill name)

#### Permitted Values:

- **gender**: Female, Male, Other, Prefer not to say
- **projectPreference[x]**: 0, 1, 2, ... (0 is the highest priority; values must be strictly sequential from 0 to n with no duplicates)
- **skill[x]/skillLevel**: Novice, Intermediate, Advanced, Expert (where Novice < Intermediate < Advanced < Expert)
- **language[x]**: A1/A2, B1/B2, C1/C2, Native (where A1/A2 < B1/B2 < C1/C2 < Native)
- **nationality**: ISO 3166-1 alpha-2
- **device**: true, false
- **firstName/lastName/email/id/studyDegree/studyProgram**: String
- **semester**: Integer

## Matching

After importing the data, all the students can be found in the student pool, located at the bottom of the screen in the utility section.
Students can be manually dragged and dropped into a project team, but the core functionality of the tool is to automatically match students to project teams.
The core functionality of TEASE is to automatically assign students to project teams using a matching algorithm.
Users can also manually drag and drop students into a project team, to fine tune the project team allocation.

It is important to create constraints for the matching algorithm to follow. Without constraints, the algorithm will match students based solely on their highest priorities, which can lead to uneven team sizes, skill distributions or other imbalances.
It is important to create constraints for the matching algorithm to follow.
Without constraints, the algorithm will match students based solely on their highest priorities, which can lead to uneven team sizes, skill distributions or other imbalances.

![Matching](matching.gif)

### Constraints

Constraints are crucial for the matching algorithm, as they determine how well the results meet the desired outcome.
Users can create new constraints by clicking the plus button in the navigation bar.

A constraint consists of three parts: project selection, filter, and limits.

Expand All @@ -111,29 +138,33 @@ The constraint must be fullfilled for each project team.

#### Filter

A filter consists of a property and a value, with some filters using comparison operators for more customization. For example, intro course proficiency can use the "at least" operator to filter for students with a minimum skill proficiency level of advanced.
A filter consists of a property and a value, with some filters using comparison operators for more customization.
For example, intro course proficiency can use the "at least" operator to filter for students with a minimum skill proficiency level of advanced.
This includes all students with an advanced or expert skill proficiency level.

Filters can be defined based on the following properties:

- skill proficiencies
- language proficiencies
- intro course proficiency
- development devices
- gender
- nationality
- language proficiencies
- intro course proficiency
- team size

Students are then dynamically filtered based on their properties.

#### Limits

Each constraint has an upper and lower limit that the selected project team must meet. These limits refer to the number of students who meet the filter criteria and are assigned to the project team.
Each constraint has an upper and lower limit.
These limits refer to the number of students who meet the filter criteria and are assigned to the project team.
The limits must be fullfilled for each project team.

### Matching Algorithm

The matching algorithm uses a linear programming approach to match students to projects using the defined constraints.
Each student is matched to exactly one project team, with the optimization objective focused on maximizing project preferences.
The algorithm generates only valid project team allocations.
The matching algorithm uses a linear programming approach to assign students to projects based on the defined constraints.
It ensures each student is assigned to exactly one project team, optimizing to maximize project preferences.
The algorithm generates only valid project team allocations, meaning that all constraints must be met.

### Constraint Summary

Expand All @@ -143,7 +174,7 @@ In this view, users can create new constraints using either the default constrai

The overview shows each part of the constraints: the filter, the limits, and the selected projects. By clicking the three dots on the right, users can delete, edit, or deactivate a constraint, meaning it will not be used by the matching algorithm.

By pressing the "Distribute Teams" button, the matching algorithm distributes the allocation.
By pressing the "Distribute Teams" button, the matching algorithm distributes the students.

![Constraint Summary](ConstraintSummary.jpeg)

Expand All @@ -152,10 +183,10 @@ By pressing the "Distribute Teams" button, the matching algorithm distributes th
The Statistics section allows users to view detailed statistics about project teams and students. It uses different charts to visualize different metrics. Possible metrics to analyze include:

- Priority distribution
- Skill distributions (Intro Course Proficiency and other imported skills)
- Skill distributions (Intro Course Proficiency and other imported dynamic skills)
- Device distributions (iPhone, Mac, iPad, Watch)

The statistics are crucial for assessing the quality of the distribution and are helpful for analyzing and manually fine-tuning the results.
The statistics are crucial for assessing the quality of the distribution and are helpful for analyzing and manually fine-tuning the allocation.

![Statistics](statistics.gif)

Expand All @@ -166,9 +197,9 @@ This dynamic data includes students locked to project teams, project team alloca

To prevent misuse of the collaboration server, users must first log in to PROMPT.
Once logged in, authentication to the collaboration server happens automatically.
Currently this feature is available only for data imported from PROMPT.
This feature is available only for data that users import from PROMPT.
Data synchronizes only between the same course iteration.
The imported course iteration appears in the navigation bar, with the live collaboration status displayed next to it.
The course iteration appears in the navigation bar, with the live collaboration status next to it.

![Live Collaboration](live-collaboration.gif)

Expand Down Expand Up @@ -231,6 +262,8 @@ docker compose up

Use `docker compose up --build` to build the images locally from the repository.

The application will be available at `http://localhost:80/tease`.

# Development

TEASE consists of a client and a server. The client is built with Angular, while the server utilizes Spring Boot with Java and functions as a STOMP WebSocket Broker.
Expand All @@ -243,13 +276,16 @@ To start the client, run `npm start` for a development server. After successful

The application will automatically reload if you change any of the source files.

The PROMPT API is automatically generated using `npm run openapi:generate` and is documented in [openapi_spec.yaml](https://github.com/ls1intum/tease/blob/main/client/docs/openapi_spec.yaml). To explore and edit the API documentation, you can use the [Swagger Editor](https://editor.swagger.io/). All data objects used in TEASE are declared in this documentation.
The PROMPT API is automatically generated using `npm run openapi:generate` and is documented in [openapi_spec.yaml](https://github.com/ls1intum/tease/blob/main/client/docs/openapi_spec.yaml).
To explore the API documentation use the [Swagger Editor](https://editor.swagger.io/).
This documentation declares all data objects used in TEASE.

## Server

In the server directory, run `mvn install` to install all necessary dependencies.

To start the server, run `mvn spring-boot:run`. After successful startup, the server can be accessed at `http://localhost:8081/`. The websocket server uses the STOMP messaging protocol to handle real-time communication and message exchange between clients and the server.
To start the server, run `mvn spring-boot:run`. After successful startup, the server is available at `http://localhost:8081/`.
The websocket server uses the STOMP messaging protocol to handle real-time communication and message exchange between clients and the server.

In general, there are four main STOMP paths:

Expand All @@ -258,13 +294,20 @@ In general, there are four main STOMP paths:
- course-iteration/{id}/constraints
- course-iteration/{id}/locked-students

When a new client sends a message to the discovery channel, they receive all current states of the dynamic data through the other channels. Any message sent to the allocations, constraints, or locked-students channels will be broadcasted to all connected clients, updating them with the latest information.
When a new client sends a message to the discovery channel, they receive all current states of the dynamic data through the other channels.
Any message sent to the allocations, constraints, or locked-students channels will be broadcasted to all connected clients, updating them with the latest information.

# PROMPT Integration

[PROMPT](https://github.com/ls1intum/prompt) is a support tool designed to assist program management in project-based courses. TEASE integrates closely with PROMPT, enabling direct import and export of student and project team data. The API is documented with the OpenAPI Specification in [openapi_spec.yaml](https://github.com/ls1intum/tease/blob/main/client/docs/openapi_spec.yaml). To explore the API documentation use the [Swagger Editor](https://editor.swagger.io/).
[PROMPT](https://github.com/ls1intum/prompt) is a support tool designed to assist program management in project-based courses.
TEASE integrates closely with PROMPT, enabling direct import and export of student and project team data.
The file [openapi_spec.yaml](https://github.com/ls1intum/tease/blob/main/client/docs/openapi_spec.yaml) documents the API using the OpenAPI Specification.
To explore the API documentation use the [Swagger Editor](https://editor.swagger.io/).

To deploy TEASE alongside PROMPT, install both on the same machine. Start by deploying PROMPT first. Next, deploy TEASE into a directory named `tease`, which should be one level below the top-level directory where PROMPT is installed. This is where you'll find PROMPT's Docker Compose file. Detailed installation instructions for TEASE can be found in the [Installation](#installation) section.
To deploy TEASE alongside PROMPT, install both on the same machine.
Start by deploying PROMPT first.
Next, deploy TEASE into a directory named `tease`, which should be located directly below the top-level directory named `prompt`.
Detailed installation instructions for TEASE can be found in the [Installation](#installation) section.

# Deployment

Expand Down

0 comments on commit d7c1a4c

Please sign in to comment.