From c8e7f83098c4434fff119ffba76f5c0714eecedb Mon Sep 17 00:00:00 2001
From: Harkamal Randhawa <harkamalsr@gmail.com>
Date: Mon, 20 Apr 2026 15:43:11 -0600
Subject: [PATCH] comment backend events and utils

---
 .../main/java/com/petshop/backend/BackendApplication.java  | 7 +++++++
 .../main/java/com/petshop/backend/DevStackApplication.java | 7 +++++++
 .../java/com/petshop/backend/DockerComposeSupport.java     | 7 +++++++
 .../main/java/com/petshop/backend/PortCleanupSupport.java  | 7 +++++++
 .../java/com/petshop/backend/ResetDatabaseApplication.java | 7 +++++++
 .../com/petshop/backend/RuntimeClasspathValidator.java     | 7 +++++++
 .../com/petshop/backend/event/AdoptionConfirmedEvent.java  | 7 +++++++
 .../com/petshop/backend/event/AdoptionReminderEvent.java   | 7 +++++++
 .../petshop/backend/event/AppointmentConfirmedEvent.java   | 7 +++++++
 .../petshop/backend/event/AppointmentReminderEvent.java    | 7 +++++++
 .../java/com/petshop/backend/event/EmailEventListener.java | 7 +++++++
 .../java/com/petshop/backend/event/SaleReceiptEvent.java   | 7 +++++++
 .../com/petshop/backend/exception/ApiErrorResponder.java   | 7 +++++++
 .../com/petshop/backend/exception/ApiErrorResponse.java    | 7 +++++++
 .../com/petshop/backend/exception/BusinessException.java   | 7 +++++++
 .../com/petshop/backend/exception/ConflictException.java   | 7 +++++++
 .../petshop/backend/exception/GlobalExceptionHandler.java  | 7 +++++++
 .../backend/exception/ResourceNotFoundException.java       | 7 +++++++
 .../com/petshop/backend/util/AuthenticationHelper.java     | 7 +++++++
 .../main/java/com/petshop/backend/util/ContentFilter.java  | 7 +++++++
 .../java/com/petshop/backend/util/ImageValidationUtil.java | 7 +++++++
 .../src/main/java/com/petshop/backend/util/PhoneUtils.java | 7 +++++++
 .../main/java/com/petshop/backend/util/SafeContent.java    | 7 +++++++
 .../com/petshop/backend/util/SafeContentValidator.java     | 7 +++++++
 .../main/java/com/petshop/backend/util/StringUtils.java    | 7 +++++++
 25 files changed, 175 insertions(+)

diff --git a/backend/src/main/java/com/petshop/backend/BackendApplication.java b/backend/src/main/java/com/petshop/backend/BackendApplication.java
index 584a7fd0..0731544b 100644
--- a/backend/src/main/java/com/petshop/backend/BackendApplication.java
+++ b/backend/src/main/java/com/petshop/backend/BackendApplication.java
@@ -1,3 +1,10 @@
+/*
+ * Main entry point for the pet shop backend application.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend;
 
 import com.petshop.backend.config.BusinessProperties;
diff --git a/backend/src/main/java/com/petshop/backend/DevStackApplication.java b/backend/src/main/java/com/petshop/backend/DevStackApplication.java
index 27933d4b..8effc5cb 100644
--- a/backend/src/main/java/com/petshop/backend/DevStackApplication.java
+++ b/backend/src/main/java/com/petshop/backend/DevStackApplication.java
@@ -1,3 +1,10 @@
+/*
+ * Starts the backend with Docker and auto-reload for development.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend;
 
 import com.petshop.backend.config.FlywayContextInitializer;
diff --git a/backend/src/main/java/com/petshop/backend/DockerComposeSupport.java b/backend/src/main/java/com/petshop/backend/DockerComposeSupport.java
index 4832de9b..4f02ced2 100644
--- a/backend/src/main/java/com/petshop/backend/DockerComposeSupport.java
+++ b/backend/src/main/java/com/petshop/backend/DockerComposeSupport.java
@@ -1,3 +1,10 @@
+/*
+ * Manages Docker Compose for the development database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend;
 
 import java.io.BufferedReader;
diff --git a/backend/src/main/java/com/petshop/backend/PortCleanupSupport.java b/backend/src/main/java/com/petshop/backend/PortCleanupSupport.java
index c6cb5d9b..fb941119 100644
--- a/backend/src/main/java/com/petshop/backend/PortCleanupSupport.java
+++ b/backend/src/main/java/com/petshop/backend/PortCleanupSupport.java
@@ -1,3 +1,10 @@
+/*
+ * Frees up a port by stopping whatever process is using it.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend;
 
 import java.io.BufferedReader;
diff --git a/backend/src/main/java/com/petshop/backend/ResetDatabaseApplication.java b/backend/src/main/java/com/petshop/backend/ResetDatabaseApplication.java
index 72c43ac7..6bb9c011 100644
--- a/backend/src/main/java/com/petshop/backend/ResetDatabaseApplication.java
+++ b/backend/src/main/java/com/petshop/backend/ResetDatabaseApplication.java
@@ -1,3 +1,10 @@
+/*
+ * Resets the development database by recreating the Docker container.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend;
 
 public class ResetDatabaseApplication {
diff --git a/backend/src/main/java/com/petshop/backend/RuntimeClasspathValidator.java b/backend/src/main/java/com/petshop/backend/RuntimeClasspathValidator.java
index e123f66a..2b59bd93 100644
--- a/backend/src/main/java/com/petshop/backend/RuntimeClasspathValidator.java
+++ b/backend/src/main/java/com/petshop/backend/RuntimeClasspathValidator.java
@@ -1,3 +1,10 @@
+/*
+ * Checks that required resources are on the classpath at startup.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend;
 
 import java.net.URL;
diff --git a/backend/src/main/java/com/petshop/backend/event/AdoptionConfirmedEvent.java b/backend/src/main/java/com/petshop/backend/event/AdoptionConfirmedEvent.java
index 87dad0ee..68a8fa77 100644
--- a/backend/src/main/java/com/petshop/backend/event/AdoptionConfirmedEvent.java
+++ b/backend/src/main/java/com/petshop/backend/event/AdoptionConfirmedEvent.java
@@ -1,3 +1,10 @@
+/*
+ * Event fired when an adoption is confirmed.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.event;
 
 public record AdoptionConfirmedEvent(Long adoptionId) {}
diff --git a/backend/src/main/java/com/petshop/backend/event/AdoptionReminderEvent.java b/backend/src/main/java/com/petshop/backend/event/AdoptionReminderEvent.java
index bfc3be52..0130031f 100644
--- a/backend/src/main/java/com/petshop/backend/event/AdoptionReminderEvent.java
+++ b/backend/src/main/java/com/petshop/backend/event/AdoptionReminderEvent.java
@@ -1,3 +1,10 @@
+/*
+ * Event fired to send an adoption reminder email.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.event;
 
 public record AdoptionReminderEvent(Long adoptionId) {}
diff --git a/backend/src/main/java/com/petshop/backend/event/AppointmentConfirmedEvent.java b/backend/src/main/java/com/petshop/backend/event/AppointmentConfirmedEvent.java
index 9311e8dc..7a63a5d9 100644
--- a/backend/src/main/java/com/petshop/backend/event/AppointmentConfirmedEvent.java
+++ b/backend/src/main/java/com/petshop/backend/event/AppointmentConfirmedEvent.java
@@ -1,3 +1,10 @@
+/*
+ * Event fired when an appointment is confirmed.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.event;
 
 public record AppointmentConfirmedEvent(Long appointmentId) {}
diff --git a/backend/src/main/java/com/petshop/backend/event/AppointmentReminderEvent.java b/backend/src/main/java/com/petshop/backend/event/AppointmentReminderEvent.java
index c8de75ce..c7112a30 100644
--- a/backend/src/main/java/com/petshop/backend/event/AppointmentReminderEvent.java
+++ b/backend/src/main/java/com/petshop/backend/event/AppointmentReminderEvent.java
@@ -1,3 +1,10 @@
+/*
+ * Event fired to send an appointment reminder email.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.event;
 
 public record AppointmentReminderEvent(Long appointmentId) {}
diff --git a/backend/src/main/java/com/petshop/backend/event/EmailEventListener.java b/backend/src/main/java/com/petshop/backend/event/EmailEventListener.java
index 71e0cbf6..ad9808a7 100644
--- a/backend/src/main/java/com/petshop/backend/event/EmailEventListener.java
+++ b/backend/src/main/java/com/petshop/backend/event/EmailEventListener.java
@@ -1,3 +1,10 @@
+/*
+ * Listens for events and sends the matching emails.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.event;
 
 import com.petshop.backend.repository.AdoptionRepository;
diff --git a/backend/src/main/java/com/petshop/backend/event/SaleReceiptEvent.java b/backend/src/main/java/com/petshop/backend/event/SaleReceiptEvent.java
index d21df856..4390b79e 100644
--- a/backend/src/main/java/com/petshop/backend/event/SaleReceiptEvent.java
+++ b/backend/src/main/java/com/petshop/backend/event/SaleReceiptEvent.java
@@ -1,3 +1,10 @@
+/*
+ * Event fired to send a sale receipt email.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.event;
 
 public record SaleReceiptEvent(Long saleId) {}
diff --git a/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponder.java b/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponder.java
index 0fcb82ec..9790a8e6 100644
--- a/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponder.java
+++ b/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponder.java
@@ -1,3 +1,10 @@
+/*
+ * Writes error responses to the client in a consistent format.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.exception;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
diff --git a/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponse.java b/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponse.java
index b3aea542..4f63487a 100644
--- a/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponse.java
+++ b/backend/src/main/java/com/petshop/backend/exception/ApiErrorResponse.java
@@ -1,3 +1,10 @@
+/*
+ * Holds the structure of an error response sent to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.exception;
 
 import java.time.LocalDateTime;
diff --git a/backend/src/main/java/com/petshop/backend/exception/BusinessException.java b/backend/src/main/java/com/petshop/backend/exception/BusinessException.java
index 005ee62b..b42f425b 100644
--- a/backend/src/main/java/com/petshop/backend/exception/BusinessException.java
+++ b/backend/src/main/java/com/petshop/backend/exception/BusinessException.java
@@ -1,3 +1,10 @@
+/*
+ * Thrown when a business rule is violated.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.exception;
 
 public class BusinessException extends RuntimeException {
diff --git a/backend/src/main/java/com/petshop/backend/exception/ConflictException.java b/backend/src/main/java/com/petshop/backend/exception/ConflictException.java
index a0112782..cbbfecc4 100644
--- a/backend/src/main/java/com/petshop/backend/exception/ConflictException.java
+++ b/backend/src/main/java/com/petshop/backend/exception/ConflictException.java
@@ -1,3 +1,10 @@
+/*
+ * Thrown when a request conflicts with existing data.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.exception;
 
 public class ConflictException extends RuntimeException {
diff --git a/backend/src/main/java/com/petshop/backend/exception/GlobalExceptionHandler.java b/backend/src/main/java/com/petshop/backend/exception/GlobalExceptionHandler.java
index ed070aed..f68d5c93 100644
--- a/backend/src/main/java/com/petshop/backend/exception/GlobalExceptionHandler.java
+++ b/backend/src/main/java/com/petshop/backend/exception/GlobalExceptionHandler.java
@@ -1,3 +1,10 @@
+/*
+ * Catches all exceptions and returns proper error responses.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.exception;
 
 import com.petshop.backend.service.PetService;
diff --git a/backend/src/main/java/com/petshop/backend/exception/ResourceNotFoundException.java b/backend/src/main/java/com/petshop/backend/exception/ResourceNotFoundException.java
index 08b426b7..f9d2126c 100644
--- a/backend/src/main/java/com/petshop/backend/exception/ResourceNotFoundException.java
+++ b/backend/src/main/java/com/petshop/backend/exception/ResourceNotFoundException.java
@@ -1,3 +1,10 @@
+/*
+ * Thrown when a requested resource does not exist.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.exception;
 
 public class ResourceNotFoundException extends RuntimeException {
diff --git a/backend/src/main/java/com/petshop/backend/util/AuthenticationHelper.java b/backend/src/main/java/com/petshop/backend/util/AuthenticationHelper.java
index 71f041ab..e63d048e 100644
--- a/backend/src/main/java/com/petshop/backend/util/AuthenticationHelper.java
+++ b/backend/src/main/java/com/petshop/backend/util/AuthenticationHelper.java
@@ -1,3 +1,10 @@
+/*
+ * Retrieves the currently logged-in user from the security context.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.util;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/util/ContentFilter.java b/backend/src/main/java/com/petshop/backend/util/ContentFilter.java
index 0552b2d2..8f1e4ec5 100644
--- a/backend/src/main/java/com/petshop/backend/util/ContentFilter.java
+++ b/backend/src/main/java/com/petshop/backend/util/ContentFilter.java
@@ -1,3 +1,10 @@
+/*
+ * Checks user input for scripts and inappropriate language.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.util;
 
 import com.petshop.backend.exception.BusinessException;
diff --git a/backend/src/main/java/com/petshop/backend/util/ImageValidationUtil.java b/backend/src/main/java/com/petshop/backend/util/ImageValidationUtil.java
index 4ab26d2b..c5d1ef05 100644
--- a/backend/src/main/java/com/petshop/backend/util/ImageValidationUtil.java
+++ b/backend/src/main/java/com/petshop/backend/util/ImageValidationUtil.java
@@ -1,3 +1,10 @@
+/*
+ * Validates uploaded image files for type and size.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.util;
 
 import com.petshop.backend.exception.BusinessException;
diff --git a/backend/src/main/java/com/petshop/backend/util/PhoneUtils.java b/backend/src/main/java/com/petshop/backend/util/PhoneUtils.java
index cf9646ba..8dd979e0 100644
--- a/backend/src/main/java/com/petshop/backend/util/PhoneUtils.java
+++ b/backend/src/main/java/com/petshop/backend/util/PhoneUtils.java
@@ -1,3 +1,10 @@
+/*
+ * Formats and normalizes phone numbers.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.util;
 
 public class PhoneUtils {
diff --git a/backend/src/main/java/com/petshop/backend/util/SafeContent.java b/backend/src/main/java/com/petshop/backend/util/SafeContent.java
index 6db91b6e..bd703239 100644
--- a/backend/src/main/java/com/petshop/backend/util/SafeContent.java
+++ b/backend/src/main/java/com/petshop/backend/util/SafeContent.java
@@ -1,3 +1,10 @@
+/*
+ * Annotation that marks a field for content safety validation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.util;
 
 import jakarta.validation.Constraint;
diff --git a/backend/src/main/java/com/petshop/backend/util/SafeContentValidator.java b/backend/src/main/java/com/petshop/backend/util/SafeContentValidator.java
index 6d3af630..72c26fc1 100644
--- a/backend/src/main/java/com/petshop/backend/util/SafeContentValidator.java
+++ b/backend/src/main/java/com/petshop/backend/util/SafeContentValidator.java
@@ -1,3 +1,10 @@
+/*
+ * Validates fields annotated with SafeContent for dangerous input.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.util;
 
 import jakarta.validation.ConstraintValidator;
diff --git a/backend/src/main/java/com/petshop/backend/util/StringUtils.java b/backend/src/main/java/com/petshop/backend/util/StringUtils.java
index fd795822..19f58b62 100644
--- a/backend/src/main/java/com/petshop/backend/util/StringUtils.java
+++ b/backend/src/main/java/com/petshop/backend/util/StringUtils.java
@@ -1,3 +1,10 @@
+/*
+ * Helper methods for trimming and formatting strings.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.util;
 
 public final class StringUtils {