Developer Guide

• 1. Introduction
  • 1.1 Purpose
  • 1.2 Target Audience
  • 1.3 About DonnaFin
  • 1.4 Typical User Workflow
  • 1.5 Overview of Application
• 2. Acknowledgements
• 3. Setting up, getting started
• 4. Design and Implementation
  • 4.1 Architecture
    • 4.1.1 UI component
    • 4.1.2 Logic component
    • 4.1.3 Model component
    • 4.1.4 Storage component
    • 4.1.5 Common classes
  • 4.2 Implementation and Commands
    • 4.2.1 Model-level commands
    • 4.2.2 Client-level commands
    • 4.2.3 UI-browsing commands
    • 4.3 Notes tab
• 5. Documentation, logging, testing, configuration, dev-ops
• 6. Appendix: Requirements
  • 6.1 Product scope
  • 6.2 User stories
  • 6.3 Use cases
  • 6.4 Non-Functional Requirements
  • 6.5 Glossary
• 7. Appendix: Instructions for manual testing
  • 7.1 Launch and shutdown
  • 7.2 Deleting a client
  • 7.3 Viewing and editing a client
  • 7.4 Saving data

1. Introduction

1.1 Purpose

This guide covers the architecture, implementation and design choices in DonnaFin to give the reader a clear picture of the technical details and the inner workings of DonnaFin.

1.2 Target Audience

• Developers: anyone who wishes to dive into this codebase to improve or extend on DonnaFin.
• Advanced Users: financial advisors who want to better understand DonnaFin’s features.

1.3 About DonnaFin

DonnaFin.io is a desktop application for financial advisors to keep track of their client information and related tasks. Despite the application having an intuitive Graphical User Interface (GUI), it is optimized for entering commands using a Command Line Interface (CLI).

1.4 Typical User Workflow

This activity diagram shows how one might typically navigate through the DonnaFin application.

Commands refer to the pre-defined functions available to the user. Invalid commands refer to commands that are not available in the current window or commands that are used with the wrong format.

1.5 Overview of Application

In order to better understand how DonnaFin helps financial advisors, it is useful to understand and model the key client details that a financial advisor has to keep track of.

Below is an Object-Oriented Domain Model (OODM) modelling the existing state of affairs between a financial advisor and their client/s.

DonnaFin gives financial advisors a platform to store their numerous clients and their details. In this guide it will be explained how all the different classes, and components of DonnaFin come together to create a software that is able to perform this functionality.

2. Acknowledgements

Code Reuse

• SE-EDU: Address Book 3 - served as the foundation of this project
• SE-EDU: Address Book 4 - adapted their automated GUI tests for use here.

Libraries / Framework

• JavaFX - front-end Java framework
• ShadowJAR - generating fat JARs
• Jackson - file parsing framework for .json
• JUnit - testing framework
• TestFX - automated GUI testing framework

3. Setting up, getting started

Refer to the guide Setting up and getting started.

4. Design and Implementation

Tip: The .puml files used to create diagrams in this document can be found in the diagrams folder. Refer to the PlantUML Tutorial at se-edu/guides to learn how to create and edit diagrams.

4.1 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 has two classes called Main and MainApp. It is responsible for,

• At app launch: Initializes the components in the correct sequence, and connects them with each other.
• At shut down: Shuts down the components and invokes cleanup methods where necessary.

Commons represents a collection of classes used by multiple other components.

The rest of the App consists of 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.

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 the aforementioned functionality using a concrete {Component Name}Manager class.

For example, the Logic component defines its API in the Logic.java interface and implements its functionality using the LogicManager.java. Other components interact with a given component through its interface as much as possible rather than the concrete class or through any lower-level class, as illustrated in the (partial) class diagram below. Experienced programmers may recognise this as the Facade design pattern.¹

The sections below give more details of each component.

Tip: There are some notable exceptions to the Facade pattern. For example, for the Ui component, AttributePanel, PersonCard and ClientPanel. Arguably the better implementation would be to restrict all the interactions between components to the facades, but a design decision was made to prioritize a simple implementation of critical features over adhering to the design pattern.

4.1.1 UI component

Ui.java specifies the API of this component.

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PersonListPanel in home view and CommandBox, ResultDisplay, and ClientPanel in client view. 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 that is displayed has 6 main states to switch between.

1. PERSON_LIST_PANEL
2. CONTACT
3. POLICIES
4. ASSETS
5. LIABILITIES
6. NOTES

The first state, PERSON_LIST_PANEL represents the home view of the client. It is where the user sees the information of multiple clients at the same time. The other 5 are tabs specific to each client and will thus display different information for each client. The UI keeps track of the current tab it is observing through the UIState, which is set on each tab switch command. Further details for the tab switch command can be found here.

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.

4.1.2 Logic component

API : Logic.java

Here’s a (partial) class diagram of the Logic component:

How the Logic component works:

1. When Logic is called upon to execute a command, it chooses an ABCParser class e.g AddressBookParser, ContactTabParser etc., to parse the user command.
2. This results in a Command object (more precisely, an object of one of its subclasses e.g., AddCommand) which is executed by the LogicManager.
3. The command can communicate with the Model when it is executed (e.g. to add a person).
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:

• ParserContext holds a reference to a ParserStrategy that is set based on the current tab the user is on etc.
• When ParserContext calls upon the current ParserStrategy to parse a user command, the ABCParser (ABC is a placeholder for the specific parser strategy e.g.,ContactTabParser) creates an XYZCommandParser (XYZ is a placeholder for the specific command name e.g., AddCommandParser) which uses the other classes above to parse the user command and create a XYZCommand object. Further details can be seen in the implementation of commands section here.

• All XYZCommandParser classes (e.g., AddCommandParser, DeleteCommandParser, …) inherit from the Parser abstract class so that they can be treated similarly where possible e.g, during testing.
• ClientViewParser and AddressBookParser inherit from ParserStrategy while the tab specific parsers inherit from ClientViewParser inherit.

4.1.3 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.
• stores Storage object and communicates with it to save address book to user files.

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

How is Person stored?

• JsonAdaptedPerson is created with the Jackson framework.
• Each Person in DonnaFin is stored as a JsonAdaptedPerson as shown in our class diagram above.
• The Name, Email, Phone, Address and Notes of each Person is stored as a JsonProperty of type String.
• Assets, Liabilities and Policy are stored as a List of JsonAdaptedAsset, JsonAdaptedLiability and JsonAdaptedPolicy respectively. Each JsonAdaptedAsset, JsonAdaptedLiability and JsonAdaptedPolicy is created separately using Jackson and contains the necessary fields for their respective attributes, stored as a JsonProperty of type String.
• As a Person can have more than one Asset, Liability or Policy, we have chosen to store them as nested objects rather converting them into a single String before storage and converting them back to the correct attributes on retrieval from the database.
• As such, Asset, Liability and Policy are stored in this special manner and any future attributes that share the same characteristics can be stored in the same way.

Here is an example of a Person in JSON form:

{
  "name" : "Alex Yeoh",
  "phone" : "87438807",
  "email" : "alexyeoh@example.com",
  "address" : "Blk 30 Geylang Street 29, #06-40",
  "notes" : "Likes bread",
  "policies" : [ {
    "name" : "Golden Age",
    "insurer" : "AIA",
    "totalValueInsured" : "$ 14000.00",
    "yearlyPremiums" : "$ 28.00",
    "commission" : "$ 4.00"
  } ],
  "liabilities" : [ {
    "name" : "Bank debt",
    "type" : "debt",
    "value" : "$ 20000.00",
    "remarks" : "10% interest"
  } ],
  "assets" : [ {
    "name" : "HDB @Jurong",
    "type" : "Property",
    "value" : "$ 300000.00",
    "remarks" : "BTO"
  } ]
}

4.1.5 Common classes

Classes used by multiple components are in the donnafin.commons package.

4.2 Implementation and Commands

How the architecture components interact with each other through commands

Command types fall into three main categories.

1. Model-level commands
2. Client-level commands
3. UI-browsing commands

Despite falling under the three broad categories, the commands still have many similarities. Thus, we give an in depth explanation of how the first category works. Subsequent explanation of commands from the other two categories will follow the same framework but differ slightly.

4.2.1 Model-level commands

Key properties:
1. The command interacts with model through an addition or deletion
2. The command interacts with storage through an addition or deletion.
3. The command does not access the inner details of clients but rather treat them as atomic.

Commands that fall under this category are :
1. Add
2. Delete
3. Find
4. List

The Delete command is one of the commands that fall under this category. We will be using the Delete command as the example to illustrate and explain all commands under this category.

Full sequence diagram

Logic specific sequence diagram

Here is an explanation of what takes place when the user enters the command delete 1 which falls under first category. The full sequence diagram gives the overview of what happens when a command runs. Since the main legwork is done in logic, the logic specific sequence diagram as shown above takes a deeper dive into the inner details the full sequence diagram.

Explanation of diagram above:

• The UI takes in the input command from the user and passes it to the Logic component.
• The Logic component parses the command and returns the Delete command.
• The Logic component executes the Delete command. The deletePerson method in Model is called which then deletes the Person from donnafin.json.
• The Logic component then accepts the LogicConsumer produced from the CommandResult. This consumer will alter the logic component depending on the CommandResult. In this case, for the delete command, the consumer makes no change to logic.
• The Logic component then continues with the execute command and calls the saveAddressBook method to save the updated addressBook with the deleted person. This does not involve a consumer in any way and is always part of execute command.
• The Model component then calls saveAddressBook method that engages the Storage component to save the updated changes to storage locally.
• The UI component then accepts the ``UIConsumer produced from the CommandResult. This consumer will alter the UI component depending on the CommandResult. In this case, for the delete command, the consumer makes no change to logic.

4.2.2 Client-level commands

Key Properties:

1. The command has to access and edit information regarding one specific client.
2. The command interacts and actively updates information in storage.
However, commands in the third category differ from the first in that this category deals with information within one specific client, while the first adds/deletes the client specified within the entire model.

Commands that fall into the second category are:
1. Edit
2. Append
3. Remove

Edit command is a command that edits the information of a specific client. Other commands like append and remove, also deal directly with a specific client’s information. Thus, they fall under the second category Like other commands in the other two categories, edit command follows the same general structure. We will be using the Edit command as the example to illustrate and explain all commands under this category.

Explanation:

• The UI takes in the input command from the user and passes it to the Logic component.
• The Logic component parses the input and the Edit command is returned. A consumer for PersonAdapter is created here.
• The Logic component executes the Edit command.
• During the execution of the Edit command above, the PersonAdapter accepts the consumer that edits the specified person.
• A EditCommandResult is returned from the execution of Edit Command. This CommandResult, like the two other categories contain both a consumer for UI and Logic.
• The Logic component then accepts the LogicConsumer produced from the CommandResult.
• The UI component then accepts the UIConsumer produced from the CommandResult. The UI is here to display the newly edits made.

4.2.3 UI-browsing commands

Key Properties:
1. The commands do not interact with model.
2. The commands have to handle the changing of ParserStrategy, from the current one
to ABCParser of the new tab. 3. The commands need to update the UIState of UI to keep track of which tab the user is currently on.

Commands that fall into this category are:
1. SwitchTab
2. View
3. Home

Switch tab command is a command that explicitly involves the changing of tabs, which fall under the third category. We will be using the SwitchTab command as the example to illustrate and explain all commands under this category.

Explanation of diagram above:

• The UI takes in the input command from the user and passes it to the Logic component that is responsible for parsing the input.
• The Logic component parses the command and returns the SwitchTab command.
• The Logic component executes the SwitchTab command and returns the SwitchTabCommandResult
• The Logic component then accepts the LogicConsumer produced from the SwitchTabCommandResult. In this case, for the SwitchTab command, a new ParserStrategy is set here.
• The UI component then accepts the UIConsumer produced from the CommandResult. UIState is set here.

4.3 Notes tab

The NotesTabParser is different from other tabSpecificParsers in that it has no tab specific command. However, the TextArea of the notes tab allows the user to type in any quick notes that the user would want, updating it in realtime. This is opposed to the commands however, since for commands changes to any other component only happen when the command is executed. Hence the notes tab takes advantage of a different process.

Key features about notes:

1. A listener is attached to the TextArea of the notes tab. This allows for realtime updates when typing in the TextArea. If there are any changes, the function edit in PersonAdapter is called.
2. The edit function in PersonAdapter saves the information straight away, hence making the updates realtime.

5. Documentation, logging, testing, configuration, dev-ops

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

6. Appendix: Requirements

6.1 Product scope

Target user profile:

• Financial Advisor
• Has a need to manage a significant number of clients
  • Keep track of their financial and personal information
• Prefer desktop apps over other types
• Tech-savvy, comfortable with keyboard shortcuts (CLI apps)
• Can type fast
• Prefers typing to mouse interactions

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

The product provides financial advisors with a clean, easy to use interface to prepare them for meetings and maintain good relationships with their clients. On a per-client basis, DonnaFin keeps track and displays client’s financial details, their contact details, and any notes about the client. In the main page, it collates all clients for easy access. In the client information page, financial details of the specific client selected is neatly segmented into tabs for convenient and quick access.

The product will not help them with work relations with other financial advisors as the product’s scope only covers the personal use of the product. It does not link with any financial calculators, financial databases or cover market information.

6.2 User stories

Priorities: (must have) - HIGH, Medium (nice to have) - MEDIUM, Low (unlikely to have) - LOW

6.3 Use cases

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

UC01: Adding a client to DonnaFin
State: Home Window

MSS

1. User requests to add client along with the relevant details.
2. DonnaFin announces that the client has been successfully added.
   Use Case ends.

Extensions

• 1a. The user types the command using the wrong syntax.
  • 1a1. DonnaFin shows an error message and displays the correct format for the user to use and a correct example.
    Use Case resumes from step 1.

UC02: Deleting a client from DonnaFin
State: Home Window

MSS

1. User requests to delete a client from DonnaFin using the right syntax.
2. DonnaFin announces that the client has been successfully deleted.
   Use case ends.

Extensions

• 1a. The given index is invalid.

  • 1a1. DonnaFin shows an error message.

    Use case resumes from step 1.

UC03: Finding a client by name
State: Home Window

MSS

1. User chooses to find a client within DonnaFin using the right syntax.

2. DonnaFin displays the clients that match the input keyword.

   Use case ends.

Extensions

• 1a. The user types the command using the wrong syntax.
  • 1a1. DonnaFin shows an error message.
    Use Case resumes at step 1.
• 1b. The keyword does not match any client.
  • 1b1. DonnaFin does not display any client.
    Use Case ends.

UC04: Viewing the details of a client
State: Home Window

MSS

1. User requests to view a client using the right syntax.

2. DonnaFin displays details on the client.

   Use case ends.

Extensions

• 1a. The user types the command using the wrong syntax.
  • 1a1. DonnaFin shows an error message.
    Use Case resumes at step 1.
• 1b. The given index is invalid.
  • 1b1. DonnaFin shows an error message.
    Use Case resumes at step 1.

UC05: Getting help
State: Works on both Home and Client Window

MSS

1. User requests for help to get assistance on commands.

2. DonnaFin displays a window with the user guide for the DonnaFin application.

   Use case ends.

UC06: Listing all clients
State: Home Window

MSS

1. User requests for the list of all the registered clients.

2. DonnaFin displays all the clients that has been registered within DonnaFin.

   Use case ends.

UC07: Switching to other tabs
State: Client Window

MSS

1. User requests to view another tab within the client Window.

2. DonnaFin switches the current tab to the requested tab.

   Use case ends.

Extensions

• 1a. The user types the wrong command.
  • 1a1. DonnaFin shows an error message.
    Use case resumes at step 1.
• 1b. The user types the wrong tab title.
  • 1b1. DonnaFin shows an error message and tells the user that the tab they request does not match any existing tab.
    Use case resumes at step 1.

UC08: Returning to Home Window

State: Client Window

MSS

1. User requests to return to home window.

2. DonnaFin switches the view back to home window.

   Use case ends.

Extensions

• 1a. The user types the wrong command.
  • 1a1. DonnaFin shows an error message.
    Use case resumes at step 1.

UC09: Editing a client’s contact information

State: Client Window (Contacts Tab)

MSS

1. User requests to edit client’s contact information.

2. Field is edited and client window with the updated field is shown.

   Use case ends.

Extensions

• 1a. The user types the wrong command.
  • 1a1. DonnaFin shows an error message.
    Use case resumes at step 1.
• 1b. The user types in the new field with the unsupported format.
  • 1b1. Contact is not updated and DonnaFin shows an error message.
    Use case resumes at step 1.

UC10: Adding an asset to a client

State: Client Window (Assets Tab)

MSS

1. User requests to add an asset to the client.

2. DonnaFin adds the asset.

   Use case ends.

Extensions

• 1a. User’s input does not conform with the specified format.
  • 1a1. DonnaFin shows an error message.
    Use case resumes at step 1.

UC11: Removing an asset from a client

State: Client Window (Assets Tab)

MSS

1. User requests to remove an asset from the client.

2. DonnaFin removes the asset.

   Use case ends.

Extensions

• 1a. User’s input does not conform with the specified format.
  • 1a1. DonnaFin shows an error message and displays the correct format for the user to use with a correct example
    Use Case resumes at step 1.
• 1b. User’s given index is invalid.
  • 1b1. DonnaFin shows an error message.
    Use Case resumes at step 1.

UC12: Adding a liability to a client

State: Client Window (Liabilities Tab)

MSS

1. User requests to add a liability to the client.

2. DonnaFin adds the liability.

   Use case ends.

Extensions

• 1a. User’s input does not conform with the specified format.
  • 1a1. DonnaFin shows an error message.
    Use case resumes at step 1.

UC13: Removing a liability from a client

State: Client Window (Liabilities Tab)

MSS

1. User requests to remove a specific liability from the client.

2. DonnaFin deletes the liability.

   Use case ends.

Extensions

• 1a. User’s input does not conform with the specified format.
  • 1a1. DonnaFin shows an error message and displays the correct format for the user to use with a correct example
    Use Case resumes at step 1.
• 1b. User’s given index is invalid.
  • 1b1. DonnaFin shows an error message.
    Use Case resumes at step 1.

UC14: Adding a policy to a client

State: Client Window (Policies Tab)

MSS

1. User requests to add a policy to the client.

2. DonnaFin adds the policy.

   Use case ends.

Extensions

• 1a. User’s input does not conform with the specified format.
  • 1a1. DonnaFin shows an error message.
    Use case resumes at step 1.

UC15: Removing a policy from a client

State: Client Window (Policies Tab)

MSS

1. User requests to remove a policy from the client.

2. DonnaFin removes the policy.

   Use case ends.

Extensions

• 1a. User’s input does not conform with the specified format.
  • 1a1. DonnaFin shows an error message and displays the correct format for the user to use with a correct example
    Use Case resumes at step 1.
• 1b. User’s given index is invalid.
  • 1b1. DonnaFin shows an error message.
    Use Case resumes at step 1.

UC16: Exiting the application
State: Works on both Home and Client Window

MSS

1. User requests to exit the application.

2. DonnaFin exits and closes.

   Use case ends.

6.4 Non-Functional Requirements

1. Should work on any mainstream OS as long as it has Java 11 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. A novice with no coding background should be able to use the address book.
5. The system should respond within 100 milliseconds.
6. The size of the application should be no more than 100 MB.
7. All data should be stored locally.
8. The application should not need a remote server to function.
9. The application should not require any installer to start functioning.
10. The GUI should appear fine for screen resolutions 1920x1080 and higher.

6.5 Glossary

• Mainstream OS: Windows, Linux, Unix, OS-X
• Private client detail: A client detail that is not meant to be shared with others
• Asset: Things of present or future value owned by a client
• Liability: Things that the client owes to a debtor which would lead to an outflow of money in the future.
• Policy: A contract between an insurer and policyholder (the client in this case) where the policy holder receives financial protection or reimbursement against losses. ——————————————————————————————————————–

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

7.1 Launch and shutdown

1. Initial launch

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

   2. Double-click the jar file Expected: Shows the GUI with a set of sample clients. The window size may not be optimised for your display.

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. { more test cases …​ }

7.2 Deleting a client

1. Deleting a client while all clients are being shown (home window)

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

   2. Test case: delete 1
      Expected: First client is deleted from the list. Details of the deleted client shown in the status message. Timestamp in the status bar is updated.

   3. Test case: delete 0
      Expected: No client 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.

2. { more test cases …​ }

7.3 Viewing and editing a client

1. Enter client window

   1. Prerequisites: Currently in the home window

   2. Test case: view 1
      Expected: client window will be shown, and you can inspect the details of the client.

   3. Test case: view -4
      Expected: As it is not a valid index, you will remain in the home window with an error command output.

   4. Test case: editing fields Expected: Switching tabs and editing fields with the commands listed in the user guide here works correctly.

2. { more test cases …​ }

7.4 Saving data

1. Dealing with missing/corrupted data files

   1. {explain how to simulate a missing/corrupted file, and the expected behavior}

2. { more test cases …​ }