PowerBake Developer Guide

Acknowledgements

PowerBake is a brownfield project built upon the AddressBook-Level3 project created by SE-EDU.

• Libraries used: JavaFX, Jackson, JUnit5

Setting up, getting started

Refer to the guide Setting up and getting started.

^ Back to top

Design

Architecture

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

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.

^ Back to top

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, PastryListPanel and 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. Such as methods which help load the FXML files. Due to the sheer number of components inhering from the abstract UiPart class, the inheritance has been shown in the diagram below instead.

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.

^ Back to top

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.

^ Back to top

Model Component

API : Model.java

The Model component,

• stores the address book data.

1. all Person objects (which are contained in a UniquePersonList object).
2. all Pastry objects (which are contained in a UniquePastryList object).
3. all Order objects (which are contained in a UniqueOrderList 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.
• same idea applies to Pastry and Order objects.
• 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)

^ Back to top

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 powerbake.address.commons package.

^ Back to top

Implementation

This section describes how some noteworthy features were implemented.

add order - Add Order

This command enables the addition of an Order for a specified Client in the Model. Its implementation involves validating client existence, pastry availability, and coordinating updates between the Model and UI components.

As a refresher, this is the add order command as described in the User Guide:

add order CLIENT_INDEX -pn PASTRY_NAME -q QUANTITY [-pn PASTRY_NAME -q QUANTITY]

add order 1 -pn Croissant -q 10 -pn Apple Pie -q 20 

Overview

When executed, this command parses user input and creates an internal representation of the order data. The sequence proceeds as follows:

1. Parse Command and Validate Client:

   • The input command text is parsed to identify the client index and order details.
   • The system validates that the client index exists in the current filtered client list.
   • If the client is found, the process continues with validating pastry items.

2. Validate Pastry Items:

   • For each pastry name specified, the system checks if it exists in the current pastry list.
   • The system ensures no duplicate pastry entries exist in a single order.
   • Valid quantities are checked for each pastry.

3. Create and Add Order:

   • A new Order object is created with the validated client and a list of OrderItem objects.
   • Each OrderItem contains a reference to a Pastry and its quantity.
   • The order is automatically assigned a "pending" status.

4. Model Update:

   • The model adds the new order to the address book, which updates the internal list of orders.
   • This triggers observers to notify relevant UI components.

5. Automatic UI Refresh:

   • The OrderListPanel UI component, which observes changes in the list of orders, detects the addition and refreshes its display.
   • The UI reflects this change by showing a new OrderCard for the recently added order.

Sequence Diagram

This sequence diagram shows the overall flow of the add order command.

^ Back to top

Documentation, Logging, Testing, Configuration, Dev-ops

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

^ Back to top

Appendix: Requirements

Product Scope

Target user profile:

• Is a small home bakery
• Sells their own pastries online through home deliveries
• Prefers desktop apps over other types
• Can type fast
• Prefers typing to mouse interactions
• Is reasonably comfortable using CLI apps
• Uses English as their main language

Value proposition: Keeping track of customers and their orders is hard for small business owners, this provides them with fast access to their orders that they can track.

• Provides a customer list where they are able to track customers and their orders
• Provides an order list so they can keep track of customers orders
• Provides a pastry list so they can keep track of their pastries

User Stories

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

^ Back to top

Use Cases

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

Use case: View Client Details

MSS

1. User requests to list all clients

2. PowerBake shows a list of clients

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

Use case: Add Client

MSS

1. User types add client command into PowerBake

2. PowerBake adds client details

   Use case ends.

Use case: Edit Client

MSS

1. User types edit client command with details into PowerBake

2. PowerBake updates the client details

   Use case ends.

Extensions

• 1a. Index is invalid

  • 1a1. PowerBake prints error message

  Use case ends.

• 1b. No fields are specified for editing

  • 1b1. PowerBake prints error message

  Use case ends.

• 1c. Format of edited fields is invalid

  • 1c1. PowerBake prints error message

  Use case ends.

Use case: Delete Client

MSS

1. User types delete client command (with index) into PowerBake

2. PowerBake delete client details

   Use case ends.

Extensions

• 1a. Index is invalid

  • 1a1. PowerBake prints error message

  Use case ends.

Use case: Find Client

MSS

1. User types find client command with keyword into PowerBake

2. PowerBake displays clients matching the keyword

   Use case ends.

Extensions

• 2a. No clients match the keyword

  • 2a1. PowerBake shows an empty list

  Use case ends.

Use case: View Pastries Details

MSS

1. User requests to list all pastries

2. PowerBake shows a list of pastries

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

Use case: Add Pastries

MSS

1. User types add pastries command into PowerBake

2. PowerBake adds pastries details

   Use case ends.

Use case: Edit Pastry

MSS

1. User types edit pastry command with details into PowerBake

2. PowerBake updates the pastry details

   Use case ends.

Extensions

• 1a. Index is invalid

  • 1a1. PowerBake prints error message

  Use case ends.

• 1b. No fields are specified for editing

  • 1b1. PowerBake prints error message

  Use case ends.

• 1c. Format of edited fields is invalid

  • 1c1. PowerBake prints error message

  Use case ends.

Use case: Delete Pastries

MSS

1. User types delete pastries command (with index) into PowerBake

2. PowerBake delete pastries details

   Use case ends.

Extensions

• 1a. Index is invalid

  • 1a1. PowerBake prints error message

  Use case ends.

Use case: Find Pastry

MSS

1. User types find pastry command with keyword into PowerBake

2. PowerBake displays pastries matching the keyword

   Use case ends.

Extensions

• 2a. No pastries match the keyword

  • 2a1. PowerBake shows an empty list

  Use case ends.

Use case: View Orders

MSS

1. User requests to list all orders

2. PowerBake shows a list of orders

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

Use case: Add Order

MSS

1. User types add order command into PowerBake

2. PowerBake adds order details

   Use case ends.

Extensions

• 1a. The client index is invalid

  • 1a1. PowerBake shows an error message

  Use case ends.

• 1b. The pastry name provided doesn't exist

  • 1b1. PowerBake shows an error message

  Use case ends.

• 1c. The quantity provided is invalid

  • 1c1. PowerBake shows an error message

  Use case ends.

Use case: Edit Order

MSS

1. User types edit order command with status into PowerBake

2. PowerBake updates the order status

   Use case ends.

Extensions

• 1a. Index is invalid

  • 1a1. PowerBake prints error message

  Use case ends.

• 1b. Status value is invalid

  • 1b1. PowerBake prints error message

  Use case ends.

Use case: Delete Order

MSS

1. User types delete order command (with index) into PowerBake

2. PowerBake deletes order

   Use case ends.

Extensions

• 1a. Index is invalid

  • 1a1. PowerBake prints error message

  Use case ends.

Use case: Find Order

MSS

1. User types find order command with keyword into PowerBake

2. PowerBake displays orders matching the keyword

   Use case ends.

Extensions

• 2a. No orders match the keyword

  • 2a1. PowerBake shows an empty list

  Use case ends.

^ Back to top

Non-Functional Requirements

1. The system shall provide a graphical user interface compatible with major operating systems.
2. The system must function offline with full capabilities.
3. All data must persist between sessions, requiring no re-entry of client or pastry information.
4. The interface must be intuitive enough that users unfamiliar with computers can navigate it with minimal confusion.
5. The system must load order and client pages in under 2 seconds, even when handling 500+ entries.

^ Back to top

Glossary

^ Back to top

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. Double-click the jar file or run java -jar powerbake.jar

   Expected: Shows the GUI with a set of sample clients, pastry and order.

2. Shutdown

   1. Click "File" in the top left-hand corner of the GUI
   2. Click "Exit" in the drop-down menu

   Expected: The app shuts down and all data is saved.

Adding a Client

1. Pre-requisite: Launched the app

2. Test case: add client Baobao -p 12345678 -e bao@gmail.com -a Sengkang Central.

   Expected: New client is added and displayed in client scrolling panel. Success message is displayed.

3. Test case: add client Baobao -p 12345678

   Expected: Error message is displayed. Correct format is displayed in display box.

4. Other incorrect commands to try: add Client, add baobao

   Expected: Error message is displayed. Correct format is displayed in display box.

Adding a Pastry

1. Pre-requisite: Launched the app

2. Test case: add pastry Croissant -pr 5.00.

   Expected: New pastry is added and displayed in pastry scrolling panel. Success message is displayed.

3. Test case: add pastry Croissant

   Expected: Error message is displayed. Correct format is displayed in display box.

4. Other incorrect commands to try: add Pastry, add pastry Bao -pr 5.111

   Expected: Error message is displayed. Correct format is displayed in display box.

Adding an Order

1. Pre-requisite:

   1. Launched the app
   2. Add at least one Client and Pastry

2. Test case: add order 1 -pn Croissant -q 100.

   Expected: New order for client of index 1 is added and displayed in order scrolling panel. Success message is shown.

3. Test case: add order 1

   Expected: Error message is displayed. Correct format is displayed in display box.

4. Other incorrect commands to try: add order 1 -pn Croissant, add order

   Expected: Error message is displayed. Correct format is displayed in display box.

Delete a Client

1. Pre-requisite:

   1. Launched the app
   2. Have at least one client

2. Test case: delete client 1.

   Expected: Delete client of index one and removed from client scrolling panel. Success message displayed.

3. Test case: delete client -1.

   Expected: Error message displaying invalid index.

4. Other incorrect commands to try: delete Client

   Expected: Error message displaying invalid index.

Delete a Pastry

1. Pre-requisite:

   1. Launched the app
   2. Have at least one pastry

2. Test case: delete pastry 1.

   Expected: Delete pastry of index one and removed from pastry scrolling panel. Success message displayed.

3. Test case: delete pastry -1.

   Expected: Error message displaying invalid index.

4. Other incorrect delete commands to try: delete Pastry

   Expected: Error message displaying invalid format.bove

Delete an Order

1. Pre-requisite:

   1. Launched the app
   2. Have at least one order

2. Test case: delete order 1.

   Expected: Delete order of index one and removed from order scrolling panel. Success message displayed.

3. Test case: delete order -1.

   Expected: Error message displaying invalid index.

4. Other incorrect delete commands to try: delete Order

   Expected: Error message displaying invalid format.

Edit a Client

1. Pre-requisite:

   1. Launched the app
   2. Have at least one client

2. Test case: edit client 1 -n Bobby.

   Expected: Edit client's name of index one to Bobby. Success message displayed.

3. Test case: edit client Bobby.

   Expected: Error message displaying invalid format.

4. Other incorrect commands to try: edit client 1

   Expected: Error message displaying invalid format.

Edit a Pastry

1. Pre-requisite:

   1. Launched the app
   2. Have at least one pastry

2. Test case: edit pastry 1 -n Pie.

   Expected: Edit Pastry's name of index one to Pie. Success message displayed.

3. Test case: edit pastry Pie.

   Expected: Error message displaying invalid format.

4. Other incorrect commands to try: edit pastry

   Expected: Error message displaying invalid format.

Edit an Order

1. Pre-requisite:

   1. Launched the app
   2. Have at least one order

2. Test case: edit order 1 -s delivered.

   Expected: Edit order's status to delivered. Success message displayed.

3. Test case: edit order 1.

   Expected: Error message displaying invalid format.

4. Other incorrect commands to try: edit order

   Expected: Error message displaying invalid format.

Find a Client

1. Pre-requisite:

   1. Launched the app

2. Test case: find client Bobby.

   Expected: Display client list with matching keywords.

3. Test case: find Bobby.

   Expected: Error message displaying invalid format.

Find a Pastry

1. Pre-requisite:

   1. Launched the app

2. Test case: find pastry Croissant.

   Expected: Display pastry list with matching keywords.

3. Test case: find Croissant

   Expected: Error message displaying invalid format.

Find an Order

1. Pre-requisite:

   1. Launched the app

2. Test case: find order Bobby.

   Expected: Display client list with matching keywords.

3. Test case: find Bobby.

   Expected: Error message displaying invalid format.

View all Clients

1. Pre-requisite:

   1. Launched the app

2. Test case: view client.

   Expected: Display full client list.

3. Test case: view.

   Expected: Error message displaying invalid format.

View all Pastry

1. Pre-requisite:

   1. Launched the app

2. Test case: view pastry.

   Expected: Display full pastry list.

3. Test case: view.

   Expected: Error message displaying invalid format.

View all Orders

1. Test case: view order.

   Expected: Display full order list.

2. Test case: view.

   Expected: Error message displaying invalid format.

^ Back to top

Appendix: Planned Enhancements

1. Improve help Command Pop-up to Include Command Overview

Currently, the help pop-up only contains a link to the User Guide online. However this could be unintuitive as users have to copy the link and open the browser to access the User Guide. Information such as an overview of the commands should be readily available in the help pop-up. This will allow users to quickly access the information they need without having to leave the app.

Proposed Changes:

• Add a command overview to the help pop-up.

This will provide users with a quick reference to the available commands and their usage.

2. Enhance Client and Pastry NAME Validation

Currently, PowerBake only allows alphanumeric characters and spaces in client and pastry names. This is a limitation as some names may contain special characters such as slashes, hyphens, accented characters and different languages. In the future, we will enhance the validation to allow these characters so that names such as Janet Smith-Johnson, Mike O'Leary, María José and etc. can be added to our system.

Proposed Changes:

• Allow for special characters and accented characters, widening the scope of valid names that can be added to the system.

These changes are expected to improve PowerBake's consistency and usability especially when used with other languages.

3. Improve EMAIL Validation for Clients

PowerBake's current email validation doesn't fully verify that email addresses it receives are actually valid.
One example of this is that invalid emails that do not contain valid top-level domains (TLDs) can be added. This can lead to accepting technically invalid email addresses that won't function for client communications.

Proposed Changes:

• Explore different email validations techniques like using Apache Commons Validator to enhance email validation.

This improvement will help ensure that client contact information is accurate and functional, reducing communication failures.

4. Make Certain Fields Optional when Adding Clients

Currently, parameters NAME, PHONE, ADDRESS and EMAIL are mandatory when adding a client. However, there may be situations where certain information is not available at the time of client creation, such as some clients who may lack an email address.

Proposed Changes:

• Make the email and address fields optional when adding a new client.
• Provide visual indicators in the UI for clients with incomplete information.
• Add the ability to update client profiles later when the missing information becomes available.

These changes will make the client registration process more flexible and accommodate various business scenarios where complete information may not be immediately available.

5. Enhance Add Order Functionality with Batch Processing

Currently, users can only create one order at a time, requiring separate command executions for multiple clients even when they're ordering the same pastries. This is inefficient for bakery owners who often process similar bulk orders for different clients.

Proposed Changes:

• Implement a new batch order command syntax that allows multiple client orders to be created simultaneously.
• Enable specifying multiple client indices when the pastry selections are identical.
• Add validation to ensure all client indices are valid before processing any orders.

These improvements would significantly reduce the time spent on data entry for bakery owners who process multiple similar orders in a single session.

6. Enhance Search Functionality with Filtering and Sorting Capabilities

The current search functionality for clients/pastries/orders only allows searching by name. This limitation makes it difficult to quickly locate items based on other important criteria such as phone number, address, price, order status, date, pastry type and etc..

Proposed Changes:

• Extend the find command to support additional search parameters including phone number, address, price, order status, date, pastry type and etc..
• Implement sorting capabilities for search results based on different attributes (phone number, price, order, date and etc.).
• Add combined filtering options to narrow search results using multiple criteria simultaneously.

These improvements will give bakery owners more powerful tools to manage their workflow, especially when dealing with a large volume of items.

7. Enhance Safety of the clear Command

Currently, after hitting Enter, the clear command will immediately delete all data without any confirmation.
This can lead to accidental data loss if there is any user error or misconception.

Proposed Changes:

• Implement a confirmation dialog that appears when the user types clear and hits Enter.
• The confirmation dialog will clearly state the consequences of the action and require the user to confirm before proceeding.

These changes will make the clear command safer to use and reduce the risk of accidental data loss.

8. Enhance Versatility of the clear Command

Currently, the clear command will delete ALL stored data.
This may not be the ideal usage of the command as users may only want to clear a specific list (e.g clearing only the client list instead of all lists).

Proposed Changes:

• Implementation of clear command to take in arguments such as client, pastry and order to specify which list to clear.

These changes will make the clear command more versatile to use and not as destructive.

9. Enhance Parsing of User Input

Currently, PowerBake allows for multiple consecutive spaces in names. This should not be allowed as it leads to inconsistent formatting and validation.

Proposed Changes:

• Trim consecutive spaces to a single space. This will ensure that names are formatted consistently and correctly.

These changes are expected to improve PowerBake's consistency and usability.

10. Inconvenience on editing Order Status

Currently, PowerBake does not update the selected order's status in the Details Panel on the right when an order is edited. This is due to a known limitation of JavaFX library where the properties of a property are unable to be "listened to". See here for details. This should not be allowed as it is an inconvenience for the user to switch to another order and back again for the UI to refresh itself.

Proposed Changes:

• Update the UI automatically when an order is edited.

These changes are expected to improve PowerBake's consistency and usability.