CareBook Developer Guide

---

Acknowledgements

Some of CareBook features are adapted from the AddressBook-Level3 project created by the SE-EDU initiative. As such, CareBook contains some of the code and documentation from AddressBook-Level3.

The list of third-party libraries used are: JavaFX, Jackson, JUnit5

---

Setting up, getting started

Refer to the guide Setting up and getting started.

---

Design

Architecture

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

Given below is a quick overview of main components and how they interact with each other.

Main components of the architecture

Main (consisting of classes Main and MainApp) is in charge of the app launch and shut down.

• At app launch, it initializes the other components in the correct sequence, and connects them up with each other.
• At shut down, it shuts down the other components and invokes cleanup methods where necessary.

The bulk of the app's work is done by the following four components:

• UI: The UI of the App.
• Logic: The command executor.
• Model: Holds the data of the App in memory.
• Storage: Reads data from, and writes data to, the hard disk.

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

How the architecture components interact with each other

The Sequence Diagram below shows how the components interact with each other for the scenario where the user issues the command delete A10A.

Each of the four main components (also shown in the diagram above),

• defines its API in an interface with the same name as the Component.
• implements its functionality using a concrete {Component Name}Manager class (which follows the corresponding API interface mentioned in the previous point.

For example, the Logic component defines its API in the Logic.java interface and implements its functionality using the LogicManager.java class which follows the Logic interface. Other components interact with a given component through its interface rather than the concrete class (reason: to prevent outside component's being coupled to the implementation of a component), as illustrated in the (partial) class diagram below.

The sections below give more details of each component.

UI component

The API of this component is specified in Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, StudentListPanel, StatusBarFooter etc. All these, including the MainWindow, inherit from the abstract UiPart class which captures the commonalities between classes that represent parts of the visible GUI.

The UI component uses the JavaFx UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the MainWindow is specified in MainWindow.fxml

The UI component,

• executes user commands using the Logic component.
• listens for changes to Model data so that the UI can be updated with the modified data.
• keeps a reference to the Logic component, because the UI relies on the Logic to execute commands.
• depends on some classes in the Model component, as it displays Student object residing in the Model.

Logic component

API : Logic.java

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

The sequence diagram below illustrates the interactions within the Logic component, taking execute("delete A10A") 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., DeleteStudentCommandParser) 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., DeleteStudentCommand) which is executed by the LogicManager.
3. The command can communicate with the Model when it is executed (e.g. to delete a student).
   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., AddStudentCommandParser, DeleteStudentCommandParser, ...) inherit from the Parser interface so that they can be treated similarly where possible e.g, during testing.

Model component

API : Model.java

The Model component,

• stores the CareBook data i.e., all Student objects (which are contained in a UniqueStudentList object).
• stores the currently 'selected' Student objects (e.g., results of a search query) as a separate filtered list which is exposed to outsiders as an unmodifiable ObservableList<Student> that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change.
• stores a UserPref object that represents the user’s preferences. This is exposed to the outside as a ReadOnlyUserPref objects.
• does not depend on any of the other three components (as the Model represents data entities of the domain, they should make sense on their own without depending on other components)

Storage component

API : Storage.java

The Storage component,

• can save both CareBook data and user preference data in JSON format, and read them back into corresponding objects.
• inherits from both AddressBookStorage and UserPrefStorage, which means it can be treated as either one (if only the functionality of only one is needed).
• depends on some classes in the Model component (because the Storage component's job is to save/retrieve objects that belong to the Model)

Common classes

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

---

Implementation

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

Add a Student

Logic Classes:

• AddStudentCommand.java
• AddStudentCommandParser.java

AddStudentCommandParser parses the input entered by user before executing AddStudentCommand to add a student to Model

This is illustrated in the activity diagram below:

• isValidPhone ensures that phone number is exactly 8 digits and begin with either 6, 8 or 9.
• isValidEmail ensures that email has the @ domain.
• isUniqueId ensures that is unique.
• isValidParentName and isValidStudentName both ensure that they only contain alphanumeric characters

If all the above conditions are satisfied, the student is added to the model.

Export Student Records

Logic Classes:

• ExportCommand.java
• ExportCommandParser.java

ExportCommandParser parses the input entered by user before executing ExportCommand to export student name, parent name, student ID, parent email, parent phone number and attendance history of all students in Model.

This is illustrated in the activity diagram below:

• isValidFileName ensures that fileName only contains alphanumeric characters or underscore.
• isValidFileLength ensures that fileName does not exceed 100 characters.

If all the above conditions are satisfied, export command will be successfully executed and a .csv file will be created in directory where carebook.jar file is placed.

Delete a Student

Logic Classes:

• DeleteStudentCommand.java
• DeleteStudentCommandParser.java

DeleteStudentCommandParser parses the input entered by user before executing DeleteStudentCommand to delete a student from Model

• isValidId ensures that the studentId entered already exists in CareBook

If the above condition is satisfied, delete student command will be successfully executed.

Find a Student

Logic classes:

• FindStudentCommand.java
• FindStudentCommandParser.java

• isValidId ensures that the studentId entered already exists in CareBook

If the above condition is satisfied, find student command will be successfully executed.

FindStudentCommandParser parses the input entered by user before executing FindStudentCommand to find a student from Model

---

Documentation, logging, testing, configuration, dev-ops

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

---

Appendix: Requirements

Product scope

Target user profile:

• Daycare teacher managing daily rosters of 30 to 40 students (aged 1 to 12)
• Prefers desktop apps over other types
• Can type fast
• Prefers typing to mouse interactions
• Is reasonably comfortable using CLI apps

Value proposition: CareBook helps daycare teachers manage classroom and parent communication by providing instant CLI access to students' information and streamlining repetitive tasks like daily attendance and maintaining student records.

User stories

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

Use cases

(For all use cases below, the System is the CareBook and the Actor is the Daycare Teacher, unless specified otherwise.)

Use case: UC1 - Add a New Student

MSS

1. User requests to add a student.

2. CareBook validates student details (student name, parent name, student ID, phone number, email address and address).

3. CareBook adds the new student.

4. CareBook confirms successful addition.

   Use case ends.

Extensions

• 2a. CareBook detects an invalid student name, parent name, student ID, phone number, email address, or address.

  • 2a1. CareBook displays an error message.

    Use case resumes from step 1.

• 2b. CareBook detects a duplicate student ID.

  • 2b1. CareBook displays an error message.

    Use case resumes from step 1.

• 2c. CareBook detects an incorrect command format or unknown command.

  • 2c1. CareBook displays an error message.

    Use case resumes from step 1.

Use case: UC2 - Edit a Student

MSS

1. User requests to edit a student with new details by using student ID.

2. CareBook verifies that the student exists.

3. CareBook updates the student with the new details.

4. CareBook confirms successful edit.

   Use case ends.

Extensions

• 2a. CareBook detects an invalid student ID or is unable to find student ID.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

• 2b. CareBook detects an incorrect command format or unknown command.

  • 2b1. CareBook displays an error message.

    Use case resumes at step 1.

Use case: UC3 - Delete a Student

MSS

1. User requests to delete a student by student ID.

2. CareBook verifies that the student exists.

3. CareBook removes the student.

4. CareBook confirms successful removal.

   Use case ends.

Extensions

• 2a. CareBook detects an invalid student ID or is unable to find student ID.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

• 2b. CareBook detects an incorrect command format or unknown command.

  • 2b1. CareBook displays an error message.

    Use case resumes at step 1.

Use case: UC4 - View All Students

MSS

1. User requests to list all students.

2. CareBook displays a list of all students.

   Use case ends.

Extensions

• 2a. CareBook detects an empty list of students.

  • 2a1. CareBook displays an error message.

    Use case ends.

Use case: UC5 - Find a Student by Student ID

MSS

1. User requests to find a student by student ID.

2. CareBook verifies that the student exists.

3. CareBook retrieves the student’s details.

4. CareBook displays the student’s information.

   Use case ends.

Extensions

• 2a. CareBook detects an invalid student ID or is unable to find student ID.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

• 2b. CareBook detects an incorrect command format or unknown command.

  • 2b1. CareBook displays an error message.

    Use case resumes at step 1.

Use case: UC6 - Mark a Student Attendance as Present

MSS

1. User requests to mark a student as present by student ID.

2. CareBook verifies that the student exists.

3. CareBook updates the attendance record for that student.

4. CareBook confirms that the student has been marked present.

   Use case ends.

Extensions

• 2a. CareBook detects an invalid student ID, is unable to find student ID, or finds that the student is already marked as present.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

• 2b. CareBook detects an incorrect command format or unknown command.

  • 2b1. CareBook displays an error message.

    Use case resumes at step 1.

Use case: UC7 - Mark a Student Attendance as Absent

MSS

1. User requests to mark a student as absent by student ID.

2. CareBook verifies that the student exists.

3. CareBook updates the attendance record for that student.

4. CareBook confirms that the student has been marked absent.

   Use case ends.

Extensions

• 2a. CareBook detects an invalid student ID, is unable to find student ID, or finds the that student is already marked as absent.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

• 2b. CareBook detects an incorrect command format or unknown command.

  • 2b1. CareBook displays an error message.

    Use case resumes at step 1.

Use case: UC8 - Clear All Students

MSS

1. User requests to clear all students.

2. CareBook clears all students.

   Use case ends.

Use case: UC9 - View the Instruction Guide

MSS

1. User requests for help.

2. CareBook displays a list of all commands, their respective parameters, and an example of usage.

   Use case ends.

Use case: UC10 - Mark All Students Attendance as Present

MSS

1. User requests to mark all students as present.

2. CareBook updates the attendance record for every student as present.

3. CareBook confirms that all students have been marked present.

   Use case ends.

Extensions

• 2a. CareBook detects an empty list of students.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

Use case: UC11 - Mark All Students Attendance as Absent

MSS

1. User requests to mark all students as absent.

2. CareBook updates the attendance record for every student as absent.

3. CareBook confirms that all students have been marked absent.

   Use case ends.

Extensions

• 2a. CareBook detects an empty list of students.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

Use case: UC12 - Export All Students Information

MSS

1. User requests to export all students information with a filename.

2. CareBook saves all students information into the directory where the CareBook application is located.

   Use case ends.

Extensions

• 2a. CareBook detects an invalid filename.

  • 2a1. CareBook displays an error message.

    Use case resumes at step 1.

• 2b. CareBook detects an empty list of students.

  • 2b1. CareBook displays an error message.

    Use case resumes at step 1.

Non-Functional Requirements

1. Should work on any mainstream OS as long as it has Java 17 or above installed.
2. Should be able to hold up to 50 students without a noticeable sluggishness in performance for typical usage.
3. System does not take more than 1s to load all data from files when launching.
4. All commands execute in less than 1s, including saving of data to files.
5. 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.
6. Commands should be intuitive and easy to remember.
7. Data should be saved after each change-causing command.
8. Error messages should offer support to user (help user get the right commands).
9. The app should not require complex installation steps.
10. It should be a lightweight application (<100MB) and not require additional dependencies beyond Java.

Glossary

• Command: An instruction entered by the Daycare Teacher into the CareBook system to perform a specific action (e.g., "add", "delete", "find", "list", "mark", "help").
• Command Format: The required structure and syntax for a command, including any necessary parameters (e.g., "add <sn/StudentName> <id/StudentId> <pn/ParentName> <p/Phone> <e/Email> <a/Address>" for adding a student).
• Daycare Teacher: The primary user of the CareBook application, responsible for managing student records and attendance.
• Mainstream OS: Windows, Linux, Unix, MacOS
• Private contact detail: A contact detail that is not meant to be shared with others
• Student Record: A set of data representing a student's personal information, including details like student ID, name, parent contact, and attendance.
• Validation: The system’s process of checking that entered data (e.g., Student ID, ParentPhoneNumber) meets predefined rules before accepting it.

---

Appendix: Instructions for manual testing

Given below are instructions to test the app manually.

Launch and shutdown

1. Initial launch

   1. Download the CareBook.jar file and copy into an empty folder
      
      
   2. Ensure you have Java 17 or above installed in your computer.
      
      
   3. Open a command terminal, cd into the folder you placed your .jar file and type java -jar CareBook.jar and press enter to run CareBook application.
      Expected:
      • Shows the GUI with a set of sample students.
      • 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 typing java -jar CareBook.jar and pressing enter.
      Expected:
      • The most recent window size and location is retained.
        
        

3. Verifying Logs during launch

   1. Launch the app by typing java -jar CareBook.jar and pressing enter.
      
      
   2. Observe the logs printed in the terminal during startup.
      Expected:
      • Logs should be displayed with appropriate timestamps.
      • Warnings about JavaFX configuration may appear but should not affect functionality.

Deleting a student

1. Deleting a student while all students are being shown

   1. Prerequisites: List all students using the list command. Multiple students in the list.
      
      
   2. Test case: delete A10A
      Expected:
      • Student with ID A10A 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 A99Z
      Expected:
      • No student is deleted. Error details shown in the status message. Status bar remains the same.
        
        
   4. Other incorrect delete commands to try: delete, delete a10, ... (where student ID is invalid).
      Expected:
      • Similar to previous.
        
        

2. Deleting a Student When No Students Are Displayed

   1. Prerequisites: Clear the list using the clear command.
      
      
   2. Test case: delete A99Z
      Expected:
      • No student is deleted. Error details shown in the status message. Status bar remains the same.

Saving data

1. Dealing with missing data files

   1. Navigate to the application's data directory.
      
      
   2. Delete or rename the data file (e.g., carebook.json).
      
      
   3. Launch the app. Expected:
      • The application should create a new default data file if one does not exist.
      • The list of students should contain default sample student data.
      • A warning message (e.g., “Creating a new data file data\carebook.json populated with a sample CareBook.”) should be logged.
        
        

2. Dealing with corrupted data files

   1. Navigate to the application's data directory and open carebook.json in a text editor.
      
      
   2. Modify the content to be invalid JSON (e.g., remove a closing brace or change a key name to an invalid format).
      
      
   3. Save the file and launch the app. Expected:
      • The application should detect the corruption and handle it.
      • A warning message (e.g., "WARNING: Error reading from jsonFile file data\carebook.json: ...") should be logged.
      • The app will launch with an empty student list.
      • The application should not crash and should remain functional.
        
        

3. Ensuring data is saved after adding/deleting a student

   1. Launch the app and modify the data by adding/deleting a student.
      
      
   2. Close the application and re-open it. Expected:
      • The added/deleted student should appear/not appear in the list.

Appendix: Effort

1. Difficulty Level and Challenges Faced

   Our project builds on AddressBook Level 3 (AB3) but required significant refactoring to better fit our target users' needs. As a result, the complexity of data management, validation, and UI representation increased.
   
   Key challenges included:

   • Extensive refactoring: From person model to student model.
   • Editing and updating test cases: Ensuring existing test cases remained valid after structural changes while writing new ones for added functionalities.
   • Maintaining code consistency: Ensuring that refactored components integrated smoothly without introducing regressions.
     
     

2. Effort Required

   The project effort was distributed across key areas:
   

   • Feature Development (45%) – Modifying existing commands and implementing new commands (e.g. mark, markall, export).
   • Testing & Debugging (30%) – Updating test cases, refactoring test structure, and ensuring correctness after modifications.
   • Data Management & Storage (25%) – Modifying JSON storage to handle new fields in Student model.
     
     

3. Achievements

   • Successfully modified AB3 to align with our target users' needs while maintaining its core functionality.
   • Refactored the codebase effectively, improving maintainability and extensibility.

Appendix: Planned Enhancements

Team members (count): 5

1. Improve UI (Main Window and Find Window) for long names and addresses: When dealing with long name and addresses, CareBook truncates these values in both the main and find window. Furthermore, find window cannot be resized. To improve this in the future, we would make the UI display long name and address values and make find window resizable.

2. Modify edit command to detect changes: When editing student contact, CareBook does not recognise that no changes are made and edit command is allowed to go through without throwing an error. For future improvements, we would make changes such that edit command will detect no changes are being made and throw an error.

3. Modify UI to display student name and studentId in sorted order: When adding new students, student that has just been added will appear at the bottom of the UI display. This makes it hard for users to track their students. For future improvements, we would implement a comparator class to sort students by their student ID.

4. Modify export command to export student records to different file types and different directories: When exporting student records, the exported file is automatically saved as a .csv file to the current directory of carebook.jar file. When user tries to copy and paste records from .csv file to file types like excel, there is a slight formatting issue. For future improvements, we would implement a method to allow users to export to a different file type and directory of their choice.

5. Modify add command to allow names with special characters: Currently, users can only add student and parent names that consist of alphanumeric characters and space. For future improvements, we plan to allow users to add names with special characters like @, / or names in different languages (e.g. Arabic, Chinese).

6. Modify add command to validate that email contains a period: Currently, users can enter emails that do not contain a period in the domain (e.g. a@bc). For future improvements, we plan to enhance email validation by ensuring that the domain part of the email contains at least one period (e.g. example.com) to better reflect real-world email formats.

7. Automatically refresh attendance records on a new date: Currently, users need to trigger a refresh to update the attendance records on a new date. When a user is working on this app at late night, past 12am, the date will change, hence they will have to manually refresh the data using commands like list. For further improvement, we plan to automatically detect a date change while the app is running, and refresh the attendance records without user-triggered actions.

8. Modify clear command to clear attendance record only: Currently, attendance records accumulate over time with no option to delete them, making it difficult for users to manage large volumes of data. For future improvements, we would allow users to clear only the attendance records in CareBook.

9. Modify find command to search using student name: Currently, the searches for students using their student ID. We plan to modify it to also accept student names, allowing users to quickly locate a student's information by name, which will be useful in emergency situations.

10. Modify list command to display only present or absent students: Currently, the list command displays all the students. As a future improvements, we plan to allow users to either list the present or absent students, to make it easier to identify which students are not present.