# SAM (Study Abroad Matching)
## Product Details
### Q1: What are you planning to build?
SAM is a web application designed to facilitate the application and matching processes of a university's study abroad program.

Generally, universities with study abroad programs have a selection committee who reviews the applications and manually matches students to partner universities.
Students submit motivation letters, a wish list of the partner universities they want to go to, their study plans for each wish, and their GPA and test scores.

There are three main flaws in the current application and matching processes:
* Students send their application materials through different channels and the committee has to collect them from each of these different channels.
* The matching method is based on a greedy method. i.e. students are assigned one by one given their individual wishes to universities until no spots are left. Hence The scope of the matching is very narrow and the overall result is only considered at the end.
* The matching is done manually and there is no room for experimenting with evaluation criteria or matching methods.

SAM intervenes in all steps of the matching process to solve these issues:
* Students can write their motivation letters, make their wish lists, and upload relevant documents directly through SAM.
* SAM produces a matching based on clever algorithms inspired from recent research papers in game theory.
* The selection committee can edit the matching and ranking criteria and export the results.
* SAM provides a live matching and comparison tool.

#### Interactive mockup for the selection committee interface
link : https://adobe.ly/2B262ZT
* To generate a matching of students, click on the "Matching" box from the home page or the "Matching" tab on the left sidebar.
* The first page of the matching process allows the user to configure the weighting of GPA and motivation scores for each school. SAM will dynamically display an anonymous student list as the weighting changes.
* Clicking "SUBMIT" on the bottom right will finalize the selection criteria and display a complete results spreadsheet.
* To view student data, click on the "Student Data" box from the home page or the "Student Data" tab on the left sidebar.
* To manually add a student, click on "ADD STUDENT" at the top of the page and input their data.
* To view a student's details, click on their name or ID number.
* To edit or delete a student, open their details page and click on "EDIT STUDENT" or "DELETE STUDENT" at the top of the page.
* To view program info, click on the "Program Info" box from the home page or the "Program Info" tab on the left sidebar.
* To add a program, click on "ADD PROGRAM" at the top of the page and input program info.
* To view a program's details, click on the program name.
* To edit or delete a program, click on "EDIT" or "DELETE" at the top of the page.

### Q2: Who are your target users?
* Sophie is our early adopter. She manages the selection committee at Ecole Polytechnique, France - where four of our team members come from. She has experience with Excel and currently uses it for most of the selection process.

* Edison is a third year student at Ecole Polytechnique. He went through the process of applying to a study abroad program last year. He is currently abroad at Georgia Institute of Technology. He likes when everything is done electronically, and doesn't want to go to different offices to collect signatures.

* Olivier is the advisor of the computer science students who want to go abroad. He has to verify each of their study plans for each university which he receives via email. Olivier receives multiple emails a day and is very busy. Emails very often get lost in his inbox.

### Q3: Why would your users choose your product? What are they using today to solve their problem/need?

* SAM will allow Sophie to focus by being the only platform she has to interact with.
She currently has to get files from different platforms at each step of the application: Test scores from emails, wish lists from limesurvey, and study plans from advisors.
* SAM will allow Sophie to make better decisions with less energy.
Currently, Sophie has to finalize the selection criteria before starting the matching process, and has to repeat the process if she is not satisfied with the final result. By providing live matching results given an input criteria, SAM allows Sophie to adjust the criteria at any time and find the ones that satisfy her the most.
* SAM provides the best matching possible satisfying students wishes.
Indeed, SAM will use a customized version of the Gale-Shapley stable matching algorithm.
* SAM will provide students a stress free application process.
With SAM, Edison will not be worried that his study plan will get lost in his advisor's mailbox. SAM groups all aplication steps in a single plaform, keeps track of deadlines, and sends reminders to advisors.
Edison struggled to submit his wishes on limesurvey and one of his motivation letters was lost because of the platform's timeout. SAM will be user-friendly and reliable.
* SAM will allow very busy Olivier to spend the little time he has for students applying abroad efficiently.
SAM provides all the study plans of the students in one platform and allows Olivier to open meeting slots bookable by students.

### Q4: How will you build it?

#### Technology stack

##### Languages, frameworks and hosting

We will use Python (3.7) for all backend code, and will use the Django web framework to develop our web app. React is the only JS framework which has unified web developers in our century and will therefore be our tool of choice for frontend development.

We are considering two deployment options: Google Cloud Platform and the school‘s local servers. Although we would rather develop on GCP, our early adopter has specific security requirements and is concerned by the Cloud Act and GDPR. They are used to deploying their tools locally.

Rationale for these decisions is located in the highlights section.

##### Deployment details

SAM will present as a web app that feels like a desktop app (like drive, box, etc). As mentioned above, the server side code will likely run on Google App Engine. There will be three different front end interfaces: one for exchange students, one for university administrative teams (selection committee), one for exchange advisors.

**Describe the architecture - what are the high level components or patterns you will use? Diagrams are useful here.**


The server app will run on GAE and interact with the Cloud SQL database where the core matching data will be stored. Our data centralization features will be implemented using Google Cloud Storage in the backend. Components labeled _MVP_ are our priority as they are essential to SAM. We aim to implement the components labeled _Additional Features_ by the end of the course but they will come second to the matching functionality.

**Will you be using third party applications or APIs? If so, what are they?**

We will be using external technologies to integrate our system with existing tools. Indeed, our early adopter currently uses office tools such as Excel to solve the problem, which warrants our integration with office suites such as:
- Office 365
- GSuite (Google Drive)

The latter will offer a familiar interface to the matching data and student files to the selection committee and student advisors. These technologies are included in the diagram above as targets for exporting data.

We will also consider an external service to ease digital signing of study plans: DocuSign.

##### Testing strategy

Here are our candidate approaches for testing:
- Django’s testing capabilities for simple tests
- Our early adopter will try the product and report issues
- Maybe
uuy tests conducted by humans (see above)

###### Frontend

Jest will be our javascript testing framework for unit and integration testing. It's simple to set up and includes snapshot testing for UI consistency. It can be used alongside Selenium.

###### Backend

Django has extensive built in testing modules/classes RequestFactory/Client. However, any other testing framework such as Pytest and Selenium can be integrated to Django.

Overall strategy for testing:
- Use either PyTest or PyUnit for unit testing.
- Use Django's Client class to test behaviour of GET and POST requests, in particular whether correct template is being rendered.
- Use Selenium framework to test JavaScript part of Web application. Namely, to test rendered HTML and overall behaviour of web application. This part is particularly important for final product. (Functional testing)

### Q5: What are the user stories that make up the MVP?

_Student Exchange Selection Committee perspective:_
* **User Story:** As a member of the student exchange selection committee verifying the integrity of application files before selection, I want to automate the task of verifying that each student application respects the prescribed rules (sufficient GPA, language requirements, advisor approval, valid wishlist...) for each university, so as to save myself the inconvenience of going through each application folder individually.
**Acceptance Criteria:**
* A feature that allows users to add universities to SAM, specifying each university's requirements.
* When adding a new student to SAM, check that their application file matches the requirements of every university in their wishlist. Otherwise, output an error message preventing the addition of this student to SAM.
* **User Story:** As a member of the student exchange selection committee selecting students for each university, I want to provide a ranking of applying students for each exchange university and obtain in return *the best* distribution of all students across these universities, in order to save myself the time of building numerous student-uni configurations and comparing them.
**Acceptance Criteria:**
* A feature allowing users to rank all students having applied to a university, for all available universities.
* A *Match* feature which matches each student to an university, respecting universities' quotas and students' relative rankings, while trying to maximize student satisfaction by giving each their best choice.
* **User Story:** As a student officer reviewing the selection outcomes, I want to be able to easily visualize the distribution of students with respect to their selected wish, in order to evaluate at a glance the general conciliation of student wishes to selection outcome.
**Acceptance Criteria:** A feature which, following each matching process, displays a graph of the number of students as a function of the n-th choice obtained by each student.

* **User Story:** As head of the student exchange selection committee, I want all exchange related student documents (wishlists, motivations, certificates...) and administrative data (GPAs, student rankings per uni...) to be sent by each concerned individual to one centralized place, in order to avoid having to use various platforms (LimeSurvey, Excels, e-mails...) and have a staff member retrieve each necesary document themselves.
**Acceptance Criteria:** See below _Acceptance Criteria (Centralization)_.

_Dean perspective:_
* **User Story:** As the dean of the Bachelor Program, I want the distribution of students across exchange universities to follow a more standardized process, so as to reduce student interrogations and complaints through transparent and objective selection.
**Acceptance Criteria:** A fixed algorithm which takes care of the student-university matching process. (This allows the details of the algorithm to be communicated to students.)

_Student Advisors perspective:_
* **User Story:** As a student advisor, I want to be able to review all students' study plans in a single location, so that I don't need to receive, organize, and reply to individual e-mails from each student with a study plan pdf in attachments.
**Acceptance Criteria:** See below _Acceptance Criteria (Centralization)_.
* **User Story:** As a student advisor, I would like to be able to digitally sign a student’s study plan so as to avoid having to print it and scan it again.
**Acceptance Criteria:** See below _Acceptance Criteria (Centralization)_.

_Student perspective:_
* **User Story:** As a prospective exchange student, I want a platform to which I can reliably send all my exchange application documents at once or over several sessions, so that I can save myself the trouble of having to read a new email and follow a new weblink for each required document submission, and at the risk of eventually missing a submission deadline.
**Acceptance Criteria:** See below _Acceptance Criteria (Centralization)_.
* **User Story:** As an exchange student who must have his study plan signed by several advisors, I would like to upload it in one place where it will be available to all advisors for comment and signature, which they will be able to do in parallel (as opposed to the sequential email case).
**Acceptance Criteria:** See below _Acceptance Criteria (Centralization)_.

* **Acceptance Criteria (Centralization):**
* A web platform with user authentication (for admin staff, students and advisors) which gives each user a profile and different priviledges.
* Students can submit their wishes, and files (motivation letter, certificates, study plan). They have access to their own profile and the files they have submitted.
* Advisors have access to all students' study plans. They can upload an electronic signature that is added to a student's study plan when it is accepted by the advisor. They can also leave a comment on the a student's study plan for review.
* Admin/Selection staff have access to all students' files, and an option to approve or grade a document (i.e. approve validity of TOEFL 118/120 score, grade a motivation letter).
* Notifications are displayed to relevant users when a document is modified (i.e. advisor requests study plan modification, so student is notified that he must modify his study plan).

----

## Process Details
### Roles & responsibilities
#### Skander Moalla _Aka Scrum lord_
**Roles:** Scrum master / reseach scientist
**Description**: As a scrum master, Skander is responsible of ensuring a truly agile development cycle by planning the sprints and making sure they are executed as planned: respect of sprint backlog and organization the necessary meetings.
As a scientist, he is responsible of developing and testing the main algorithm that will be used for the matching feature.
**Strengths:** 2 years of experience with python, solid maths training, game theory and mechanism design enthusiast, experienced in team leading.
**Weaknesses:** Never used Django nor React, lacking experience in architechture/stack design, unaware of deployment and shipping technologies.

#### Loan Tricot
**Roles:** Product owner / manager / architect
**Description:** As a product manager, Loan must point out which part of the developers’ work is useless to the client. He is the sanity check of the team. The product manager must be proactive and guide developers’ work by interacting often with the early adopter to receive feedback and further understand the customer’s needs.
As a tech architect, Loan is concerned with the separation of the application implementation into different components. He ensures each component adheres to a specification so that they can all rely on each other’s behavior and be developed independently.
**Strengths:** Significant experience with google cloud platform and architecting solutions. Excellent python programmer.
**Weaknesses:** Underestimates how much time a task will take. A strong sense of how things should be done — maybe too strong (clearly too strong).

**Development Team**
#### Teo Chaban
**Role:** Researcher and Developer
**Description**: Will be responsible to research the best algorithms to solve our problem, and try to taylor it to the particular needs of the project. Will also be responsible to make sure that the coding side of development is running smooth, and implement the researched algorithms.
**Strengths:** Backend coding, statistics, math, development methodologies.
**Weaknesses:** Limited experience with integration of back and front end and no experience with deployment technologies.

#### Marine Hoche
**Role:** Researcher
**Description** read scientific papers (mainly on matching algorithms) to find the best algorithms to solve our problem and present the solutions to the rest of the team, develop and test these algorithms
**Challenges** Find efficient algorithms that really suit our needs, discuss with the product manager to verify the compatibility with the consumer's needs and with the tech leader for the smooth integration of the algorithms.
**Strengths**: Strong background in maths and statistics, comfortable in coding in python, already worked on a software development project within a big team
**Weakenesses** methodologies (be too focused on the research side ie finding the best algorithm possible without testing intermediate options), code documentation, limited knowledge in version control

#### Guillaume Lainé
**Role(s):** Software Engineer
**Description**: Will be responsible of using the technology stack chosen by the tech lead and organising and developing the features thought up by the researchers on the team, and documenting code.
**Strengths:** Mathematics, coding, documentation.
**Weaknesses:** UI/UX, version control, development methodologies.

#### Osman Afandiyev
**Role:** Tech lead
**Description:** Will be responsible for choosing technologies which are most optimal for development and deployment of a project and maintaining overall awareness of those technologies usage in a team.
**Strengths:** Have previous experience with full stack development, knowledge of various technologies out there, rich experience with development of database.
**Weaknesses:** Limited knowledge of developing algorithms and proving it's correctness, no knowlege/experience of graphic design or any front end.

#### Grey Lee
**Role(s):** Designer
**Description**: Will be responsible for SAM's UI/UX and visual design, including logos and style guide. Will also be responsible for integrating design elements in front end development.
**Strengths:** Graphic design, front end, client communication
**Weaknesses:** Limited experience with the tech stack platforms, algorithm design, back end.

### Team Rules

#### Culture

At SAM the hapiness and productivity of each team member are priorities. It is important that everyone has the opportunity to develop the skills they value. In fact, working on a task that deeply interests a member and serves their personal and academic objectives is much more enriching. It will be performed efficiently, carefully and with greater precision. We have thus insisted on this point during the role assignment, we didn't require someone in charge of a particular topic to be particularly skilled in it but rather to be strongly motivated to learn it.

Diversity is what makes our team strong. That is, diversity in academic background but also diversity in origin, personality, and values.

#### Communication

##### Within the team
We use slack to communicate. This platform allows us to set different channels, thus having subteam communications and more general ones on the same platform, along with a channel to communicate with our assigned TA.

We have an urgent channel on Slack which must be checked at least once a day. All the members must have notifications enabled on their phone for this specific channel.

##### With our partner:
We have an independent project but have an early adopter which is Ecole Polytechnique in France. We are directly communicating with Sophie — Who manages the study abroad commitee — by email and video conference.

#### Meetings:

* Weekly meetings are mandatory, we can change the date/time of the meeting in case someone is unavailable.
* If an additional meeting is needed or a meeting must be rescheduled, it should be planned at least 2 days beforehand.
* The scrum master is responsible for the meeting's schedule: the scrum master
* introduces the meeting's subjects
* ensures every item is addressed in a timely manner

#### Conflict Resolution:

##### Conflict scenarios:

* _A key decision has to be taken but there are two different points of view within the team:_
It's necessary to talk about it, to list the pros and cons of each idea, that every member of the team tells the other his/her point of view on each idea and after that to do a vote. In this way, we can come up with the solution that is the best for the team and the projects and every member will have deeply thought about the consequences/interests/defaults of each of the different options.

* _We are one hour before the deadline of one of the deliverable and one of the team member has not completed his/her task:_
To prevent this situation, we will do a meeting a couple of days before each due date to review the work of everybody and give time for some modifications. If this still happens, then if it was due to a personal issue, the team will show its best support to the member and will explain the circumstences to the teaching team hoping to get an extension of the deadline. If the team member failed to complete their task because of bad time management, then we will submit the assignment as it is, bear the responsibilty together. But the team member will have to bring tasty snacks to the next meeting.

* Two team members do not get along and are thus unable to work on a common task (inefficiency in their work because of recurrent conflicts).
The scrum master, or any other team member will evaluate the conflict, make their best to solve them: if it is due to miscommunication or values. In any way, the team will never tolerate any kind of conflict to perdure. However for special circumstances. These two persons would be assigned independent tasks.

### Events
We meet twice a week. Once during the tutorial slot on Tuesdays and once on Friday in Robarts. We perform our stand up meetings at the beginning of those meetings. Each team member briefly describes what they have been working on recently and what they plan to do for the next week. Friday's meeting, the longer one, is also the one during which we schedule our sprint planning, review, and retrospective. Since we value everybody learning from the project, we also discuss important decisions and challenges of each subteam during these meetings. Most importantly since we do not see each other everyday, it is crucial for our friendship and team spirit to see each other at least twice a week.

Code reviews are done online.

### Partner Meetings

We do not have an official partner but we do have an early adopter: Ecole Polytechnique. As mentioned above. We are directly communicating with Sophie — Who manages the study abroad commitee — by email and video conference.

#### First meeting

The very first meeting with our early adopter was about understanding the customer’s problem better, and identifying where we can bring value:
- What is their current approach to matching students and exchange programs (Detailed process with explicit steps) ?
- How much time does each step take ? Which part of the process os the most frustrating ?
- Given our suggestion for a solution (a short presentation of our concept product), what do they believe will help them the most / which feature do they believe will have the more value ?
- Can they provide us will a small dataset for our proof of concept ?

We took detailed notes of the answers to each question above.

#### Future meetings
We will meet with Sophie when deemed necessary: collect her feedback on some design or to conduct a live demo. Otherwise we keep a regular conversation via email to get answers any questions we have.

### Artifacts

Project management tools for development:
- Github projects with Zenhub
- Github Issues
- Meeting notes for every team meeting involving important decisions

Product management tools:
- Github projects / zenhub / issues as above for product backlog
- Meeting notes for every partner meeting
- Feature specifications using https://www.ietf.org/rfc/rfc2119.txt

Documents will be stored on github or google drive depending on which of those is more appropriate.

### Highlights

#### Reponsible design

A feature of SAM involves displaying live results of student rankings per university given the importance of each criteria. We noticed that the amount of information displayed in the live results could be a source of bias for Sophie while tweaking the input parameters (app's tool to set different paramaters like the importance of GPA, quality of the motivation letters,...). Indeed seeing the name of some particular student bouncing in and out of a university's quota could bias Sophie. Thus displaying ID's is enough.
In a general way, displaying more information than the minimal required can only introduce bias in the system. It is thus important to design our app in a way to minimize this bias since the final assignment of students to universities must be as fair as possible.

#### Technology stack rationale

##### Languages

To code the matching algorithms, we were thinking about switching to C++ because it is faster. Python is however more convenient. Moreover, given the data is so small scale (O(students * universities) for each customer), it is unlikely C++ would make a noticeable difference.

##### Frameworks

Our options for a python web framework, in order of decreasing preference:
1. **Django**
2. Pyramid
3. Flask (too raw)
4. aiohttp web (overkill)

Django is one of the most popular python web frameworks. It is modern and well maintained. Django comes with batteries included:
- ORM to manage database interactions
- User authentication capabilities
- Testing capabilities
- ...

Flask defines itself as a micro framework and relies on extensions to do the full job. It is very difficult to create non-trivial apps with Flask and the learning curve is quite steep.

Flask allows for more flexibility. Flexibility is however a double edged sword: the time we spend making technology decisions (choosing which database to use, etc) will be time we don’t spend building the MVP. Django is opinionated and allows to focus on the business logic. Given that we must build an MVP in under 2 months, Django is the better fit.

##### Hosting

Cloud Platforms in order of decreasing preference:
1. **Google Cloud**
2. AWS
3. Azure

Google cloud platform makes it very easy to integrate with gsuite for office (drive, *sheets*, docs). Exporting from google files to microsoft’s formats is built in google’s APIs. This allows to integrate SAM with our customers’ current tools.

Loan has extensive experience with Google’s APIs, along with their API authentication and authorization systems. This will help avoid wasting time ! Authentication / authorization issues are very time consuming and should not be underestimated.

Google App Engine is google‘s main web app PaaS. It is very well integrated with Python 3.7 and supports Django.

Google Cloud SQL is exactly what it sounds like. It is well integrated with Django’s database system and App Engine. There is extensive documentation to guide us.

After consulting the IT department of Ecole Polytechnique, it turned out that to use the university's authentification (like the weblogin idpz page of U of T) the app had to be hosted on their server. Moreover for the app to be properly used by Ecole Polytechnique, it has to go through an audit for security by the IT department and be compliant with some legal matter (GPDR, hosting in europe, etc ...).
We decided to proceed with Google cloud platform to allow the team members to gain experience with a modern and frequently used technology. Doing so, also enable us to offer our product to other universities than Ecole Polytechnique.
We will use the domain name of email addresses for authentification. A consequence to this decision is that Sophie using SAM in december for the new class will no longer be a final milestone project (since deploying the app on Polytechnique's servers might take more time).
However, we still hope to achieve such result. Indeed, we know some projects using the same tech stack as SAM that are running on Ecole Polytechnique's.
#### Artifacts:

Jira was among our options as a scrum board. but, we didn't elect it since it would represent a new software that the team has to learn to use and get used to. We prefered settling with Github project and the plugin ZenHub which is powerful enought and allows the team members to have everything centralized (code and Scrum board) and focus on the development.