InsuraBook Developer Guide

Acknowledgements

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

We would like to acknowledge the following third-party libraries and tools used in this project:

Libraries:

• JavaFX - Used for building the graphical user interface
• Jackson - Used for JSON parsing and data serialisation
• JUnit5 - Used as the testing framework
• Gradle - Used for build automation and dependency management
• Checkstyle - Used for code quality and style checking
• JaCoCo - Used for code coverage analysis

Documentation:

• PlantUML - Used for generating UML diagrams in documentation

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

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., 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)

Person Class

For a detailed view of the Person class and its associated attribute classes (Name, Phone, Email, etc.), refer to the dedicated diagram below:

The Person class encapsulates all contact information for InsuraBook users. Key design decisions:

• Required Fields: Only Name and Phone are required fields. All other fields (Email, Address, Occupation, Age, Priority, Income Bracket, Tags) are optional.
• Validation: Each attribute class (Name, Phone, Email, etc.) performs its own validation upon construction.
• Editability: Person fields can be modified through the edit command, allowing users to update contact information as needed.
• Tag Support: Persons can have multiple tags, including a special DncTag for "Do Not Call" compliance.

Note: An alternative (arguably, a more OOP) model is given below. It has a Tag list in the AddressBook, which Person references. This allows AddressBook to only require one Tag object per unique tag, instead of each Person needing their own Tag objects.

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)
• uses Jackson-friendly adapter classes (JsonAdaptedPerson, JsonAdaptedTag) to bridge between domain models and JSON representation

Common classes

Classes used by multiple components are in the seedu.address.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 initialised with the initial address book state, and the currentStatePointer pointing to that single address book state.

Step 2. The user executes delete 5 command to delete the 5th person in the address book. The delete command calls Model#commitAddressBook(), causing the modified state of the address book after the delete 5 command executes to be saved in the addressBookStateList, and the currentStatePointer is shifted to the newly inserted address book state.

Step 3. The user executes add n/David …​ to add a new person. The add command also calls Model#commitAddressBook(), causing another modified address book state to 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.

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

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

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.

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.

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.

The following activity diagram summarises 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 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

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

Appendix: Requirements

Product scope

Target user profile:

• busy telemarketing agents who sell insurance
• need to manage large lists of clients and new leads
• require quick access to client names, phone numbers, and other essential information during calls
• prefer desktop apps over other types
• can type fast and are reasonably comfortable using CLI apps
• need to find, add, and update records efficiently without interrupting their workflow

Value proposition:

• saves time
• prevent lost information
• ensures timely follow-ups
• streamlines management

User stories

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

Use cases

UC1 - Delete a Person

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

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

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

UC2 - Add New Contact

MSS: 
   1.  User requests to add a new contact with details (name, phone, email, etc.)
   2.  InsuraBook validates the contact information
   3.  InsuraBook adds the contact to the list
   4.  InsuraBook displays success message with contact details
   Use case ends.

Extensions:
   2a. Required fields are missing.
      2a1. InsuraBook shows an error message indicating missing fields.
      Use case ends.

   2b. Phone number format is invalid.
      2b1. InsuraBook shows an error message about invalid phone format.
      Use case ends.

   2c. Email format is invalid.
      2c1. InsuraBook shows an error message about invalid email format.
      Use case ends.

   2d. Contact with same name and phone already exists.
      2d1. InsuraBook shows an error message about duplicate contact.
      Use case ends.

UC3 - Edit Contact Details

MSS: 
   1.  User requests to list persons
   2.  InsuraBook shows a list of persons
   3.  User requests to edit a specific person's details with new information
   4.  InsuraBook validates the new information
   5.  InsuraBook updates the contact details
   6.  InsuraBook displays success message with updated details
   Use case ends.

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

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

   4a. New information format is invalid.
      4a1. InsuraBook shows an error message indicating invalid format.
      Use case resumes at step 3.

   4b. Edited contact would become a duplicate of an existing contact.
      4b1. InsuraBook shows an error message about duplicate contact.
      Use case resumes at step 3.

UC4 - Find Contacts by Keywords

MSS: 
   1.  User requests to find contacts using search keywords
   2.  InsuraBook searches for matching contacts by name
   3.  InsuraBook displays a list of matching contacts
   Use case ends.

Extensions:
   1a. No keywords provided.
      1a1. InsuraBook shows an error message about missing keywords.
      Use case ends.

   3a. No contacts match the search criteria.
      3a1. InsuraBook displays an empty list with a message indicating no matches.
      Use case ends.

UC5 - Tag a Contact

MSS: 
   1.  User requests to list persons
   2.  InsuraBook shows a list of persons
   3.  User requests to add tags to a specific person
   4.  InsuraBook validates the tag format
   5.  InsuraBook adds the tags to the contact
   6.  InsuraBook displays success message with updated contact
   Use case ends.

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

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

   4a. Tag format is invalid (e.g., contains special characters).
      4a1. InsuraBook shows an error message about invalid tag format.
      Use case resumes at step 3.

UC6 - Set Contact Priority

MSS: 
   1.  User requests to list persons
   2.  InsuraBook shows a list of persons
   3.  User requests to set priority for a specific person (HIGH, MEDIUM, or LOW)
   4.  InsuraBook validates the priority value
   5.  InsuraBook updates the contact's priority
   6.  InsuraBook displays success message with updated priority
   Use case ends.

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

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

   4a. Priority value is invalid.
      4a1. InsuraBook shows an error message indicating valid priority levels.
      Use case resumes at step 3.

Non-Functional Requirements

Technical Requirements

1. Should work on any mainstream OS as long as it has Java 17 or above installed.
2. Should work without requiring an installer or any additional software installation beyond Java.
3. Should function offline without requiring an internet connection for core features.

Usability Requirements

4. 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.
5. The system should be usable by telemarketing agents who are novice users of CLI applications, with minimal training required.
6. Error messages should be clear and provide actionable guidance to help users correct their inputs.
7. The user interface should remain responsive and not freeze during operations.

Reliability and Data Integrity

8. Should not lose any data during normal operations or graceful shutdowns.
9. Should automatically save data after each modification to prevent data loss.
10. Should provide data validation to prevent corruption of the contact database.
11. Should handle corrupted data files gracefully by alerting the user rather than crashing.

Scalability Requirements

12. Should maintain performance even when the database grows from 100 to 1000 contacts.
13. Sorting and filtering operations should scale linearly with the number of contacts.

Portability Requirements

14. Should store data in a human-editable text format (JSON) for easy portability and backup.
15. Should be able to run from any directory without requiring installation to a specific location.
16. Data files should be portable across different operating systems without modification.

Compliance and Privacy Requirements

17. Should provide a "Do Not Call" (DNC) feature to comply with telemarketing regulations.

Documentation Requirements

18. Should provide comprehensive user documentation covering all features and commands.
19. Should include example commands and use cases in the user guide for common tasks.
20. Developer documentation should be sufficient for new developers to set up and contribute to the project.

Constraints

21. The project should be completed within the semester timeline with regular iterative releases.
22. The system should work without requiring elevated permissions or administrator rights.
23. Should not use any paid third-party libraries or services.

Quality Requirements

24. The user interface should be intuitive enough that common tasks can be performed without referring to documentation.
25. Command syntax should be consistent across all features to reduce learning curve.

Glossary

• CLI: Command Line Interface - a text-based interface where users type commands to interact with the application
• DNC: Do Not Call - a regulatory compliance feature that marks contacts who should not be contacted for telemarketing
• GUI: Graphical User Interface - a visual interface that allows users to interact through graphical elements
• JavaFX: A Java library used for creating desktop applications with graphical user interfaces
• JSON: JavaScript Object Notation - a lightweight data format used for storing and exchanging data
• Mainstream OS: Windows, Linux, Unix, MacOS

Appendix: Instructions for manual testing

Given below are instructions to test the app manually.

Launch and shutdown

Adding a contact

Editing a contact

Deleting a contact

Finding contacts

Priority management

Income bracket management

Do Not Call (DNC) tag management

Saving data

Appendix: Planned Enhancements

Team size: 5

1. Allow multiple phone number fields with international format support: Currently, the phone number field only accepts numeric digits and each contact can have only one phone number. However, telemarketers frequently need to store multiple contact numbers (home, mobile, office) for the same person and require support for special characters like -, +, and ( ) to accommodate international country codes and phone extensions.

2. Add confirmation dialog for clear command: Currently, the clear command immediately deletes all contacts from InsuraBook without requesting user confirmation. A single typo or accidental command execution can permanently delete an insurance agent's entire client database. Although data is saved to file after each operation, there is no recovery mechanism to restore cleared contacts. This poses a significant risk for professionals managing hundreds of client records. To address this, we plan to implement a confirmation dialog that requires the user to explicitly confirm the action before deletion proceeds.

3. Reduce restriction on DNC feature: Currently, the "Do Not Call" (DNC) feature prevents editing any field of contacts tagged with DNC, including non-call-related information like address or occupation. For example, if a client with a DNC tag moves, the agent cannot update the address without removing the DNC tag first. To address this, we plan to reduce the restrictions to only prevent editing of name and phone number fields, while allowing updates to other contact information. We also plan to add a dedicated reversal command to eliminate the need to delete/re-add workaround.

4. Provide in-app command reference for help command: Currently, the help command only directs users to an external online User Guide link, forcing CLI users to interrupt their workflow, open a web browser, and manually navigate documentation simply to recall a command format. This lack of in-app reference significantly hinders the efficiency and usability for fast-typists and power users who value staying within the terminal environment. To address this, we plan to update the help command to display a brief summary of all available commands and their basic syntax directly in the application. The external User Guide link can be retained as a secondary option for users needing more comprehensive details.

5. Improve Unicode character support for international contacts: Currently, the application handles Unicode characters inconsistently across different fields. The TAG field is limited to alphanumeric characters and spaces, while the EMAIL field only accepts standard ASCII characters, preventing agents from working with clients who use internationalised email addresses with native scripts (e.g., Chinese, Arabic). This creates barriers for telemarketing agents with diverse, multilingual client bases. To address this, we plan to extend the TAG field to accept all Unicode characters and extend the EMAIL field to support internationalised email addresses with foreign characters, while maintaining current restrictions for NAME and other fields to ensure data consistency.