Developer Guide

• Table of Contents
  • Acknowledgements
  • Setting up, getting started
  • Design
    • Architecture
    • UI component
    • Logic component
    • Model component
    • Storage component
    • Common classes
  • Implementation
    • Add feature
    • Attach feature
    • Delete feature
    • Update feature
    • Find feature
    • Export feature
    • Clear feature
    • List feature
    • Help feature
    • Exit feature
    • Undo feature
      • Undo state behaviour summary
      • Design considerations
  • Documentation, logging, testing, configuration, dev-ops
  • Appendix: Requirements
    • Product scope
    • User stories
    • Use cases
  • Non-Functional Requirements
    • Compatibility
    • Performance
    • Usability
    • Reliability
    • Maintainability
    • Portability
    • Glossary
  • Appendix: Instructions for manual testing
    • Test setup
    • Launch, shutdown, and UI state
    • Command parsing and basic validation
    • Feature-level test cases
      • Add
      • Attach
      • Update
      • Find and list interaction
      • Delete
      • Export
      • Clear
      • Help
      • Undo
    • Data persistence and recovery tests
    • Regression checklist (quick pass before release)

---

Acknowledgements

• This project is based on the AddressBook Level-3 application.
• Class names were renamed from AB3 defaults to CatPals-related names to better match the project domain.
• AI-assisted development tools used: Claude Code and Cursor.

---

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, CatListPanel, CatDetailPanel, 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. A SplashScreen is also shown on startup before the MainWindow is initialised; it does not extend UiPart.

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 sequence diagram below illustrates how the UI handles a user command:

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 Cat objects 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 cat).
   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 Cat objects (which are contained in a UniqueCatList object).
• stores the currently ‘selected’ Cat objects (e.g., results of a search query) as a separate filtered list which is exposed to outsiders as an unmodifiable ObservableList<Cat> 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 seedu.address.commons package.

---

Implementation

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

Add feature

The add command allows users to add a new cat profile to the cat notebook. It is implemented via AddCommand, which extends Command, and AddCommandParser, which parses the user’s input.

Format: add n/NAME t/TRAIT l/LOCATION [h/HEALTH_STATUS]

• n/NAME, t/TRAIT, and l/LOCATION are required.
• h/HEALTH_STATUS is optional.
• You can specify up to 3 t/TRAIT prefixes, but duplicate traits are not allowed.

The add command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser identifies the add keyword and creates an AddCommandParser, which parses the remaining arguments (name, trait, location, and optional health status) into a Cat object wrapped in an AddCommand.
3. LogicManager calls AddCommand#execute(model).
4. AddCommand checks for duplicates via Model#hasCat(cat). If a cat with the same name already exists, a CommandException is thrown.
5. If no duplicate is found, Model#addCat(cat) is called to persist the new cat.
6. A CommandResult is returned with a success message.

Attach feature

The attach command allows users to attach an image to an existing cat profile, or reset a previously attached image back to auto-detection. It is identified by index or name. It is implemented via AttachCommand, which extends Command, and AttachCommandParser, which parses the user’s input.

Format:

• attach INDEX IMAGE_PATH or attach CAT_NAME IMAGE_PATH — attach an image
• attach INDEX --reset or attach CAT_NAME --reset — clear the explicit image path and fall back to auto-detection

AttachCommandParser splits on the last space to separate the identifier from the image path or --reset flag. This allows cat names with spaces (e.g. Snowy White) to be used as identifiers.

The attach command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser identifies the attach keyword and creates an AttachCommandParser, which splits the arguments on the last space. If the last token is --reset, a reset AttachCommand is created (no image path). Otherwise, the last token is parsed as an image path.
3. LogicManager calls AttachCommand#execute(model).
4. If this is not a reset, AttachCommand verifies that the image file exists on disk. If not, a CommandException is thrown.
5. The target cat is resolved:
   • If an index was given, the cat is retrieved from the filtered list via Model#getFilteredCatList(). An out-of-bounds index throws a CommandException.
   • If a name was given, the cat is searched case-insensitively across the full cat list via Model#getAddressBook(). A missing name throws a CommandException.
6. A new Cat object is constructed with the updated image path (or an empty CatImage for reset), and Model#setCat(catToEdit, updatedCat) is called.
7. A CommandResult is returned with a success message (MESSAGE_ATTACH_SUCCESS or MESSAGE_RESET_SUCCESS).

Delete feature

The delete command allows users to remove an existing cat profile from the cat notebook, identified by index or name. It is implemented via DeleteCommand, which extends Command, and DeleteCommandParser, which parses the user’s input.

Format: delete INDEX or delete CAT_NAME

The delete command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser identifies the delete keyword and creates a DeleteCommandParser, which attempts to parse the argument as an index first. If that fails, it treats the argument as a cat name (case-insensitive).
3. LogicManager calls DeleteCommand#execute(model).
4. DeleteCommand retrieves the current filtered cat list via Model#getFilteredCatList().
5. The target cat is resolved:
   • If an index was given, the cat at that position is retrieved. An out-of-bounds index throws a CommandException.
   • If a name was given, the cat is located by exact name match. If no match is found, a CommandException is thrown.
6. Model#deleteCat(cat) is called to remove the cat from the address book.
7. A CommandResult is returned with a success message.

Update feature

The update command allows users to change an existing cat’s name, traits, location, or health status. The cat is identified either by index or by name, both matched against the currently displayed (filtered) list. It is implemented via UpdateCommand, which extends Command, and UpdateCommandParser, which parses the user’s input.

Format: update CAT_NAME [n/NAME] [t/TRAIT]... [l/LOCATION] [h/HEALTH_STATUS] or update INDEX [n/NAME] [t/TRAIT]... [l/LOCATION] [h/HEALTH_STATUS]

• At least one of n/, t/, l/, or h/ must be present; otherwise a ParseException is thrown with MESSAGE_INVALID_COMMAND_FORMAT (showing UpdateCommand.MESSAGE_USAGE). If prefixes are present but all values are empty after parsing, a ParseException is thrown with UpdateCommand.MESSAGE_NOT_EDITED.
• n/, t/, l/, and h/ are case-insensitive for the add and update commands (e.g. N/ and n/ are treated the same). This is done in UpdateCommandParser#normalizeUpdatePrefixes before tokenization.
• Duplicate n/, l/, or h/ prefixes in one command are rejected via ArgumentMultimap#verifyNoDuplicatePrefixesFor.
• Multiple t/TRAIT prefixes are allowed (subject to the usual cap of three traits and no duplicates within the parsed list).
• Supplying t/ replaces the cat’s entire trait list with the traits given in that command. To keep existing traits, the user must include them again alongside any new ones. A lone t/ with no value clears all traits (parsed as an empty trait list).
• If the target is specified by name, lookup is case-insensitive (equalsIgnoreCase on the full name) and searches the filtered list (Model#getFilteredCatList()). If no cat matches, a CommandException is thrown with UpdateCommand.MESSAGE_INVALID_CAT_NAME.
• If the target is specified by index, it refers to the filtered list (Model#getFilteredCatList()). An out-of-bounds index results in Messages.MESSAGE_INVALID_CAT_DISPLAYED_INDEX.
• After applying edits, if the updated cat would duplicate another cat’s identity (same name as a different entry), Model#hasCat causes a CommandException with UpdateCommand.MESSAGE_DUPLICATE_CAT.

The following sequence diagram shows how an update operation is carried out:

The update command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser identifies the update keyword and creates an UpdateCommandParser, which normalizes prefix casing, tokenizes arguments, and parses the preamble as either an index or a valid Name, together with an EditCatDescriptor for the fields to change.
3. LogicManager calls UpdateCommand#execute(model).
4. UpdateCommand resolves the cat to edit from the filtered list (by both index and name), then builds an updated Cat via createEditedCat, merging descriptor fields with the existing cat.
5. Duplicate-name checks and Model#setCat are applied. If the updated cat no longer matches the current filter predicate, the filtered list is updated to keep the edited cat visible alongside the other filtered results.
6. A CommandResult is returned with a success message.

Find feature

The find command updates which cats are shown in the UI by applying a CatContainsKeywordsPredicate over the address book. It is implemented via FindCommand and FindCommandParser.

Format: find [n/NAME]... [l/LOCATION]... [t/TRAIT]... [h/HEALTH_STATUS]... — at least one of n/, l/, t/, or h/ must be present, and there must be no preamble (anything before the first prefix causes a parse error).

• FindCommandParser normalizes n/t/l/h prefix casing (case-insensitive), then tokenizes and validates keywords (non-empty, single token per value).
• FindCommand#execute calls Model#updateFilteredCatList(predicate) with a CatContainsKeywordsPredicate. If the filtered list is empty, FindCommand.MESSAGE_NO_MATCH is returned; otherwise an overview message is shown.

The following sequence diagram shows how a find operation is carried out:

The find command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser identifies the find keyword and creates a FindCommandParser, which parses prefixed keywords into a CatContainsKeywordsPredicate wrapped in a FindCommand.
3. LogicManager calls FindCommand#execute(model).
4. FindCommand updates the filtered cat list via Model#updateFilteredCatList(predicate).
5. A CommandResult is returned (either a “no match” message or a listed-cats overview).

Export feature

The export feature allows users to export the currently displayed cat list to an HTML file. It is implemented via ExportCommand, which extends Command, and ExportCommandParser, which parses the optional title/filename argument.

Format: export [TITLE]

• If TITLE is omitted, the file is saved as export.html with the heading “Cat List”.
• If TITLE is provided (e.g. export Utown Cats), spaces are replaced with hyphens for the filename (Utown-Cats.html), and the original text is used as the page heading (Utown Cats).
• TITLE must not contain any of the characters \ / : * ? " < > |, otherwise a ParseException is thrown.

The following sequence diagram shows how an export operation is carried out:

The export command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser identifies the export keyword and creates an ExportCommandParser, which trims the remaining arguments. If empty, a default ExportCommand is returned. Otherwise, spaces are replaced with hyphens to form the filename and the original trimmed text becomes the page title; invalid filename characters cause a ParseException.
3. LogicManager calls ExportCommand#execute(model).
4. ExportCommand retrieves the currently filtered cat list via Model#getFilteredCatList(). This respects any active find filters — only the cats currently shown in the UI are exported.
5. An HTML string is built for each cat and written to <filename>.html in the application’s working directory.
6. A CommandResult is returned indicating how many cats were exported and the output filename.

Clear feature

The clear command removes all cats from the address book by replacing it with an empty AddressBook. It is implemented via ClearCommand, which extends Command. There is no dedicated parser — AddressBookParser instantiates ClearCommand directly when the user types clear (any extra text after the command word is not parsed and does not affect execution).

The following sequence diagram shows how a clear operation is carried out:

The clear command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser creates a ClearCommand.
3. Before execution, LogicManager clears any saved undo state via Model#clearUndoState() (since clear is not treated as an undoable single-cat command in the same way as add / delete / update / attach).
4. LogicManager calls ClearCommand#execute(model).
5. ClearCommand calls Model#setAddressBook(new AddressBook()), removing all cat entries.
6. A CommandResult is returned with a success message.
7. LogicManager persists the empty address book via Storage#saveAddressBook.

List feature

The list command shows all cats in the address book. It is implemented via ListCommand, which extends Command, and requires no dedicated parser class. Like help, exit, and clear, extra parameters are silently ignored — AddressBookParser instantiates ListCommand directly regardless of any trailing arguments.

Implementation flow:

1. User types e.g. list (or list foo) and presses Enter.
2. AddressBookParser#parseCommand() matches the command word "list" and returns a new ListCommand.
3. ListCommand#execute() calls Model#updateFilteredCatList(PREDICATE_SHOW_ALL_CATS) and returns a success result.

Help feature

The help command shows usage information by returning a CommandResult that signals the UI to open the help window. It is implemented via HelpCommand, which extends Command. There is no dedicated parser — AddressBookParser instantiates HelpCommand directly when the user types help.

The following sequence diagram shows how the help command is handled:

The help command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser creates a HelpCommand with no arguments.
3. LogicManager calls HelpCommand#execute(model) (the model is not modified).
4. A CommandResult is returned with showHelp set to true; the UI then opens the help window.

Exit feature

The exit command shuts down the application. It is implemented via ExitCommand, which extends Command. There is no dedicated parser — AddressBookParser instantiates ExitCommand directly when the user types exit.

The following sequence diagram shows how the exit command is handled:

The exit command works as follows:

1. LogicManager receives the command string and delegates parsing to AddressBookParser.
2. AddressBookParser creates an ExitCommand with no arguments.
3. LogicManager calls ExitCommand#execute(model) (the model is not modified).
4. A CommandResult is returned with exit set to true; the UI then terminates the application.

Undo feature

The undo mechanism uses a single-snapshot approach managed by ModelManager. Before executing any undoable command (add, delete, update, attach), LogicManager calls Model#saveUndoState(), which saves a deep copy of the current AddressBook into a previousAddressBook field. When the user runs undo, the saved snapshot is restored.

The mechanism exposes the following operations via the Model interface:

• Model#saveUndoState() — Saves a snapshot of the current address book before an undoable command runs.
• Model#clearUndoState() — Clears the saved snapshot. Only called after clear, since it is a destructive non-reversible command.
• Model#canUndo() — Returns true if there is a saved snapshot available.
• Model#undoLastChange() — Restores the address book to the saved snapshot and clears it.
• Model#getUndoSnapshot() — Returns the current undo snapshot (used for rollback on command failure).
• Model#setUndoSnapshot(snapshot, hasState) — Restores a previous undo snapshot (used for rollback on command failure).

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

Step 1. The user launches the application for the first time. No undo snapshot exists yet (previousAddressBook is null, hasUndoableState is false).

Step 2. The user executes add n/Mochi t/Calico l/UTown to add a new cat. Before the add command executes, LogicManager backs up the existing undo snapshot and calls Model#saveUndoState(), saving the current address book state. If the command succeeds, LogicManager also stores the full command text ("add n/Mochi t/Calico l/UTown") for use in the undo confirmation dialog. If the command fails, LogicManager rolls back the undo snapshot to its previous state.

Step 3. The user executes update Mochi l/PGPR to update the cat’s location. Before the update command executes, LogicManager calls Model#saveUndoState() again, overwriting the previous snapshot with the current state (post-add). The stored command text is updated to "update Mochi l/PGPR".

Step 4. The user now decides that updating the location was a mistake, and executes the undo command.

1. MainWindow checks Logic#canUndo() to see if a snapshot exists.
2. Since a snapshot exists, MainWindow shows a confirmation dialog displaying the last undoable command: “Are you sure you want to undo the following command? > update Mochi l/PGPR”.
3. If the user confirms, MainWindow calls Logic#executeCommand(undoCommand).
4. UndoCommand#execute() calls Model#undoLastChange(), which restores the address book to the snapshot (post-add state) and clears the snapshot.

The following sequence diagram shows how an undo operation goes through the UI and Logic components. Before the undo is executed, MainWindow calls Logic#canUndo() to check whether there is a saved state to restore. If there is, a confirmation dialog is shown. The undo is only carried out if the user confirms.

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

Step 5. The user then executes the command list. Read-only commands (list, find, help, export, exit) do not modify the address book and do not affect the undo state. If a snapshot existed before list, it remains available for undo afterwards.

Step 6. The user executes clear. Since clear is a destructive non-reversible command, LogicManager calls Model#clearUndoState() to discard any saved snapshot. The user cannot undo a clear.

Undo state behaviour summary

Command type	Examples	Effect on undo state
Undoable	add, delete, update, attach	Saves a new snapshot (overwrites any previous)
Destructive non-reversible	clear	Clears the snapshot
Read-only	list, find, help, export, exit, undo	No effect — snapshot is preserved

Design considerations:

Aspect: How undo executes:

• Alternative 1 (current choice): Saves the entire address book as a single snapshot.

  • Pros: Easy to implement. One level of undo is sufficient for most use cases.
  • Cons: May have performance issues in terms of memory usage for very large data sets. Only supports one level of undo.

• Alternative 2: Individual command knows how to undo by itself.

  • Pros: Will use less memory (e.g. for delete, just save the cat being deleted). Could support multi-level undo.
  • Cons: We must ensure that the implementation of each individual command is correct.

---

Documentation, logging, testing, configuration, dev-ops

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

---

Appendix: Requirements

Product scope

Target user profile:

• is a member of NUS Cate Cafe CCA
• has a need to manage a significant number of stray cats in NUS Campus
• prefer desktop apps over other types
• can type fast
• prefers typing to mouse interactions
• is reasonably comfortable using CLI apps

Value proposition:

Provides fast, CLI-optimized access to information of stray cats living in NUS campus so volunteers can reliably identify cats and keep key status details up to date. Designed for personal or small-team use; not a veterinary medical system, shelter operations tool, or public registry.

User stories

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

Priority	As a …	I want to …	So that I can…
* * * *	regular feeder	search a cat by name/alias in the CLI	identify it quickly on the spot
* * * *	volunteer	update a cat’s key status fields (e.g., sterilised/ear-tipped, friendliness, usual area)	our data stays accurate for small-team coordination
* * * *	volunteer	add cat entries	keep the record of a newly-found stray cat
* * * *	user	delete a cat profile	remove duplicate entries or data errors to keep the database clean
* * *	frequent user	use short-hand flags (e.g., -n for name, -t for territory)	type faster
* * *	volunteer	add and search by multiple identifiers (alias, coat color, landmark)	still find a cat when I don’t know its name
* * *	volunteer updating a cat’s record	prompted by the CLI for confirmation before applying changes	not accidentally overwrite important information
* * *	volunteer	export the list of cats data stored in this app	get a physical copy of the list
* * *	volunteer	undo or revert my last update	be away from the risk where accidental edits permanently corrupt records
* * *	volunteer	tag a cat with quick flags (e.g., “shy”, “approachable”, “avoid”)	interact safely and consistently
* * *	user	see a quick profile of each cat on the main page	get an overview of all the cats without diving into details
* * *	new user	run a guided “first-time” CLI help command	learn the workflow quickly
* * *	volunteer	filter cats by certain attributes	get the information of a group of cats that share some similarities
* * *	volunteer	attach an image of the cat	see how the cat is looked like in the most directly way
* *	user	use a personal account and a corresponding key to login	be away from the issue that unauthorized users will have access to this system
* *	user	attach a link that keeps an archive of the cat (videos, more pictures) for each cat recorded in this system	more information of cats can be retrieved without taking up storage inside of this app
* *	commitee member	edit a cat’s profile to change their status to “adopted”	stop deploying resources for cats that are no longer on campus
* *	volunteer	mark a cat’s entry grey to indicate that the cat has unfortunately died	show respect and R.I.P to cats
* *	first time user	learn how to use this app with a tutorial provided when I first open it	get myself familiar without exploring by myself
*	volunteer	auto-identify a cat from a photo using on-device recognition	be free from typing names at all
*	volunteer	see a list of “Missing in Action” cat	rescue them in time
*	volunteer	use fuzzy search and typo tolerance	find cats quickly even with imperfect spelling
*	volunteer	“favorite” a set of cats	pull up my usual watchlist with one command
*	volunteer	create a “needs follow-up” note (non-medical)	be in the situation where the next person knows what to check without guessing
*	volunteer	maintain a “cat family tree / social graph” (friendships, rivalries, territories)	understand colony dynamics over time
*	volunteer	record structured medical observations (symptoms checklist + severity)	get to the concerns consistently (not a diagnosis)
*	volunteer	log medication administration (drug name, dosage, time, handler)	track the treatment history and thus reduces mistakes
*	volunteer	get “triage suggestions” based on symptoms	know whether to monitor, isolate, or escalate (high-risk, needs careful disclaimers)
*	volunteer	use arrow keys (or command history)	quickly repeat a previous complex command without re-typing it entirely
*	volunteer	keep track of where the cat is last seen (especially if out of its own territory)	track the cat in a more detailed way

{More to be added}

Use cases

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

Use case 1 (U1): Add a cat

MSS

1. User requests to add a cat

2. CatPals adds the cat

   Use case ends.

Extensions

• 1a. The provided name is blank.

  • 1a1. CatPals shows an error message: “Name must not be blank!”. Use case ends.

• 1b. The name length exceeds 30 characters.

  • 1b1. CatPals shows an error message: “Name must be no longer than 30 chars!”. Use case ends.

• 1c. The name contains symbols.

  • 1c1. CatPals shows an error message: “The name must not contain symbols!”. Use case ends.

• 1c2. The name consists of only numbers (e.g. 123).

  • 1c2a. CatPals shows an error message: “Name must contain at least one letter and cannot be only numbers!”. Use case ends.

• 1d. A cat with the same name already exists in CatPals.

  • 1d1. CatPals shows an error message: “The cat name already exists!”. Use case ends.

• 1e. The trait field is blank.

  • 1e1. CatPals shows an error message: “Your Add command is incomplete. Please enter again.”. Use case ends.

• 1f. The user inputs more than 3 traits.

  • 1f1. CatPals shows an error message: “You added more than 3 traits to the cat. Please only add up to 3 traits.”. Use case ends.

• 1g. The user inputs duplicate traits.

  • 1g1. CatPals shows an error message: “You cannot add duplicate traits!”. Use case ends.

• 1h. The location field is blank.

  • 1h1. CatPals shows an error message: “Location must not be blank!”. Use case ends.

• 1i. The location length exceeds 50 characters.

  • 1i1. CatPals shows an error message: “Location must be no longer than 50 chars!”. Use case ends.

• 1j. The user inputs duplicate location prefixes (e.g. l/Utown l/Science).

  • 1j1. CatPals shows an error message: “Multiple values specified for the following single-valued field(s): l/”. Use case ends.

• 1k. The trait length exceeds 50 characters.

  • 1k1. CatPals shows an error message: “Trait must be no longer than 50 chars!”. Use case ends.

• 1l. The health status length exceeds 50 characters.

  • 1l1. CatPals shows an error message: “Health status must be no longer than 50 chars!”. Use case ends.

Use case 2 (U2): Delete a cat

MSS

1. User requests to list cats
2. CatPals shows a list of cats
3. User requests to delete a specific cat in the list

4. CatPals deletes the cat

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

• 3a. The user requests to delete by name.

  • 3a1. The name is blank or contains invalid symbols.
    • 3a1a. CatPals shows an error message: “Invalid command format! delete: Deletes the cat identified by the index number or name in the displayed cat list. Parameters: INDEX (must be a positive integer) or CAT_NAME Example: delete 1 Example: delete Whiskers”. Use case ends.
  • 3a2. The name does not match any cat in CatPals.
    • 3a2a. CatPals shows an error message: “No cat with the name ‘Mocha’ found in the displayed list.”. Use case ends.

• 3b. The user requests to delete by number (index).

  • 3b1. The number is blank.
    • 3b1a. CatPals shows an error message: “Invalid command format! delete: Deletes the cat identified by the index number or name (case-sensitive) in the displayed cat list. Parameters: INDEX (must be a positive integer) or CAT_NAME Example: delete 1 Example: delete Whiskers”. Use case ends.
  • 3b2. The number is out of range (invalid index).
    • 3b2a. CatPals shows an error message: “The cat index provided is invalid”. Use case resumes at step 2.

Use case 3 (U3): Search for a cat using its name

MSS

1. User requests to find a specific cat by name
2. CatPals shows all cat profiles that match the search

3. User selects a cat profile from the search results to view its details

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

• 3a. There is no profile with a matching name.

  • 3a1. CatPals shows an error message: “There is no such profile in my records! Is there a typo?”.

    Use case ends.

Use case 4 (U4): Help command

MSS

1. User requests to see the help guide

2. CatPals shows a list of available commands and their formats

   Use case ends.

Extensions

• 1a. The help command is typed incorrectly.

  • 1a1. CatPals shows an error message: “No such command found!”.

    Use case ends.

Use case 5 (U5): Update cat status

MSS

1. User requests to list cats
2. CatPals shows a list of cats
3. User requests to update the status (traits, location, or health) of a specific cat in the list

4. CatPals updates the status of the cat

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

• 3a. The user requests to update by name.

  • 3a1. The name is blank or the command format is invalid.
    • 3a1a. CatPals shows an error message with the correct command format. Use case ends.
  • 3a2. The name does not match any cat in the displayed list.
    • 3a2a. CatPals shows an error message: “No cat with the name ‘' found in the displayed list.". Use case ends.

• 3b. The user requests to update by index.

  • 3b1. The index is blank or the command format is invalid.
    • 3b1a. CatPals shows an error message with the correct command format. Use case ends.
  • 3b2. The index is out of range (invalid index).
    • 3b2a. CatPals shows an error message: “The cat index provided is invalid”. Use case resumes at step 2.

• 3c. The updated status data is invalid.

  • 3c1. The user inputs more than 3 traits.
    • 3c1a. CatPals shows an error message: “You added more than 3 traits to the cat. Please only add up to 3 traits.”. Use case ends.
  • 3c2. The user inputs duplicate traits.
    • 3c2a. CatPals shows an error message: “You cannot add duplicate traits!”. Use case ends.
  • 3c3. The updated cat name already exists (duplicates another cat).
    • 3c3a. CatPals shows an error message: “This cat already exists in the cat notebook.”. Use case ends.

Use case 6 (U6): Undo last action

MSS

1. User requests to undo the previous command.
2. CatPals shows a confirmation dialog displaying the command that will be undone.
3. User confirms the undo.
4. CatPals reverts the last change made to the notebook.

5. CatPals shows a success message confirming the restoration.

   Use case ends.

Extensions

• 1a. There is no saved undo state (no undoable command has been run yet, or the state was cleared by clear).

  • 1a1. CatPals shows a message: “Nothing to undo.”

    Use case ends.

• 1b. Read-only commands (list, find, help, export) were run after the last undoable command.

  • 1b1. The undo state is preserved across read-only commands, so the user can still undo the last undoable command. Flow continues at step 2.

• 3a. User cancels the confirmation dialog.

  • 3a1. The undo is not performed. No state change occurs.

    Use case ends.

Use case 7 (U7): Attach an image to a cat profile

MSS

1. User provides the target cat (by index or name) and the image file path
2. CatPals validates the file path and format, then attaches the image to the cat profile

3. CatPals shows a success message confirming the attachment

   Use case ends.

Extensions

• 1a. The target index is out of bounds.
  • 1a1. CatPals shows an error message: “The cat index provided is invalid”. Use case ends.
• 1b. The target cat name does not match any cat in CatPals.
  • 1b1. CatPals shows an error message: “No cat with the name <name> found.”. Use case ends.
• 1c. The user provides --reset instead of an image path.
  • 1c1. CatPals clears the explicit image path for the cat, reverting to auto-detection.
  • 1c2. CatPals shows a success message confirming the reset. Use case ends.
• 2a. The provided file path does not exist.
  • 2a1. CatPals shows an error message: “Image file not found: <path>”. Use case ends.
• 2b. The file is not a supported image format (not .jpg, .jpeg, or .png).
  • 2b1. CatPals shows an error message indicating the incorrect format and the supported types. Use case ends.

Use case 8 (U8): Export cat data

MSS

1. User requests to export the currently displayed cat list, optionally providing a title (e.g. export Utown Cats)
2. CatPals exports the cats to an HTML file named after the title (e.g. utown-cats.html), using the title as the page heading

3. CatPals shows a success message indicating how many cats were exported and the output filename

   Use case ends.

Extensions

• 1a. No title is provided (user types just export).
  • 1a1. CatPals exports to export.html with the default heading “Cat List”. Use case ends.
• 1b. The title contains invalid filename characters (e.g. \ / : * ? " < > |).
  • 1b1. CatPals shows an error message listing the disallowed characters. Use case ends.

Use case 9 (U9): Filter cats by traits

MSS

1. User requests to filter cats by specific traits (e.g. find t/Friendly)

2. CatPals displays a list of cats that match the specified traits

   Use case ends.

Extensions

• 2a. No cats match the specified traits.
  • 2a1. CatPals shows an error message: “There is no such profile in my records! Is there a typo?”. Use case ends.

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 cats without a noticeable sluggishness in performance for typical usage.
3. 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.

Compatibility

• Should work on any mainstream OS (Windows, macOS, Linux) as long as Java 17 or above is installed.

Performance

• Should be able to hold up to 1000 cat records without noticeable sluggishness in performance for typical usage.
• Response time for adding, deleting, or editing a record should be under 1 second.
• Search results should be displayed within 0.5 seconds of input.

Usability

• A user with above average typing speed for regular English text should be able to accomplish most tasks faster using commands than using the mouse.
• A new user should be able to complete their first cat record entry within 5 minutes.

Reliability

• Data should be automatically saved after each operation without requiring manual saving.
• Data should be fully recoverable after an unexpected application crash.

Maintainability

• Adding new fields should not require significant code refactoring.

Portability

• The system’s data should be exportable to open, human-readable formats (e.g. HTML) to facilitate backup, migration, and interoperability with other systems.

{More to be added}

Glossary

• Mainstream OS: Windows, Linux, Unix, MacOS
• JavaFX: A Java library used to build the graphical user interface (GUI) of this application
• FXML: An XML-based file format used by JavaFX to define the layout and structure of UI components separately from application logic
• Component: A self-contained, replaceable part of the application (e.g., UI, Logic, Model, Storage), each responsible for a distinct concern and communicating with others only through defined interfaces
• Coupling: The degree of dependency between components. Low coupling is preferred, as it means changes to one component are less likely to break others
• Model: The component that holds all in-memory application data (cat entries)
• ObservableList: A JavaFX list that automatically notifies listeners (such as the UI) when its contents change, enabling the display to refresh without manual intervention
• Filtered List: A view of the full entry list showing only entries that match current search criteria. It updates dynamically as the underlying data or filter changes
• State/CatPals state: A complete snapshot of the application’s data at a given point in time. Used by the undo feature to restore previous versions
• Sequence Diagram: A UML diagram showing how objects interact with each other in a specific time-ordered sequence of method calls
• Activity diagram: A UML diagram showing the flow of control through a process, including decision points and parallel actions
• Class diagram: A UML diagram showing the structure of classes, their attributes, methods, and relationships (e.g., inheritance, association)
• MSS: Main Success Scenario. The primary, happy-path flow of a use case, describing what happens when everything goes as expected with no errors or exceptions
• PlantUML: A tool that generates UML diagrams from plain text descriptions. The .puml files in this project define all architectural diagrams
• Lifeline (in sequence diagrams): The vertical dashed line in a sequence diagram representing an object’s existence over time. It ends with a destroy marker (X) when the object is no longer needed

---

Appendix: Instructions for manual testing

Given below are instructions to test the app manually.

Test setup

1. Download the latest catpals.jar into an empty folder.
2. Ensure Java 17 or above is installed.
3. Launch with java -jar catpals.jar from that folder.
4. Ensure data/addressbook.json is created after first successful data-changing command.
5. Keep a backup copy of data/addressbook.json before destructive tests (clear, malformed file tests).

Launch, shutdown, and UI state

1. Initial launch
   1. Run java -jar catpals.jar.
   2. Expected: splash screen appears, then main window opens after pressing Space.
   3. Expected: sample cat entries are shown on first run.
2. Window preference persistence
   1. Resize and reposition the app window.
   2. Close and relaunch.
   3. Expected: window size and position are restored.
3. Keyboard navigation
   1. Use Up / Down arrows in command box.
   2. Expected: selected cat changes and detail panel updates.
4. Graceful exit
   1. Run exit.
   2. Expected: app closes without errors.

Command parsing and basic validation

1. Unknown command
   1. Test case: foobar
   2. Expected: error indicating unknown command.
2. Case-insensitive command words where supported
   1. Test cases: FIND n/Bowie, HeLp, LiSt.
   2. Expected: command behavior matches lowercase equivalent.
3. Extra parameters policy checks
   1. Test cases: help extra, clear extra, exit extra, list extra
   2. Expected: command still executes (extra text ignored).

Feature-level test cases

Add

1. Valid add
   1. Test case: add n/Brownie t/Friendly t/Orange l/Utown h/Healthy
   2. Expected: new cat appears in list with all fields.
2. Required fields missing
   1. Test case: add n/Brownie l/Utown
   2. Expected: parse/usage error.
3. Trait constraints
   1. Test case: more than 3 traits.
   2. Expected: validation error.
   3. Test case: duplicate trait values.
   4. Expected: validation error.
4. Location constraints
   1. Test case: duplicate location prefixes (e.g. add n/Brownie t/Friendly l/Utown l/Science).
   2. Expected: error message “Multiple values specified for the following single-valued field(s): l/”.
5. Duplicate identity
   1. Add a cat, then add another with same name.
   2. Expected: duplicate-cat rejection.

Attach

1. Attach by index
   1. Test case: attach 1 images/bowie.png
   2. Expected: selected cat displays image (if path exists).
2. Attach by name
   1. Test case: attach Bowie images/bowie.png
   2. Expected: matching cat gets image.
3. Invalid path
   1. Test case: attach 1 images/does-not-exist.png
   2. Expected: command fails with invalid path/file message.
4. Invalid target
   1. Test case: attach 999 images/bowie.png
   2. Expected: invalid index error.

Update

1. Update by index
   1. Test case: update 1 n/Snowy t/White l/COM3 h/Vaccinated
   2. Expected: cat fields update after confirmation.
2. Update by current name
   1. Test case: update Snowy h/Healthy
   2. Expected: correct cat updated.
3. No fields provided
   1. Test case: update 1
   2. Expected: error indicating at least one field required.
4. Trait replacement semantics
   1. Test case: update 1 t/Shy
   2. Expected: existing traits are replaced by only Shy.
5. Cancel path
   1. Run valid update, then cancel at confirmation dialog.
   2. Expected: no data change.

Find and list interaction

1. Single-field find
   1. Test case: find n/Bow
   2. Expected: only matching names remain in filtered list.

2.Multi-field find

1. Test case: find l/Utown t/Friendly

2. Expected: results satisfy all specified field groups.

3. No match behavior
   1. Test case: find n/NoSuchCat
   2. Expected: empty list and no-match message.
4. Reset after filtering
   1. Test case: run any find, then list.
   2. Expected: full cat list is shown again.

Delete

1. Delete by filtered index
   1. Run find to reduce list.
   2. Test case: delete 1
   3. Expected: first cat in filtered view is removed after confirmation.
2. Delete by name
   1. Test case: delete Brownie
   2. Expected: cat with that name is removed after confirmation.
3. Invalid index/name
   1. Test cases: delete 0, delete 999, delete NoSuchCat
   2. Expected: command fails without data change.
4. Cancel path
   1. Run valid delete, then cancel confirmation.
   2. Expected: no deletion occurs.

Export

1. Default export
   1. Test case: export
   2. Expected: export.html is created in app folder.
2. Custom filename
   1. Test case: export utown cats
   2. Expected: utown-cats.html is created.
3. Filter-aware export
   1. Run find l/Utown, then export subset.
   2. Expected: exported file contains only currently displayed cats.
4. Invalid filename characters
   1. Test case: export bad:name
   2. Expected: validation error; no file created.

Clear

1. Confirm clear
   1. Test case: clear
   2. Confirm dialog.
   3. Expected: all cats removed.
2. Cancel clear
   1. Test case: clear, then cancel.
   2. Expected: list remains unchanged.

Help

1. Open help UI
   1. Test case: help
   2. Expected: help window/panel is shown.

Undo

1. Undo supported commands
   1. Perform add, then undo.
   2. Expected: confirmation dialog appears showing the full add command. After confirming, added cat is reverted.
   3. Repeat for delete, update, and attach.
2. Undo after read-only commands (state preserved)
   1. Run add, then find, then undo.
   2. Expected: undo still works — the add is reverted because read-only commands preserve the undo state.
   3. Run add, then list, then undo.
   4. Expected: undo still works — the add is reverted.
3. Undo after clear (state cleared)
   1. Run add, then clear, then undo.
   2. Expected: Nothing to undo. (clear clears the undo state).
4. Undo with no prior undoable command
   1. Launch app fresh, then undo.
   2. Expected: Nothing to undo.
5. Repeated undo
   1. Run one undoable command, then undo twice.
   2. Expected: first succeeds (with confirmation dialog), second reports nothing to undo.
6. Undo confirmation cancel
   1. Run add, then undo, then press Escape on the confirmation dialog.
   2. Expected: undo is cancelled, the added cat remains.

Data persistence and recovery tests

1. Persistence across restart

   1. Add/update/delete at least one cat.
   2. Close app and relaunch.
   3. Expected: latest data state is preserved.
2. Missing data file
   1. Close app.
   2. Rename data/addressbook.json to addressbook.backup.json.
   3. Relaunch.
   4. Expected: app starts with empty/sample fallback state (no crash), and recreates data file when data changes are made.
3. Corrupted data file
   1. Close app.
   2. Edit data/addressbook.json and intentionally break JSON syntax.
   3. Relaunch.
   4. Expected: app handles read failure gracefully (error log/message) and starts without crashing.
   5. Restore backup file and relaunch to continue normal testing.

Regression checklist (quick pass before release)

1. add, update, delete, attach still work end-to-end.
2. find + list interaction remains correct.
3. export output file is generated and readable in browser.
4. clear confirmation works and clears all entries.
5. undo behavior matches current one-level design and command support.
6. Data survives restart and window preferences persist.