Developer Guide

🎉 Welcome to ModMate, your ultimate companion for managing your modules and timetables at the National University of Singapore (NUS)!

📚 ModMate is designed to help students efficiently organize their academic schedules, bookmark favorite modules, and explore detailed module information.

✨ Whether you’re a student looking to streamline your academic life, an instructor reviewing this project, or a curious reader, ModMate offers a simple and intuitive command-line interface to create personalized timetables, manage modules, and much more.

💡 This project is part of the CS2113 course at NUS and was taken in AY2024-2025 Semester 2.

Acknowledgements
Glossary
Setting up in IntelliJ
Design
1. Architecture
2. How Components Interact
Implementation
Product Scope
1. Target User Profile
2. Value Proposition
User Stories
Non-Functional Requirements
Appendix: Instructions for Manual Testing

Acknowledgements

The application integrates with the NUSMods API to fetch module data. Special thanks to the NUSMods team for providing their publicly available API.
Command parsing logic is inspired by AddressBook-Level3.
UML diagrams were created using PlantUML.

Glossary

Module - A course or subject offered by the university.
Timetable - A schedule of modules organized by semester.
CLI - Command Line Interface, a text-based user interface.

Setting up in IntelliJ

Prerequisites: JDK 17 (use the exact version), update IntelliJ to the most recent version.

Ensure IntelliJ JDK 17 is defined as an SDK, as described here – this step is not needed if you have used JDK 17 in a previous IntelliJ project.
Import the project as a Gradle project, as described here.
Verify the setup: After the importing is complete, locate the src/main/java/modmate/Main.java file, right-click it, and choose Run Main.main(). If the setup is correct, you should see something like the below:
```
> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes

> Task :Main.main()
```

Keep the src\main\java folder as the root folder for Java files (i.e., don’t rename those folders or move Java files to another folder outside of this folder path), as this is the default location some tools (e.g., Gradle) expect to find Java files.

Design

Architecture

Architecture Diagram

The Architecture Diagram above provides a high-level overview of the system. It shows the main components of the application and how they interact with each other.

Main components of the architecture:

Main: Handles application startup and shutdown. It initializes and connects the other components.
Command: Encapsulates user actions such as adding modules, searching for modules, or viewing timetables.
CommandLine: Parses user input and maps it to specific commands.
LogUtil: Provides centralized logging functionality for debugging and tracking application behavior.

How Components Interact

User Input: The user enters a command via the CLI.
Command Parsing: The CommandLine component parses the input and creates the appropriate Command object.
Command Execution: The Command interacts with other components to perform the requested operation.
API Interaction: If module data is required, the Command invokes NUSModsAPI, which uses HttpUtil to fetch data from the NUSMods API and processes it using JsonParser.
Data Update: The application’s state is updated based on the command’s execution.
Output Display: The results of the operation are displayed to the user.

This design ensures a clear separation of concerns, making the application modular and easier to maintain.

Implementation

View Module Details Feature

Proposed Implementation

The viewMod feature allows users to retrieve and display details about a module by providing its code or name. This functionality relies on fetching module data from an external API and handling cases where the requested module is not found. The feature is implemented in the viewMod function, which operates as follows:

It asserts that the input is neither null nor empty.
It attempts to retrieve the module using modFromCodeOrName.
If a match is found, it displays the detailed module information and logs the action.
If no match is found, it informs the user and logs the failure.

This feature involves the following key operations:

viewMod(inputCodeOrName): Main entry point for viewing module details.
modFromCodeOrName(modCodeOrNameGiven): Attempts to find a module based on the provided code or name.
fetchModuleByCode(moduleCode): Fetches module details from the NUSMods API.

Example Usage Scenario

1. The user enters a module code or name. The viewMod function is triggered, and the system logs the request.

2. The system checks for a module matching the provided input using modFromCodeOrName. If found, it retrieves full details from fetchModuleByCode.

3a. If a module is found, its details are displayed, and a log entry is saved.

3b. If no module is found, an error message is displayed, and the failure is logged.

Design Considerations

Data Retrieval Method
- Alternative 1 (Current Choice): Fetch from External API Each Time
  - Pros: Ensures the latest module details are always retrieved.
  - Cons: API calls may introduce latency.
- Alternative 2: Cache Module Data Locally
  - Pros: Reduces API calls, improving performance.
  - Cons: Data may become outdated without a refresh mechanism.
Error Handling
- Alternative 1 (Current Choice): Log Errors and Return Empty Result
  - Pros: Ensures errors are recorded for debugging.
  - Cons: Users do not receive detailed error messages.
- Alternative 2: Provide User-Friendly Error Messages
  - Pros: Helps users understand failures.
  - Cons: Adds complexity in differentiating error types.

Summary

The viewMod feature provides a simple way to retrieve and display module details based on user input. It ensures robustness by handling errors and logging events while maintaining a straightforward implementation that prioritizes real-time data retrieval. Future improvements may include caching for performance optimization and enhanced error messaging.

Timetable Management Feature

Purpose

Allows users to create, update, and view multiple academic schedules.

Implementation

Two core methods in the User class:

addTimetable(String timetableName) - Method to add a new timetable for the user.
getTimetable(String timetableName) - Method to display the user’s timetables (mods included in the timetable).

These methods are supported by Schedule class for storage structure:

addTimetable(String timetableName) first checks whether there are any duplicate timetables with the same name.

It checks through a list called List<Schedule> timetables and if duplicate timetable found, an error message, “Timetable ‘X’ already exists”, will be displayed.

If no duplicate timetable found, a new Schedule object is instantiated and a new timetable of timetableName will be created. It is added to timetables list, after which a success message, “Timetable ‘X’ created successfully”, is displayed.
getTimetable(String timetableName) searches through a list called timetables, as mentioned earlier.

If timetable with corresponding timetableName is found, a formatted String is returned which shows, the timetable name, all added modules and module details.

If timetable is not found, an error message, “Timetable ‘X’ not found”, will be displayed.

Design Rationale

Usage of List<Schedule> allowed for maintainable insertion order of timetables and straightforward iteration.
Moreover, with the timetable duplication checking it allows for unnecessary object creation and potential naming conflicts.

Possible Extensions: Merging of multiple timetables

The following UML Sequence diagram effectively shows how these two methods are implemented with the inclusion of user inputs of createtimetable and timetable for addTimetable(String timetableName) and getTimetable(String timetableName) respectively.

Adding/Removing a mod to a timetable

Adds/Removes a new module (Mod) to a specified timetable.

Format: addModToTimetable TIMETABLE_NAME MOD_CODE_OR_NAME removeModFromTimetable TIMETABLE_NAME MOD_CODE_OR_NAME

The TIMETABLE_NAME is the name of the timetable to which the module is being added.
The MOD_CODE_OR_NAME is the code or name of the module to add/remove.
The operation checks for the timetable and module’s existence, adds/removes the module to the timetable, and saves the updated state.

Example Usage:

addModToTimetable "Fall 2025 Schedule" "CS1010"

This will add the module CS1010 to the timetable “Fall 2025 Schedule”.

Design Explanation

addModToTimetable:
- Loops through the timetables list to find a timetable by name (case-insensitive).
- Calls addMod on the found timetable to add the Mod object.
- If no timetable is found, an error message is printed.
removeModFromTimetable:
- Functions similarly to addModToTimetable, but calls removeMod instead of addMod on the timetable.

Alternatives Considered

Optimization with a Map:
- Instead of searching through the entire list of Timetable objects every time, we could use a Map<String, Timetable>, where the key is the timetable name. This would speed up lookups to O(1) time complexity, providing faster access when managing timetables.
Error Handling:
- Current Approach: Instead of just printing an error, we could throw a custom exception (e.g., TimetableNotFoundException) when a timetable is not found. This would formalize error handling and make it easier to manage error propagation through the system.
- Pros: Clear and formal error management, making it easier to debug and handle specific cases.
- Cons: Adds complexity, especially if the exception handling needs to be propagated or caught higher in the stack.

Sequence Diagram

SequenceDiagram

Schedule Management within Timetables

Purpose: Allows users to select their preferred modules, based on accurate data provided by NUSMods
Implementation: The Schedule class provides methods to add, remove, and view modules. The class is built on top of the Timetable class, which is the internal format NUSMods stores its timetable data in. Each class session is represented as a Lesson object; one of which contains the type (lecture, tutorial, lab, etc.), its period (day & time), and the class venue.
- Furthermore, in conjunction with ScheduleMod, users can select the lecture, tutorial, and lab slots they would attend, to allow for more granular selection and modification of the timetables.
Rationale: Encapsulating timetable logic in a dedicated class improves maintainability and testability.

The class diagram that represents the overview of the Schedule class is shown below: