TutorEase Developer Guide

---

Acknowledgements

This project is based on the AddressBook-Level3 project created by the SE-EDU initiative.

Generative AI tools such as ChatGPT and Copilot were used for the purposes of creating and ideating Junit test cases and method names, writing detailed Javadocs and some code refactoring.

---

Setting up, getting started

Refer to the guide Setting up and getting started.

---

Design

Architecture

The Architecture Diagram given above explains the high-level design of the App.

Given below is a quick overview of main components and how they interact with each other.

Main components of the architecture

Main (consisting of classes Main and MainApp) is in charge of the app launch and shut down.

• At app launch, it initializes the other components in the correct sequence, and connects them up with each other.
• At shut down, it shuts down the other components and invokes cleanup methods where necessary.

The bulk of the app's work is done by the following four components:

• UI: The UI of the App.
• Logic: The command executor.
• Model: Holds the data of the App in memory.
• Storage: Reads data from, and writes data to, the hard disk.

Commons represents a collection of classes used by multiple other components.

How the architecture components interact with each other

The Sequence Diagram below shows how the components interact with each other for the scenario where the user issues the command contact delete 1.

Each of the four main components (also shown in the diagram above),

• defines its API in an interface with the same name as the Component.
• implements its functionality using a concrete {Component Name}Manager class (which follows the corresponding API interface mentioned in the previous point.

For example, the Logic component defines its API in the Logic.java interface and implements its functionality using the LogicManager.java class which follows the Logic interface. Other components interact with a given component through its interface rather than the concrete class (reason: to prevent outside component's being coupled to the implementation of a component), as illustrated in the (partial) class diagram below.

The sections below give more details of each component.

UI component

The API of this component is specified in Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PersonListPanel,
LessonListPanel, StatusBarFooter etc. All these, including the MainWindow, inherit from the abstract UiPart class
which captures the commonalities between classes that represent parts of the visible GUI.

The UI component uses the JavaFx UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the MainWindow is specified in MainWindow.fxml

The UI component,

• executes user commands using the Logic component.
• listens for changes to Model data so that the UI can be updated with the modified data.
• keeps a reference to the Logic component, because the UI relies on the Logic to execute commands.
• depends on some classes in the Model component, as it displays Person and Lesson object residing in the Model.

Logic component

API : Logic.java

Here's a (partial) class diagram of the Logic component:

The sequence diagram below illustrates the interactions within the Logic component, taking execute("contact delete 1") API call as an example.

How the Logic component works:

1. When Logic is called upon to execute a command, in this case execute("contact delete 1), it is passed to an TutorEaseParser object which in turn creates a parser that matches the type of command. In this case, it is the ContactCommandParser as we are executing a command related to contacts. Commands related to lessons will use LessonCommandParser.
2. The ContactCommandParser will create the specific contact command parser corresponding to the execution. In this case, a DeleteContactCommandParser will be created to parse the command.
3. This results in a Command object, specifically a DeleteContactCommand in this case, which is executed by theLogicManager.
   (Note that DeleteContactCommand is a subclass of ContactCommand which is a subclass of Command)
4. The command can communicate with the Model when it is executed, in this case, to delete a person.
   Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and the Model) to achieve.
5. The result of the command execution is encapsulated as a CommandResult object which is returned back from Logic.

Here are the other classes in Logic (omitted from the class diagram above) that are used for parsing a user command:

How the parsing works:

• When called upon to parse a user command, the TutorEaseParser class creates a ContactCommandParser or LessonCommandParser based on the first word that the tutor keys in, which creates XYZContactCommandParser(e.g. AddContactCommandParser, DeleteContactCommandParser) and XYZLessonCommandParser (e.g. AddLessonCommandParser) respectively. XYZContactCommandParser and XYZLessonCommandParser use the other classes shown above to parse the user command and create a XYZContactCommand or XYZLessonCommand object (e.g., AddContactCommand) which the TutorEaseParser returns back as a Command object.
• All XYZContactCommandParser and XYZLessonCommandParser classes (e.g., AddContactCommandParser, DeleteContactCommandParser, ...) inherit from theParser interface so that they can be treated similarly where possible e.g, during testing.

Extra Pointers about parsing:

• For basic one-word commands like help, exit, and clear, they are handled directly within the parseCommand function in TutorEaseParser without the need for a dedicated parser. These simple commands are omitted in the Parser classes diagram to enhance clarity and reduce clutter.
• Various contact and lesson command parsers are represented as XYZContactCommandParser and XYZLessonCommandParser, respectively. However, their behaviour varies slightly depending on the function. For example, ArgumentMultimap is used exclusively in parsers for add, delete, and edit commands, while ArgumentTokenizer is only used in parsers for add and edit commands. Not specifying every parser reduces clutter and conveys the high-level message concisely.

Model component

API : Model.java

The Model component,

• stores the address book data i.e., all Person objects (which are contained in a UniquePersonList object).
• stores the currently 'selected' Person objects (e.g., results of a search query) as a separate filtered list which is exposed to outsiders as an unmodifiable ObservableList<Person> that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change.
• stores a UserPref object that represents the user’s preferences. This is exposed to the outside as a ReadOnlyUserPref objects.
• does not depend on any of the other three components (as the Model represents data entities of the domain, they should make sense on their own without depending on other components)

Storage component

API : Storage.java

The Storage component,

• can save contact data, lesson data and user preference data in JSON format, and read them back into corresponding objects.
• inherits from TutorEaseStorage, LessonSchedule and UserPrefStorage, which means it can be treated as either one (if only the functionality of only one is needed).
• depends on some classes in the Model component (because the Storage component's job is to save/retrieve objects that belong to the Model)

Common classes

Classes used by multiple components are in the tutorease.address.commons package.

---

Documentation, logging, testing, configuration, dev-ops

• Documentation guide
• Testing guide
• Logging guide
• Configuration guide
• DevOps guide

---

Appendix: Requirements

Product scope

Target user profile:

• Freelance pre-university home tutors
• Manages a significant number of students
• Prefers desktop applications
• Prefers typing to mouse interactions
• Is reasonably comfortable using CLI apps

Value proposition: Our software enhances tutoring efficiency by

• Simplifying management tasks
• Reducing scheduling conflicts
• Providing a clear overview of classes and finances

It enables seamless tutor coordination with primary to junior college level students and guardians, improving communication and organization, ultimately leading to a more effective and stress-free educational experience.

User stories

Priorities: MVP (must have), 2 (nice to have), 3 (unlikely to have)

First time user

Beginner to the software

A little bit familiar with the software

Expert user

Use cases

Use Case: UC01 - Add contact

MSS:

1. Tutor keys in required fields to add a contact.
2. TutorEase adds the contact.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Use Case: UC02 - Delete contact

MSS:

1. Tutor keys in required fields to delete contact.
2. TutorEase deletes the contact.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Use Case: UC03 - List contacts

MSS:

1. Tutor keys in list contacts command.
2. TutorEase lists all the contacts stored.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Use Case: UC04 - Edit contacts

MSS:

1. Tutor keys in required fields to edit a contact.
2. TutorEase edits the contact. Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Use Case: UC05 - Find contacts with a specific name keyword

MSS:

1. Tutor keys in a keyword in the required field to find contacts whose names contain any of the keywords.
2. TutorEase lists the contacts with the given keyword.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.
    
    
• 1b. No contacts found matching the entered keyword.
  • 1b1. TutorEase displays a message letting Tutor know that no contacts were found with the given keyword(s).
  • 1b2. Tutor enters a new keyword.
    Use case resumes from Step 2.

Use Case: UC06 - Add lesson for student

Precondition: Student exists in the system.

MSS:

1. Tutor keys in required fields to add a lesson for a student contact.
2. TutorEase adds the lesson to the student.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.
    
    
• 1b. TutorEase detects that the student index is invalid.
  • 1b1. TutorEase prompts Tutor to key in an index for a student that exists.
  • 1b2. Tutor enters new data.
    Steps 1b1 to 1b2 are repeated until the data entered are correct.
    Use case resumes from Step 2.
    
    
• 1c. TutorEase detects there is an overlapping lesson at the specified date time.
  • 1c1. TutorEase prompts Tutor that there is an overlapping lesson.
  • 1c2. Tutor enters new data.
    Steps 1c1 to 1c2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Use Case: UC07 - Delete lesson for student

MSS:

1. Tutor keys in required fields to delete student contact.
2. TutorEase deletes the lesson for the student.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.
    
    
• 1b. TutorEase detects that the student does not exist.
  • 1b1. TutorEase prompts Tutor to key in data for a student that exists.
  • 1b2. Tutor enters new data. Steps 1b1 to 1b2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Use Case: UC08 - List all lessons

MSS:

1. Tutor keys in required fields to list all lessons.
2. TutorEase lists all lessons.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Use Case: UC09 - Find lessons by student names

MSS:

1. Tutor keys in a keyword in the required field, to find lessons with students whose names contain any of the keywords.
2. TutorEase lists lessons that match the requirement.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.
    
    
• 1b. No lessons found matching the entered keyword.
  • 1b1. TutorEase displays a message letting Tutor know that no lessons were found with the given keyword(s).
  • 1b2. Tutor enters a new keyword.
    Use case resumes from Step 2.

Use Case: UC10 - Clear all entries

MSS:

1. Tutor keys in clear command.
2. TutorEase clears all entries about contacts and lessons.
   Use case ends.

Extensions:

• 1a. TutorEase detects bad or wrongly formatted inputs.
  • 1a1. TutorEase prompts Tutor with correct format.
  • 1a2. Tutor enters new data.
    Steps 1a1 to 1a2 are repeated until the data entered are correct.
    Use case resumes from Step 2.

Non-Functional Requirements

1. A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.
2. Data Requirements:
   • Size: System must be able to handle at least 1,000 student records, with each containing personal information and lesson schedules.
   • Volatility: Contact information is not expected to be changed frequently, but lessons schedules may change frequently. System must allow quick updates without issues.
   • Data persistency: All students and lesson data should be stored and retrievable until entry has been deleted.
3. Environment Requirements:
   • Technical Compatability: System must be compatible with Mainstream OS as long as it has Java 17 or above installed.
   • Server Requirements: Stored locally.
4. Capacity:
   • User Capacity: System is designed for local use and therefore for 1 local user.
   • Data Capacity: As mentioned above within Data Requirements.
5. Documentation:
   • User Guide: A complete user guide will be provided for tutor, detailing every command and cover common troubleshooting scenarios.
   • Developer Guide: Comprehensive developer guide will be available, to facilitate future development and maintenance.
6. Fault Tolerance:
   • Error handling: System should handle up to 90% of incorrect inputs (incorrect date formats, missing fields or etc) without crashing and should provide meaningful error messages to guide users to correct the input.
7. Portability:
   • System must be portable across devices with different operating systems, allowing tutors to install it easily.
8. Quality:
   • Ease of Use: System should be usable by tutors with minimal computer literacy and include intuitive CLI commands and user-friendly prompts.
   • Testing coverage: Unit tests should cover at least 60% of codebase, ensuring high reliability during future updates.
9. Testability:
   • Automated Testing: System should support automated unit and integration testing for continuous integration, allowing future updates to be tested without manual intervention.

Glossary

• Mainstream OS: Windows, Linux, Unix, MacOS
• Private contact detail: A contact detail that is not meant to be shared with others
• Pre-U Home Tuition Teacher: A teacher who offers Primary to Junior College level tuition at the student’s home.
• Locale date time format: The date time format the users’ computer uses.

---

Appendix: Instructions for manual testing

Given below are instructions to test the app manually.

Launch and shutdown

1. Initial launch

   1. Download the jar file and copy into an empty folder.

   2. Open a command terminal, cd into the folder you put the jar file in, and use the command java -jar tutorease.jar to run the application.
      Expected: The app launches and shows the GUI with some sample data.

2. Saving window preferences

   1. Resize the window to an optimum size. Move the window to a different location. Close the window.

   2. Re-launch the app by using the command java -jar tutorease.jar in the command terminal.
      Expected: The most recent window size and location is retained.

3. Exiting the app

   1. Type the command exit into the command box and press enter.
      Expected: The app and GUI closes.

Adding a contact

1. Adding a contact for a Student.

   1. Test case: contact add n/Norbeast p/99243312 e/Norbeast12@beast.com a/Kent Ridge MRT r/Student t/Master
      Expected: A student is added to the contacts. Details of the added student are shown in the status message.

   2. Test case: contact add n/NowBeast p/223 a/Kent Ridge MRT r/Student t/Master
      Expected: No contact is added. Error details are shown in the status message.

   3. Test case: contact add n/CookBeast p/44627732 e/Norbea4st12@beast.com r/Student
      Expected: No contact is added. Error details are shown in the status message.

2. Adding a contact for a Guardian.

   1. Test case: contact add n/ETAN p/2774213 e/etan@man.com a/Tampines MRT r/Guardian t/Father
      Expected: A guardian is added to the contacts. Details of the added guardian are shown in the status message.

   2. Test case: contact add n/Mac p/44421367 a/Chicken MRT r/Guardian t/Master
      Expected: No contact is added. Error details are shown in the status message.

   3. Test case: contact add n/Pizza p/556785 e/Cooking@beast.com r/Guardian
      Expected: No contact is added. Error details are shown in the status message.

Listing all contacts

1. List all contacts in TutorEase.

   1. Prerequisite: At least one contact exists in TutorEase.

   2. Test case: contact list
      Expected: All contacts are shown.

   3. Test case: contact list 0
      Expected: All contacts are shown.

Editing a contact

1. Editing a contact when there are contacts shown on the contact list.

   1. Prerequisites: There are multiple contacts shown on the contact list.

   2. Test case: contact edit 1 n/Chicken
      Expected: First contact's name is edited. Details of the edited contact shown in the status message.

   3. Test case: contact edit 1 p/992
      Expected: First contact's phone number is edited. Details of the edited contact is shown in the status message.

   4. Test case: contact edit 1 r/Student
      Expected: Contact is not edited. Error details are shown in the status message.

2. Editing a contact when there are contacts shown on the filtered contact list.

   1. Prerequisites: At least one contact is shown on the contact list.

   2. Test case: contact edit 1 n/Duck
      Expected: First contact's name is edited. Details of the edited contact are shown in the status message.

   3. Test case: contact edit 1 p/8842
      Expected: First contact's phone number is edited. Details of the edited contact are shown in the status message.

   4. Test case: contact edit 1 r/Student
      Expected: Contact is not edited. Error details are shown in the status message.

Finding a contact

1. Finding a contact by name.

   1. Prerequisites: There are multiple contacts, with at least one contact whose name is Alice and at least one contact whose name is Bob. None of the contacts whose name is Test or contains the word Test. These names are case-insensitive.

   2. Test case: contact find Alice
      Expected: Contacts whose name is Alice or contains the word Alice will be displayed. There should be at least one as per the prerequisites.

   3. Test case: contact find Test
      Expected: No contacts is found. Details are shown in the status message.

   4. Other incorrect contact find commands to try: contact find, contact find x (where x is a name of a contact, a name that does not belong to any of the contacts or a word that is not in the names of any contact)
      Expected: Similar to previous.

Deleting a contact

1. Deleting a contact while all contact are being shown.

   1. Prerequisites: List all contact using the contact list command. Multiple contact in the list.

   2. Test case: contact delete 1
      Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message.

   3. Test case: contact delete 0
      Expected: No contact is deleted. Error details shown in the status message. Status bar remains the same.

   4. Other incorrect delete commands to try: contact delete, contact delete x, ... (where x is larger than the list size)
      Expected: Similar to previous.

Adding a lesson

1. Adding a lesson when all students are shown.

   1. Prerequisite: At least one student exists in the contact list.

   2. Test case: lesson add sid/1 f/10 d/11-11-2024 12:00 h/1
      Expected: A lesson is added to the student with index 1. Details of the added lesson shown in the status message.

   3. Test case: lesson add sid/0 f/10 d/11-11-2024 12:00 h/1
      Expected: No lesson is added. Error details are shown in the status message.

   4. Test case: lesson add sid/1 f/10 d/11-11-2024 12:00 h/1
      Expected: No lesson is added. Error details are shown in the status message.

2. Adding a lesson on filtered contact list.

   1. Prerequisite: At least one student exists in the contact list.

   2. Test case: lesson add sid/1 f/10 d/12-11-2024 12:00 h/1
      Expected: A lesson is added to the student with index 1 in the filtered contact list. Details of the added lesson is shown in the status message.

Listing all lessons

1. List all lessons in the schedule.

   1. Prerequisite: At least one lesson exists in the lesson schedule.

   2. Test case: lesson list
      Expected: All lessons in the lesson schedule are shown.

   3. Test case: lesson list 0
      Expected: All lessons in the lesson schedule are shown.

Deleting a lesson

1. Deleting a lesson when there are lessons shown in the lesson schedule.

   1. Prerequisites: There are multiple lessons in the lesson schedule.

   2. Test case: lesson delete 1
      Expected: First lesson is deleted from the lesson schedule. Details of the deleted lesson is shown in the status message.

   3. Test case: lesson delete 0
      Expected: No lesson is deleted. Error details are shown in the status message.

   4. Other incorrect delete commands to try: lesson delete, lesson delete x, ... (where x is larger than the list size)
      Expected: Similar to previous.

2. Deleting a lesson when there are lessons shown in the filtered lesson schedule.

   1. Prerequisites: Executed a lesson find command and there are multiple lessons in the filtered lesson schedule.

   2. Test case: lesson delete 1
      Expected: First lesson is deleted from the filtered lesson schedule. Details of the deleted lesson are shown in the status message.

   3. Test case: lesson delete 0
      Expected: No lesson is deleted. Error details are shown in the status message.

   4. Other incorrect delete commands to try: lesson delete, lesson delete x (where x is larger than the filtered list size)
      Expected: Similar to previous.

Finding a lesson

1. Finding a lesson when there are lessons shown in the lesson schedule.

   1. Prerequisites: There are multiple lessons in the lesson schedule, with at least one lesson with a student whose name is Alice and at least one lesson with a student whose name is Bob. None of the lessons have a student whose name is Test or contains the word Test. These names are case-insensitive.

   2. Test case: lesson find Alice
      Expected: Lessons with student whose name is Alice or contains the word Alice will be displayed on the lesson panel. There should be at least one as per the prerequisites.

   3. Test case: lesson find Test
      Expected: No lesson is found. Details are shown in the status message.

   4. Other incorrect lesson find commands to try: lesson find, lesson find x (where x is a name of a student who does not have a lesson, a name that does not belong to any of the students that have lessons or a word that is not in the names of the students that have lessons)
      Expected: Similar to previous.

Clearing TutorEase

1. Clearing TutorEase when there are contacts and lessons.

   1. Prerequisites: There are multiple contacts and lessons in the contact list and lesson schedule.

   2. Test case: clear
      Expected: All contacts and lessons are cleared.

---

Appendix: Planned Enhancements

Team Size: 4

1. Unique Attributes and Relationship Modeling for Students and Guardians

Recognizing the importance of capturing more details about different types of contacts, we plan to incorporate additional attributes for students, such as grade levels, subjects and exam dates. To support clear organization, we’ll also implement a tagging system that links each student to their respective guardian, making it easier to manage relationships and access relevant information at a glance. In the event that a student does not have contact information, they will be required to be linked to a guardian, ensuring that there exist a way to contact the student.

2. Overlapping Lesson Time Handling

We recognize the need for clarity around overlapping lesson scheduling. Options for managing overlaps will include:

• Allowing overlapping sessions for group lessons or pair lessons.
• Enabling you to customize settings for overlap permissions based on the type of lesson.

3. Enhanced Name Field Support

To accommodate a more diverse range of names, such as names with commas, accented characters, hyphens, etc., we plan to update the application to allow names with these characters. In the future, the system will support a wider variety of name formats, making it more inclusive and user-friendly.

Additionally, if extra whitespace is accidentally added between names (e.g., double space between first and last name), the system will show a warning to alert you of potential duplicate entries due to spacing inconsistencies.

4. Past Lesson Management

To enhance lesson organization, we plan to introduce features that clearly distinguish past lessons. This will include options to automatically hide completed lessons or display them in a different color for easy identification. You will also be able to toggle the visibility of past lessons, allowing them to focus on upcoming schedules while still being able to reference completed sessions if needed.

5. Support for Decimal Places in Fees

We have acknowledged that it might be possible to charge an odd number (ie $25) per lesson for an even number of hours (ie 2 hours), resulting in the fee per hour not being an integer. To provide more flexibility in fee management, we plan to introduce support for decimal places in fee amounts. This will allow you to input and manage fees with greater precision, catering to scenarios where fees are calculated to fractional values (e.g., for hourly rates or partial payments).

6. Support for More Screen Resolutions

An example of this issue is when a Tutor creates a contact with a name, address, tag, and email that are longer than expected. Part of the UI will be cut off if the screen resolution is not big enough. To ensure that the application is accessible to users with a wide range of screen sizes, we plan to optimize the user interface for additional screen resolutions so that none of the elements are cut off or hidden from view, regardless of the screen size.

7. Allow integer values above 2,147,483,647

Although it is highly unlikely that an integer value would exceed 2,147,483,647 under normal usage, the system currently only supports integer values up to 2,147,483,647. To accommodate larger values, we plan to update the system to allow for integer values above this limit. This will ensure that you can input and manage larger values without encountering any issues related to the integer limit.