PROJECT: ORGANice

1. Overview

This document is written to document my role and contributions to ORGANice. ORGANice is a project undertaken in CS2103T, the introductory Software Engineering module offered by NUS. I was required to work with 4 other students to morph Address Book 3, an existing desktop application, to another desktop application within 7 weeks.

As part of the module constraints, the application must have a Command Line Interface (CLI). This means that users must be able to use the application’s features by typing commands instead of clicking buttons.

Our team chose to morph Address Book 3 to ORGANice, an organ matching desktop application designed for hospital administration staff who prefer typing. It is written in Java, and has about 10,000 lines of code (LoC). The JavaFX framework is used to create the Graphical User Interface (GUI) of this application.

The main features of ORGANice includes:

  • storing information of patients, donors and donors

  • finding potential organ donors for patients

  • managing administrative procedures relating to organ matching.

Note the formatting used in this document:

match - Words highlighted in grey (called a mark-up) indicates that this is a command that can be executed by the application or a technical term.

Enter - Words highlighted in white and encased in a box indicates that it is a key on a keyboard.

Section 2, “Summary of contributions” - Words in blue and underlined indicates that it is a clickable link.

[Some link] - Words in blue, underlined and encased in square brackets indicates that the links are not clickable. Note that they appear in the excerpts because they are links to other documents that are not in the excerpts.

2. Summary of contributions

The following sections presents the enhancements I implemented in greater detail.

  • Major enhancement 1: added the ability to match patients and donors

    • What it does: identifies potential donors for patients in the application.

    • Justification: allows users to find suitable donors for patients efficiently based on compatibility between patients and donors.

    • Highlights: Other features, such as sorting and processing matches, depend on this feature. Therefore, I had to think of a design solution that allows for the seamless integration of other features. Also, implementing this feature required a deep understanding of how to store and change the list displayed in Address Book 3.

  • Major enhancement 2: added the ability to add patients in ORGANice.

    • What it does: allows patients to be added and stored in ORGANice

    • Justification: allows users to easily manage patient data. Storing patient data is also required for matching of patients and donors to take place.

    • Highlights: The addition of this feature required careful consideration of how to display, store and differentiate patients from other types of people in ORGANice.

  • Minor enhancement 1: added coloured tags to patients and donors.

    • What it does: indicates the statuses of patients and donors.

    • Justification: allows users to identify unmatched patients and donors at a glance.

    • Highlights: The tags are coloured differently depending on the statuses displayed. While this feature is minor, it still required careful thought to implement this.

  • Code contributed: [RepoSense]

  • Other contributions:

    • Project management:

      • Created issues to keep track of work to be done.

      • Managed release v1.3.1 on Github

    • Enhancements to existing features:

      • Wrote additional unit and integration tests for existing features to increase coverage (Pull request #275)

    • Documentation:

      • Authored the 'Introduction', 'Quick Start', 'Components of ORGANice' and 'Detecting matches' sub-sections in the 'Features' section (Pull request #138)

    • Community:

3. Contributions to the User Guide

This section documents my contributions to the User Guide. I wrote the following sections:

  • Introduction

  • Quick Start

  • Components of ORGANice

  • Detecting matches

Given below is an excerpt of my contribution to the User Guide.

(Start of extract from User Guide)

(End of extract from User Guide)

4. Contributions to the Developer Guide

This section documents my contributions to the Developer Guide. I wrote the following sections:

  • Introduction

  • Setting up

  • 'Matching feature'

Given below is an excerpt of my contribution to the Developer Guide.

(Start of extract from Developer Guide)

4.1. Matching feature

This section explains the current implementation and design considerations of the matching feature.

Matching is facilitated by the MatchCommand class, which extends the Command class. It implements the MatchCommand#match(Person donor, Patient patient) operation, which checks if the given patient and donor have compatible blood and tissue types. For the context of this application, a patient and donor pair with compatible blood and tissue types is considered as a potential match.

The following operations in ModelManager accesses the match method:

  • ModelManager#matchDonors(Patient patient) — Matches all donors in ORGANice with the specified patient. For each donor that potentially matches the patient, a MatchedDonor object is created to store the compatibility rate of the donor with the patient.

  • ModelManager#matchPatients() — Matches all donors with all patients. For every patient in ORGANice, a MatchedPatient object is created to store the number of donors that are potential matches with that patient.

MatchedDonor and MatchedPatient objects are stored in an ObservableList called listOfMatches. Contents of listOfMatches are copied to displayedPersons, which is another ObservableList that can be accessed by Logic and is displayed by the UI component.

Each time a user invokes the match feature, the contents of listOfMatches are deleted. New MatchedPatient and MatchedDonor objects are created and stored in the list again.

Given below is an example usage scenario and how the match feature works at each step:

Step 1. The user opens up the application with an existing list of patients and donors. As seen in the diagram below, there are 2 Patient and 2 Donor objects in ORGANice, and no objects in listOfMatches.

MatchState0
Figure 1. Object diagram of initial state of ORGANice

Step 2. The user types in the command match ic/all. Each patient will be matched with all donors via the MatchCommand#match operation. A MatchedPatient object is created for each patient, which stores the number of potential donors the patient has. The figure below illustrates this with the addition of mp1 and mp2, which are MatchedPatient objects of p1 and p2 respectively.

MatchState1
Figure 2. State of ORGANice after matching all patients

Step 3. The user types in the command match ic/PATIENT NRIC, where PATIENT NRIC is the NRIC of a patient in ORGANice. Existing objects in the listOfMatches are removed. For each potential donor of the specified patient, a MatchedDonor`object is created, accompanied with the compatibility rate. As seen in the figure below, `mp1 and mp2 are removed from listOfMatches. MatchedDonor objects md1 and md2 are created to represent d1 and d2 respectively. All MatchedDonor objects are then added to the listOfMatches.

MatchState2
Figure 3. State of ORGANice after matching a specific patient

The following activity diagram summarises what happens when a user executes the match feature:

MatchActivityDiagram
Figure 4. Activity diagram of the match command

4.1.1. Design considerations

This section will explain some aspects that were considered when designing the match feature.

Aspect 1: Storage of match results

This section explores several choices of storing match results of patients and donors.

  • Choice 1 (current choice): Delete MatchedPatient and MatchedDonor objects created in previous MatchCommand executions when there is a new MatchCommand executed.

    • Pros: No need to write extra code to store match results in the hard disk. Previous match results are overriden with new results from the latest match command. A scenario in which this would be important is if a user matches a patient again after editing the patient’s information. The matching would be based on the updated patient’s information.

    • Cons: Redundant matching occurs in a scenario where the user executes a match command with the same parameters twice.

  • Choice 2: For each patient, keep a list of match results. After every MatchCommand is executed, save the match results to the hard disk.

    • Pros: A history of match results is stored, thus reducing redundant matching.

    • Cons: More code to needs to be written to store match results to the hard disk.

4.1.2. Aspect 2: Display of match results

This section explains some considerations for displaying match results, which are stored in MatchedPatient and MatchedDonor objects.

  • Choice 1 (current choice):: Display MatchedDonor and MatchedPatient objects in PersonListPanel

    • Pros: Easy to implement because additional code is added to PersonListPanel, which is a UI component already existing in AddressBook 3. The constructor of PersonListPanel takes in an ObservableList<Person> object and creates a list of PersonListViewCell objects to be displayed.

    • Cons: The MatchedDonor and MatchedPatient classes need to inherit from the Person class, even though they represent match results, not people.

  • Choice 2: Create a new list panel called MatchListPanel, which displays objects of the Match class. MatchedDonor and MatchedPatient classes extend from the Match class.

    • Pros: MatchedDonor and MatchedPatient classes do not inherit unwanted methods from Person class. The Match class can contain methods more specific to matching.

    • Cons: There would be two types of list panels. Upon executing each command, the correct list panel must be selected and displayed.

(End of extract from Developer Guide)