DeveloperGuide.adoc

Dukemon - Developer Guide

By: Team SE-EDU      Since: Jun 2016      Licence: MIT

• 1. Setting up
• 2. Design
  • 2.1. Architecture
  • 2.2. UI component
  • 2.3. AppManager component
  • 2.4. Timer component
  • 2.5. Logic component
  • 2.6. Model component
  • 2.7. Game component
  • 2.8. Storage component
  • 2.9. Statistics component
  • 2.10. Common classes
• 3. Implementation
  • 3.1. AutoComplete and Command Execution
  • 3.2. Settings Feature
  • 3.3. Timer-based Features
  • 3.4. WordBank Features
  • 3.5. Statistics features
  • 3.6. [Proposed] Data Encryption
  • 3.7. [Proposed] User Profiles
  • 3.8. Logging
  • 3.9. Configuration
• 4. Documentation
• 5. Testing
• 6. Dev Ops
• Appendix A: Product Scope
• Appendix B: User Stories
• Appendix C: Use Cases
• Appendix D: Non Functional Requirements
• Appendix E: Glossary
• Appendix F: Product Survey
• Appendix G: Instructions for Manual Testing
  • G.1. Launch and Shutdown
  • G.2. Deleting a person
  • G.3. Saving data

1. Setting up

Refer to the guide here.

2. Design

2.1. Architecture

Figure 1. Dukemon Architecture Diagram

The Architecture Diagram given above explains the high-level design of Dukemon. Given below is a quick overview of each component.

💡	The .puml files used to create diagrams in this document can be found in the diagrams folder. Refer to the Using PlantUML guide to learn how to create and edit diagrams.

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 up with each other.

• At shut down: Shuts down the components and invokes cleanup method where necessary.

Commons represents a collection of classes used by multiple other components. The following class plays an important role at the architecture level:

• LogsCenter : Used by many classes to write log messages to the App’s log file.

The rest of Dukemon contains seven componenets.

• UI:
  The Graphical UI of Dukemon that interacts with the user.

• AppManager:
  The buffer between the User and Dukemon’s internal components.

• Timer:
  The internal Timer that triggers events based on time elapsed.

• Logic:
  The main command executor and performer of operations.

• Model:
  Holds the non-game data in-memory.

• Game:
  Holds the data of live game sessions in-memory.

• Storage:
  Reads data from, and writes data to, the local hard disk.

For the components UI, Logic, Model, Timer, Storage and Game:

• Defines its API in an interface with the same name as the Component.

• Exposes its functionality using a {Component Name}Manager class.

  • ie. StorageManager implements Storage, GameTimerManager implements GameTimer.

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.

Figure 2. Component interactions for delete 1 command

The sections below give more details of each component.

2.2. UI component

Figure 3. Structure of the UI Component

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

The UI component uses 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 AppManager component.

• Listens for changes to Model data and Timer through the AppManager so that the UI can be updated correspondingly.

2.3. AppManager component

Figure 4. Structure of the AppManager Component

The AppManager component serves as a Facade layer and communication hub between the internal components of Dukemon and the UI components. Using this extra layer provides better abstraction between the UI and the internal components, especially between the Timer and the UI.

AppManager communicates with both the Logic and Timer components to send feedback to the UI to display back to the user.

• Gets feedback for commands by through Logic

• Starts and Stops the Timer when required.

• Makes call-backs to the UI to update various UI components.

• Initiates collection of Statistics by pulling data (eg. Time Elapsed) from Timer and Logic.

2.4. Timer component

Figure 5. Structure of the Timer Component

API : GameTimer.java

The Timer consists of a GameTimer that will keep track of time elapsed via an internal countdown timer and notify the AppManager, who will notify the UI components.

• Dealing with the internal countdown timer that runs during a game session.

• Periodically triggering callbacks that will notify the AppManager component.

• Gets timestamps to trigger Hints via a HintTimingQueue

Due to the fact that the Timer has to work closely with the UI and AppManager (without being coupled directly), it is separated from the Logic, Model and Game components.

2.5. Logic component

This section breakdown the logic package into its internal components

Figure 6. Structure of the Logic Component

Logic is primarily built by two segments: Command and Parser.

Command

Command is an abstract class.

Four other abstract classes (HomeCommand, OpenCommand, GameCommand and SettingsCommand) extend Command.

Concrete Command classes with an execute method implementation extend one of the above four abstract classes.

Parser

ParserManager holds reference to a SpecificModeParser and a SwitchModeParser.

The SpecificModeParser changes based on current application mode.

Both of them hold references to all concrete Parser and Command Classes with the help of ClassUtil

Logic fulfils its contracts with other packages through two interfaces: Logic and UiLogicHelper

Examples of transactions promised by Logic API include command execution, command result and update statistics.

UiLogicHelper APIs is a subset of Logic APIs and only contains transactions for AutoComplete. It exposes the functionalities through the following getter methods:

• List<AutoFillAction>#getMenuItems(String text) — Gets an List of AutoFillActions to fill up AutoComplete display based on current user input given in text

• ModeEnum#getMode() — Retrieves the application mode to display visually to the user (represented by enumeration object ModeEnum)

• List<ModeEnum>#getModes() — Retrieves the possible modes the user can transition to from current mode

API : Logic.java UiLogicHelper.java

2.6. Model component

Figure 7. Structure of the Model Component

API : Model.java

The Model,

• stores a UserPref object that represents the user’s preferences.

• stores the Word Bank data.

• exposes an unmodifiable ObservableList<Card> 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.

• does not depend on any of the other three components.

ℹ️	As a more OOP model, we can store a Tag list in Address Book, which Person can reference. This would allow Address Book to only require one Tag object per unique Tag, instead of each Person needing their own Tag object. An example of how such a model may look like is given below.

2.7. Game component

Figure 8. Structure of the Game Component

The Game component,

• stores a shuffled List<Card> that is cloned/copied from a ReadOnlyWordBank.

• maintains an Index to keep track of the state of the game.

• has an associated DifficultyEnum that dictates the time allowed for each question.

• verifies Guess that are sent by Logic (User’s guesses)

2.8. Storage component

Figure 9. Structure of the Storage Component

API : Storage.java

The Storage component,

• can save UserPref objects in json format and read it back.

• can save the Address Book data in json format and read it back.

2.9. Statistics component

The Statistics component includes 2 main subcomponents:

• A GlobalStatistics, containing the user’s total number of games played and the number of games played in the current week.

• A WordBankStatisticsList, which is a collection of WordBankStatistics, one for each WordBank.

The class diagram of the Statistics component is shown below:

Figure 10. Statistics class diagram.

2.10. Common classes

Classes used by multiple components are in the seedu.Dukemon.commons package.

3. Implementation

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

3.1. AutoComplete and Command Execution

This section explains how the design choice of Dynamic Parsers fulfils AutoComplete and Command Execution.

ParserManager dynamically changes parser depending on current mode the game is at. When updating the User Interface for every keystroke, it ensures only the right commands get parsed and autocompleted at each moment.

3.1.1. Implementation details

1. ParserManager instance has reference to a SwitchModeParser and SpecificModeParser

2. When user enters a keystroke, the SwitchModeParser and/or SpecificModeParser are accessed based on internal state.

3. It updates the AutoComplete suggestions for every keystroke.

4. Internal State consists of booleans: gameIsOver, bankLoaded and enumeration ModeEnum: HOME, OPEN, GAME, SETTINGS

5. The above process is aided by ClassUtil to handle instantiation of Parser and Command objects.

   The state management is complex. The below sequence diagram demonstrates all possible workflows.

Figure 11. Activity diagram of Application flow

ℹ️	Home (No Switch) means HomeModeParser is used and SwitchModeParser is not used

3.1.2. Walkthrough of Command Execution

• Command Execution through Logic Interface

  1. A String from Ui package gets to ParserManager and gets converted into a Command object which is executed by the LogicManager.

  2. The command execution can affect the Model (e.g. adding a word meaning pair into wordbank).

  3. The result of the command execution is encapsulated as a CommandResult object which is passed back to the Ui and AppManager.

  4. In addition, the CommandResult object can also instruct the Ui to perform certain actions, such as displaying help to the user.

3.1.3. Walkthrough of AutoComplete

• AutoComplete through UiLogicHelper Interface

The following sequence diagram shows how the AutoComplete operation runs when user keys in "st" into command box.

Figure 12. Sequence Diagram of AutoComplete

3.1.4. Design Considerations

	Alternative 1	Alternative 2
Aspect 1: How parser and command objects are instantiated in SpecificModeParser	Use java reflections to hold a List of Classes and iterate through them to pick the matching Classes Pros: Open Close Principle strictly followed. Adding a command with a parser takes only one line of code. Cons: It is developer responsibility to ensure classes subclass Command object as compile time errors would not be thrown.	Use switches in Parser to match Command Word to create Parser objects if necessary else directly create Command object. Pros: Compile time error would be thrown if new command or parser does not subclass correctly. Cons: Adding a new command with parser would require the developer to insert it into multiple locations as the autocomplete feature needs an iterable command list.
Why did we choose Alternative 1: d
Aspect 2: Single Parser vs Parser Manager	Using a ParserManager to dynamically switch between Parsers based on current state Pros: Commands not belonging to specific mode would not be parsed Cons: More code to write for initial developer. However it is easily extnensible for new modes and parsers by the Open Close Principle	Use a single parser Pros We do not need to restructure the logic package. Cons Bad user experience as it autocompletes and parses commands that do not belong to a particular mode.
Why did we choose Alternative 1: d

3.1.5. Technical details

<Insert class util code demonstrating java reflections>

<Insert where one line of code can be inserted for adding new commands and parsers>

3.2. Settings Feature

3.2.1. Implementation

AppSettings was a class that was created to be integrated into the Model of the app. It currently contains these functionalities:

• difficulty [EASY/MEDIUM/HARD] to change the difficulty of the game.

• hints [ON/OFF] to turn hints on or off.

• theme [DARK/LIGHT] to change the theme of the app. Currently only supporting dark and light themes.

This feature provides the user an interface to make their own changes to the state of the machine. The settings set by the user will also be saved to a .json file under data/appsettings.json.

The activity diagram below summarizes what happens in the execution of a settings command:

Figure 13. Activity diagram of the execution of a settings command.

ℹ️	Take note that "mode" as defined in our project is the state in which the application is able to take commands specific to that mode.

Given below is a step by step walk-through of what happens when a user executes a difficulty command while in settings mode:

Figure 14. Before state of application.

Step 1:
Let us assume that the current difficulty of the application is "EASY". The object diagram above shows the current state of AppSettings.

Figure 15. Sequence diagram of Step 2.

Step 2:
When the user enters difficulty hard, the command gets passed into Ui first, which executes AppManager#execute(), which passes straight to LogicManager#execute() without any logic conditions to determine its execution path.

Figure 16. Sequence diagram of Step 3.

Step 3:
At LogicManager#execute() however, the command gets passed into a parser manager which filters out the DifficultyCommand as a non-switch command and it creates a DifficultyCommand to be executed.

Figure 17. Sequence diagram of Step 4.

Step 4:
Upon execution of the DifficultyCommand, the state of the model is changed such that the DifficultyEnum in AppSettings is now set to HARD.

Figure 18. Sequence diagram of Step 5.

Step 5:
Since the main function of the difficulty command is accomplished and all that is left is to update the ui, the CommandResult that is produced by the execution of the command goes back to Ui without much problem.

Figure 19. Sequence diagram of Step 6.

Step 6:
Assuming that there were no errors thrown during the execution of the difficulty command, the execution calls updateModularDisplay in UpdateUi. In here, the ModeEnum.SETTINGS is registered and it updates the settings display to properly reflect the change in difficulty.

The state of appSettings is then as follows:

Figure 20. After state of application

3.2.2. Design Considerations

There were a few considerations for implementing an interface that essentially allows users to touch a lot of parts of the application through settings and some of these methods break software design principles. These are the considerations we came across:

	Alternative 1	Alternative 2
Aspect 1: Where to effect change when a setting is changed by the user	Effecting the change inside the execute() command of the settings commands: Pros: Since the Command is taking care of all the execution, there is no need to worry about extra implementation of the settings' effects in their classes. Cons: However, there are certain situations that will break software design principles, such as the Single Responsibility Principle by doing the job of already existing classes.	Effecting the change in the part of the architecture that the setting is affecting. E.g, Changing the theme inside Ui or changing the difficulty inside model Pros: This method practises good software engineering principles and it abides by the architecture diagram shown above as to where the changes of the settings are being effected. Cons: This method however requires that the reader gets familiar with the whole architecture diagram as they need to know where to implement the actual change in settings as opposed to creating a new class that performs the same functionality of an existing class.
Why did we choose Alternative 2: We believe that software design principles exist for a reason. Furthermore, while alternative 1 may seem a lot simpler, Alternative 2 allows for extension just by adding new methods and refrains the user from having to extensively rework the structure of the application in order to add a new setting.
Aspect 2: How to store information regarding the different settings	Storing it inside the enumerations that make up the choices for the settings Pros: Having the information stored inside the enum allows for immutablilty, such that no other class can change the properties of the enums. Only the developer can change the values of the enums and it will subsequently affect all the methods and functionality that relies on said enum. Cons: In the case that the user wants to customise certain continuous settings such as time limit, they are unable to as those settings are already defined by the developer to be discrete options.	Storing it inside the classes that implement the settings Pros The information is easily accessible from within the class itself and there is no need for extra import classes to handle the enums in alternative 1. Cons Unlike Alternative 1, the developer can create an extension to the class implementing the setting to allow the user to customise their settings even further, allowing for continuous values to be used rather than discrete values.
Why did we choose Alternative 1: The considerations for this aspect was mainly down to how much customisability we wanted to grant our users. While having more customisability is better in some cases, in this one, we do not think the added functionality of allowing the user to extensively customise their experience with our application to be particularly impactful not necessary. Moreover, alternative 2 makes for a less organised code base and we wanted to avoid that as much as possible.

3.3. Timer-based Features

Figure 21. Screenshot of the Timer component in action.

Figure 22. Screenshot of the automatic Hints feature in action.

3.3.1. Implementation Overview - Timer

The Timer component utilizes the java.util.Timer API to simulate a stopwatch during a Game. It also relies on using Functional Interfaces as callbacks to periodically notify other components in the system. Using callbacks allows the Timer to enact changes in other components of the system without directly holding a reference to those components.

Internally, the Timer works by using the method java.util.Timer.schedule() that will schedule java.util.TimerTasks at a fixed rate.

An Observer Pattern is loosly followed between the Timer and the other components. As opposed to defining an Observable interface, the AppManager simply passes in method pointers into the Timer to callback when an event is triggered. The AppManager thus works closely with the Timer as the main hub to enact changes based on signals given by the Timer.

ℹ️	To avoid synchronization issues with the UI component, all TimerTasks (such as requesting to refresh a component of the UI) are forced to run on the JavaFX Application Thread using Platform.runLater().

Figure 23. Class diagram reflecting how the callback-functions are organized in the Timer component.

The three main events that are currently triggered by the Timer component which require a callback are:

1. Time has elapsed, callback to AppManager to update and display the new timestamp on the UI.

2. Time has run out (reached zero), callback to AppManager to skip over to next Card.

3. Time has reached a point where Hints are to be given to the User, callback to AppManager to retrieve a hint and display accordingly on the UI.

The call-backs for each of these events are implemented as nested Functional Interfaces within the GameTimer interface, which is concretized via the GameTimerManager.

3.3.2. Flow of Events

This section describes the sequential flow of events in the life cycle of a GameTimer object.

Figure 24. Sequence diagram describing the flow of registering and executing callbacks between the different components

The UI component first registers callbacks with the AppManager, who then registers callbacks with the Timer component. Periodically, the Timer will notify the AppManager to perform tasks to notify the UI component. This is to provide better abstraction between the UI and Timer.

A GameTimer instance is created by the AppManager for every Card of a Game. The AppManager provides information regarding the duration in which the Timer should run for, and whether to trigger Hints at the point when a GameTimer instance is created.

3.3.3. Design Considerations

There were a few considerations for designing the Timer this way.

	Alternative 1	Alternative 2
Aspect 1: Where and How to effect changes to the Ui and other components when the Timer triggers an event.	Holding a reference to Ui and other components directly inside GameTimer itself: Pros: Straightforward and direct, can perform many different tasks on the dependent components. Cons: Poor abstraction and high potential for cyclic dependencies, resulting in high coupling.	Using Functional Interfaces as Call-backs to notify components indirectly. Pros: Maintains abstraction and minimal coupling between Timer and other components Cons: Relies on developer to register correct call-back methods with the Timer. Different actions need to be implemented as different call-backs separately. Possible overhead in performing few levels of call-backs.
Why did we choose Alternative 2: To ensure better extendability of our code for future expansion, we felt it was important to maintain as much abstraction between components. This is also to make life easier when there comes a need to debug and resolve problems in the code.

 

3.4. WordBank Features

Dukemon, a flashcard app, requires a non-trivial implementation of a data structure to contain it’s information.
It comes along with a set of commands that either modifies it’s data, or modify the view.
These commands will then synchronise the data in storage, or update the model for viewing.
Lastly, there is a cool drag and drop feature for word banks, to transfer the files into and out of your computer.

Let’s begin by explaining some key terms:

A Card contains a word and a unique meaning. (May contain tags)
CardCommands work on Cards.

A WordBank contains multiple Cards. (May contain tags)
WordBankCommands work on WordBanks.

A WordBankList contains multiple WordBanks.

Each time a CardCommand or WordBankCommand is executed, Storage data is synchronised and Model gets updated automatically for UI to retrieve updated information for user viewing.

 

---

A quick look at Card and WordBank as it is displayed through the UI.

 

Figure 25. CardCommands

 

Figure 26. Cards

 

Figure 27. WordBankCommands

 

Figure 28. WordBanks

 

---

3.4.1. Data Structure Overview

We start from the lowest level - Card.

Figure 29. Class diagram of Card.

A Card contains a unique id, a word, a unique meaning, a set of tags.

id : for statistical tracking
word: answer to the question
meaning: the question that will appear in the game
tags: optional tag to classify cards

ℹ️	Cards with the same meaning are duplicates, and is disallowed.

 

---

Now the second level - WordBank

Figure 30. Class diagram of Word Bank.

A WordBank contains a UniqueCardList and a unique name.

UniqueCardList : prevent duplicate cards
name: unique name of the word bank

ℹ️	Internally, the UniqueCardList contains an observable list of Card. This is so any changes to the cards gets updated in the Model and thus the UI automatically.

 

---

Now the third level - WordBankList

Figure 31. Class diagram of WordBankList.

A WordBankList contains a UniqueWordBankList.

UniqueWordBankList : prevent duplicate word banks

ℹ️	Internally, the UniqueWordBankList contains an observable list of WordBank. This is so any changes to the word banks gets updated in the Model and thus the UI automatically.

In Dukemon, there is should only be one WordBankList, which is created upon Storage initialisation.
Model holds a reference to that specific WordBankList.

---

Figure 32. Entire overview WordBankList.

---

Now the integration - How these data structures are stored in Model and Storage.

Figure 33. Overview class diagram of Storage and Model.

---

3.4.2. Implementation of CardCommands and WordBankCommands

A card command edits the cards within a particular word bank. Therefore it needs to make function calls through the WordBank data structure.
A word bank command edits the word bank within that particular word bank list. Therefore it needs to make function calls through the WordBankList data structure.

To have a better understanding of how these commands work, I will show you how these commands are structured in Logic and then walk you through a Sequence Diagram of executing a particular command.

Figure 34. Overview class diagram of Logic with emphasis on CardCommands and WordBankCommands.

With the understanding of WordBankList data structure, and how the Commands are structured within Logic, I will now take you through what happens when a Command is called.
For instance, CreateCommand:

Figure 35. Sequence diagram describing the updating of WordBankList using WordBankCommand through different components

We will see the case where the input: "create bank1" is valid.

1. It gets parsed by the ParserManager. Depending on the input, a specific Command is returned. In this case, a CreateCommand object is instantiated.

2. Depending on the type of Command object, execute() performs slightly different tasks. In this case, the execute method of CreateCommand checks in Model to see if the WordBank currently already exist.

3. Relevant information is stored in CreateCommandResult and is returned back to LogicManager.

4. With the retrieved information and type of CommandResult, commandResult updates the storage through it’s method.

5. The Storage abstracts away details and contains well-written methods, each to handle different cases of CommandResult. In this case, createWordBank is called.

6. JsonWordBankListStorage contains the abstracted details of how a commandResult should be handled. For a CreateCommandResult, addWordBank and saveWordBank is called.

7. In addWordBank method, it simply adds to the only WordBankList in the entire app. This WordBankList is the same instance as referenced by Model.

8. In saveWordBank method, an even lower level saveJsonFile function is called to write to the disk. This is performed through the common class: JsonUtil.

9. In addWordBank method, it simply adds to the only WordBankList in the entire app. This WordBankList is the same instance as referenced by Model.

10. It returns void all the way back to LogicManager, and then success message is then passed back to AppManager, then to the UI to notify the user.

---

3.4.3. Drag and drop feature and it’s implementation.

As much as a pro CLI user would love to type all the commands, I figured a good old drag and drop feature will save the user lots of time.
It aims to streamline the process of sharing word banks with friends.

Figure 36. Screenshot showing drag and drop steps

Figure 37. Screenshot showing drag and drop steps

From HOME mode, you can view WordBank, then simply drag and drop a WordBank, out of the application, into say, your desktop, or chat applications.
From your computer, simply drag and drop a WordBank json file into Dukemon’s HOME page.

With the well designed WordBankList data structure and it’s functions, drag and drop feature is simply an import and export function call, linked by the JavaFX’s UI drag detection and drag dropped methods.

---

3.4.4. Design Considerations

	Alternative 1	Alternative 2
Aspect 1: Data structure for WordBankList.	Although WordBankList and WordBank have very similar structures, I made classes for each of them they each contain a unique list: Pros: User’s modification to their word banks and cards requires very different methods. These two data structure requires different access to the storage as well. With two different classes, implementation of the Commands that work on these data becomes more distinct. This ensures methods within WordBankList are written for WordBankCommands and methods within WordBank are written for CardCommands, thereby increasing cohesion of individual components and decreasing coupling between the two classes. Cons: Implementation requires much more effort.	Create a generic data structure class, and let both WordBankList and WordBank extend it. Pros: Code that are reusable in WordBank can now be reused for WordBankList. Cons: This couples WordBank with WordBankList. Does not follow the Open-Closed principle.
Why did we choose Alternative 1: Following the spirit of software engineering principles, it is better to have the basic data structure implemented well. Commands that depend on it becomes much easier to implement. (This can be seen in the drag and drop feature.)

	Alternative 1	Alternative 2
Aspect 2: Storage system for Word Banks.	One single large json file with word bank names as keys and it’s word bank data as values: Pros: Always save a snapshot of the data to the same file, regardless of what commands are executed. Cons: Unable to share word banks with friends, because one file contains all the word banks.	In the default data folder, each word bank is stored as a json file. Pros: Enables sharing of word bank files to friends. Cons: Require more consideration to deal with different type of commands which affects the storage dynamically. Harder to read from multiple files.
Why did we choose Alternative 2: This choice was based largely from the user’s perspective. As our app is designed to streamline learning, I figured that easy sharing of word banks file with friends is an important aspect in our app, and cannot be compromised.

	Alternative 1	Alternative 2
Aspect 3: Command implementation. (Same goes for Command Result implementation)	All types of commands extends a single abstract class Command: Pros: A rather simple implementation which does not break any software engineering principles. Cons: Can be further improved, as in Alternative 2.	Distinguishing WordBankCommand and CardCommand specifically - Commands that work on Cards extends the abstract CardCommand class and commands that work on WordBank extends the abstract WordBankCommand class. Pros: As I have created distinct data structure for WordBankList and WordBank, distinguished commands now work solely on their respective data structure. It follows the Single Responsibility Principle and the Separation of Concerns Principle more closely, and decreases the coupling between the two component. Cons: Requires tedious implementation to follow the principles.
Why did we choose Alternative 2: Alternative 2 allows for easy extension of the app’s functionality. Implementation of the drag and drop feature is just a function call away, as all data structure and functions are well written.

3.5. Statistics features

3.5.1. Implementation

The work of the Statistics component can be neatly captured and explained using a common series of user actions when operating the app.

User action	Statistics work	UI Statistics updates
User opens the app.	User’s GlobalStatistics and WordBankStatisticsList are loaded into Model by the MainApp.	User is shown their GlobalStatistics and their most played word bank from the WordBankStatisticsList in the main title page.
User selects a word bank.	The selected WordBankStatistics from the WordBankStatisticsList is loaded into Model.
User opens the selected word bank.		In open mode, User is shown the WordBankStatistics of the opened word bank.
User plays the game.	A GameStatisticsBuilder is used to record user actions during the game.
User finishes the game.	A GameStatistics is created from the GameStatisticsBuilder. The WordBankStatistics and GlobalStatistics are updated accordingly and saved to disk.	GameStatistics and the corresponding WordBankStatistics are displayed to user in the game result page.

We will discuss each step with its implementation details primarily on the statistics work.

1. User opens the app

When the user opens the app, their GlobalStatistics and WordBankStatisticsList are loaded into Model by MainApp.

Figure 38. Sequence diagram for loading statistics

2. User selects a word bank

When the user selects a word bank, the selected WordBankStatistics from the WordBankStatisticsList is loaded into Model.

Figure 39. Sequence diagram for selecting a word bank statistics.

It is necessary to set the active WordBankStatistics in the Model such that when the user opens the WordBank, the WordBankStatistics can be found in Model and shown in the UI.

3. User opens the selected word bank

In open mode, the user is shown the WordBankStatistics of the opened word bank, which is set in Model at step 2.

4. User plays the game

A GameStatisticsBuilder is used to record user actions during the game.

When the user starts the game by calling a StartCommand, the GameStatisticsBuilder is initialized.

Figure 40. Sequence diagram when user starts a game.

During the game, the GameStatisticsBuilder is updated with every GuessCommand or SkipCommand made. It receives the timestamp from the GameTimer which also resides in AppManager.

Figure 41. Sequence diagram when user makes a guess.

5. User finishes the game

When the user finishes the game, a GameStatistics is created from the GameStatisticsBuilder. The GameStatistics is shown to the user in the game result page.

The GameStatistics is used to update its corresponding WordBankStatistics, which is then saved to disk. Additionally, the GlobalStatistics is also updated and saved to disk.

Figure 42. Sequence diagram for saving the statistics to disk.

3.5.2. Design Considerations

There were some design considerations on implementing the statistics.

	Alternative 1	Alternative 2
Aspect 1: How to store WordBankStatistics in the storage?	Store in a separate file from the WordBank json file, but with the same name in a different directory. Example: WordBank data is stored at data/wordbanks/pokemon.json while the WordBankStatistics data is stored at data/wbstats/pokemon.json Pros: More abstraction to separate the data. Cons: The data is linked by name, so if the user changes the file name, the link is broken.	Store WordBankStatistics data in the same file as WordBank Pros: Less number of files. Cons: Data is combined into one which lowers abstraction.
Why we decided to choose Alternative 1: We decided that abstraction between the data is important as each team member should work in parallel, such that it is easier for one person to modify the storage system for the word bank and another person to modify the storage system for the word bank statistics freely.

3.6. [Proposed] Data Encryption

{Explain here how the data encryption feature will be implemented}

3.7. [Proposed] User Profiles

The user profiles could allow multiple users to use the same app and have different statistics tracked. This feature is a work in progress and will be delayed to v2.0.

3.8. Logging

We are using java.util.logging package for logging. The LogsCenter class is used to manage the logging levels and logging destinations.

• The logging level can be controlled using the logLevel setting in the configuration file (See Section 3.9, “Configuration”)

• The Logger for a class can be obtained using LogsCenter.getLogger(Class) which will log messages according to the specified logging level

• Currently log messages are output through: Console and to a .log file.

Logging Levels

• SEVERE : Critical problem detected which may possibly cause the termination of the application

• WARNING : Can continue, but with caution

• INFO : Information showing the noteworthy actions by the App

• FINE : Details that is not usually noteworthy but may be useful in debugging e.g. print the actual list instead of just its size

3.9. Configuration

Certain properties of the application can be controlled (e.g user prefs file location, logging level) through the configuration file (default: config.json).

4. Documentation

Refer to the guide here.

5. Testing

Refer to the guide here.

6. Dev Ops

Refer to the guide here.

Appendix A: Product Scope

Target user profile:

• students

• wants to learn new English words or definitions

• can type fast

• enjoys games

• is reasonably comfortable using CLI apps

Value proposition: gamify learning experiences

Appendix B: User Stories

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

Priority	As a …​	I want to …​	So that I can…​
* * *	teacher	add, edit, and delete questions in the word banks	make corrections on what my students are supposed to learn
* * *	teacher	give customised word banks and definitions	can let my students practice specific problems.
* * *	user	list all my word banks
* * *	user	give titles to word banks	recognise them better
* * *	user	delete word banks	free up some memory when I don’t need it anymore
* * *	user	see the content of the word bank	study beforehand/make changes
* * *	young student	trivia questions to be gamified	enjoy the process
* * *	student	create my own question banks	tailor fit to my learning
* * *	computer science student	have a manual of the commands available	refer to them when I am lost
* *	frequent user	easily access my most recently attempted question sets	can quickly resume my revision
* *	studious student	set and complete goals	have something to work towards
* *	student	see my test statistics	track my progress/improvement
* *	student	choose different kinds of time constraints	can simulate exam conditions
* *	student	categorise my question sets	easily look for relevant materials
* *	student	mark question sets as important/urgent	know how to prioritise my revision
* *	module coordinator	export lessons	send to their students
* *	student	share and compare my results with my classmates	know where I stand
* *	student	partition the trivia	attempt questions that I’m comfortable with
* *	weak student	have the option to see hints	won’t get stuck all the time
* *	computer science student	practise typing bash commands into the CLI	strengthen my bash skills
* *	teacher	export statistics	can compare performance across different students
*	computer science student	customize my “terminal”	changing themes/ background/ font size/ font colour, so that I feel comfortable working on it
*	teacher	protect tests with passwords	let my students do them in lessons together when password is released
*	teacher	protect the files	doesn’t get tampered when distributing to students
*	student	have smaller sized files	have more space on my computer

{More to be added}

Appendix C: Use Cases

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

Use case: Delete person

MSS

1. User requests to list persons

2. Dukemon shows a list of persons

3. User requests to delete a specific person in the list

4. Dukemon deletes the person

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

• 3a. The given index is invalid.

  • 3a1. Dukemon shows an error message.

    Use case resumes at step 2.

{More to be added}

Appendix D: Non Functional Requirements

1. Should work on any mainstream OS as long as it has Java 11 or above installed.

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

3. Users can export and import their word banks or statistics.

{More to be added}

Appendix E: Glossary

Mainstream OS

Windows, Linux, Unix, OS-X

Private contact detail

A contact detail that is not meant to be shared with others

Word Bank

A list of word-description pair that either the user can create himself or import from.

Appendix F: Product Survey

Product Name

Author: …​

Pros:

• …​

• …​

Cons:

• …​

• …​

Appendix G: Instructions for Manual Testing

Given below are instructions to test the app manually.

ℹ️	These instructions only provide a starting point for testers to work on; testers are expected to do more exploratory testing.

G.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 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 double-clicking the jar file.
      Expected: The most recent window size and location is retained.

{ more test cases …​ }

G.2. Deleting a person

1. Deleting a person while all persons are listed

   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) {give more}
      Expected: Similar to previous.

{ more test cases …​ }

G.3. Saving data

1. Dealing with missing/corrupted data files

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

{ more test cases …​ }