TAHub Contacts Developer Guide

Acknowledgements

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 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

Structure of the UI Component

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PersonListPanel, 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 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("person-delete m/A1234570L") API call as an example.

Interactions Inside the Logic Component for the `person-delete m/A1234570L` Command

Note: The lifeline for PersonDeleteCommandParser should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline continues till the end of diagram.

How the Logic component works:

  1. When Logic is called upon to execute a command, it is passed to an AddressBookParser object which in turn creates a parser that matches the command (e.g., PersonDeleteCommandParser) and uses it to parse the command.
  2. This results in a Command object (more precisely, an object of one of its subclasses e.g., PersonDeleteCommand) which is executed by the LogicManager.
  3. The command can communicate with the Model when it is executed (e.g. 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.
  4. 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 AddressBookParser class creates an XYZCommandParser (XYZ is a placeholder for the specific command name e.g., AddCommandParser) which uses the other classes shown above to parse the user command and create a XYZCommand object (e.g., AddCommand) which the AddressBookParser returns back as a Command object.
  • All XYZCommandParser classes (e.g., AddCommandParser, DeleteCommandParser, ...) inherit from the Parser interface so that they can be treated similarly where possible e.g, during testing.

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 enrollment data i.e: all StudentCourseAssociation objects contained in a StudentCourseAssociationList 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)

Course component

API: Course.java

The Course component,

  • stores the course data i.e., all Course objects (which are contained in a UniqueCourseList object).

Storage component

API : Storage.java

The Storage component,

  • can save both address book data, user preference data and enrollment data in JSON format, and read them back into corresponding objects.
  • inherits from AddressBookStorage, UserPrefStorage and StudentCourseAssociationListStorage, which means it can be treated as any 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 tahub.contacts.commons package.

Implementation

This section describes some noteworthy details on how certain features are implemented.

[Proposed] Undo/redo feature

Proposed Implementation

The proposed undo/redo mechanism is facilitated by VersionedAddressBook. It extends AddressBook with an undo/redo history, stored internally as an addressBookStateList and currentStatePointer. Additionally, it implements the following operations:

  • VersionedAddressBook#commit() — Saves the current address book state in its history.
  • VersionedAddressBook#undo() — Restores the previous address book state from its history.
  • VersionedAddressBook#redo() — Restores a previously undone address book state from its history.

These operations are exposed in the Model interface as Model#commitAddressBook(), Model#undoAddressBook() and Model#redoAddressBook() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionedAddressBook will be initialized with the initial address book state, and the currentStatePointer pointing to that single address book state.

UndoRedoState0

Step 2. The user executes person-delete m/A1234570L command to delete the person with matriculation number A1234570L in the address book. The person-delete command calls Model#commitAddressBook(), causing the modified state of the address book after the person-delete m/A1234570L command executes to be saved in the addressBookStateList, and the currentStatePointer is shifted to the newly inserted address book state.

UndoRedoState1

Step 3. The user executes person-add m/A1234570L n/David …​ to add a new person. The person-add command also calls Model#commitAddressBook(), causing another modified address book state to be saved into the addressBookStateList.

UndoRedoState2

Note: If a command fails its execution, it will not call Model#commitAddressBook(), so the address book state will not be saved into the addressBookStateList.

Step 4. The user now decides that adding the person was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoAddressBook(), which will shift the currentStatePointer once to the left, pointing it to the previous address book state, and restores the address book to that state.

UndoRedoState3

Note: If the currentStatePointer is at index 0, pointing to the initial AddressBook state, then there are no previous AddressBook states to restore. The undo command uses Model#canUndoAddressBook() to check if this is the case. If so, it will return an error to the user rather than attempting to perform the undo.

The following sequence diagram shows how an undo operation goes through the Logic component:

UndoSequenceDiagram-Logic

Note: The lifeline for UndoCommand should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.

Similarly, how an undo operation goes through the Model component is shown below:

UndoSequenceDiagram-Model

The redo command does the opposite — it calls Model#redoAddressBook(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the address book to that state.

Note: If the currentStatePointer is at index addressBookStateList.size() - 1, pointing to the latest address book state, then there are no undone AddressBook states to restore. The redo command uses Model#canRedoAddressBook() to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo.

Step 5. The user then decides to execute the command list. Commands that do not modify the address book, such as list, will usually not call Model#commitAddressBook(), Model#undoAddressBook() or Model#redoAddressBook(). Thus, the addressBookStateList remains unchanged.

UndoRedoState4

Step 6. The user executes clear, which calls Model#commitAddressBook(). Since the currentStatePointer is not pointing at the end of the addressBookStateList, all address book states after the currentStatePointer will be purged. Reason: It no longer makes sense to redo the add n/David …​ command. This is the behavior that most modern desktop applications follow.

UndoRedoState5

The following activity diagram summarizes what happens when a user executes a new command:

Design considerations

Aspect: How undo & redo executes:

  • Alternative 1 (current choice): Saves the entire address book.

    • Pros: Easy to implement.
    • Cons: May have performance issues in terms of memory usage.

  • Alternative 2: Individual command knows how to undo/redo by itself.

    • Pros: Will use less memory (e.g. for person-delete, just save the person being deleted).
    • Cons: We must ensure that the implementation of each individual command are correct.

Documentation, logging, testing, configuration, dev-ops

Appendix: Requirements

Product scope

Target user profile: Undergraduate Computer Science Student who is a Teaching Assistant (TA).

  • busy due to high CS workload
  • has a need to manage a significant number of student contacts
  • prefer desktop apps over other types
  • can type fast
  • prefers typing to mouse interactions
  • is reasonably comfortable using CLI apps

Value proposition: manage student contacts faster than a typical mouse/GUI driven app

User stories

Priorities: High (must have) - ★★★ | Medium (nice to have) - ★★ | Low (unlikely to have) - ★

Priority As a ... User I want to ... So that I can ...
★★★ Beginner Add contacts Track contact details for students joining the class
★★★ Beginner View contacts Get an overview of my students’ contact information
★★★ Beginner Delete contacts Remove students no longer in the class
★★★ Beginner Edit contacts Update contact details when they change
★★★ Beginner Add essential data about students Track students’ progress and access it when needed
★★★ Beginner View essential data about students Access key data for each student
★★★ Beginner Delete essential data about students Remove data for students who have left the class
★★★ Beginner Edit essential data about students Update student information when changes occur
★★ Beginner Search for students Quickly find student contact details
★★ Intermediate Sort students by grades Prioritize weaker students for follow-up
★★ Expert Delete students in bulk Remove multiple students quickly, e.g., after class ends
★ Intermediate Add filters to searches Narrow down search results to find specific students
★★ Intermediate Get warnings before making major changes Avoid accidental changes to important student data
★★ Beginner Explore app with sample student data Test features without needing real data
★★ Beginner Access help for available commands Learn how to use the app's functionality effectively
★ Intermediate Bulk import student data Add multiple students at once
★★ Beginner Export contact list to a CSV Back up student contact information
★★ Intermediate Merge duplicate student entries Reduce clutter in the contact list
★ Beginner Filter students by attendance status Track and follow up with absent students
★★ Intermediate Sort students alphabetically Quickly locate students in the contact list
★ Intermediate Add comments to student profiles Record observations or important information about students
★ Beginner Assign preferred communication methods to parents Ensure efficient communication through preferred channels
★ Intermediate Flag students with missing contact details Ensure all required student information is complete
★ Beginner Set communication preferences for individual students Communicate via their preferred method (Telegram, phone, etc.)

Use cases

(For all use cases below, the System is the TAHub Contacts and the Actor is the user, unless specified otherwise)

Use case: Add a contact

Main Success Scenario (MSS):

  1. User requests to add a contact with a name, email, and optionally a phone number and address.

  2. System validates the input fields:

    • a. Checks if the name is valid (alphabets and spaces only).
    • b. Checks if the email format is valid and unique.
    • c. (Optional) Checks if the phone number is valid (8 digits) and unique.
    • d. (Optional) Validates address.

  3. System adds the contact if all validations pass.

  4. System displays a success message, "New contact added: [Contact details]."

    Use case ends.

Extensions:

  • 2a. The name is in an invalid format.

    • 2a1. System shows an error message, "Invalid name format." Use case resumes at step 1.

  • 2b. The email is invalid or already exists.

    • 2b1. System shows an error message, "Invalid email format." or "Contact already exists." Use case resumes at step 1.

  • 2c. The phone number is invalid or already exists.

    • 2c1. System shows an error message, "Invalid phone number format." or "Phone number already exists." Use case resumes at step 1.

Use case: View contacts

Main Success Scenario (MSS):

  1. User requests to view all contacts.

  2. System retrieves and displays the list of all contacts with their details (name, phone number, email, address).

  3. User views the list to get an overview of student contact information.

    Use case ends.

Use case: Delete a contact

Use Case: Get Warnings Before Making Major Changes

Main Success Scenario (MSS):

  1. Tutor initiates a major change (e.g., deleting a student record or modifying multiple student details at once).

  2. System detects the action as a major change.

  3. System prompts the tutor with a warning message describing the potential consequences (e.g., "Warning: You are about to delete [Student's name]. This action cannot be undone. Do you wish to proceed?").

  4. Tutor reviews the warning and confirms whether to proceed or cancel.

  5. If confirmed, the system proceeds with the requested changes and displays a success message.

    Use case ends.

Extensions:

  • 2a. The list is empty.
    • 2a1. System shows a message, "No contacts available." Use case ends.

Use case: Delete a contact

Main Success Scenario (MSS):

  1. User requests to delete a contact by providing the index of the contact in the list.

  2. System validates the provided matriculation number.

  3. System deletes the contact if the matriculation number is valid and student with the matriculation number exists.

  4. System displays a success message, "Deleted contact: [Contact details]."

    Use case ends.

Extensions:

  • 2a. The matriculation number is invalid.

    • 2a1. System shows an error message, "Invalid matriculation number." Use case resumes at step 1.

  • 3a. The student with matriculation number does not exist.

    • 2a1. System shows an error message, "Student does not exist." Use case resumes at step 1.

    • Use case: Edit a contact

    Main Success Scenario (MSS):

    1. User requests to edit the contact by providing the matriculation number of the contact and the fields to update (name, phone, email, address).

    2. System validates the provided matriculation number and input fields:

      • a. Checks if the contact with the given matriculation number exists.
      • b. Validates the new name, email, phone and address as per the same rules as in the add contact case.

    3. System updates the contact with the new details if all validations pass.

    4. System displays a success message, "Contact updated: [Updated contact details]."

      Use case ends.

    Extensions:

    • 2a. The student with matriculation number does not exist.

      • 2a1. System shows an error message, "Student does not exist." Use case resumes at step 1.

    • 2b. The new name is invalid.

      • 2b1. System shows an error message, "Invalid name format." Use case resumes at step 1.

    • 2c. The new email is invalid or already exists.

      • 2c1. System shows an error message, "Invalid email format." or "Contact already exists." Use case resumes at step 1.

    • 2d. The new phone number is invalid or already exists.

      • 2d1. System shows an error message, "Invalid phone number format." or "Phone number already exists." Use case resumes at step 1.

    Use case: Add essential data about students

    Main Success Scenario (MSS):

    1. User requests to add essential data (such as progress or status) for a specific student.

    2. System prompts the user to provide the student’s essential data, such as progress, performance, or notes.

    3. System validates the input and associates the data with the correct student.

    4. System confirms the addition of the data with a success message.

      Use case ends.

    Extensions:

    • 2a. The provided data is invalid.

      • 2a1. System shows an error message, "Invalid data format." Use case resumes at step 1.

    • 3a. The student does not exist in the system.

      • 3a1. System shows an error message, "Student not found." Use case ends.

    Use case: View essential data about students

    Main Success Scenario (MSS):

    1. User requests to view essential data for a specific student.

    2. System retrieves and displays the student's essential data, such as progress, performance, or notes.

    3. User views the essential data to track the student's progress.

      Use case ends.

    Extensions:

    • 2a. The student does not exist in the system.

      • 2a1. System shows an error message, "Student not found." Use case ends.

    • 2b. No essential data has been recorded for the student.

      • 2b1. System shows a message, "No essential data available for this student." Use case ends.

    Use case: Delete essential data about students

    Main Success Scenario (MSS):

    1. User requests to delete essential data for a specific student.

    2. System prompts the user for confirmation to delete the essential data for the student.

    3. User confirms the deletion.

    4. System deletes the student’s essential data and shows a success message, "Essential data for [Student] has been deleted."

      Use case ends.

    Extensions:

    • 2a. The student does not exist in the system.

      • 2a1. System shows an error message, "Student not found." Use case ends.

    • 3a. User cancels the deletion.

      • 3a1. System aborts the deletion process. Use case ends.

    • 4a. No essential data exists for the student.

      • 4a1. System shows a message, "No essential data to delete for this student." Use case ends.

    Use case: Edit essential data about students

    Main Success Scenario (MSS):

    1. User requests to edit essential data for a specific student.

    2. System prompts the user to provide new or updated essential data for the student.

    3. System validates the input and updates the student’s essential data.

    4. System shows a success message, "Essential data for [Student] has been updated."

      Use case ends.

    Extensions:

    • 2a. The student does not exist in the system.

      • 2a1. System shows an error message, "Student not found." Use case ends.

    • 2b. The provided data is invalid.

      • 2b1. System shows an error message, "Invalid data format." Use case resumes at step 1.

    • 4a. No changes were made to the data.

      • 4a1. System shows a message, "No changes detected." Use case ends.

    Use case: Search students

    Main Success Scenario (MSS):

    1. User requests to find students by providing keywords.

    2. System searches for contacts whose names contain the given keywords (case-insensitive).

    3. System displays the matching contacts if found.

      Use case ends.

    Extensions:

    • 2a. No contacts match the keywords.
      • 2a1. System shows a message, "No contacts found." Use case ends.

    Use case: Sort students by grades

    Main Success Scenario (MSS):

    1. User requests to sort students by their grades.

    2. System retrieves all students and their corresponding grades.

    3. System sorts the students by grades in ascending order (prioritizing weaker students).

    4. System displays the sorted list of students with their grades for follow-up.

      Use case ends.

    Extensions:

    • 3a. No students have grades recorded.
      • 3a1. System shows a message, "No grade data available for sorting." Use case ends.

    Use case: Delete students in bulk

    Main Success Scenario (MSS):

    1. User requests to delete multiple students from the system.

    2. System prompts the user to confirm the deletion of the selected students.

    3. User confirms the bulk deletion.

    4. System deletes the selected students and displays a success message for the deletion.

      Use case ends.

    Extensions:

    • 1a. User does not select any students for deletion.

      • 1a1. System shows a message, "No students selected for deletion." Use case ends.

    • 2a. User cancels the deletion.

      • 2a1. System aborts the bulk deletion process. Use case ends.

    • 4a. One or more of the selected students do not exist in the system.

      • 4a1. System skips deleting non-existent students and completes deletion for valid students.
      • 4a2. System shows a message, "Some students could not be deleted as they do not exist."

    Use case: Add filters to searches

    Main Success Scenario (MSS):

    1. User requests to search for students with additional filters (e.g., by grade, or other criteria).

    2. System prompts the user to specify the filters (e.g., grade range etc.).

    3. User specifies the filters and submits the search request.

    4. System retrieves students that match the specified filters and displays the filtered list.

      Use case ends.

    Extensions:

    • 2a. The provided filter is invalid.

      • 2a1. System shows an error message, "Invalid filter. Please provide valid criteria." Use case resumes at step 2.

    • 4a. No students match the specified filters.

      • 4a1. System shows a message, "No students found matching the filters." Use case ends.

    • 4a. Tutor cancels the operation.

      • System aborts the change and returns to the previous state.
      • System displays a message: "Operation cancelled."
      • Use case ends.

    Use Case: Get Warnings Before Making Major Changes

    1. Tutor initiates a major change (e.g., deleting a student record or modifying multiple student details at once).

    2. System detects the action as a major change.

    3. System prompts the tutor with a warning message describing the potential consequences (e.g., "Warning: You are about to delete [Student's name]. This action cannot be undone. Do you wish to proceed?").

    4. Tutor reviews the warning and confirms whether to proceed or cancel.

    5. If confirmed, the system proceeds with the requested changes and displays a success message.

      Use case ends.

    Extensions:

    • 2a. The list is empty.
      • 2a1. System shows a message, "No contacts available." Use case ends.

    Use Case: Explore App with Sample Student Data

    Use Case: Explore App with Sample Student Data

    Main Success Scenario (MSS):

    1. Tutor selects an option to load the app with sample student data.

    2. System loads pre-populated sample student data into the app.

    3. Tutor interacts with the sample data, testing features such as adding, editing, and deleting students, without affecting any real data.

    4. System processes tutor actions using the sample data.

    5. Tutor completes the exploration of the app and returns to normal mode.

    6. System displays a message confirming that all changes made in the sample mode are not saved.

      Use case ends.

    Use Case: Access Help for Available Commands

    Main Success Scenario (MSS):

    1. Tutor requests help (e.g., by typing a help command or selecting a help option from the menu).

    2. System displays a list of available commands and their descriptions.

    3. Tutor reviews the commands and selects one for further clarification.

    4. System provides detailed usage instructions and examples for the selected command.

    5. Tutor follows the instructions to learn how to use the specific functionality.

      Use case ends.

    Extensions:

    • 3a. Tutor requests help for an unsupported command.
      • System shows an error message: "Command not recognized. Please review the available commands."
      • Use case resumes at step 3.

    Use Case: Bulk Import Student Data

    Main Success Scenario (MSS):

    1. Tutor selects the bulk import option in the system.

    2. System prompts the tutor to upload a file containing student data in the required format (e.g., CSV).

    3. Tutor uploads the file.

    4. System validates the file format and student data based on predefined rules (e.g., required fields such as name, email, and valid formats).

    5. If validation passes, system imports the students into the app.

    6. System displays a success message: "Successfully imported [number] students."

    7. Tutor reviews the imported student data.

      Use case ends.

    Extensions:

    • 4a. File format is invalid.

      • System displays an error message: "Invalid file format. Please use the correct format (e.g., CSV)."
      • Use case resumes at step 2.

    • 4b. Some student data is invalid.

      • System displays an error message: "Error importing [X] students due to invalid data (e.g., missing fields, invalid email format). Please correct the data and try again."
      • System provides the option to retry the import after corrections.
      • Use case resumes at step 2.

    Use Case: Export Contact List to a CSV

    Main Success Scenario (MSS):

    1. Tutor selects the option to export the contact list.

    2. System prompts the tutor to specify the file name and location for the CSV file.

    3. Tutor confirms the file name and location.

    4. System generates the CSV file with the contact list, including details such as name, phone number, email, and address.

    5. System displays a success message: "Contact list successfully exported to [file location]."

      Use case ends.

    Extensions:

    • 2a. Export fails due to file system error (e.g., permission denied).
      • System displays an error message: "Export failed. Please check your file permissions and try again."
      • Use case resumes at step 2.

    Use Case: Merge Duplicate Student Entries

    Main Success Scenario (MSS):

    1. Tutor selects the option to merge duplicate student entries.

    2. System scans the contact list for potential duplicates (based on name, email, or phone number).

    3. System presents the tutor with a list of duplicate entries and prompts for confirmation of the merge.

    4. Tutor confirms which entries to merge.

    5. System merges the selected entries and updates the contact list accordingly.

    6. System displays a success message: "Duplicates successfully merged."

      Use case ends.

    Extensions:

    • 3a. No duplicates found.

      • System displays a message: "No duplicates found in the contact list."
      • Use case ends.

    • 4a. Tutor cancels the merge.

      • System aborts the merge operation and returns to the previous screen.
      • Use case ends.

    Use Case: Filter Students by Attendance Status

    Main Success Scenario (MSS):

    1. Tutor selects the option to filter students by attendance status.

    2. System prompts the tutor to choose a specific attendance status (e.g., present, absent, late).

    3. Tutor selects the desired attendance status.

    4. System filters and displays the list of students matching the selected attendance status.

    5. Tutor reviews the filtered list to track or follow up with the absent students.

      Use case ends.

    Extensions:

    • 4a. No students match the selected attendance status.
      • System displays a message: "No students match the selected attendance status."
      • Use case ends.

    Use Case: Sort Students Alphabetically

    Main Success Scenario (MSS):

    1. Tutor selects the option to sort students alphabetically.

    2. System prompts the tutor to choose a sorting criterion (e.g., by first name, by last name).

    3. Tutor selects the desired criterion.

    4. System sorts the students based on the selected criterion.

    5. Tutor reviews the sorted contact list for quick reference or location.

      Use case ends.

    Extensions:

    • 4a. Contact list is empty.
      • System displays a message: "No students available to sort."
      • Use case ends.

    Use Case: Add Comments to Student Profiles

    Main Success Scenario (MSS):

    1. Tutor selects a student profile.

    2. Tutor chooses the option to add a comment to the student's profile.

    3. System prompts the tutor to enter the comment.

    4. Tutor enters the desired observation or important information about the student as a comment.

    5. System saves the comment and associates it with the student's profile.

    6. System displays a success message: "Comment added to [Student's name] profile."

      Use case ends.

    Extensions:

    • 4a. Comment is empty or invalid.
      • System displays an error message: "Invalid comment. Please enter a valid comment."
      • Use case resumes at step 3.

    Use Case: Assign Preferred Communication Methods to Parents

    Main Success Scenario (MSS):

    1. Tutor selects a student profile.

    2. Tutor chooses the option to assign a preferred communication method for the student's parents.

    3. System displays available communication methods (e.g., phone, email, messaging apps).

    4. Tutor selects one or more preferred methods.

    5. System saves the selected preferences for the student's parents.

    6. System displays a success message: "Preferred communication method(s) saved for [Student's name] parents."

      Use case ends.

    Extensions:

    • 4a. No communication method selected.
      • System displays an error message: "Please select at least one communication method."
      • Use case resumes at step 3.

    Use Case: Flag Students with Missing Contact Details

    Main Success Scenario (MSS):

    1. Tutor selects the option to check for missing contact details.

    2. System scans the contact list for students with incomplete or missing contact information (e.g., missing phone number or email).

    3. System displays a list of students with incomplete contact details.

    4. Tutor chooses to review the flagged students and updates the missing information as needed.

      Use case ends.

    Extensions:

    • 3a. No students with missing contact details.
      • System displays a message: "All student contact details are complete."
      • Use case ends.

    Use Case: Set Communication Preferences for Individual Students

    Main Success Scenario (MSS):

    1. Tutor selects a student profile.

    2. Tutor chooses the option to set a preferred communication method for the student.

    3. System displays available communication methods (e.g., Telegram, phone, email).

    4. Tutor selects the student's preferred method.

    5. System saves the selected preference.

    6. System displays a success message: "Preferred communication method saved for [Student's name]."

      Use case ends.

    Extensions:

    • 4a. No communication method selected.
      • System displays an error message: "Please select a communication method."
      • Use case resumes at step 3.

    Non-Functional Requirements

    1. Should work on any mainstream OS as long as it has Java 17 or above installed.
    2. Should be able to hold up to 1000 persons without a noticeable sluggishness in performance for typical usage.
    3. 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.

    {More to be added}

    Glossary

    • Mainstream OS: Windows, Linux, Unix, MacOS
    • Private contact detail: A contact detail that is not meant to be shared with others

    Appendix: Instructions for manual testing

    Given below are instructions to test the app manually.

    Note: These instructions only provide a starting point for testers to work on; testers are expected to do more exploratory testing.

    Launch and shutdown

    1. Initial launch

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

      2. Double-click the jar file Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.

    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 double-clicking the jar file.
        Expected: The most recent window size and location is retained.

    Deleting a person

    1. Deleting a person while all persons are being shown

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

      2. Test case: person-delete m/A1234560L
        Expected: contact with matriculation number A1234560L is deleted from the list. Details of the deleted contact shown in the status message. Timestamp in the status bar is updated.

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

      4. Other incorrect delete commands to try: person-delete, person-delete x, ... (where x is a matriculation number of student that does not exist)
        Expected: Similar to previous.

    Adding, Deleting, and Editing courses

    Similar to adding, deleting and editing persons, but with courses.

    The courses are stored in file data/courselist.json.

    Warning: If any of the fields in courselist.json are invalid, no courses will be loaded and the json file will be cleared.

    Field Format
    COURSE_CODE must be in the form A+xxxxB where A+ is 1 or more uppercase letters, xxxx is a 4-digit number, B is an optional uppercase letter.
    COURSE_NAME must only contain alphanumeric characters and spaces, and not be blank.
    Note: The course code is unique and cannot be duplicated.

    Test sequence

    Prerequisite: Ensure courses with course codes CS2103T and MA1521 are not already added.

    1. Adding course-add c/COURSE_CODE n/COURSE_NAME
    • 1.1 Test case: course-add c/CS2103T n/Software Engineering
      • Expected: A new course with course code CS2103T and course name Software Engineering is added. Success message shown.
    • 1.2 Test case: course-add c/CS2103T n/Software Engineering
      • Expected: Error message shown, as Course with course code CS2103T already exists.
    1. Editing course-edit c/COURSE_CODE n/COURSE_NAME
    • 2.1 Test Case: course-edit c/CS2103T n/Software Engineering 1.
      • Expected: The course with course code CS2103T is updated with the new course name Software Engineering 1. Success message shown.
    • 2.2 Test Case: course-edit c/MA1521 n/Software Engineering 1.
      • Expected: Error message shown, as Course with course code MA1521 does not exist.
    1. Deleting course-delete c/COURSE_CODE
    • 3.1 Test Case: course-delete c/CS2103T
      • Expected: The course with course code CS2103T is deleted. Success message shown.
    • 3.2 Test Case: course-delete c/MA1521
      • Expected: Error message shown, as Course with course code MA1521 does not exist.

    Note: The manual test cases are to be run sequentially (eg 1.1, 1.2, 2.1, 2.2 etc).

    Enrolling a student into a course and tutorial

    1. Enrolling an existing student into an existing course on TAHub

      1. Prerequisites: Ensure that both student and course objects have been created. (In this case, the student object with matriculation number A2345678Y and the course object with course code MA1521 must already be created.)

      2. Test case: enroll m/A2345678Y c/MA1521 tut/T17

        Expected: The student with matriculation number A2345678Y is enrolled into tutorial T17 of the course MA1521. A success message will be shown to the user.

      3. Test case: enroll m/A2345678Y c/MA1521 tut/T17 (again)

        Expected: An error message will be displayed to the user and no new enrollment will occur.

    2. Enrolling an existing student into an invalid course on TAHub

      1. Prerequisites: Ensure that a student object has been created but a course with course code CS3233 has not been created

      2. Test case: enroll m/A2345678Y c/CHUNITHM tut/T17

        Expected: An error message will be displayed to the user and no enrollment will occur as the course code entered has an invalid format.

      3. Test case: enroll m/A2345678Y c/CS3233 tut/T17

        Expected: An error message will be displayed to the user and no enrollment will occur as no such course with course code exists on TAHub.

    Managing Attendance

    1. Marking students as present

      1. Prerequisites: Ensure that both student and course objects have been created and the student is enrolled into a valid tutorial of the course. (In this case, the student object with matriculation number A0286651Y, the course object with course code MA1521 must already be created and the student must be enrolled in tutorial T17)
      2. Test case: attend-present m/A0286651Y c/MA1521 tut/T17
        Expected: Student marked present. Success message shown.

    2. Marking students as absent

      1. Prerequisites: Ensure that both student and course objects have been created and the student is enrolled into a valid tutorial of the course. (In this case, the student object with matriculation number A0286651Y, the course object with course code MA1521 must already be created and the student must be enrolled in tutorial T17)
      2. Test case: attend-absent m/A0286651Y c/MA1521 tut/T17
        Expected: Student marked absent. Success message shown.
      3. Test case: attend-absent m/A0286651Y c/MA1521 tut/T17
        Expected: Error message shown. Student not found.

    3. Clearing attendance records

      1. Prerequisites: Student has existing attendance record
      2. Test case: attend-clear m/A2345678Y c/MA1521 tut/T17
        Expected: Attendance cleared. Success message shown.

    Saving data

    1. Dealing with missing/corrupted data files
      1. Prerequisites: TAHub Contacts must have been run at least once with a data-modifying operation.
      2. Test case: missing file(s) - delete one or more of the .json files in ./data
        Expected: TAHub Contacts automatically loads a set of sample data to replace the missing data. (This behavior is meant to be used for loading sample data when first running the program)
      3. Test case: corrupted file(s) - corrupt one or more of the .json files in ./data, for instance, by deleting the trailing } and invalidating the JSON format.
        Expected: TAHub Contacts loads with empty data.

    Appendix: Planned Enhancements

    1. Add a course-list command to list all courses so that user can view courses in the system.
    2. Add support for more Tutorial IDs by changing the regular expressions (i.e:VALIDATION_REGEX) used to accommodate other valid tutorial ids (e.g: T01A).
    3. Modify all commands that takes in m/MATRICULATION_NUMBER to allow option of accepting index of the person in the list.
    4. The NAME attribute for person shall have a maximum length of 50 characters.
    5. Add an attendance (or similar) command that opens the Attendance window instead of using a mouse to click the Attendance button.
    6. Add more detailed error messages that tell the user specifically what fields are missing instead of simply "required fields are missing"
    7. Modify enroll/unenroll commands to not allow the same student to join multiple tutorials of the same course.