Developer Guide

Acknowledgements

This project is adapted from the AddressBook-Level3 (AB3) foundation created for NUS’ CS2103T Software Engineering course.

---

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

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("delete 1") API call as an example.

This sequence diagram illustrates a more complex interaction within the Logic component, taking execute("filter ev/cycling") API call as the example.

How the Logic component works:

1. When Logic is called upon to execute a command, it is passed to the LinkUp AddressBookParser object which in turn creates a parser that matches the command (e.g., DeleteCommandParser) 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., DeleteCommand) 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 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 both address book data and user preference data in JSON format, and read them back into corresponding objects.
• inherits from both AddressBookStorage 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 seedu.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:

• are small-scale leaders and organizers who need a lightweight but effective way to manage and access their contacts without relying on large enterprise tools
• has a need to manage a significant number of contacts (200-300)
• is actively managing events or activities and coordinating volunteers between time-constrained periods
• prefer desktop apps over other types
• prefers typing to mouse interactions
• has basic command-line familiarity

Primary Users:

• Community & Club Leaders (e.g., student societies, cultural clubs, sports teams)
• Non-Profit & Volunteer Leads (e.g., NGO project leads, charity group organizers)
• Small Organization / Business Team Leads (e.g., startups, tuition centers, hobby groups)

User Persona:

• Bryce is a university student studying a non-IT field. He is involved in many university clubs and leads some of them where he manages over 150+ members in the club. He needs to coordinate events and volunteers which requires him to handle large contact list and track roles efficiently. However, he does not require integrated communication features. Bryce also has basic proficiency on the usage of command line interfaces gained through his university modules

Value proposition:

LinkUp empowers club leaders and small organizations to streamline people and event management, offering a simple yet focused solution which is comprehensive enough to handle real-world coordination, allowing leaders to focus on leading rather than organizing.

• Optimize contact management through keyboard-driven contact management, minimizing time spent navigating traditional GUIs
• Helps to strike an ideal balance between the complexities of full-scale Customer Relationship Management Systems (CRM) and the simplicity of spreadsheets, giving leaders more control
• Offers efficient and powerful features such as event-role grouping, favourites, filters and skill-based tagging for better management

User stories

Priorities: High (must have) - * * *, Medium (nice to have) - * *, Low (unlikely to have) - *

Use cases

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

Use case: Viewing Contacts

MSS

1. User requests to view all contacts.
2. LinkUp displays all contacts.

Use case: Add Contact

MSS

1. User requests to add contact.
2. LinkUp adds the contact and displays updated list of contacts.
   Use case ends.

Extensions

    1a. LinkUp detects missing field information.
        1a1.LinkUp displays an error message.
        Use case ends.

    1b. Phone number and/or name and/or email already exist in LinkUp.
        1b1. LinkUp shows duplicate contact error message.
        Use case ends.

    1c. Invalid field format (E.g. usage of alphabets in phone number)
        1c1. LinkUp shows invalid input message.
        Use case ends.

    1d. Invalid command format.
        1d1. LinkUp shows error message.
        Use case ends.

Use case: Find Contact

MSS

1. User requests to find a contact by name.
2. LinkUp displays list of matching contacts.
   Use case ends.

Extensions

    1a. LinkUp finds no matching contacts.
        Use case ends.

    1b. Invalid command format.
        1b1. LinkUp shows error message.
        Use case ends.

Use case: Delete Contact

MSS

1. User requests to list persons.
2. LinkUp shows a list of persons.
3. User requests to delete a specific person in the list.
4. LinkUp deletes the person.
   Use case ends.

Extensions

    2a. The list is empty.
        Use case ends.

    3a. The given index is invalid.
        3a1. LinkUp shows an error message.
        Use case resumes at step 2.

    3b. Invalid command format.
        3b1. LinkUp shows error message.
         Use case resumes at step 2.

Use case: Mark Contact as Favourite

MSS

1. User requests to list persons.
2. LinkUp shows a list of persons.
3. User requests to mark a specific contact as favourite.
4. LinkUp marks the contact as favourite and displays confirmation message.
   Use case ends.

Extensions

    2a. The list is empty.
        Use case ends.

    3a. The given index is invalid.
        3a1. LinkUp displays an error message.
        Use case resumes at step 2.

    3b. The contact is already marked as favourite.
        3b1. LinkUp displays a message indicating that the contact is already favourite.
        Use case resumes at step 2.

    3c. Invalid command format.
        3c1. LinkUp shows error message.
        Use case resumes at step 2.

Use case: Unmark Favourite Contact

MSS

1. User requests to list persons.
2. LinkUp shows a list of persons.
3. User requests to unmark a specific contact from favourites.
4. LinkUp unmarks the contact as favourite and displays confirmation message.
   Use case ends.

Extensions

    2a. The list is empty.
        Use case ends.

    3a. The given index is invalid.
        3a1. LinkUp displays an error message.
        Use case resumes at step 2.

    3b. The contact is not as favourite.
        3b1. LinkUp displays a message indicating that the contact is not a favourite.
        Use case resumes at step 2.

    3c. Invalid command format.
        3c1. LinkUp shows error message.
        Use case resumes at step 2.

Use case: List Favourite Contacts

MSS

1. User requests to view all favourite contacts.
2. LinkUp displays a list of favourite contacts.
   Use case ends.
   

Extensions

    1a. There are no favourite contacts.
        1a1. LinkUp displays a message indicating that there are no favourites.
        Use case ends.

    1b. Invalid command format.
        1b1. LinkUp shows error message.
        Use case ends.

Use case: Filter Contacts

MSS

1. User requests to filter contacts by any field.
2. LinkUp displays contacts that match the filter condition.
   Use case ends.

Extensions

    1a. No contacts match the filter condition.
        1a1. LinkUp displays an empty list.
        Use case ends.
   
    1b. Invalid command format.
        1b1. LinkUp shows error message.
        Use case ends.

Use case: Clear All Contacts

MSS

1. User requests to clear all contacts.
2. LinkUp deletes all contacts and displays an empty list.
   Use case ends.
   

Use case: Add Skill to Contact

MSS

1. User requests to list persons.
2. LinkUp shows a list of persons.
3. User requests to add one or more skills to a specific contact.
4. LinkUp displays a success message and updates the contact’s skills.
   Use case ends.
   

Extensions

    2a. The list is empty.
        Use case ends.

    3a. The given index is invalid.
        3a1. LinkUp displays an error message.
        Use case resumes at step 2.

    3b. The skill to add already exists for the contact.
        3b1. LinkUp displays a error message indicating which skills are already present. 
        Use case resumes at step 2.

    3c. Invalid skill added to contact
        3c1. Linkup shows invalid skill error message. 
        Use case resumes at step 2.

    3d. Invalid command format.
        3d1. LinkUp shows an error message. 
        Use case resumes at step 2. 

Use case: Delete Skill from Contact

MSS

1. User requests to list persons.
2. LinkUp shows a list of persons.
3. User requests to remove one or more skills to a specific contact.
4. LinkUp displays a success message and updates the contact’s skills.
   Use case ends.
   

Extensions

    2a. The list is empty.
        Use case ends.

    3a. The given index is invalid.
        3a1. LinkUp displays an error message.
        Use case resumes at step 2.

    3b. The skill to delete does not exist for the contact.
        3b1. LinkUp displays a error message indicating which skills are missing. 
        Use case resumes at step 2.

    3c. Invalid skill added to contact
        3c1. Linkup shows invalid skill error message. 
        Use case resumes at step 2.

    3d. Invalid command format.
        3d1. LinkUp shows an error message. 
        Use case resumes at step 2. 

Use case: Copy Add Command string to Clipboard

MSS

1. User requests to list persons.
2. LinkUp shows a list of persons.
3. User requests to copy the add command string of a specific contact.
4. LinkUp copies the add command string of the specified contact to the clipboard.
5. LinkUp displays a success message indicating that the command has been copied.
   Use case ends.

Extensions

    2a. The list is empty. 
        Use case ends.

    3a. The given index is invalid.
        3a1. LinkUp displays an error message. 
        Use case resumes at step 2.

    3b. Invalid command format.
        3b1. LinkUp shows an error message. 
        Use case resumes at step 2. 

Use case: Edit Contact

MSS

1. User requests to list persons.
2. LinkUp displays a list of persons.
3. User requests to edit a contact.
4. LinkUp edits the contact and displays the new information.
   Use case ends.

Extensions

    2a. The list is empty. 
        Use case ends.

    3a. The given index is invalid.
        3a1. LinkUp displays an error message. 
        Use case resumes at step 2.

    3b. The user provides invalid or incomplete fields (e.g., invalid email or phone format).
        3b1. LinkUp displays an error message. 
        Use case resumes at step 2.

    3c. The user does not specify any field to edit. 
        3c1. LinkUp displays a message indicating that at least one field must be provided. 
        Use case resumes at step 2.

    3d. The edited information results in a duplicate contact.
        3d1. LinkUp displays a duplicate contact error message. 
        Use case resumes at step 2.

    3e. Invalid command format.
        3e1. LinkUp shows error message. 
        Use case ends.

    3f. The user edits only role or only event without the other field.
        3f1. LinkUp displays an error message.
        Use case resumes at step 2.

Use case: View Help

MSS

1. User requests to view help information.
2. LinkUp displays example commands and a help window.
   Use case ends.

Extensions

    1a. Invalid command format.
        1a1. LinkUp shows error message.
        Use case ends.

Use case: Exit LinkUp

MSS

1. User requests to exit the app.
2. LinkUp closes.
   Use case ends.

Non-Functional Requirements

1. LinkUp should work on any Mainstream OS as long as it has Java 17 or above installed.
2. LinkUp shall provide an interface that is easily navigable and usable by first-time users with basic digital literacy.
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.
4. LinkUp can store up to 1000 contacts without any noticeable difference in performance for typical usage.
5. LinkUp responds to your inputs within 2 seconds.
6. LinkUp will ensure that all user data remains locally stored and is not transmitted online.
7. Linkup will maintain consistent coding standards and 75% automated test coverage to ensure long-term project health.
8. ⁠Should allow LinkUp to be packaged in a file (eg. ⁠.jar ⁠file) for ease of distribution and deployment.

Glossary

1. Mainstream OS: Windows, Linux, Unix, MacOS
2. Basic digital literacy: The ability to perform fundamental computer operations such as downloading and installing software, typing commands, and navigating interfaces
3. GUI: Graphical User Interface
4. CLI: Command Line Interface
5. JDK: Java Development Kit
6. MSS: Main Success Scenario
7. CRM: Customer Relationship Management System

---

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 the command terminal and navigate into the folder with LinkUp.jar.

   3. Type java -jar LinkUp.jar to run the application.
      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.

3. Shutdown

   1. Press the close window button or type exit.
      Expected: LinkUp will shut down instantly and save your contact data in your computer.

Adding a person

Adding a person while all persons are being shown

1. Test case: add n/John Doe p/98765432 e/johnd@example.com t/abc123 ev/Double or Nothing r/Orientation Camp Organiser
sk/Cooking sk/Python
   Expected: Contact is added to the list. Details of the new contact will be shown.

2. Test case: add n/John Doe p/98765432 e/johnd@example.com t/abc123 ev/Double or Nothing r/Orientation Camp Organiser
sk/Cooking sk/Python
   Expected: Duplicate contact. No person is added. Error details shown in the status message.

3. Test case: add n/John Doe e/johnd@example.com t/abc123 ev/Double or Nothing r/Orientation Camp Organiser
sk/Cooking sk/Python
   Expected: Invalid command format. No person is added. Error details shown in the status message.

4. Other incorrect add commands to try: add, add n/John Doe p/^^^^^5432 e/johnd@example.com t/abc123 ev/Double or Nothing r/Orientation Camp Organiser, ...
   Expected: Similar to previous.

Deleting a person

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: delete 1
   Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message.

3. Test case: delete 0
   Expected: Invalid command. No person is deleted. Error details shown in the status message.

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

Editing a person

Editing 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: edit 1 n/John
   Expected: First contact name is changed to John. Details of the deleted contact shown in the status message.

3. Test case: edit 0 n/John
   Expected: Invalid command. No person is edited. Error details shown in the status message.

4. Other incorrect edit commands to try: edit, edit 1 p/^^^, edit x, ... (where x is larger than the list size)
   Expected: Similar to previous.

Filtering contacts

Filtering persons while all persons are being shown

1. Test case: filter r/Organiser
   Expected: All contacts with the role as Organiser are listed.

2. Test case: filter
   Expected: Invalid command. Error details shown in the status message.

Finding a person by name

Finding a person while all persons are being shown

1. Test case: find John
   Expected: All contacts with the name as John are listed.

2. Test case: find
   Expected: Invalid command. Error details shown in the status message.

Marking/Unmarking a person as favourite

Marking/Unmarking a person as favourite while all persons are being shown

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

2. Test case: fav 1
   Expected: First contact is marked as favourite. A heart symbol appears beside the contact.

3. Test case: fav 1 again
   Expected: Message that says 1st contact is already marked as favourite is shown.

4. Test case: unfav 0
   Expected: Invalid command. No person is unmarked from favourites. Error details shown in the status message.

5. Other incorrect favourite commands to try: fav, fav x, ... (where x is larger than the list size)
   Expected: Similar to previous.

Adding skills to a person

Adding skills to 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: addskill 1 sk/adobe sk/python
   Expected: First contact is added the skill adobe and python.

3. Test case: addskill 1 sk/adobe again
   Expected: Message that says 1st contact already has the inputted skill.

4. Test case: addskill 0 sk/jokes
   Expected: Invalid command. No skill is added. Error details shown in the status message.

5. Test case: addskill 1 sk/jok*91es
   Expected: Invalid skill. No skill is added. Error details shown in the status message.

6. Other incorrect favourite commands to try: addskill, addskill 1 sk/9%aggss ejd, addskill x sk/fight (where x is larger than the list size)
   Expected: Similar to previous.

Deleting skills from a person

Adding skills to 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: dskill 1 sk/adobe
   Expected: First contact removed of the skill adobe.

3. Test case: dskill 1 sk/adobe again
   Expected: Message that says the contact does not have the inputted skill.

4. Test case: dskill 0 sk/jokes
   Expected: Invalid command. No skill is removed. Error details shown in the status message.

5. Test case: dskill 1 sk/jok*91es
   Expected: Invalid skill. No skill is added. Error details shown in the status message.

6. Other incorrect skills commands to try: dskill, dskill 1 sk/9%aggss hi, dskill x sk/fight (where x is larger than the list size)
   Expected: Similar to test case 4.

Copy

Copy the command of the person while all persons are being shown

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

2. Test case: copy 1
   Expected: Add command string of the first contact is copied to the clipboard. Success message shown in the result display box.

3. Test case: copy 0
   Expected: Invalid command. No command is copied. Error details shown in the status message.

4. Other incorrect copy commands to try: copy abc, copy 9%aggss, copy x (where x is larger than the list size)
   Expected: Similar to previous.

Saving data

1. Simulate saving data

   1. Launch LinkUp.
   2. Add/delete/edit a contact.
   3. Close LinkUp.
   4. Relaunch LinkUp.
      Expected: The edited contact list will be restored when you relaunch LinkUp.
      
      

2. Simulate a missing file

   1. Close LinkUp.
   2. Head to the data folder of LinkUp.
   3. Delete the addressbook.json file.
   4. Relaunch LinkUp.
      Expected: LinkUp loads and lists sample contacts.
      
      

3. Simulate a corrupted file

   1. Close LinkUp.
   2. Head to the data folder of LinkUp.
   3. Edit the contents of the addressbook.json file and add invalid characters (eg. $%^#).
   4. Relaunch LinkUp.
      Expected: LinkUp's contact list will be empty.
      
      

Appendix: Effort

Difficulty level: 8/10

LinkUp's main difficulty was in having to understand the classes already implemented in AB3 and using those classes to implement our new features.

Challenges faced:

Some challenges faced include the implementation of Event and Role as a Key-Value pair in a HashMap so that it can take in multiple Event and Role with each Role corresponding to an Event. To implement this, the storage component had to be updated with a JsonAdaptedEventWithRole class so that the data could be stored and read from the Json file.

Another challenging feature would be the Filter Command which filters the address book based on any number of fields. To implement this we created a FilterPredicate class which would take in a PersonFilter to create a predicate to test each contact with.

Achievements:

New features from AB3:

1. Favourite function
2. Add and delete skills(tags in AB3)
3. Filter function
4. Stores multiple Events and Roles per contact
5. Copy command
6. General UI changes
7. Stores Telegram instead of Address
8. Delete multiple contacts at once

Appendix: Planned Enhancements

Team Size: 5

1. Add and Remove Event + Role Command
   • Currently, the only way to add or remove Events and Roles is through the use of the Edit Command. However, this will rewrite all current Events and Roles. We plan to implement a command to easily add and delete event and roles from contacts similar to the add and delete skills feature.
     
     
2. Extra AND/OR Parameter for Filter Function
   • The Filter Function filters for contacts that match at least one parameter from each field (e.g. 1 parameter from name, 1 parameter from event, etc.) However, this limits users who might want to filter for any contact matching one parameter from any field. By implementing a AND/OR field, users can toggle between 2 different modes of filtering, based on what they need.
     
     
3. Filtering to match more than 1 word
   • Due to the current implementation, the Filter function cannot filter for phrases that are more than 1 word long ( e.g. filter for "Alex Yeoh" specifically). We plan to implement this by parsing inputs with a dash to replace the space (e.g. filter "Alex-Yeoh" to filter for "Alex Yeoh").
     
     
4. Delete by fields
   • By using the FilterPredicate class created for the Filter feature we can implement a Delete by field feature where the user can delete all contacts matching the field. (Example input: Delete n/Alex will delete all contacts with Alex in their name).
     
     
5. Add information on whether an event has passed
   • Right now, there is no information on the date and time of each event. We plan to implement a command to allow users to include more specific information of each event and edit this information easily. Once an event has passed, the colour of the event bubble will turn to red. This will make it easier for our users to manage his contacts.
     
     
6. Provide more specific error messages for the various errors
   • Currently, in the case that an invalid input is inputted, it does not clearly show a specific error message but rather shows an error message with all the requirements for the input. (Example input : edit 1 p/p1121211 ; Error Message : Phone numbers must only include digits, pluses, dashes, commas, round brackets, may start with 0, and must contain between 3 and 18 digits.) This can be better improved by stating a more specific message such as phone numbers cannot have alphabets in it, so that the users will be aware of the specific error instead of spending time figuring it out, improving their overall user experience.
7. Support Multiple Languages Name
   • LinkUp currently only supports names with english alphabet characters which limits usability for users with names in other languages such as Tamil, Chinese, Arabic, etc. To cater to a wider range of users and enhance inclusivity LinkUp can be extended to support Unicode characters allowing names in various languages.