Developer Guide

• Acknowledgements
• Setting up, getting started
• Design
  • Architecture
  • UI component
  • Logic component
  • Model component
  • Storage component
  • Common classes
• Implementation
  • NRIC validation feature
    • Context
    • Where validation happens
    • Checksum algorithm
    • Design considerations
    • Tests
  • [Proposed] Undo/redo feature
    • Proposed Implementation
    • Design considerations:
  • [Proposed] Data archiving
    • Proposed Implementation
    • Design considerations:
  • [Proposed] Automated Appointment Reminders
    • Proposed Implementation
• Documentation, logging, testing, configuration, dev-ops
• Appendix: Requirements
  • Product scope
  • User stories
  • Use cases
  • Non-Functional Requirements
  • Glossary
• Appendix: Instructions for manual testing
  • Launch and shutdown
  • Deleting a patient
  • Saving data
• Appendix: Planned Enhancements

---

Acknowledgements

• AddressBook-Level3 (AB3): The original source code for this application was adapted from the AddressBook-Level3 project created by the SE-EDU initiative.
• NRIC Checksum: Introduce documentation for NRIC checksum. Link
• JavaFX: Used for the Graphical User Interface (GUI). Link
• JUnit5: Used for the unit testing framework. Link
• PlantUML: Used to generate the diagrams in this documentation. Link
• Icons: PNG Icons from ICONPACKS

---

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

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

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

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

The sections below give more details of each component.

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, PatientListPanel, 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 Patient 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 1") API call as an example.

How the Logic component works:

1. When Logic is called upon to execute a command, it is passed to an AddressBookParser object which in turn creates a parser that matches the command (e.g., DeleteCommandParser) and uses it to parse the command.
2. This results in a Command object (more precisely, an object of one of its subclasses e.g., DeleteCommand) which is executed by the LogicManager.
3. The command can communicate with the Model when it is executed (e.g. to delete a patient).
   Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and the Model) to achieve.
4. The result of the command execution is encapsulated as a CommandResult object which is returned back from Logic.

Here are the other classes in Logic (omitted from the class diagram above) that are used for parsing a user command:

How the parsing works:

• When called upon to parse a user command, the AddressBookParser class creates an XYZCommandParser (XYZ is a placeholder for the specific command name e.g., AddCommandParser) which uses the other classes shown above to parse the user command and create a XYZCommand object (e.g., AddCommand) which the AddressBookParser returns back as a Command object.
• All XYZCommandParser classes (e.g., AddCommandParser, DeleteCommandParser, …) inherit from the Parser interface so that they can be treated similarly where possible e.g, during testing.

Model component

API : Model.java

The Model component,

• stores the address book data i.e., all Patient objects (which are contained in a UniquePatientList object).
• stores the currently ‘selected’ Patient objects (e.g., results of a search query) as a separate filtered list which is exposed to outsiders as an unmodifiable ObservableList<Patient> 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 address book data and user preference data in JSON format, and read them back into corresponding objects.
• inherits from both AddressBookStorage and UserPrefStorage, which means it can be treated as either one (if only the functionality of only one is needed).
• depends on some classes in the Model component (because the Storage component’s job is to save/retrieve objects that belong to the Model)

Common classes

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

---

Implementation

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

NRIC validation feature

Context

NRIC/FIN is a core patient identifier and must be validated strictly. The app validates NRIC in two layers:

1. Structure check: first letter + seven digits + checksum letter.
2. Checksum check: Singapore NRIC/FIN modulus-11 checksum, including prefix-specific letter tables.

This prevents malformed or checksum-invalid NRIC values from entering the model.

Where validation happens

Validation is centralized in Nric (model), instead of being duplicated in parser/storage:

• AddCommandParser and EditCommandParser parse the ic/ value and construct Nric.
• JsonAdaptedPatient also constructs Nric during JSON deserialization.
• Nric#isValidNric(String) is therefore the single source of truth for all input paths.

This design guarantees consistent behavior for CLI input, test fixtures, and persisted data loading.

Checksum algorithm

For an NRIC/FIN value with prefix P, digits d1..d7, and suffix letter L:

1. Compute weighted sum using weights [2, 7, 6, 5, 4, 3, 2].
2. Add prefix offset:
   • +4 for T and G
   • +3 for M
   • +0 for S and F
3. Compute remainder = sum mod 11.
4. Compute checkDigit = 11 - (remainder + 1).
5. Map checkDigit to letter table based on prefix group:
   • S/T -> ABCDEFGHIZJ
   • F/G -> KLMNPQRTUWX
   • M -> KLJNPQRTUWX

NRIC is valid only if computed suffix letter equals L.

Design considerations

Aspect: location of checksum logic

• Alternative 1 (chosen): keep checksum logic in Nric.
  • Pros: one validation implementation across parser, model, and storage.
  • Cons: parser tests must use checksum-valid NRIC fixtures.
• Alternative 2: validate in parser only.
  • Pros: simpler parser flow.
  • Cons: invalid values could still enter through storage or future non-parser paths.

Tests

NRIC behavior is covered by:

• NricTest: constructor guardrails, normalization, format checks, checksum-valid and checksum-invalid cases.
• AddCommandParserTest: invalid NRIC parsing failures.
• JsonAdaptedPatientTest: invalid NRIC in JSON rejected during conversion.

In addition, shared test fixtures (e.g., TypicalPatients, PatientBuilder) use checksum-valid NRIC values to avoid false failures.

[Proposed] Undo/redo feature

Proposed Implementation

The proposed undo/redo mechanism is facilitated by VersionedAddressBook. It extends AddressBook with an undo/redo history, stored internally as an addressBookStateList and currentStatePointer. Additionally, it implements the following operations:

• VersionedAddressBook#commit()— Saves the current address book state in its history.
• VersionedAddressBook#undo()— Restores the previous address book state from its history.
• VersionedAddressBook#redo()— Restores a previously undone address book state from its history.

These operations are exposed in the Model interface as Model#commitAddressBook(), Model#undoAddressBook() and Model#redoAddressBook() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionedAddressBook will be initialized with the initial address book state, and the currentStatePointer pointing to that single address book state.

Step 2. The user executes delete 5 command to delete the 5th patient in the address book. The delete command calls Model#commitAddressBook(), causing the modified state of the address book after the delete 5 command executes to be saved in the addressBookStateList, and the currentStatePointer is shifted to the newly inserted address book state.

Step 3. The user executes add n/David …​ to add a new patient. The add command also calls Model#commitAddressBook(), causing another modified address book state to be saved into the addressBookStateList.

Step 4. The user now decides that adding the patient was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoAddressBook(), which will shift the currentStatePointer once to the left, pointing it to the previous address book state, and restores the address book to that state.

The following sequence diagram shows how an undo operation goes through the Logic component:

Similarly, how an undo operation goes through the Model component is shown below:

The redo command does the opposite — it calls Model#redoAddressBook(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the address book to that state.

Step 5. The user then decides to execute the command list. Commands that do not modify the address book, such as list, will usually not call Model#commitAddressBook(), Model#undoAddressBook() or Model#redoAddressBook(). Thus, the addressBookStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitAddressBook(). Since the currentStatePointer is not pointing at the end of the addressBookStateList, all address book states after the currentStatePointer will be purged. Reason: It no longer makes sense to redo the add n/David …​ command. This is the behavior that most modern desktop applications follow.

The following activity diagram summarizes what happens when a user executes a new command:

Design considerations:

Aspect: How undo & redo executes:

• Alternative 1 (current choice): Saves the entire address book.
  • Pros: Easy to implement.
  • Cons: May have performance issues in terms of memory usage.
• Alternative 2: Individual command knows how to undo/redo by itself.
  • Pros: Will use less memory (e.g. for delete, just save the patient being deleted).
  • Cons: We must ensure that the implementation of each individual command are correct.

[Proposed] Data archiving

The proposed data archiving feature allows doctors to move inactive or deceased patients from the active patient list to an archive. This reduces visual clutter and improves performance while retaining historical records.

Proposed Implementation

The archiving mechanism will be facilitated by adding an ArchiveBook to the Model, functioning similarly to the AddressBook.

• An archive PATIENT_INDEX command will be added.
• Model will be extended with Model#archivePatient(Patient) and Model#unarchivePatient(Patient).
• When a patient is archived, they are removed from the active UniquePatientList and added to the ArchiveBook.
• The Storage component will be updated to save the ArchiveBook to a separate data/archive.json file.

Design considerations:

• Alternative 1 (current choice): Use a separate ArchiveBook and archive.json.
  • Pros: Keeps the main AddressBook lightweight and fast. Prevents archived patients from appearing in regular search results.
  • Cons: Requires duplicating some model and storage logic.
• Alternative 2: Add an isArchived boolean field to the Patient model.
  • Pros: Simpler to implement.
  • Cons: The main JSON file will continue to grow indefinitely, potentially degrading performance over time.

[Proposed] Automated Appointment Reminders

The proposed appointment reminder feature will alert the doctor of any upcoming appointments within the next 24 hours upon launching the application or while it is running.

Proposed Implementation

• A ReminderManager class will be added to the Logic component.
• ReminderManager will periodically query the Model for patients with an Appointment whose start time falls within a specific threshold (e.g., next 24 hours).
• The UI will be updated to include a ReminderPanel that observes the ReminderManager and displays upcoming appointments in a dedicated side panel or via visual indicators next to patient names.

---

Documentation, logging, testing, configuration, dev-ops

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

---

Appendix: Requirements

Product scope

Target user profile:

• has a need to manage a significant number of patient contacts, and appointments.
• prefer desktop apps over other types
• can type fast
• prefers typing to mouse interactions
• is reasonably comfortable using CLI apps
• may vary in technological confidence but prefers efficient keyboard-driven interaction

Value proposition: manage patient details like chronic conditions, severe allergies, and appointment scheduling faster than a typical mouse/GUI driven app

User stories

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

Priority	As a …	I want to …	So that I can …
* * *	Doctor	add a patient’s chronic condition	provide informed care
* * *	Doctor	add an appointment date to a patient	track my daily schedule
* * *	Doctor	delete a patient record	keep my database clean of inactive patients
* * *	Doctor	initialize a new empty data file	start using the system without manual setup
* * *	Doctor	see sample usage instructions on first launch	learn the system quickly
* * *	Doctor	load an existing data file	continue work across sessions
* * *	Doctor	receive a clear error message and correction technique when I enter an invalid command	fix my command
* * *	Less Tech Savvy Doctor	want the program to work immediately after opening	don’t have to install or configure anything
* * *	New User	view a list of available commands	know what actions are possible
* *	Doctor	edit a patient’s record	keep my database updated to the newest information
* *	Doctor	be alerted if I book two appointments at the same time	avoid double-booking myself
* *	Doctor	input command arguments in any order	don’t have to memorize rigid syntax
* *	Doctor	tag a patient with ‘High Risk’	am extra cautious when reviewing their file
* *	Doctor	mark an allergy as “Severe”	it stands out visually when I open the patient profile
* *	Doctor	be warned before permanently deleting a patient record	don’t lose data accidentally
* *	Doctor	be told when a search returns no results	know the system is working correctly
* *	Doctor	record a patient’s blood type	provide it quickly in an emergency
*	Doctor	list all patients with a specific allergy	avoid prescribing dangerous medication during an outbreak or shortage
*	Doctor	search for a patient by a partial or misspelled name	find records quickly even if I don’t remember the exact spelling
*	Doctor	use command aliases (e.g., a for add)	minimize typing time while talking to a patient
*	Doctor	list all patients taking a specific medication	contact them if that drug is recalled
*	Doctor	add a “Next Checkup” date	follow up on chronic condition progress
*	Doctor	scrub “soft deleted” data permanently	comply with “right to be forgotten” regulations
*	Doctor	link related patients	review hereditary patterns
*	Doctor	attach external specialist notes	have a full care picture
*	Tech Savvy Doctor	chain commands together	add a patient and their first appointment in one line

Use cases

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

Use case: Schedule an appointment for an existing patient

MSS

1. Doctor searches for a patient by name.
2. DoctorWho displays a list of matching patients.
3. Doctor identifies the correct patient’s index.
4. Doctor requests to add an appointment for that index with a date, time, and duration.
5. DoctorWho adds the appointment and displays a success message.
   Use case ends.

Extensions

• 2a. The list is empty (i.e. no patients found).
  • 2a1. DoctorWho shows an empty list.
  • 2a2. Doctor uses the add command to create a new patient (Refer to Add Patient use case).
    Use case resumes at step 4.
• 4a. The requested time slot overlaps with an existing appointment.
  • 4a1. DoctorWho displays a warning message about the overlap.
  • 4a2. DoctorWho adds the appointment anyway (system allows flexible scheduling).
    Use case ends.
• 4b. The patient index is invalid.
  • 4b1. DoctorWho shows an error message.
    Use case resumes at step 3.

Use case: Add an allergy to a patient

MSS

1. Doctor requests to list all patients.
2. DoctorWho shows the list of patients.
3. Doctor identifies the patient and uses the command to add a new allergy tag.
4. DoctorWho updates the patient record and displays a success message.
   Use case ends.

Extensions

• 3a. The patient already has the specified allergy listed.
  • 3a1. DoctorWho shows an error message: “Patient already has the allergy.”
    Use case resumes at step 3.

Use case: Delete a patient

MSS

1. Doctor requests to list all patients.
2. DoctorWho displays the list of patients.
3. Doctor specifies the INDEX of the patient to delete.
4. DoctorWho removes the specified patient from the system.
5. DoctorWho removes all appointments associated with that patient.
6. DoctorWho displays a confirmation message indicating the patient has been deleted.
   Use case ends.

Extensions

• 3a. The specified INDEX is invalid.
  • 3a1.DoctorWho displays an error message indicating that the index is invalid.
    Use case ends.

Use Case 07: List Appointments

Preconditions:

• User has launched the DoctorWho application.
• User is at the command prompt.

Main Success Scenario:

1. User requests to list appointments.
2. DoctorWho displays all appointments.

3. DoctorWho presents the appointments in ascending start date-time order.

   Use case ends.

Extensions:

• 1a. User requests to list appointments for a specific date.
  • 1a1. DoctorWho displays only appointments on the specified date.

  • 1a2. DoctorWho presents the results in ascending start date-time order.

    Use case ends.

• 1b. User enters an invalid date value.

  • 1b1. DoctorWho shows an error message.

    Use case ends.

• 1c. User enters an invalid date format.

  • 1b1. DoctorWho shows an error message.

    Use case ends.

• 2a. There are no appointments to display.

  • 2a1. DoctorWho shows an empty result list and a corresponding status message.

    Use case ends.

Post conditions:

• The currently displayed list is updated to show appointment-based results.
• If a date is provided, only appointments on that date are shown.

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 1000 patient records without a noticeable sluggishness in performance for typical usage.
3. A user with a typing speed of at least 50 WPM should be able to complete any mandatory CRUD task (e.g., adding a patient) faster than an equivalent GUI.
4. Data must be saved locally in a human-readable JSON format to allow for manual inspection or external backup without using the app.
5. The system should handle corrupted data files by notifying the user and failing gracefully rather than crashing.
6. The system should be fully functional in an offline environment with no dependency on external servers or internet connectivity.

Glossary

• Mainstream OS: Windows, Linux, Unix, macOS. (Relevant to Setting up)
• GUI (Graphical User Interface): A visual interface that allows users to interact with the software through graphical elements like windows, buttons, and icons. (Relevant to Architecture/UI)
• CLI (Command Line Interface): A text-based interface where the user provides input by typing commands. (Relevant to Architecture/Logic)
• JavaFX: The software platform and graphical library used to build the DoctorWho desktop interface. (Relevant to UI Component)
• Prefix: A short identifier followed by a forward slash (e.g. d/ for date) used to define arguments in a command. (Relevant to Logic Component)
• Prefix-based Matching: A parsing technique where data fields are identified by short leading characters (e.g., n/ for Name) rather than by their position in a sequence. (Relevant to Logic Component)
• Medical Tag: A general term encompassing both Conditions (e.g. Diabetes) and Allergies (e.g. Penicillin). (Relevant to Model Component)
• JSON: JavaScript Object Notation, a text-based interchange data format, for storing or transmitting data. ( Relevant to Storage Component)
• CRUD: An acronym for Create, Read, Update, and Delete—the four basic functions of persistent storage. (Relevant to Implementation)
• MVP: Minimum Viable Product; the core set of features required to make the app functional for Dr. Lee. (Relevant to Appendix: Requirements)
• Private contact detail: A contact detail that is not meant to be shared with others. (Relevant to User Stories)
• Index: A positive integer representing the position of an item in the currently displayed list in the UI. ( Relevant to Use Cases)
• Overlap: A situation where a new appointment’s time interval (start time + duration) intersects with an existing appointment’s interval. (Relevant to Use Cases)
• ISO 8601: The international standard for the representation of dates and times (e.g. YYYY-MM-DD). (Relevant to Use Cases/NFRs)
• NFR (Non-Functional Requirement): A requirement that specifies criteria that can be used to judge the operation of a system, rather than specific behaviors (e.g. security, reliability). (Relevant to NFR Section)
• Scalability: The measure of the system’s ability to handle a growing amount of data (e.g. thousands of patients) without performance degradation. (Relevant to NFR Section)
• Orphan Schedule: An appointment record that remains in the system after the associated patient has been deleted. DoctorWho prevents this via automated purging. (Relevant to NFR Section)

---

Appendix: Instructions for manual testing

Given below are instructions to test the app manually.

Launch and shutdown

1. Initial launch

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

   2. Double-click the jar file 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.

3. { more test cases …​ }

Deleting a patient

1. Deleting a patient while all patients are being shown

   1. Prerequisites: List all patients using the list command. Multiple patients 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 patient 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 …​ }

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 …​ }

Appendix: Planned Enhancements

1. Include support for slashes (/) in patient name. Currently, we ask the user to remove slashes when entering the patient’s name. However, this means that the stored patient name may not be a match their exact government name. We plan to implement apostrophe string enclosing to allow such special characters to be included in the name without conflicting with the special characters used for the argument prefixes.
2. Include cross-checks between a patient’s date of birth and NRIC. Currently, we don’t check that the patient’s birth year matches their NRIC due to complexities and edge cases. Additionally, patients born before 1968 won’t have their birth year as the first two digits of their NRIC, making this impossible in certain cases. We plan to implement a best-effort check that will flag possible mismatches.