# SAM

## Description

_Note: anytime a paragraph is written in italics, it is not a part of the README.md but rather an aside. We deem those necessary as although none of our planned features are actually complete, we have made significant progress towards an MVP and each individual feature. Most of our issues are integration problems._

_Note: we have not successfully deployed our application yet. Each of our components runs independently but none fully interact. Anytime we provide a URL with prefix `http://studyabroadmatching.com/`, this URL does not represent a working link but rather our ambition to produce a working link._

### As a member of the administrative team

#### Some context

Imagine you work at university X. This university has a study abroad program that allows its students to spend a semester abroad at one of its partner universities.

To be eligible, students have to apply to the study abroad program by providing a wish of the universities they want to go to, motivation letters for their wishes, and their gpa.

Your job is to evaluate the student application and wishlists and come up with a final matching of students to universities.

#### Universities

Your first step as the administrator of your study abroad program is to declare which universities are your partners. To do this you must fill out a form at `http://studyabroadmatching.com/universities/add`. This form allows you to specify the university's:
- name
- region (Europe, Asia, ...)
- quota or maximum number of exchanges candidates
- minimum GPA for exchange students
- minimum age for exchange students
- excluded nationalities: relevant in the case of China, who does not wish to accept Chinese natives into exchange programs
- acceptable majors for exchange students

You can later consult an overview of all the universities you added at `http://studyabroadmatching.com/universities`. You can consult all universities of a single region.

To consult the details of a single university, access `http://studyabroadmatching.com/universities/{name}`. To edit those details, access `http://studyabroadmatching.com/universities/{name}/edit`

Each university can also be associated to several language requirements, which may be specified on the same page as that of the university profile. They specify the test (e.g. TOEFL iBT) and the necessary score (e.g. 110).

_The functionality was successfully implemented in the backend (API) as will be demonstrated in the demo. Although drafts were created for the pages of a react app in the frontend, those pages were not integrated with the API._

#### Students viewed by administrator

As the administrator of your university's study abroad program, you wish to consult which students are applying to partner universities. You can do so at `http://studyabroadmatching.com/students`. On this same page, you can consult which student applied to a specific university.

Upon clicking on any of the students listed on the page, you will access their details. You can access the following information:
- first and last name
- nationality
- date of birth
- GPA
- list of universities they are applying to

_The functionality was successfully implemented in the backend (API) as will be demonstrated in the demo. Although drafts were created for the pages of a react app in the frontend, those pages were not integrated with the API._

#### Matchings

As the administrator of the study abroad program, your main job is to match students for universities. To create a matching, simply follow `http://studyabroadmatching.com/matchings/add` and specify the matching's name and concerned exchange semester.

After creating the matching, you will be redirected to `http://studyabroadmatching.com/matchings/{pk}`. You can fill in the criteria for your matching at `http://studyabroadmatching.com/matchings/{pk}/edit` by clicking the _edit_ button. These criteria are at the core of the value added by SAM. They are a way of specifying what you wish to obtain from a matching without computing the matching manually by yourself. The criteria are:
- for each partner university
- the weight put on the GPA and Motivation Letter to rank applicants
- optionally overwrite (only for this matching) quotas a minimum GPAs you set for the university
- for each student
- a boost on their GPA (advised by professors)
- for each student application
- a motivation letter grade, specific to this matching

You can consult all created matchings at `http://studyabroadmatching.com/matchings`. You can request to see all matchings created for a particular semester.

You can compare the pairings (between students and partner universities) created by two different matching by selecting them on this page and clicking a _compare_ button. This will redirect you to a tool hosted at `http://studyabroadmatching.com/matchings/compare`.

The statistics hosted there are:
- for each student, the rank in their wishlist of the university he/she has been matched with (0 if unmatched)
- the number of students matched to each university
- the number of students matched to their ith choice
- empty universities
- unmatched students

_Some functionality (matching criteria resource) was successfully implemented in the backend (API) but the pairings are not yet accessible from the API. The algorithms to compute pairings and comparisons have been implemented but are not called by the other components yet. Although drafts were created for the pages of a react app in the frontend, those pages were not integrated with the API._

### As a _student_

#### Student profile

As a student wishing to partake in a study abroad program, you wish to apply to some of the several host universities offered by your degree program. To do so, you must first open `http://studyabroadmatching.com/students/add` and create a student profile.

After creation, you will be redirected to your profile, at `http://studyabroadmatching.com/students/{pk}`. You may edit it by clicking the _edit_ button, which will redirect you to `http://studyabroadmatching.com/students/{pk}/edit`.

The information contained in the student profile (and editable) is the same as the one accessible from the administrator's point of view.

_The functionality was successfully implemented in the backend (API) as will be demonstrated in the demo. Although drafts were created for the pages of a react app in the frontend, those pages were not integrated with the API._

#### Applications

SAM's value added to students is the application process. To apply to a university, you must create an application at `http://studyabroadmatching.com/applications/add`. After the creation of this application, you will be redirected to `http://studyabroadmatching.com/applications/{pk}`. You may edit this application by clicking the _edit_ button which will redirect you to `http://studyabroadmatching.com/applications/{pk}/edit`.

The information you can view and edit for each of your applications is:
- the university this application is for
- the semester you are applying for
- your motivation letter
- your study plan (planned courses) as a link to a PDF file

When applying to universities, you must also attempt to fulfill the language requirements. You can do this by specifying language attempts on you application edit page. You must input which test you took and what score you obtained, on which date.

_The functionality was successfully implemented in the backend (API) as will be demonstrated in the demo. Although drafts were created for the pages of a react app in the frontend, those pages were not integrated with the API._