🏠 PropertyPal Developer Guide

---

Acknowledgements

• This project is based on the AddressBook-Level3 project created by the SE-EDU initiative.
• Libraries used: JavaFX, Jackson, JUnit5

---

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.

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)

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.

---

Implementation

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

OR search in find command

Implementation

The find command supports searching across multiple fields (e.g., name, phone, email, address, price, etc.) using OR semantics. This behaviour is implemented in the PersonContainsKeywordsPredicate class, which defines how each Person is tested against the given search keywords.

When the user enters a find command such as:

find n/Alice e/gmail

the system constructs a PersonContainsKeywordsPredicate containing separate lists of keywords for each prefix (n/ → name, e/ → email). The predicate then evaluates to true if any of the person’s fields contain any of the corresponding keywords. This is done through a series of anyMatch calls and a final || chain:

return nameMatches || phoneMatches || emailMatches || addressMatches
        || priceMatches || propertyTypeMatches || intentionMatches;

Rationale for OR search

1. Intuitive user experience
   1. Users typically expect inclusive search results and typing multiple keywords should broaden the search, not restrict it.
   2. For example, searching find n/Alice e/gmail should return both:
      1. Alice Tan (name contains "Alice")
      2. Bob Lee (email contains "gmail")
2. Consistency with common search mode
   1. Search behaviour in file explorers, contact apps, and web engines generally follows OR semantics. Matching this mental model makes the feature easier to use and reduces confusion.
3. Flexibility in partial recall
   1. Users may not remember exact details (e.g., only the email domain or property type). OR semantics let them find relevant entries even when they recall only part of the information.
4. Performance and maintainability
   1. The predicate short-circuits on the first match, improving performance. The modular field checks also make it straightforward to add or remove searchable fields in the future.

---

Documentation, logging, testing, configuration, dev-ops

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

---

Appendix: Planned Enhancements

Team size: 4

1. Enhance 'find' to find by area (by postal code): Currently, the find command uses String matching to find the relevant addresses, but this does not account for proximity of locations. For example, in Singapore, Fernvale is located in Sengkang, but entering find a/Sengkang does not bring up results from Fernvale. We plan to allow users to find by postal code in the address field, enabling more accurate area-based searches. This will ensure each contact has a postal code for checking if two addresses are in the same vicinity.
2. Enhance 'find' to support partial numeric ranges: Currently, the find command allows users to search by exact price, or a range of prices with a minimum and maximum value (inclusive). It does not support finding by partial ranges (e.g. find pr/-5000 and find pr/3000-). We plan to support finding by partial values as long as a '-' is detected within the input to increase flexibility of the command.
3. Enhance 'find' to highlight fields that match in results: If the user enters a complex query that searches by multiple different fields, it may be difficult to tell at a glance which parts of the results match the query. To solve this problem, we intend to highlight specific fields in the results that match the given query, allowing users to identify results with more matches at a glance.
4. Allow column arrangements to be saved in user preferences: Users can currently drag and reorder columns in the contact list as they wish, but these orderings are reset whenever the application is reopened. We intend to persist column arrangements in preferences.json so that user preferences are restored whenever PropertyPal is reopened.
5. Allow column widths to be adjusted through typing: Currently, if the user adds a contact with long inputs, certain values in the contact list may appear truncated. Users can currently manually adjust these column widths by dragging the column headers, but this may annoy them if they typically prefer typing, or if multiple columns need to be adjusted at once. We plan to expand the current column resizing feature to also support typed adjustments (e.g. through a resize command), providing an alternative to manual dragging.
6. Change the delimiter symbol: Our application currently uses a / to parse inputs for different fields, but this may cause conflicts with the name and address field which also allow its use as inputs. Slashes in addresses are infrequently used to denote building and apartment numbers (e.g. 12/24 Smith Street), while slashes in names may appear in South Asian naming conventions (e.g. S/O, D/O). These should rarely cause conflicts with our prefixes (e.g. n/, e/, a/), but using another character as a delimiter such as = could help to eliminate such risks entirely.
7. Provide more details about entries in deletion confirmation screen: PropertyPal supports deleting multiple entries at once if they share the same name, but the confirmation screen only shows the name of the person, which would be identical aside from case-sensitivity. This makes it difficult for the user to differentiate entries from each other. To improve the user experience, we intend to include more details about each contact in the confirmation screen (e.g. intention, address) to help users disambiguate the entries.

---

Appendix: Planned Features

[Proposed] 1. 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.

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 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 delete, just save the person being deleted).
  • Cons: We must ensure that the implementation of each individual command are correct.

{more aspects and alternatives to be added}

[Proposed] 2. Track Offers Feature

Overview

In the real estate workflow, agents often receive multiple offers for a single property and must decide which to pursue or present to their clients. Currently, PropertyPal captures only the client’s essential details — such as name, contact, intention, property type, and listed price — but does not provide a way to record or monitor offers made by prospective buyers or tenants.

This enhancement aims to address that gap by introducing a “Track Offers” feature. It allows agents to document the highest or most recent offer received for each client’s property, providing a clearer picture of ongoing negotiations and helping agents manage deals more effectively.

Proposed Implementation

A new optional attribute, Offer, will be introduced in the Person class to represent the latest or best offer received for the client’s property. Through this feature, agents can:

• View the current best offer alongside other property details in the main list.
• Add, update, or clear the offer using a new command syntax.
• Keep clients’ offer information consistent and up to date as new bids are received.

Example command:

offer 3 o/480000

This updates the third client’s record with a best offer of $480,000.

Design Considerations

Aspect: Representation of offer data

• Option 1 (selected): Store only one value — the best or latest offer — per client. Pros: Straightforward to implement, minimal storage required, integrates smoothly with existing UI. Cons: No visibility of previous offers.

• Option 2: Maintain a list of all offers received. Pros: Useful for tracking offer history or market activity. Cons: Increases complexity and may clutter the interface.

Example Usage

---

Appendix: Requirements

Product scope

Target user profile:

• real estate agents who manage a large number of client contacts
• frequently need to search or filter clients by specific details (e.g., name, phone)
• prefers typing to mouse interactions

Value proposition:

• allows efficient searching and filtering of clients by any field (name, phone, email, address)
• enables quick addition, editing, and deletion of client contact details

User stories

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

{More to be added}

Use cases

(For all use cases below, the System is PropertyPal and the Actor is the user (real estate agent), unless specified otherwise)

Use case 1: Add a client contact

Guarantees:

• Client details are saved if all fields are valid and at least 1 field is unique.
• No duplicates will be created.

MSS

1. User enters the add command with all required details in a single line.

2. PropertyPal adds the new client and displays a success message.

   Use case ends.

Extensions

• 1a. Invalid input (e.g. wrong format)

  • 1a1. PropertyPal displays an error message indicating the correct format.

  • 1a2. User re-enters data.

    Steps 1a1 - 1a2 are repeated until the input entered is valid.

    Use case resumes from step 2.

• 1b. Duplicate client detected

  • 1b1. PropertyPal displays a message indicating client already exists.

    Use case ends.

• 1c. Duplicate name or address detected, but at least 1 other detail is unique

  • 1c1. PropertyPal adds the new client and displays a success message, with a warning that a contact with the same name or address is detected.

    Use case ends.

Use case 2: Delete a client contact

Guarantees:

• The specified client is removed from the list if a valid name is provided.
• No deletion occurs without user confirmation when multiple matches exist.

MSS

1. User enters delete command with the full name of the client.

2. If exactly one match is found, PropertyPal deletes the client and displays a success message.

   Use case ends.

Extensions

• 1a. No matching record found

  • 1a1. PropertyPal displays a message indicating no such record found.

    Use case ends.

• 1b. Multiple matches found

  • 1b1. PropertyPal lists all matching clients with indices.

  • 1b2. User enters the index of the client to delete.

  • 1b3. PropertyPal deletes the client and displays a success message.

    Use case ends.

• 1c. Invalid input (e.g. empty name, invalid characters).

  • 1c1. PropertyPal displays an error message indicating the correct format.

  • 1c2. User re-enters data.

    Steps 1c1 - 1c2 are repeated until the input entered is valid.

    Use case resumes from step 2.

Use case 3: List all client contacts

MSS

1. User enters list command.

2. PropertyPal displays a list of all clients in lexicographical (alphabetical and numerical) order and a success message.

   Use case ends.

Extensions

• 1a. Invalid input (e.g. typo)

  • 1a1. PropertyPal displays an error message indicating that the command is not recognized.

    Use case ends.

Use case 4: Find clients by specific field(s)

Guarantees:

• PropertyPal displays all clients that match the given search keyword(s).
• Each matching client is displayed only once, even if it matches multiple criteria.

MSS

1. User enters find command with keyword(s).

2. PropertyPal displays a list of all matching clients in the order they were added.

   Use case ends.

Extensions

• 1a. Invalid input (e.g. missing prefix or keyword, input too short)

  • 1a1. PropertyPal displays an error message indicating the correct format.

  • 1a2. User re-enters data.

    Steps 1a1 - 1a2 are repeated until the input entered is valid.

    Use case resumes from step 2.

• 1b. No matches found

  • 1b1. PropertyPal displays a message indicating no matching clients found.

    Use case ends.

Use Case 5: Edit a client contact

Guarantees:

• The specified client's details are updated if all provided fields are valid.
• No duplicate clients are created as a result of the edit operation.

MSS

1. User requests to edit a specific client by index and provides one or more fields to update .

2. PropertyPal updates the client's details and displays a success message.

   Use case ends.

Extensions

• 1a. Invalid index (e.g. -1 or index is larger than total number of clients)

  • 1a1. PropertyPal displays an error message indicating invalid index.

  • 1a2. User re-enters data.

    Steps 1a1 - 1a2 are repeated until the input entered is valid.

    Use case resumes from step 2.

• 1b. No fields are provided for editing

  • 1b1. PropertyPal displays an error message indicating that at least one field must be provided.

  • 1b2. User re-enters data.

    Steps 1b1 - 1b2 are repeated until the input entered is valid.

    Use case resumes from step 2.

• 1c. Edited details would create a duplicate client (all fields identical to an existing client)

  • 1c1. PropertyPal displays an error message indicating that the client already exists.

  • 1c2. User re-enters data.

    Steps 1c1 - 1c2 are repeated until the input entered is valid.

    Use case resumes from step 2.

• 1d. Invalid input (e.g. missing index)

  • 1d1. PropertyPal displays an error message indicating the correct format.

  • 1d2. User re-enters data.

    Steps 1d1 - 1d2 are repeated until the input entered is valid.

    Use case resumes from step 2.

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.
4. Should be able to start up quickly within a few seconds on a typical computer.
5. Should be able to run on laptops with 4GB RAM and above.
6. Error messages should be easy to understand by an average user.
7. All features work without internet access.

Glossary

• Mainstream OS: An operating system that is widely used, actively maintained, and has substantial market share and community support. These systems typically receive regular security updates and support running modern Java applications. (e.g. Windows, Linux, Unix, macOS)
• Private contact detail: A contact detail that is not meant to be shared with others
• Command: A text instruction entered by the user (e.g., add, delete) to perform an action.
• CLI: Command Line Interface
• GUI: Graphical User Interface
• JavaFx: A Java library for building GUI applications
• FXML: An XML-based language for defining the layout of JavaFx GUIs
• Argument/Parameter: Extra information provided with a command (e.g., n/John Doe in add).
• Field: A specific data component of a client record, such as “name”, “email”, or “phone number”.
• Prefix: A short identifier (e.g., n/, p/, e/, a/) used to indicate the type of information in a command.
• Duplicate entry: A contact record that has the same intention, name, phone, email, address, property type, and price as another existing record.
• Intention: Refers to the client's property transaction goal (either sell or rent). This field helps categorize clients based on their property-related objectives.
• Property Type: Describes the type of property a client is trying to sell/rent (e.g. hdb, condo etc.)
• UniquePersonList: A custom list implementation used within the Model to store Person objects, ensuring all entries are unique based on defined criteria.
• VersionedAddressBook: A proposed future extension of the AddressBook class that supports undo/redo functionality by maintaining a history of address book states.
• Postal Code: A short series of letters and/or numbers assigned to a specific geographic area.

---

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. Open a terminal in the location of the JAR file and run java -jar "PropertyPal.jar"
      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 re-doing step 1.2.
      Expected: The most recent window size and location is retained.

Adding a Person

1. Add with all fields present

   • Test case: add i/sell n/John Doe p/98765432 e/johnd@example.com a/John Street #12-34 pt/HDB 3 room flat pr/470000
     Expected: New person successfully added to the list. Status message shows confirmation and details of the new entry.

2. Add with missing mandatory field

   • Test case: add n/Jane Tan p/91234567 e/jane@example.com a/Tampines Avenue pt/Condo
     Expected: Error message shown — invalid command format.

3. Add duplicate person

   • Test case: Add a person with exactly the same details as an existing contact (e.g., same name, phone, email, address, price, property type, and intention).

   • Note: Equality matching is case-insensitive — differing letter case does not avoid duplication.
     Expected: Error message — This person already exists in PropertyPal.

4. Add person with same name but with at least one different field

   • Test case: Add the same name but with a different address or price.
     Expected: Person is added successfully; warning message displayed about entry with similar/same existing name.

Editing a Person

1. Edit phone and email

   • Prerequisite: There is a person in the contact list.
   • Test case: edit 1 p/99998888 e/johnupdated@example.com
     Expected: The first person’s phone and email fields are updated. Status bar timestamp changes.

2. Edit with invalid index

   • Test case: edit 0 n/NAME
     Expected: Error message shown. No changes made.

3. Edit without specifying any field

   • Test case: edit 1
     Expected: Error message — at least one field must be provided.

Finding Persons

1. Find by single field

   • Test case: find n/John
     Expected: Lists all contacts with “John” in their name (case-insensitive).

2. Find by multiple prefixes

   • Test case: find n/John p/9123
     Expected: Lists contacts whose name or phone number matches.

3. Find by price range

   • Test case: find pr/400000-600000
     Expected: Lists all persons whose property price is within the range.

4. Find by intention

   • Test case: find i/rent
     Expected: Lists all contacts whose intention is “rent”.

5. Invalid find syntax

   • Test case: find
     Expected: Error message — at least one prefix must be provided.

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: delete 1
      Expected: First contact 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: 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: delete, delete x, ... (where x is larger than the list size)
      Expected: Similar to previous.

Clearing All Entries

1. Test case: clear
   Expected: All entries removed from the list. Empty table displayed.

2. Invalid input: clear extra
   Expected: Command still accepted (extra parameters ignored).