PROJECT: TimeBook

Overview

My team was tasked to work on a basic command line interface desktop AddressBook application for our Software Engineering project. We chose to morph AddressBook to an application, TimeBook that makes scheduling team meetings a breeze for students. Students can keep track of their various on-going projects and sync the schedule of their project members onto a single platform. They can easily find common free time slot within a project group and we will suggest the closest location for everyone to meet. With TimeBook, scheduling Project meetings will no longer be a hassle.

TimeBook

guiComponent
Figure 1. Home window of TimeBook

My role was to be the project manager and create an algorithm to compute the best location for a meeting based on the project members' initial locations. This resolves the issue of students having to pick from the vast variety of options to choose the most suitable venues for project team meetings.The following sections illustrates this feature in detail, as well as the relevant documentation I have added to the user and developer guides in relation to these enhancements.

Summary of contributions

This section shows a summary of my contribution to TimeBook. It includes the contribution to code base, documentation and other helpful contributions.

Major Feature added: I added a feature that helps project teams choose the closest location for everyone to meet. Below is a visual representation of the feature:

SuccessfulPopup
Figure 2. Home window of TimeBook

  1. What it does: The popup command will display a popup(Figure 2 above) with information on are the three best place for everyone to meet during the school day. We define the best place to meet as the location that requires the least average travelling distance. As seen above, the users will be given the top 3 location with the least average travelling distance. They will know what the average travelling distance for each location and a picture of the location in Google Maps.

  2. Justification: NUS is a large campus with over five-hundred different venues to conduct the project meeting. Finding the best place to meet for a project can be a hassle as project teams the best location. This feature tackles this issue by using Google Maps to compute an unbiased closest common location that will benefit the team as a whole.

  3. Highlights: This feature works closely with external data sources such as NUSMods API(Application Programming Interface) to determine the initial location of the project members and Google Maps to compute the average traveling distance. Additionally I had to apply graph theory concepts to develop an algorithm to compute the closest common location. This feature is closely dependent on Ui, Scheduling and NUSMods component of TimeBook. I had to work closely with the other group members to ensure the seamless integration of this feature into TimeBook.

  4. Challenges:

    1. Google Maps:

      1. Google Maps APIs calls cost USD$10-USD$20/1000 calls. I had to minimise API calls by having a deep understanding of Google Maps APIs and carefully designing this feature to optimise resources constraints.

      2. There were bugs in Google Maps API and I had to meticulously analyze the API to identify potential break points caused by them.

      3. Google Maps Distance Matrix API only allows for return 100 elements per call but the complete graph I had to construct requires 10,000 elements. I had to carefully split the elements to blocks less than 100 and combine them together after the API was called.

    2. NUS Mods:

      1. Not all locations on NUS Mods were identifiable on Google Maps, I had to create a systematical approach to convert the locations on NUS Mods to locations that are identifiable on Google Maps.

    3. Credits: Utilized NUSMods and Google Maps API to get the necessary data for the feature.

Other Contributions

  • Code contributed: Repo Sense

    • Wrote test cases for Storage component #261. Increase coverage by 4%.

    • Worked with Marcus to implement caching of NUSMods and Google Maps API data.

  • Project management:

    • In charge of making sure the team meets the weekly deadline and delegated issues among the team.

    • Managed releases v1.1 - v1.4 (4 releases) on GitHub

    • Created Issue and Pull Request templates for more standardization in the repository.

    • Introduced an agile planning board here

    • Designed TimeBook logo for additional branding.

  • Enhancements to existing features:

    • Wrote test cases for storage component and increased coverage by 4% (Pull requests #261)

  • Documentation:

    • Adopted Open API Specification style of documentation into the UG for a clearer, more standardized and easier to read user guide.

      • Group each command into tag so that we can split explanation of the User logic into the tags explanation and the detailed command logic into the command explanation.

    • Drew high level design diagram for Storage component.

  • Tools:

    • Integrated a third party API(Google Maps) to the project

    • Introduced Lucid Chart to the team for easy design of UML diagrams.

    • Integrated Codacy into the repository.

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Closest Common Location

TimeBook will also help you to decide where to meet for your project meetings by suggesting to you an optimal location for everyone. The optimal location is the closest location for everyone to meet in NUS based on their schedule. In time book we define the optimal location for everyone as the closest common location.

Steps

  1. Set up your group by:

    1. Adding your group members to your TimeBook with addperson command

    2. Adding your group to TimeBook with addgroup command

    3. Add your group members to your group with addtogroup command

  2. Get the relevant information for your group schedule with show g/[GROUP_NAME]

    1. Identify the ID and Week of the time slot you want to get the closest common location for.

  3. With the free time slot id and week get the details for the closest common location with selectfreetime command

  4. Press esc button to close the popup

Constraints

Due to the lack of internet connectivity, TimeBook will only support locations that are in NUSMods and identifiable by Google Maps. The full list of supported locations is below.

Definitions

  1. We define closest common location as the location that requires the least average distance to travel to and from different sources by car.

  2. Locations that are not supported are voided and are not used for the calculations of the closest common location and average travelling distance.

  3. Refer to the Developer Guide on how we computed the closest common location.

Select Free Time selectfreetime

Select a free time slot to launch a popup window with all the relevant information to help you make decide on the venue to conduct your project meetings at. The image below is an example of the popup.

Below is an example of a popup.

SuccessfulPopup
Figure 3. An example of a popup when selectfreetime is executed

command: selectfreetime [week/WEEK_NUMBER] i/FREETIMESLOTID

Examples:

  • selectfreetime i/3

  • selectfreetime week/2 i/3

Description

When the command is executed, a popup will appear that shows all the information of the closest common location for a particular free time slot in a group.

Prerequisite

  1. You must be have group on TimeBook with members in it.

  2. You must execute show g/[GROUP NAME] before executing selectfreetime command.

Parameters

  1. [WEEK_NUMBER]

    • Description: The week(1-4) of the group schedule you want to select the free time slot from. If parameter is not stated, it will default to the first week(the default schedule when you execute show g/GROUP_NAME).

    • Type: Integer

    • Enum: 1, 2, 3, 4

  2. FREETIMESLOTID

    • Description: ID of the free time slot in the schedule. You can get this from the number in the free time slot box. You can only enter the id that is shown on the screen.

    • Type: Integer

Success Response

If you follow the steps above, a popup will appear as seen in the Figure above.

There are two main information that you will see in the popup when you execute the command.

  1. The summary of the results that will be displayed on the top of the popup.

    1. Your best location to meet up is: The first choice location to meet(closest for everyone).

    2. Everyone’s locations: List of locations that the group members will be at before the free time slot.

    3. Out of all these locations, the valid locations are: List of TimeBook supported locations that the group members will be at before the free time slot that.

      1. Subset of the Everyone’s locations: list

    4. Locations that cannot be found in NUS: List of locations that the group members will be at before the free time slot but not supported by TimeBook.

      1. Subset of the Everyone’s locations: list

      2. If all the locations are valid, this attribute will be empty as seen in the Figure above

  2. The full details of the first, second and third closest common location will be shown at the bottom of the popup.

    1. First choice represents the first closest and so on and so forth.

    2. The average distance(m) to reach the various locations will be displayed below the respective choices.

    3. The picture of the location of the venue on Google Maps will be displayed below each choice.

      1. For locations that are not supported on Google Maps, a picture of the center of NUS will be displayed.

Failure Response

  • Error when all the source locations are not recognised by TimeBook, a popup will not appear.

Feedback box will show:

 We could not find a common location because all places cannot be found in NUS. The locations are:

  • Error when all the group members are not in school before the free time slot, a popup will not appear.

Feedback box will show:

We could not find a common location because:
Everyone has not started their schedule yet. Feel free to meet up any time.

  • Error when invalid free time slot ID entered.

Feedback box will show:

Invalid time slot ID: 0. Please enter a valid id as shown in the GUI.

  • Error when invalid GROUP_NAME entered.

Feedback box will show:

Cannot recognise GROUP_NAME. Make sure you entered the correct value.

Close popup esc

After you are done with viewing the information on the popup press esc button on your keyboard to close the popup and and return to the main screen.

Format: esc button on keyboard.

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

Closest Common Location

Closest common location utilises Google Maps API to get the best center location to meet for a group project meeting. We define this location as Closest Common Location. Below is an example of this feature.

Popup
Figure 4. Popup for the closest common location.

Definition

  • Due to connectivity constraints, we cannot support location outside of NUS. View User Guide for the full list of location we support.

  • The closest location is the location that has the least average travelling distance by car from the various sources.

  • All invalid locations are omitted and will not be considered in the computation of the closest common locations.

Algorithm

  1. Create a complete graph where the vertices are the different locations in NUS and edges are the respective travelling distance by car from location u to v

  2. Represent this graph in a v x v matrix where i represent the source location and j represent destination location and distanceMatrix[i][j] represents the time needed to travel from i to j

  3. To get the closest common location of S1 …​ Sn:

    1. Get the rows i = l1 …​ ln

    2. Sum the values of the rows to a new row totalDistance

    3. The smallest value in the row is the closest common location

Below is an example of how the algorithm is applied on arbitrary locations l1…​ln with arbitrary travelling distance to compute the closest common location for l2,ln-2 and ln1.

Algorithm
Figure 5. Example of how the algorithm is used. The closest common location for this instance is ln-2.

Implementation

Consideration

  1. Google Maps API charges USD$10-USD$20 per 1000 call.

  2. Google Maps Distance Matrix Api has a limit of 100 elements for every API call.

  3. Google Maps Api has bug

    1. Inconsistency in identifying locations. Example

      1. NUS_LT17 is identified as the correct location and LT17 is not.

      2. NUS_AS6 is not identified as the correct location but AS6 is identified as the correct location.

    2. Certain locations are not supported by Google Maps

      1. S4 and S6 are identifiable but S5 is not.

    3. Some locations are valid on Google Maps Places Api but not on Google Maps Distance Matrix Api.

  4. Not all venues on NUSMods are identifiable on Google Maps API.

  5. Some venues on NUSMods are in the same building(ie AS6-0213 and AS6-0214).

Implementation

The image below represents the Class Diagram for Closest Common Location component of TimeBook

GmapsClassDiagram
Figure 6. Class Diagram for Closest Common Location Component

There are 3 main aspects to the implementation of this component.

  1. External API

  2. Creating the matrix

  3. Getting the closest location

External API

To support the limited internet connection, we preprocess the relevant data and save it into the resources directory (See External APIs).

Constructing the graph matrix

Below is the sequence diagram for the creation of the matrix.

Gmaps-Sequence-Diagram
Figure 7. Sequence diagram for the construction of the graph matrix

Brief overview The initialising of the matrix is broken into 2 steps. The first step is to get the list of locations in NUSMods and checking against Google Maps API if that location is identifiable by Google. The second step is to use the identifiable location to construct the matrix.

Steps

  1. Check if the name of the location in NUSMods is identifiable on Google Maps. ProcessVenues#process is the driver for this step.

    1. Call NUSMods API with Cache#loadVenues to get an array of Venues in NUS,

    2. Iterate through each venue and sanitize it to Google Maps Identifiable location.

      1. Sanitizes the location name given by NUSMods by appending NUS_ to the front and removing any characters after - or / as the room in the building does not matter. This will help to reduce the cost of Google Maps API calls.

      2. UrlUtil#conditionalLocationName maps the location name that are not supported on Google Maps to a valid location name.

      3. Each venue in the array will have a validLocationName and placeId mapped to it in the Location class. This will help with the generation of Google Maps Distance Matrix API and retrieving of the location image from Google Maps Maps Static API

  2. Construct matrix. ProcessLocationGraph#process is the driver for this step.

    1. Get the list of valid location with the relevant data(placeId and validLocationName)

    2. Divide this list into blocks of 10 to keep under the 100 element limit of Google Maps.

    3. Call Google Maps Distance Matrix Api for all the blocks in the list.

    4. Combine the API response into a single 2-Dimensional array where distanceMatrix: ArrayList<ArrayList<Long>>.

    5. Use the constructed 2-Dimensional to instantiate LocationGraph which would be utilised to compute all the closest common location.

Getting closest location

ClosestLocation#closestLocationData executes algorithm above to compute the closest common location. Similar to how JSON is used to transfer data in HTTP APIs, ClosestCommonLocationData is used to transfer the relevant data to the UI to display the popup.

Design Considerations

Aspect: Location

Aspect:

Choice

Pros

Cons

How to process the location.

1. Get the distance of the location directly from the NUSMods.

1. Simplify the code base as we can directly call Google Maps API after calling NUSMods API.

1. Bad time complexity as there would be quadratically more data to process. Prone to error as Google Maps might identify AS6-0114 but not AS6-0223.

2. Sanitize the Locations on NUSMods API according to their buildings(ie AS6-0114→AS6) (Current choice)

1. Save time and space complexity as the number of venues will decrease by a factor of 10.

1. Increase in complexity of the code base as an additional step of processing will be required.