Chen Anqi - Project Portfolio

Want your expenses tracked under a recurring budget? Simple enough with this command: addbudget.

The concrete format is:

For example, after typing:

You’ll see that a new budget school is created, and set to $300, recurring monthly, starting from 1 Oct 2019.

Now that you’ve successfully added a few different budgets, wonder how to toggle between them? Try this magical command: switchbudget, which switches the primary budget to any other budget in one click!

The concrete format is:

For example, suppose you’re at primary budget school now. After typing:

You will see that the primary budget panel is switched from school to outside school. Every expense you add from now on will be tracked under the outside school budget instead.

To get an overview of all the budgets at hand, simply type:

You’ll see a list of all budgets in MooLah.

A typo? On a second thought? No worries, you can easily modify your budget with editbudget.

The concrete format is:

For example, if the second budget shown in the list is school, recurring monthly, amount set as $300, refreshed on the 1st of each month, after typing:

It will change to school expenses, capped at $400, refreshed on the 5th of each month.

Don’t want it any more? Use deletebudget to say bye to your budget!

The concrete format is:

For example, after typing:

The budget with the name school will be deleted.

Budget names are too long? Don’t worry, there’s an easier way to delete them: deletebudget-id.

The concrete format is:

You’ll see the corresponding budget disappear from the list.

Don’t feel like living on budgets any more? You can clear them all, just using this simple command: clearbudget.

Wanna see your archived expenses in the past? The command switchperiod is the time machine you need.

The concrete format is:

For example, suppose you have a monthly budget school, refreshed on the 1st of each month; and suppose it is November now. After typing:

You’ll see all expenses tracked under school from 1 May to 31 May this year.

When you are staring at the primary budget panel, and suddenly want to modify an expense…​ Rather than switch back to the general expense list, there’s a quicker way to do it: you can edit it directly from this budget panel! The trick is: editexpense-primary.

The concrete format is:

The INDEX depends on the current budget’s expenses, instead of the general expense list.

Similarly to editing expense inside a budget, you can delete an expense directly from the budget panel: deleteexpense-primary.

The concrete format is:

The INDEX depends on the current budget’s expenses, instead of the general expense list.

Budgets form a partition of all expenses. That is, an Expense must belong to one and only one Budget, and all expenses from all Budget must add up to the total number in the general expense list. Each Expense keeps track of its own Budget through the budgetName attribute — this is possible because UniqueBudgetList disallows duplicate budget names. On the other hand, each Budget keeps track of a list of Expense added to this budget, as shown in the figure below.

There are five commands related to the addition, modification and removal of budgets, namely: AddBudgetCommand, EditBudgeCommand, DeleteBudgetByIndexCommand, DeleteBudgetByNameCommand, and ClearBudgetsCommand.

Here is the class diagram of AddBudgetCommand:

As shown in the figure above, AddBudgetCommand has 2 methods: (i) validate(model), which checks whether the command is legal (i.e. will not result in duplicate budgets being added to MooLah), and throws CommandException to notify user of the illegal input if any; (ii) execute(model), which runs this command in model and successfully adds a new Budget.

The following sequence diagram shows how the add budget operation works:

As shown in the figure above, when user inputs "addbudget …​", LogicManager executes the String, and MooLahParser creates the corresponding CommandParser which parses the input into an AddBudgetCommand. AddBudgetCommand then validates itself by checking if there is an identical Budget already existing in MooLah. If no duplicate budgets are found, it executes the command, adding the new Budget to MooLah. After that, AddBudgetCommand creates a CommandResult and passes it back to LogicManager. LogicManager then saves the updated MooLah as Json file, and returns the CommandResult to GUI to be displayed to user.

The implementation of other commands follows a similar flow as AddBudgetCommand, differing only in the parameters and corresponding methods in ModelManager. A noteworthy implementation in EditBudgetCommand is that it has a inner class EditBudgetDescriptor to record the updated attributes of the budget, which is then used in the method EditBudgetCommand#createEditedBudget(Budget, EditBudgetDescriptor) to create an edited Budget, maintaining non-updated attributes the same as the original Budget.

When a Budget is edited, the original budget’s expenses will be transferred to the updated budget through Budget#transferExpensesTo(Budget other). The transfer process does two things: (i) set the expenses’s budgetName to the new budget’s name; (ii) add the expenses to the new budget’s expense list. Similarly, when a Budget is deleted, all its expenses will be transferred to Default Budget through the same method.

At any time, there is one, and only one, primary budget in MooLah. All expenses added will go to this primary budget. If the user wants to track expenses under a different budget, he switches to the target budget first, before adding the expense. A newly created budget is automatically set to primary. MooLah creates a Default Budget upon first launching. If no budget is created by the user, expenses will be tracked under this Default Budget, which has a huge budget limit (10^21) and budgeting period (100 years).

The SwitchBudgetCommand takes in a budget name and switches primary budget to that budget. Given below is an example usage scenario of SwitchBudgetCommand:

Step 1. The user launches MooLah for the first time. The default budget will be created and set as the primary budget.

Step 2. The user adds an expense "bubble tea". Since the default budget is the primary one, this expense will go under default budget.

Step 3. The user creates a budget "School". Since "School" is newly added, it will be set as the primary budget.

Step 4. The user adds an expense "chicken rice". Since "School" is the primary budget, this expense will go under "School".

Step 5. The user now wants to add another expense "movie", but does not want it tracked under "School". As such, the user executes switchbudget d/default budget. The default budget is now the primary budget.

Step 6. The user adds the expense "movie", which is tracked under the current primary budget - default budget.

A budget is like a sliding window that moves along the time axis. The window has a fixed size determined by BudgetPeriod, an enum class with five values: DAY, WEEK, MONTH, YEAR, INFINITY (for Default Budget). Only expenses within the current window are shown in the app. Every time the budget refreshes, the window "slides" to the next period, starting with an empty screen that gradually gets populated with newly added expenses over time. This is achieved through the BudgetWindow class.

Here is the class diagram of BudgetWindow:

As shown in the figure above, BudgetWindow has 3 attributes: startDate, endDate, and period. The start and end dates are modifiable, but the period is fixed. This corresponds to the above-mentioned "sliding window" concept.

A budget keeps a list of all expenses ever been tracked by this budget, including historical ones. Additionally, it has a method Budget#getCurrentPeriodExpenses() that filters from this list expenses within the current budgeting period, which in turn get to be shown on MooLah’s GUI.

When users want to view expenses in a past period, they can do so by executing SwitchPeriodCommand. This command takes in a Timestamp and switches the budget window to a period anchored by that Timestamp. This is achieved by BudgetWindow#normalize(Timestamp anchor) method.

Given below is an example usage scenario of SwitchPeriodCommand:

Step 1. The user has a monthly budget "school" that recurs on the 5th of each month. Suppose the current date is 10 Nov. As a result, the current budgeting period will be 5 Nov - 4 Dec.

Step 2. The user wants to view expenses in September. As such, the user executes switchperiod t/20-09 (20-09 is interchangeable with any other dates within 5 Sep - 4 Oct). This command calls BudgetWindow#normalize, which shifts the window’s start and end dates to 5 Sep and 4 Oct respectively, while maintaining the fixed period — MONTH. As a result, the user sees expenses tracked under the budget during 5 Sep - 4 Oct.

The BudgetWindow#normalize method is also called upon adding a new Budget to MooLah. No matter how far the start date inputted by the user is from now, it will be normalized to the current period, such that expenses added subsequently will correctly be reflected in the budget panel.

Each budget, once added, will recur infinitely. This is achieved by Budget#refresh(), along with the Timekeeper class. Every 0.05 second, Timekeeper checks if the system time is at day break, and call Budget#refresh() if necessary. Subsequently, BudgetWindow#normalize is called; the anchor passed in is current time. As a result, the Budget is successfully normalized to the current period.

ListBudgetsCommand updates Model’s FilteredBudgetList with a Predicate to show all budgets. The command returns a CommandResult with view request to BudgetListPanel.PANEL_NAME. Subsequently, MainWindow#changePanel(PanelName) will switch the currently shown panel to BudgetListPanel. ListBudgetsCommand has the same effect as "view budget list".

There are three classes related to the UI display of budgets:

The progress bar in BudgetCard shows the proportion used against the budget limit. This is calculated by Budget#calculateProportionUsed(), which divides the sum of all current period expenses against the budget limit, returning a Percentage that wraps the result (rounded to the nearest integer).

Besides, the budget also gives popup notification when proportion used reaches 50%, 90%, and 100%. These 3 status correspond to Budget#isHalf(), Budget#isNear() and Budget#isExceeded(). Before each command in MooLah is executed, the initial values of these 3 booleans are recorded by LogicManager#recordInitialPrimaryBudgetStatus(), which returns a boolean array of size 3. At the end of each command, the final values of these 3 booleans are recorded again by LogicManager#recordFinalPrimaryBudgetStatus(). The two arrays are then passed into MainWindow#showWarningIfAny() for a comparision, and if any values have changed, MainWindow#showPopupMessage() will show the corresponding pop up notification to remind the user of the budget progress.

Budget objects are stored in Json format, through the JsonAdaptedBudget class. The Json file has the same properties as the budget, except: (i) it flattens the BudgetWindow field into start date, end date and period, for clearer display; (ii) it stores a list of UniqueIdentifier to expenses, instead of a list of JsonAdaptedExpense.

The following activity diagram summarizes what happens to budgets when the app launches and when a new expense is added:

Budgeting-related commands integrate well with Undo-Redo feature, by extending UndoableCommand. Undoable commands are those modifying data in MooLah, for example, AddBudgetCommand and EditBudgetCommand. On the other hand, commands that only result in GUI changes, such as ListBudgetsCommand, are not undoable.

A difficulty here is to make every undo (or redo) change immediately reflected on GUI. Since undo rollbacks models, this dictates that every change must result in a new Budget object being created and replacing the old one. Otherwise, even though the change is effective in the back end, it might not show in the front end because the Budget in two models points to the same object. This issue is handled by Budget#deepCopy(), which is widely called from UniqueBudgetList, in every method that modifies the existing budgets.