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/config/ActivityLoggingFilter.java b/backend/src/main/java/com/petshop/backend/config/ActivityLoggingFilter.java
index 0c30cece..ef6749da 100644
--- a/backend/src/main/java/com/petshop/backend/config/ActivityLoggingFilter.java
+++ b/backend/src/main/java/com/petshop/backend/config/ActivityLoggingFilter.java
@@ -1,3 +1,11 @@
+/*
+ * Logs write operations (POST, PUT, DELETE) to the activity log.
+ * Skips GET requests and internal endpoints like health checks.
+ * Builds a human-readable description for each action.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import com.petshop.backend.entity.User;
@@ -77,11 +85,24 @@ public class ActivityLoggingFilter extends OncePerRequestFilter {
         activityLogService.record(userId, activity);
     }
 
+    /**
+     * Turns a request method + URL + status into a human-readable description
+     * like "Created a new product" or "Failed login attempt".
+     * Parses the URL as /api/v1/{resource}/{id?}/{sub?}/{subsub?} and matches
+     * against known patterns.
+     * @param method HTTP method (GET, POST, etc.)
+     * @param rawUri the request URI, possibly with query params
+     * @param status the HTTP response status code
+     * @return a readable description, or null if we don't recognize the pattern
+     */
     private String describe(String method, String rawUri, int status) {
+        // Strip query params so we only deal with the path
         String uri = rawUri.contains("?") ? rawUri.substring(0, rawUri.indexOf('?')) : rawUri;
+        // Split into segments: [api, v1, resource, id/action, sub, ...]
         String[] parts = uri.replaceFirst("^/+", "").split("/");
         if (parts.length < 3) return null;
 
+        // parts[2] is the resource name (e.g. "products", "auth", "cart")
         String r = parts[2];
         String seg3 = parts.length > 3 ? parts[3] : null;
         String seg4 = parts.length > 4 ? parts[4] : null;
@@ -89,6 +110,8 @@ public class ActivityLoggingFilter extends OncePerRequestFilter {
 
         boolean seg3IsId = seg3 != null && seg3.matches("\\d+");
         boolean seg4IsId = seg4 != null && seg4.matches("\\d+");
+        // Normalize: if seg3 is a numeric ID, treat seg4 as the sub-action
+        // otherwise seg3 itself is the sub-action (like "login", "add", etc.)
         String id = seg3IsId ? seg3 : null;
         String sub = seg3IsId ? seg4 : seg3;
         String subsub = seg3IsId ? seg5 : seg4;
diff --git a/backend/src/main/java/com/petshop/backend/config/ActivityLoggingFilterRegistrationConfig.java b/backend/src/main/java/com/petshop/backend/config/ActivityLoggingFilterRegistrationConfig.java
index 66427661..b57f574d 100644
--- a/backend/src/main/java/com/petshop/backend/config/ActivityLoggingFilterRegistrationConfig.java
+++ b/backend/src/main/java/com/petshop/backend/config/ActivityLoggingFilterRegistrationConfig.java
@@ -1,3 +1,9 @@
+/*
+ * Registers the activity logging filter with the servlet container.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import org.springframework.boot.web.servlet.FilterRegistrationBean;
diff --git a/backend/src/main/java/com/petshop/backend/config/ApplicationStartupListener.java b/backend/src/main/java/com/petshop/backend/config/ApplicationStartupListener.java
index 24ad9a6a..f937ad82 100644
--- a/backend/src/main/java/com/petshop/backend/config/ApplicationStartupListener.java
+++ b/backend/src/main/java/com/petshop/backend/config/ApplicationStartupListener.java
@@ -1,3 +1,9 @@
+/*
+ * Runs once on startup to mark past appointments as completed.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import com.petshop.backend.service.AppointmentService;
diff --git a/backend/src/main/java/com/petshop/backend/config/BusinessProperties.java b/backend/src/main/java/com/petshop/backend/config/BusinessProperties.java
index 6d1cee18..d154fe7e 100644
--- a/backend/src/main/java/com/petshop/backend/config/BusinessProperties.java
+++ b/backend/src/main/java/com/petshop/backend/config/BusinessProperties.java
@@ -1,3 +1,10 @@
+/*
+ * Business settings loaded from application.yml (store hours,
+ * slot intervals, image size limits, discount/loyalty config).
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
diff --git a/backend/src/main/java/com/petshop/backend/config/CacheConfig.java b/backend/src/main/java/com/petshop/backend/config/CacheConfig.java
index 4a8bc6b0..839002ca 100644
--- a/backend/src/main/java/com/petshop/backend/config/CacheConfig.java
+++ b/backend/src/main/java/com/petshop/backend/config/CacheConfig.java
@@ -1,3 +1,10 @@
+/*
+ * Sets up Caffeine caching for the app. Currently used to cache
+ * user auth lookups so the filter doesn't query the DB every time.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import com.github.benmanes.caffeine.cache.Caffeine;
diff --git a/backend/src/main/java/com/petshop/backend/config/DataInitializer.java b/backend/src/main/java/com/petshop/backend/config/DataInitializer.java
index 89cbb18e..56a26deb 100644
--- a/backend/src/main/java/com/petshop/backend/config/DataInitializer.java
+++ b/backend/src/main/java/com/petshop/backend/config/DataInitializer.java
@@ -1,3 +1,11 @@
+/*
+ * Creates default admin, staff, and customer accounts on startup
+ * if they don't already exist. Also fills in missing fields on
+ * existing accounts to keep them consistent.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/config/FlywayContextInitializer.java b/backend/src/main/java/com/petshop/backend/config/FlywayContextInitializer.java
index 15c9b976..94d05d32 100644
--- a/backend/src/main/java/com/petshop/backend/config/FlywayContextInitializer.java
+++ b/backend/src/main/java/com/petshop/backend/config/FlywayContextInitializer.java
@@ -1,3 +1,10 @@
+/*
+ * Runs Flyway migrations before the app starts. Retries up to
+ * 15 times so the app can wait for the database container to be ready.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import org.flywaydb.core.Flyway;
diff --git a/backend/src/main/java/com/petshop/backend/config/LocalCatalogSeedInitializer.java b/backend/src/main/java/com/petshop/backend/config/LocalCatalogSeedInitializer.java
index 18e64f05..74b6bfff 100644
--- a/backend/src/main/java/com/petshop/backend/config/LocalCatalogSeedInitializer.java
+++ b/backend/src/main/java/com/petshop/backend/config/LocalCatalogSeedInitializer.java
@@ -1,3 +1,10 @@
+/*
+ * Adds extra pet and product seed data in the local dev profile
+ * if the database only has the base seed rows.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import com.petshop.backend.repository.PetRepository;
diff --git a/backend/src/main/java/com/petshop/backend/config/TomcatPathToleranceConfig.java b/backend/src/main/java/com/petshop/backend/config/TomcatPathToleranceConfig.java
index 9a89c5ab..7b6b3d7e 100644
--- a/backend/src/main/java/com/petshop/backend/config/TomcatPathToleranceConfig.java
+++ b/backend/src/main/java/com/petshop/backend/config/TomcatPathToleranceConfig.java
@@ -1,3 +1,10 @@
+/*
+ * Tells Tomcat to accept backslashes in URLs so the Android
+ * and desktop clients don't get rejected for path issues.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import org.springframework.boot.tomcat.servlet.TomcatServletWebServerFactory;
diff --git a/backend/src/main/java/com/petshop/backend/config/TrailingSlashNormalizationFilter.java b/backend/src/main/java/com/petshop/backend/config/TrailingSlashNormalizationFilter.java
index 38ececb9..f915ec4f 100644
--- a/backend/src/main/java/com/petshop/backend/config/TrailingSlashNormalizationFilter.java
+++ b/backend/src/main/java/com/petshop/backend/config/TrailingSlashNormalizationFilter.java
@@ -1,3 +1,10 @@
+/*
+ * Strips trailing slashes and normalizes paths so /api/pets/
+ * and /api/pets both hit the same controller.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import jakarta.servlet.FilterChain;
@@ -63,6 +70,12 @@ public class TrailingSlashNormalizationFilter extends OncePerRequestFilter {
         filterChain.doFilter(wrapper, response);
     }
 
+    /**
+     * Cleans up a URL path by fixing backslashes, collapsing double slashes,
+     * lowercasing API/WS paths, and stripping trailing slashes.
+     * @param value the raw path string
+     * @return the normalized path, or null if input was null
+     */
     private String normalizePath(String value) {
         if (value == null) {
             return null;
@@ -74,6 +87,7 @@ public class TrailingSlashNormalizationFilter extends OncePerRequestFilter {
         if (shouldLowercase(normalized)) {
             normalized = normalized.toLowerCase(java.util.Locale.ROOT);
         }
+        // Strip trailing slashes but keep the root "/" intact
         int end = normalized.length();
         while (end > 1 && normalized.charAt(end - 1) == '/') {
             end--;
diff --git a/backend/src/main/java/com/petshop/backend/config/WebSocketAuthChannelInterceptor.java b/backend/src/main/java/com/petshop/backend/config/WebSocketAuthChannelInterceptor.java
index c7f23fc4..0b55b216 100644
--- a/backend/src/main/java/com/petshop/backend/config/WebSocketAuthChannelInterceptor.java
+++ b/backend/src/main/java/com/petshop/backend/config/WebSocketAuthChannelInterceptor.java
@@ -1,3 +1,11 @@
+/*
+ * Intercepts WebSocket messages to authenticate and authorize users.
+ * Validates the token on CONNECT, then checks permissions on
+ * SUBSCRIBE and SEND for chat topics.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import com.petshop.backend.entity.User;
@@ -33,6 +41,14 @@ public class WebSocketAuthChannelInterceptor implements ChannelInterceptor {
         this.chatService = chatService;
     }
 
+    /**
+     * Intercepts every STOMP message before it's sent. On CONNECT it validates the
+     * JWT and stores the authenticated user. On SUBSCRIBE/SEND it checks that the
+     * user has access to the requested chat destination.
+     * @param message the STOMP message being sent
+     * @param channel the channel the message is going through
+     * @return the original message if everything checks out
+     */
     @Override
     public Message<?> preSend(Message<?> message, MessageChannel channel) {
         StompHeaderAccessor accessor = StompHeaderAccessor.wrap(message);
@@ -95,6 +111,14 @@ public class WebSocketAuthChannelInterceptor implements ChannelInterceptor {
         return message;
     }
 
+    /**
+     * Tries to figure out who the user is from multiple sources: the principal on the
+     * message, the session attributes (fallback for some STOMP clients), or by
+     * re-parsing the token from headers as a last resort.
+     * @param principal the principal attached to the message, may be null
+     * @param accessor the STOMP header accessor for fallback lookups
+     * @return the User entity, or null if unauthenticated
+     */
     private User resolveUser(Principal principal, StompHeaderAccessor accessor) {
         Principal currentPrincipal = principal;
         if (currentPrincipal == null && accessor.getSessionAttributes() != null) {
@@ -136,6 +160,13 @@ public class WebSocketAuthChannelInterceptor implements ChannelInterceptor {
         return user;
     }
 
+    /**
+     * Checks if the user is allowed to subscribe to this destination.
+     * Customers can only subscribe to their own conversations, not the
+     * staff-wide conversation feed.
+     * @param destination the STOMP destination being subscribed to
+     * @param user the user trying to subscribe
+     */
     private void authorizeSubscription(String destination, User user) {
         destination = normalizeDestination(destination);
         if (destination == null || destination.startsWith("/user/queue/")) {
@@ -157,6 +188,12 @@ public class WebSocketAuthChannelInterceptor implements ChannelInterceptor {
         throw new IllegalArgumentException("Not authorized to subscribe to destination");
     }
 
+    /**
+     * Checks if the user is allowed to send a message to this destination.
+     * Only allows sending to conversation message endpoints that the user has access to.
+     * @param destination the STOMP destination being sent to
+     * @param user the user trying to send
+     */
     private void authorizeSend(String destination, User user) {
         destination = normalizeDestination(destination);
         Long conversationId = extractConversationId(destination, "/app/chat/conversations/");
diff --git a/backend/src/main/java/com/petshop/backend/config/WebSocketConfig.java b/backend/src/main/java/com/petshop/backend/config/WebSocketConfig.java
index 67dc1048..4ff58981 100644
--- a/backend/src/main/java/com/petshop/backend/config/WebSocketConfig.java
+++ b/backend/src/main/java/com/petshop/backend/config/WebSocketConfig.java
@@ -1,3 +1,10 @@
+/*
+ * WebSocket configuration for the live chat feature.
+ * Registers STOMP endpoints and the auth interceptor.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.config;
 
 import org.springframework.context.annotation.Configuration;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ActivityLogController.java b/backend/src/main/java/com/petshop/backend/controller/ActivityLogController.java
index 6d202ddb..35e9f79c 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ActivityLogController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ActivityLogController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles requests for viewing user activity logs.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.activity.ActivityLogResponse;
diff --git a/backend/src/main/java/com/petshop/backend/controller/AdoptionController.java b/backend/src/main/java/com/petshop/backend/controller/AdoptionController.java
index 1be65273..2fa0fc71 100644
--- a/backend/src/main/java/com/petshop/backend/controller/AdoptionController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/AdoptionController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles pet adoption requests and approvals.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.adoption.AdoptionRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/AiChatController.java b/backend/src/main/java/com/petshop/backend/controller/AiChatController.java
index a20ef4f7..733cafb4 100644
--- a/backend/src/main/java/com/petshop/backend/controller/AiChatController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/AiChatController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles AI-powered chat for getting pet care advice.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.ai.AiChatRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/AnalyticsController.java b/backend/src/main/java/com/petshop/backend/controller/AnalyticsController.java
index 08aea44d..bd7cde45 100644
--- a/backend/src/main/java/com/petshop/backend/controller/AnalyticsController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/AnalyticsController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles dashboard analytics and sales reporting for staff and admins.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.analytics.DashboardResponse;
diff --git a/backend/src/main/java/com/petshop/backend/controller/AppointmentController.java b/backend/src/main/java/com/petshop/backend/controller/AppointmentController.java
index 301b4a77..7ce43cd6 100644
--- a/backend/src/main/java/com/petshop/backend/controller/AppointmentController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/AppointmentController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles booking and managing pet service appointments.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.appointment.AppointmentRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/AuthController.java b/backend/src/main/java/com/petshop/backend/controller/AuthController.java
index e1d14e67..ecbaea8d 100644
--- a/backend/src/main/java/com/petshop/backend/controller/AuthController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/AuthController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles user login, registration, password reset, and profile updates.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.auth.AvatarUploadResponse;
diff --git a/backend/src/main/java/com/petshop/backend/controller/CartController.java b/backend/src/main/java/com/petshop/backend/controller/CartController.java
index 975d786a..bb535b09 100644
--- a/backend/src/main/java/com/petshop/backend/controller/CartController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/CartController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles shopping cart operations like adding and removing items.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.cart.*;
diff --git a/backend/src/main/java/com/petshop/backend/controller/CategoryController.java b/backend/src/main/java/com/petshop/backend/controller/CategoryController.java
index bbce6ec9..da6f3a9f 100644
--- a/backend/src/main/java/com/petshop/backend/controller/CategoryController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/CategoryController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles managing product and pet categories.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.category.CategoryRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ChatController.java b/backend/src/main/java/com/petshop/backend/controller/ChatController.java
index f1e26209..29fef9c1 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ChatController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ChatController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles chat conversations and messages between users.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.chat.ConversationRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ChatWebSocketController.java b/backend/src/main/java/com/petshop/backend/controller/ChatWebSocketController.java
index 4bee487c..84274143 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ChatWebSocketController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ChatWebSocketController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles real-time chat messaging over WebSocket connections.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.config.WebSocketAuthChannelInterceptor;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ContactController.java b/backend/src/main/java/com/petshop/backend/controller/ContactController.java
index cfd4326f..f91fa983 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ContactController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ContactController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles sending contact form messages from customers.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/controller/CouponController.java b/backend/src/main/java/com/petshop/backend/controller/CouponController.java
index 44fdbd04..a9ab098c 100644
--- a/backend/src/main/java/com/petshop/backend/controller/CouponController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/CouponController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles creating and managing discount coupons.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/CustomerController.java b/backend/src/main/java/com/petshop/backend/controller/CustomerController.java
index 534fc06e..4ed81357 100644
--- a/backend/src/main/java/com/petshop/backend/controller/CustomerController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/CustomerController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles staff and admin operations for managing customer accounts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/DropdownController.java b/backend/src/main/java/com/petshop/backend/controller/DropdownController.java
index 756a9fca..0c7fe2ae 100644
--- a/backend/src/main/java/com/petshop/backend/controller/DropdownController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/DropdownController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles providing dropdown menu options for forms across the app.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.DropdownOption;
diff --git a/backend/src/main/java/com/petshop/backend/controller/EmployeeController.java b/backend/src/main/java/com/petshop/backend/controller/EmployeeController.java
index 05cc8553..41a4b50d 100644
--- a/backend/src/main/java/com/petshop/backend/controller/EmployeeController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/EmployeeController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles admin operations for managing employee accounts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.user.UserRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/HealthController.java b/backend/src/main/java/com/petshop/backend/controller/HealthController.java
index 8ee609c3..ce6729b9 100644
--- a/backend/src/main/java/com/petshop/backend/controller/HealthController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/HealthController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles health check requests to verify the server is running.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import org.springframework.http.ResponseEntity;
diff --git a/backend/src/main/java/com/petshop/backend/controller/InventoryController.java b/backend/src/main/java/com/petshop/backend/controller/InventoryController.java
index f7aea48f..f6716e1d 100644
--- a/backend/src/main/java/com/petshop/backend/controller/InventoryController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/InventoryController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles tracking product stock levels across store locations.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/MyPetController.java b/backend/src/main/java/com/petshop/backend/controller/MyPetController.java
index 5d4ad1ef..e9f12262 100644
--- a/backend/src/main/java/com/petshop/backend/controller/MyPetController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/MyPetController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles customers viewing and managing their own pets.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.pet.MyPetRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/PetController.java b/backend/src/main/java/com/petshop/backend/controller/PetController.java
index a708a4db..d83841ae 100644
--- a/backend/src/main/java/com/petshop/backend/controller/PetController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/PetController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles managing pets available in the shop.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/PetImageController.java b/backend/src/main/java/com/petshop/backend/controller/PetImageController.java
index 2cd9845f..8442e060 100644
--- a/backend/src/main/java/com/petshop/backend/controller/PetImageController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/PetImageController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles uploading, retrieving, and deleting pet images.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.pet.PetResponse;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ProductController.java b/backend/src/main/java/com/petshop/backend/controller/ProductController.java
index 418d113a..acfc4fd4 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ProductController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ProductController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles creating, updating, and browsing products in the shop.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ProductImageController.java b/backend/src/main/java/com/petshop/backend/controller/ProductImageController.java
index fb9ffa08..de19b1fc 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ProductImageController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ProductImageController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles uploading, retrieving, and deleting product images.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.product.ProductResponse;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ProductSupplierController.java b/backend/src/main/java/com/petshop/backend/controller/ProductSupplierController.java
index f521cb76..c9f3a844 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ProductSupplierController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ProductSupplierController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles linking products to their suppliers.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.productsupplier.BulkDeleteProductSupplierRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/PurchaseOrderController.java b/backend/src/main/java/com/petshop/backend/controller/PurchaseOrderController.java
index c73d9fcc..9386ce14 100644
--- a/backend/src/main/java/com/petshop/backend/controller/PurchaseOrderController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/PurchaseOrderController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles purchase orders for restocking products from suppliers.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.purchaseorder.PurchaseOrderResponse;
diff --git a/backend/src/main/java/com/petshop/backend/controller/RefundController.java b/backend/src/main/java/com/petshop/backend/controller/RefundController.java
index b8e20241..399099de 100644
--- a/backend/src/main/java/com/petshop/backend/controller/RefundController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/RefundController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles requesting and processing refunds for orders.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.refund.RefundRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/SaleController.java b/backend/src/main/java/com/petshop/backend/controller/SaleController.java
index bc40b066..36039046 100644
--- a/backend/src/main/java/com/petshop/backend/controller/SaleController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/SaleController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles creating and viewing sales and customer orders.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.sale.SaleRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/ServiceController.java b/backend/src/main/java/com/petshop/backend/controller/ServiceController.java
index 4789321a..3b42e11e 100644
--- a/backend/src/main/java/com/petshop/backend/controller/ServiceController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/ServiceController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles managing pet services like grooming and veterinary care.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/StoreController.java b/backend/src/main/java/com/petshop/backend/controller/StoreController.java
index dc7bf8f5..2984597e 100644
--- a/backend/src/main/java/com/petshop/backend/controller/StoreController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/StoreController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles managing store locations for the pet shop.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/SupplierController.java b/backend/src/main/java/com/petshop/backend/controller/SupplierController.java
index eb5c065d..9c0ff083 100644
--- a/backend/src/main/java/com/petshop/backend/controller/SupplierController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/SupplierController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles managing suppliers who provide products to the shop.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/controller/UserAvatarController.java b/backend/src/main/java/com/petshop/backend/controller/UserAvatarController.java
index ac7d146c..df453194 100644
--- a/backend/src/main/java/com/petshop/backend/controller/UserAvatarController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/UserAvatarController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles uploading, retrieving, and deleting user profile pictures.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/controller/UserController.java b/backend/src/main/java/com/petshop/backend/controller/UserController.java
index 28ef9f9e..ec28f50c 100644
--- a/backend/src/main/java/com/petshop/backend/controller/UserController.java
+++ b/backend/src/main/java/com/petshop/backend/controller/UserController.java
@@ -1,3 +1,9 @@
+/*
+ * Handles admin operations for managing all user accounts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.controller;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/dto/activity/ActivityLogResponse.java b/backend/src/main/java/com/petshop/backend/dto/activity/ActivityLogResponse.java
index 3d5bc890..0139a12d 100644
--- a/backend/src/main/java/com/petshop/backend/dto/activity/ActivityLogResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/activity/ActivityLogResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Activity log entry returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.activity;
 
 import java.time.LocalDateTime;
diff --git a/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionRequest.java b/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionRequest.java
index 0a45996f..1a3385f4 100644
--- a/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating an adoption.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.adoption;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionResponse.java b/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionResponse.java
index 7b8e821b..cadcc199 100644
--- a/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/adoption/AdoptionResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Adoption record returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.adoption;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/adoption/CustomerAdoptionRequest.java b/backend/src/main/java/com/petshop/backend/dto/adoption/CustomerAdoptionRequest.java
index 4272b2db..ef20e1f3 100644
--- a/backend/src/main/java/com/petshop/backend/dto/adoption/CustomerAdoptionRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/adoption/CustomerAdoptionRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a customer requests to adopt a pet.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.adoption;
 
 import jakarta.validation.constraints.NotNull;
diff --git a/backend/src/main/java/com/petshop/backend/dto/ai/AiChatRequest.java b/backend/src/main/java/com/petshop/backend/dto/ai/AiChatRequest.java
index b043b27c..a147b7ba 100644
--- a/backend/src/main/java/com/petshop/backend/dto/ai/AiChatRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/ai/AiChatRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when asking the AI chatbot a question.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.ai;
 
 import java.util.List;
diff --git a/backend/src/main/java/com/petshop/backend/dto/ai/AiChatResponse.java b/backend/src/main/java/com/petshop/backend/dto/ai/AiChatResponse.java
index 05f310b4..93f6a7a9 100644
--- a/backend/src/main/java/com/petshop/backend/dto/ai/AiChatResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/ai/AiChatResponse.java
@@ -1,3 +1,9 @@
+/*
+ * AI chatbot reply returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.ai;
 
 public class AiChatResponse {
diff --git a/backend/src/main/java/com/petshop/backend/dto/analytics/DashboardResponse.java b/backend/src/main/java/com/petshop/backend/dto/analytics/DashboardResponse.java
index 56788f77..49768b4b 100644
--- a/backend/src/main/java/com/petshop/backend/dto/analytics/DashboardResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/analytics/DashboardResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Dashboard analytics data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.analytics;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentRequest.java b/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentRequest.java
index d1c3847a..810f4a92 100644
--- a/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when booking or updating an appointment.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.appointment;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentResponse.java b/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentResponse.java
index b2e9a9ba..274c7d39 100644
--- a/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/appointment/AppointmentResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Appointment details returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.appointment;
 
 import java.time.LocalDate;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/AvatarUploadResponse.java b/backend/src/main/java/com/petshop/backend/dto/auth/AvatarUploadResponse.java
index 8e75af96..b2e07935 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/AvatarUploadResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/AvatarUploadResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Avatar upload result returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import java.util.Objects;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordRequest.java b/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordRequest.java
index 529581cc..39539be7 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a user requests a password reset.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordResponse.java b/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordResponse.java
index 6062a196..d9d22253 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/ForgotPasswordResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Forgot password result returned with a reset token.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 public class ForgotPasswordResponse {
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/LoginRequest.java b/backend/src/main/java/com/petshop/backend/dto/auth/LoginRequest.java
index 970c4719..37f734c9 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/LoginRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/LoginRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a user logs in.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/LoginResponse.java b/backend/src/main/java/com/petshop/backend/dto/auth/LoginResponse.java
index e3d01c11..c546e002 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/LoginResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/LoginResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Login result returned to the client with a token.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import java.util.Objects;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/ProfileUpdateRequest.java b/backend/src/main/java/com/petshop/backend/dto/auth/ProfileUpdateRequest.java
index 97b978b0..422a6bd2 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/ProfileUpdateRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/ProfileUpdateRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a user updates their profile.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import jakarta.validation.constraints.Email;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/RegisterRequest.java b/backend/src/main/java/com/petshop/backend/dto/auth/RegisterRequest.java
index 4758d923..d4d81a9d 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/RegisterRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/RegisterRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a new user registers an account.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import jakarta.validation.constraints.Email;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/RegisterResponse.java b/backend/src/main/java/com/petshop/backend/dto/auth/RegisterResponse.java
index 7e016985..91c59b72 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/RegisterResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/RegisterResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Registration result returned to the client after signing up.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import java.util.Objects;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordRequest.java b/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordRequest.java
index 3f20f7f7..5c1ee5a6 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a user sets a new password using a reset token.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordResponse.java b/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordResponse.java
index 0edf18a7..0522d527 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/ResetPasswordResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Password reset confirmation returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 public class ResetPasswordResponse {
diff --git a/backend/src/main/java/com/petshop/backend/dto/auth/UserInfoResponse.java b/backend/src/main/java/com/petshop/backend/dto/auth/UserInfoResponse.java
index 74dbc039..34e980eb 100644
--- a/backend/src/main/java/com/petshop/backend/dto/auth/UserInfoResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/auth/UserInfoResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Logged-in user profile data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.auth;
 
 import java.util.Objects;
diff --git a/backend/src/main/java/com/petshop/backend/dto/cart/AddToCartRequest.java b/backend/src/main/java/com/petshop/backend/dto/cart/AddToCartRequest.java
index 6075ad4c..666aabb8 100644
--- a/backend/src/main/java/com/petshop/backend/dto/cart/AddToCartRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/cart/AddToCartRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when adding a product to the shopping cart.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.cart;
 
 import jakarta.validation.constraints.Min;
diff --git a/backend/src/main/java/com/petshop/backend/dto/cart/ApplyCouponRequest.java b/backend/src/main/java/com/petshop/backend/dto/cart/ApplyCouponRequest.java
index 290d4434..b7143dbe 100644
--- a/backend/src/main/java/com/petshop/backend/dto/cart/ApplyCouponRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/cart/ApplyCouponRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when applying a coupon code to the cart.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.cart;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/cart/CartItemResponse.java b/backend/src/main/java/com/petshop/backend/dto/cart/CartItemResponse.java
index 6b13e1bc..e3476652 100644
--- a/backend/src/main/java/com/petshop/backend/dto/cart/CartItemResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/cart/CartItemResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Single cart item returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.cart;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/cart/CartResponse.java b/backend/src/main/java/com/petshop/backend/dto/cart/CartResponse.java
index 58ff0444..3e3f7d4a 100644
--- a/backend/src/main/java/com/petshop/backend/dto/cart/CartResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/cart/CartResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Full shopping cart data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.cart;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutRequest.java b/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutRequest.java
index 856582ed..93960872 100644
--- a/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a customer checks out their cart.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.cart;
 
 import jakarta.validation.constraints.NotNull;
diff --git a/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutResponse.java b/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutResponse.java
index c703fbc0..d5b7a829 100644
--- a/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/cart/CheckoutResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Checkout result returned to the client after placing an order.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.cart;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/cart/UpdateCartItemRequest.java b/backend/src/main/java/com/petshop/backend/dto/cart/UpdateCartItemRequest.java
index 205aaa4a..b831939c 100644
--- a/backend/src/main/java/com/petshop/backend/dto/cart/UpdateCartItemRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/cart/UpdateCartItemRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when updating the quantity of a cart item.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.cart;
 
 import jakarta.validation.constraints.Min;
diff --git a/backend/src/main/java/com/petshop/backend/dto/category/CategoryRequest.java b/backend/src/main/java/com/petshop/backend/dto/category/CategoryRequest.java
index b099826f..0ad382cc 100644
--- a/backend/src/main/java/com/petshop/backend/dto/category/CategoryRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/category/CategoryRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a category.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.category;
 
 import com.petshop.backend.util.SafeContent;
diff --git a/backend/src/main/java/com/petshop/backend/dto/category/CategoryResponse.java b/backend/src/main/java/com/petshop/backend/dto/category/CategoryResponse.java
index 6d9e1569..93f1e459 100644
--- a/backend/src/main/java/com/petshop/backend/dto/category/CategoryResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/category/CategoryResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Category data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.category;
 
 import java.time.LocalDateTime;
diff --git a/backend/src/main/java/com/petshop/backend/dto/chat/ConversationRequest.java b/backend/src/main/java/com/petshop/backend/dto/chat/ConversationRequest.java
index 8677865a..1c9d833d 100644
--- a/backend/src/main/java/com/petshop/backend/dto/chat/ConversationRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/chat/ConversationRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when starting a new conversation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.chat;
 
 public class ConversationRequest {
diff --git a/backend/src/main/java/com/petshop/backend/dto/chat/ConversationResponse.java b/backend/src/main/java/com/petshop/backend/dto/chat/ConversationResponse.java
index cef833cd..bd8bec78 100644
--- a/backend/src/main/java/com/petshop/backend/dto/chat/ConversationResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/chat/ConversationResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Conversation details returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.chat;
 
 import com.petshop.backend.entity.Conversation;
diff --git a/backend/src/main/java/com/petshop/backend/dto/chat/MessageRequest.java b/backend/src/main/java/com/petshop/backend/dto/chat/MessageRequest.java
index 0784054b..e7900aab 100644
--- a/backend/src/main/java/com/petshop/backend/dto/chat/MessageRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/chat/MessageRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when sending a chat message.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.chat;
 
 public class MessageRequest {
diff --git a/backend/src/main/java/com/petshop/backend/dto/chat/MessageResponse.java b/backend/src/main/java/com/petshop/backend/dto/chat/MessageResponse.java
index 146f0229..2a602cc2 100644
--- a/backend/src/main/java/com/petshop/backend/dto/chat/MessageResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/chat/MessageResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Chat message returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.chat;
 
 import com.petshop.backend.entity.Message;
diff --git a/backend/src/main/java/com/petshop/backend/dto/chat/UpdateConversationRequest.java b/backend/src/main/java/com/petshop/backend/dto/chat/UpdateConversationRequest.java
index 4c043a79..d3125659 100644
--- a/backend/src/main/java/com/petshop/backend/dto/chat/UpdateConversationRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/chat/UpdateConversationRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when changing the status of a conversation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.chat;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/common/BulkDeleteRequest.java b/backend/src/main/java/com/petshop/backend/dto/common/BulkDeleteRequest.java
index bec920f1..203bf7c6 100644
--- a/backend/src/main/java/com/petshop/backend/dto/common/BulkDeleteRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/common/BulkDeleteRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when deleting multiple records at once.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.common;
 
 import jakarta.validation.constraints.NotEmpty;
diff --git a/backend/src/main/java/com/petshop/backend/dto/common/CouponRequest.java b/backend/src/main/java/com/petshop/backend/dto/common/CouponRequest.java
index ffa7f766..1817cc69 100644
--- a/backend/src/main/java/com/petshop/backend/dto/common/CouponRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/common/CouponRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a coupon.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.common;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/common/CouponResponse.java b/backend/src/main/java/com/petshop/backend/dto/common/CouponResponse.java
index 9d763817..2221c92a 100644
--- a/backend/src/main/java/com/petshop/backend/dto/common/CouponResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/common/CouponResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Coupon details returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.common;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/common/DropdownOption.java b/backend/src/main/java/com/petshop/backend/dto/common/DropdownOption.java
index 6ea0d058..f655fb5b 100644
--- a/backend/src/main/java/com/petshop/backend/dto/common/DropdownOption.java
+++ b/backend/src/main/java/com/petshop/backend/dto/common/DropdownOption.java
@@ -1,3 +1,9 @@
+/*
+ * Simple id and label pair used for dropdown menus.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.common;
 
 import java.util.Objects;
diff --git a/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryRequest.java b/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryRequest.java
index 7ad02d3a..5b3c4ef0 100644
--- a/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when updating inventory for a product.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.inventory;
 
 import jakarta.validation.constraints.NotNull;
diff --git a/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryResponse.java b/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryResponse.java
index 5879a554..d208fde9 100644
--- a/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/inventory/InventoryResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Inventory record returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.inventory;
 
 import java.time.LocalDateTime;
diff --git a/backend/src/main/java/com/petshop/backend/dto/pet/MyPetRequest.java b/backend/src/main/java/com/petshop/backend/dto/pet/MyPetRequest.java
index 37942a47..0daafc98 100644
--- a/backend/src/main/java/com/petshop/backend/dto/pet/MyPetRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/pet/MyPetRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when a customer adds or updates their own pet.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.pet;
 
 import jakarta.validation.constraints.Max;
diff --git a/backend/src/main/java/com/petshop/backend/dto/pet/MyPetResponse.java b/backend/src/main/java/com/petshop/backend/dto/pet/MyPetResponse.java
index 15117334..2c03726f 100644
--- a/backend/src/main/java/com/petshop/backend/dto/pet/MyPetResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/pet/MyPetResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Customer's own pet data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.pet;
 
 public class MyPetResponse {
diff --git a/backend/src/main/java/com/petshop/backend/dto/pet/PetRequest.java b/backend/src/main/java/com/petshop/backend/dto/pet/PetRequest.java
index 4d0986bb..cc7b693a 100644
--- a/backend/src/main/java/com/petshop/backend/dto/pet/PetRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/pet/PetRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a pet listing.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.pet;
 
 import com.petshop.backend.util.SafeContent;
diff --git a/backend/src/main/java/com/petshop/backend/dto/pet/PetResponse.java b/backend/src/main/java/com/petshop/backend/dto/pet/PetResponse.java
index b7113bb1..fd6b7cc9 100644
--- a/backend/src/main/java/com/petshop/backend/dto/pet/PetResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/pet/PetResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Pet data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.pet;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/product/ProductRequest.java b/backend/src/main/java/com/petshop/backend/dto/product/ProductRequest.java
index e1ca9241..f5bd69f7 100644
--- a/backend/src/main/java/com/petshop/backend/dto/product/ProductRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/product/ProductRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a product.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.product;
 
 import com.petshop.backend.util.SafeContent;
diff --git a/backend/src/main/java/com/petshop/backend/dto/product/ProductResponse.java b/backend/src/main/java/com/petshop/backend/dto/product/ProductResponse.java
index c08abf9a..df11c90b 100644
--- a/backend/src/main/java/com/petshop/backend/dto/product/ProductResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/product/ProductResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Product data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.product;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/productsupplier/BulkDeleteProductSupplierRequest.java b/backend/src/main/java/com/petshop/backend/dto/productsupplier/BulkDeleteProductSupplierRequest.java
index 7eb8a3cc..c2b488e0 100644
--- a/backend/src/main/java/com/petshop/backend/dto/productsupplier/BulkDeleteProductSupplierRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/productsupplier/BulkDeleteProductSupplierRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when deleting multiple product-supplier links at once.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.productsupplier;
 
 import jakarta.validation.constraints.NotEmpty;
diff --git a/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierKey.java b/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierKey.java
index 557dbeda..8f819c0b 100644
--- a/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierKey.java
+++ b/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierKey.java
@@ -1,3 +1,9 @@
+/*
+ * Composite key identifying a product-supplier relationship.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.productsupplier;
 
 import java.util.Objects;
diff --git a/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierRequest.java b/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierRequest.java
index 1bc05210..3d7dd214 100644
--- a/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when linking a product to a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.productsupplier;
 
 import jakarta.validation.constraints.NotNull;
diff --git a/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierResponse.java b/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierResponse.java
index 4190dabb..0aac04d1 100644
--- a/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/productsupplier/ProductSupplierResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Product-supplier link data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.productsupplier;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/purchaseorder/PurchaseOrderResponse.java b/backend/src/main/java/com/petshop/backend/dto/purchaseorder/PurchaseOrderResponse.java
index 98f81914..3a91e113 100644
--- a/backend/src/main/java/com/petshop/backend/dto/purchaseorder/PurchaseOrderResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/purchaseorder/PurchaseOrderResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Purchase order data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.purchaseorder;
 
 import java.time.LocalDate;
diff --git a/backend/src/main/java/com/petshop/backend/dto/refund/RefundItemResponse.java b/backend/src/main/java/com/petshop/backend/dto/refund/RefundItemResponse.java
index 8c33c168..b033202b 100644
--- a/backend/src/main/java/com/petshop/backend/dto/refund/RefundItemResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/refund/RefundItemResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Single refunded item returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.refund;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/refund/RefundRequest.java b/backend/src/main/java/com/petshop/backend/dto/refund/RefundRequest.java
index 37121047..216a1be5 100644
--- a/backend/src/main/java/com/petshop/backend/dto/refund/RefundRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/refund/RefundRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when requesting a refund for a sale.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.refund;
 
 import com.petshop.backend.dto.sale.SaleItemRequest;
diff --git a/backend/src/main/java/com/petshop/backend/dto/refund/RefundResponse.java b/backend/src/main/java/com/petshop/backend/dto/refund/RefundResponse.java
index dc469dd4..0c356e63 100644
--- a/backend/src/main/java/com/petshop/backend/dto/refund/RefundResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/refund/RefundResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Refund record returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.refund;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/refund/RefundUpdateRequest.java b/backend/src/main/java/com/petshop/backend/dto/refund/RefundUpdateRequest.java
index 22dddf95..dbd458ff 100644
--- a/backend/src/main/java/com/petshop/backend/dto/refund/RefundUpdateRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/refund/RefundUpdateRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when updating the status of a refund.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.refund;
 
 import jakarta.validation.constraints.NotBlank;
diff --git a/backend/src/main/java/com/petshop/backend/dto/sale/SaleItemRequest.java b/backend/src/main/java/com/petshop/backend/dto/sale/SaleItemRequest.java
index dad7011a..ea3cf486 100644
--- a/backend/src/main/java/com/petshop/backend/dto/sale/SaleItemRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/sale/SaleItemRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Single line item included in a sale request.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.sale;
 
 import jakarta.validation.constraints.NotNull;
diff --git a/backend/src/main/java/com/petshop/backend/dto/sale/SaleRequest.java b/backend/src/main/java/com/petshop/backend/dto/sale/SaleRequest.java
index b0e7989f..c81d5fdb 100644
--- a/backend/src/main/java/com/petshop/backend/dto/sale/SaleRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/sale/SaleRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when recording a new sale.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.sale;
 
 import jakarta.validation.Valid;
diff --git a/backend/src/main/java/com/petshop/backend/dto/sale/SaleResponse.java b/backend/src/main/java/com/petshop/backend/dto/sale/SaleResponse.java
index af116212..4fdbe968 100644
--- a/backend/src/main/java/com/petshop/backend/dto/sale/SaleResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/sale/SaleResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Sale record returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.sale;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/service/ServiceRequest.java b/backend/src/main/java/com/petshop/backend/dto/service/ServiceRequest.java
index 464fefda..390eece7 100644
--- a/backend/src/main/java/com/petshop/backend/dto/service/ServiceRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/service/ServiceRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a service.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.service;
 
 import com.petshop.backend.util.SafeContent;
diff --git a/backend/src/main/java/com/petshop/backend/dto/service/ServiceResponse.java b/backend/src/main/java/com/petshop/backend/dto/service/ServiceResponse.java
index 4f0300ab..b68d186d 100644
--- a/backend/src/main/java/com/petshop/backend/dto/service/ServiceResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/service/ServiceResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Service data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.service;
 
 import java.math.BigDecimal;
diff --git a/backend/src/main/java/com/petshop/backend/dto/store/StoreRequest.java b/backend/src/main/java/com/petshop/backend/dto/store/StoreRequest.java
index fca03db1..b849023a 100644
--- a/backend/src/main/java/com/petshop/backend/dto/store/StoreRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/store/StoreRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a store.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.store;
 
 import com.petshop.backend.util.SafeContent;
diff --git a/backend/src/main/java/com/petshop/backend/dto/store/StoreResponse.java b/backend/src/main/java/com/petshop/backend/dto/store/StoreResponse.java
index bf5cafd2..12c8be06 100644
--- a/backend/src/main/java/com/petshop/backend/dto/store/StoreResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/store/StoreResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Store data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.store;
 
 import java.time.LocalDateTime;
diff --git a/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierRequest.java b/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierRequest.java
index a0eb2b6a..5efd27d0 100644
--- a/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.supplier;
 
 import com.petshop.backend.util.SafeContent;
diff --git a/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierResponse.java b/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierResponse.java
index d23b4a2b..d382f61d 100644
--- a/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/supplier/SupplierResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Supplier data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.supplier;
 
 import java.time.LocalDateTime;
diff --git a/backend/src/main/java/com/petshop/backend/dto/user/UserRequest.java b/backend/src/main/java/com/petshop/backend/dto/user/UserRequest.java
index 04c82e43..491ace3d 100644
--- a/backend/src/main/java/com/petshop/backend/dto/user/UserRequest.java
+++ b/backend/src/main/java/com/petshop/backend/dto/user/UserRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Data sent when creating or updating a user account.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.user;
 
 import com.petshop.backend.util.SafeContent;
diff --git a/backend/src/main/java/com/petshop/backend/dto/user/UserResponse.java b/backend/src/main/java/com/petshop/backend/dto/user/UserResponse.java
index 6c8ffd68..9cc8d6f1 100644
--- a/backend/src/main/java/com/petshop/backend/dto/user/UserResponse.java
+++ b/backend/src/main/java/com/petshop/backend/dto/user/UserResponse.java
@@ -1,3 +1,9 @@
+/*
+ * User account data returned to the client.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.dto.user;
 
 import java.time.LocalDateTime;
diff --git a/backend/src/main/java/com/petshop/backend/entity/ActivityLog.java b/backend/src/main/java/com/petshop/backend/entity/ActivityLog.java
index b445b7c4..508c3ee6 100644
--- a/backend/src/main/java/com/petshop/backend/entity/ActivityLog.java
+++ b/backend/src/main/java/com/petshop/backend/entity/ActivityLog.java
@@ -1,3 +1,10 @@
+/*
+ * Represents an activity log entry in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Adoption.java b/backend/src/main/java/com/petshop/backend/entity/Adoption.java
index e5dae5aa..fdc88a96 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Adoption.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Adoption.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a pet adoption record in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Appointment.java b/backend/src/main/java/com/petshop/backend/entity/Appointment.java
index 0e80f58e..3ac8df7d 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Appointment.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Appointment.java
@@ -1,3 +1,10 @@
+/*
+ * Represents an appointment in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Cart.java b/backend/src/main/java/com/petshop/backend/entity/Cart.java
index 61066af6..65a25fa3 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Cart.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Cart.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a shopping cart in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/CartItem.java b/backend/src/main/java/com/petshop/backend/entity/CartItem.java
index 1ad4c144..6268eaa6 100644
--- a/backend/src/main/java/com/petshop/backend/entity/CartItem.java
+++ b/backend/src/main/java/com/petshop/backend/entity/CartItem.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a single item in a shopping cart.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Category.java b/backend/src/main/java/com/petshop/backend/entity/Category.java
index ee79207e..a837a326 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Category.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Category.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a product category in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Conversation.java b/backend/src/main/java/com/petshop/backend/entity/Conversation.java
index 080228eb..1a8d7d9b 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Conversation.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Conversation.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a chat conversation between a customer and staff.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Coupon.java b/backend/src/main/java/com/petshop/backend/entity/Coupon.java
index ba234f12..667e3fd9 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Coupon.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Coupon.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a discount coupon in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Inventory.java b/backend/src/main/java/com/petshop/backend/entity/Inventory.java
index ac859c64..836e06f2 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Inventory.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Inventory.java
@@ -1,3 +1,10 @@
+/*
+ * Represents inventory stock for a product.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Message.java b/backend/src/main/java/com/petshop/backend/entity/Message.java
index 7c7bc498..330b5649 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Message.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Message.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a single message in a conversation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/PasswordResetToken.java b/backend/src/main/java/com/petshop/backend/entity/PasswordResetToken.java
index bd6c5494..03a9353b 100644
--- a/backend/src/main/java/com/petshop/backend/entity/PasswordResetToken.java
+++ b/backend/src/main/java/com/petshop/backend/entity/PasswordResetToken.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a password reset token for a user.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.Column;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Pet.java b/backend/src/main/java/com/petshop/backend/entity/Pet.java
index 604a24db..94e47ce3 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Pet.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Pet.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a pet in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Product.java b/backend/src/main/java/com/petshop/backend/entity/Product.java
index 84c17c1a..e78f4c2e 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Product.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Product.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a product in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/ProductSupplier.java b/backend/src/main/java/com/petshop/backend/entity/ProductSupplier.java
index 95aa6017..f85189ad 100644
--- a/backend/src/main/java/com/petshop/backend/entity/ProductSupplier.java
+++ b/backend/src/main/java/com/petshop/backend/entity/ProductSupplier.java
@@ -1,3 +1,10 @@
+/*
+ * Represents the link between a product and its supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/PurchaseOrder.java b/backend/src/main/java/com/petshop/backend/entity/PurchaseOrder.java
index fd50c120..f417c1f0 100644
--- a/backend/src/main/java/com/petshop/backend/entity/PurchaseOrder.java
+++ b/backend/src/main/java/com/petshop/backend/entity/PurchaseOrder.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a purchase order placed with a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Refund.java b/backend/src/main/java/com/petshop/backend/entity/Refund.java
index f6b9b45d..92e3a8d9 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Refund.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Refund.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a refund for a sale.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/RefundItem.java b/backend/src/main/java/com/petshop/backend/entity/RefundItem.java
index 30e675c2..989dd1f2 100644
--- a/backend/src/main/java/com/petshop/backend/entity/RefundItem.java
+++ b/backend/src/main/java/com/petshop/backend/entity/RefundItem.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a single item in a refund.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Sale.java b/backend/src/main/java/com/petshop/backend/entity/Sale.java
index d1134b58..19f687e6 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Sale.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Sale.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a sale transaction in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/SaleItem.java b/backend/src/main/java/com/petshop/backend/entity/SaleItem.java
index b80ab370..25b47ddf 100644
--- a/backend/src/main/java/com/petshop/backend/entity/SaleItem.java
+++ b/backend/src/main/java/com/petshop/backend/entity/SaleItem.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a single item in a sale.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Service.java b/backend/src/main/java/com/petshop/backend/entity/Service.java
index 6b6c4267..f669b1b7 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Service.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Service.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a pet service offered by the store.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import jakarta.persistence.*;
diff --git a/backend/src/main/java/com/petshop/backend/entity/StoreLocation.java b/backend/src/main/java/com/petshop/backend/entity/StoreLocation.java
index 1f79a830..9ba26619 100644
--- a/backend/src/main/java/com/petshop/backend/entity/StoreLocation.java
+++ b/backend/src/main/java/com/petshop/backend/entity/StoreLocation.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a store location in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import com.petshop.backend.util.PhoneUtils;
diff --git a/backend/src/main/java/com/petshop/backend/entity/Supplier.java b/backend/src/main/java/com/petshop/backend/entity/Supplier.java
index 911aad08..e1abde9c 100644
--- a/backend/src/main/java/com/petshop/backend/entity/Supplier.java
+++ b/backend/src/main/java/com/petshop/backend/entity/Supplier.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a supplier in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import com.petshop.backend.util.PhoneUtils;
diff --git a/backend/src/main/java/com/petshop/backend/entity/User.java b/backend/src/main/java/com/petshop/backend/entity/User.java
index 97b8dfc5..abb36bcd 100644
--- a/backend/src/main/java/com/petshop/backend/entity/User.java
+++ b/backend/src/main/java/com/petshop/backend/entity/User.java
@@ -1,3 +1,10 @@
+/*
+ * Represents a user account in the database.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.entity;
 
 import com.petshop.backend.util.PhoneUtils;
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/repository/ActivityLogRepository.java b/backend/src/main/java/com/petshop/backend/repository/ActivityLogRepository.java
index 09bf817a..f9bae4eb 100644
--- a/backend/src/main/java/com/petshop/backend/repository/ActivityLogRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/ActivityLogRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for activity logs.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.ActivityLog;
diff --git a/backend/src/main/java/com/petshop/backend/repository/AdoptionRepository.java b/backend/src/main/java/com/petshop/backend/repository/AdoptionRepository.java
index ba351042..1f919e90 100644
--- a/backend/src/main/java/com/petshop/backend/repository/AdoptionRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/AdoptionRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for adoptions.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Adoption;
diff --git a/backend/src/main/java/com/petshop/backend/repository/AppointmentRepository.java b/backend/src/main/java/com/petshop/backend/repository/AppointmentRepository.java
index 774c1427..2feb77be 100644
--- a/backend/src/main/java/com/petshop/backend/repository/AppointmentRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/AppointmentRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for appointments.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Appointment;
diff --git a/backend/src/main/java/com/petshop/backend/repository/CartItemRepository.java b/backend/src/main/java/com/petshop/backend/repository/CartItemRepository.java
index f610233c..01cb42e9 100644
--- a/backend/src/main/java/com/petshop/backend/repository/CartItemRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/CartItemRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for cart items.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.CartItem;
diff --git a/backend/src/main/java/com/petshop/backend/repository/CartRepository.java b/backend/src/main/java/com/petshop/backend/repository/CartRepository.java
index ab5d816a..521b6399 100644
--- a/backend/src/main/java/com/petshop/backend/repository/CartRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/CartRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for shopping carts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Cart;
diff --git a/backend/src/main/java/com/petshop/backend/repository/CategoryRepository.java b/backend/src/main/java/com/petshop/backend/repository/CategoryRepository.java
index b1871d1f..1819ebbb 100644
--- a/backend/src/main/java/com/petshop/backend/repository/CategoryRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/CategoryRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for categories.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Category;
diff --git a/backend/src/main/java/com/petshop/backend/repository/ConversationRepository.java b/backend/src/main/java/com/petshop/backend/repository/ConversationRepository.java
index 9ec1fde9..34af3e45 100644
--- a/backend/src/main/java/com/petshop/backend/repository/ConversationRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/ConversationRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for conversations.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Conversation;
diff --git a/backend/src/main/java/com/petshop/backend/repository/CouponRepository.java b/backend/src/main/java/com/petshop/backend/repository/CouponRepository.java
index 0034a887..8f283821 100644
--- a/backend/src/main/java/com/petshop/backend/repository/CouponRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/CouponRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for coupons.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Coupon;
diff --git a/backend/src/main/java/com/petshop/backend/repository/InventoryRepository.java b/backend/src/main/java/com/petshop/backend/repository/InventoryRepository.java
index 82f3c797..53a9cb69 100644
--- a/backend/src/main/java/com/petshop/backend/repository/InventoryRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/InventoryRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for inventory records.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Inventory;
diff --git a/backend/src/main/java/com/petshop/backend/repository/MessageRepository.java b/backend/src/main/java/com/petshop/backend/repository/MessageRepository.java
index 6c87be6e..6e039d9a 100644
--- a/backend/src/main/java/com/petshop/backend/repository/MessageRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/MessageRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for messages.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Message;
diff --git a/backend/src/main/java/com/petshop/backend/repository/PasswordResetTokenRepository.java b/backend/src/main/java/com/petshop/backend/repository/PasswordResetTokenRepository.java
index e436fb59..df8e5bae 100644
--- a/backend/src/main/java/com/petshop/backend/repository/PasswordResetTokenRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/PasswordResetTokenRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for password reset tokens.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.PasswordResetToken;
diff --git a/backend/src/main/java/com/petshop/backend/repository/PetRepository.java b/backend/src/main/java/com/petshop/backend/repository/PetRepository.java
index c5f8d73a..1e395895 100644
--- a/backend/src/main/java/com/petshop/backend/repository/PetRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/PetRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for pets.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Pet;
diff --git a/backend/src/main/java/com/petshop/backend/repository/ProductRepository.java b/backend/src/main/java/com/petshop/backend/repository/ProductRepository.java
index 140031d0..ef45c25f 100644
--- a/backend/src/main/java/com/petshop/backend/repository/ProductRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/ProductRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for products.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Product;
diff --git a/backend/src/main/java/com/petshop/backend/repository/ProductSupplierRepository.java b/backend/src/main/java/com/petshop/backend/repository/ProductSupplierRepository.java
index 15d17703..fa824b19 100644
--- a/backend/src/main/java/com/petshop/backend/repository/ProductSupplierRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/ProductSupplierRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for product-supplier links.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.ProductSupplier;
diff --git a/backend/src/main/java/com/petshop/backend/repository/PurchaseOrderRepository.java b/backend/src/main/java/com/petshop/backend/repository/PurchaseOrderRepository.java
index 5ebf9457..a914c934 100644
--- a/backend/src/main/java/com/petshop/backend/repository/PurchaseOrderRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/PurchaseOrderRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for purchase orders.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.PurchaseOrder;
diff --git a/backend/src/main/java/com/petshop/backend/repository/RefundRepository.java b/backend/src/main/java/com/petshop/backend/repository/RefundRepository.java
index fe507c3f..7fb00539 100644
--- a/backend/src/main/java/com/petshop/backend/repository/RefundRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/RefundRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for refunds.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Refund;
diff --git a/backend/src/main/java/com/petshop/backend/repository/SaleItemRepository.java b/backend/src/main/java/com/petshop/backend/repository/SaleItemRepository.java
index 0b67f95e..d5ed04aa 100644
--- a/backend/src/main/java/com/petshop/backend/repository/SaleItemRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/SaleItemRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for sale items.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.SaleItem;
diff --git a/backend/src/main/java/com/petshop/backend/repository/SaleRepository.java b/backend/src/main/java/com/petshop/backend/repository/SaleRepository.java
index 19a93ee9..61e4cd69 100644
--- a/backend/src/main/java/com/petshop/backend/repository/SaleRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/SaleRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for sales.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Sale;
diff --git a/backend/src/main/java/com/petshop/backend/repository/ServiceRepository.java b/backend/src/main/java/com/petshop/backend/repository/ServiceRepository.java
index e6271dfd..3f3509bd 100644
--- a/backend/src/main/java/com/petshop/backend/repository/ServiceRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/ServiceRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for services.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Service;
diff --git a/backend/src/main/java/com/petshop/backend/repository/StoreRepository.java b/backend/src/main/java/com/petshop/backend/repository/StoreRepository.java
index 5ee3758b..2733fb1a 100644
--- a/backend/src/main/java/com/petshop/backend/repository/StoreRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/StoreRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for store locations.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.StoreLocation;
diff --git a/backend/src/main/java/com/petshop/backend/repository/SupplierRepository.java b/backend/src/main/java/com/petshop/backend/repository/SupplierRepository.java
index c7dd2307..690beebf 100644
--- a/backend/src/main/java/com/petshop/backend/repository/SupplierRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/SupplierRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for suppliers.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.Supplier;
diff --git a/backend/src/main/java/com/petshop/backend/repository/UserRepository.java b/backend/src/main/java/com/petshop/backend/repository/UserRepository.java
index 022a3162..f2b0155c 100644
--- a/backend/src/main/java/com/petshop/backend/repository/UserRepository.java
+++ b/backend/src/main/java/com/petshop/backend/repository/UserRepository.java
@@ -1,3 +1,10 @@
+/*
+ * Database queries for users.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
+
 package com.petshop.backend.repository;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/security/AppPrincipal.java b/backend/src/main/java/com/petshop/backend/security/AppPrincipal.java
index 30ceca66..f1a1c8b5 100644
--- a/backend/src/main/java/com/petshop/backend/security/AppPrincipal.java
+++ b/backend/src/main/java/com/petshop/backend/security/AppPrincipal.java
@@ -1,3 +1,10 @@
+/*
+ * Represents the currently logged-in user in the security context.
+ * Holds the user ID, username, role, and token version.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/security/JwtAuthenticationFilter.java b/backend/src/main/java/com/petshop/backend/security/JwtAuthenticationFilter.java
index db7d47fc..52823e98 100644
--- a/backend/src/main/java/com/petshop/backend/security/JwtAuthenticationFilter.java
+++ b/backend/src/main/java/com/petshop/backend/security/JwtAuthenticationFilter.java
@@ -1,3 +1,10 @@
+/*
+ * Filter that runs on every request to validate the JWT token
+ * and set up the security context if the token is valid.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.entity.User;
@@ -30,12 +37,20 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
         this.apiErrorResponder = apiErrorResponder;
     }
 
+    /**
+     * Extracts the JWT from the Authorization header, validates it, and sets up
+     * the Spring Security context so downstream filters/controllers know who the user is.
+     * @param request the incoming HTTP request
+     * @param response the HTTP response (used to write 401 errors)
+     * @param filterChain the remaining filters to invoke
+     */
     @Override
     protected void doFilterInternal(
             @NonNull HttpServletRequest request,
             @NonNull HttpServletResponse response,
             @NonNull FilterChain filterChain
     ) throws ServletException, IOException {
+        // Skip requests that don't have a Bearer token
         final String authHeader = request.getHeader("Authorization");
         final String jwt;
         if (authHeader == null || !authHeader.startsWith("Bearer ")) {
@@ -43,6 +58,7 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
             return;
         }
 
+        // Strip "Bearer " prefix to get the raw token
         jwt = authHeader.substring(7);
         Long userId;
         String username;
@@ -58,6 +74,7 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
             return;
         }
 
+        // Only set up auth context if there isn't one already for this request
         if (userId != null && SecurityContextHolder.getContext().getAuthentication() == null) {
             if (jwtUtil.extractExpiration(jwt).before(new Date())) {
                 writeUnauthorized(request, response, "Invalid or expired token", null);
@@ -69,6 +86,7 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
                 writeUnauthorized(request, response, "User account is inactive", null);
                 return;
             }
+            // Token version mismatch means the user logged out or changed password
             if (!authData.tokenVersion().equals(jwtTokenVersion)) {
                 writeUnauthorized(request, response, "Invalid or expired token", null);
                 return;
@@ -82,6 +100,7 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
                 return;
             }
 
+            // Build the authentication object and store it in the security context
             AppPrincipal principal = new AppPrincipal(userId, username, role, jwtTokenVersion);
             UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
                     principal,
diff --git a/backend/src/main/java/com/petshop/backend/security/JwtUtil.java b/backend/src/main/java/com/petshop/backend/security/JwtUtil.java
index b0a5fec5..fc4c0a4f 100644
--- a/backend/src/main/java/com/petshop/backend/security/JwtUtil.java
+++ b/backend/src/main/java/com/petshop/backend/security/JwtUtil.java
@@ -1,3 +1,10 @@
+/*
+ * JWT token utility for generating, parsing, and validating tokens.
+ * Tokens store userId, username, role, and a version for invalidation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.entity.User;
@@ -50,6 +57,12 @@ public class JwtUtil {
         return extractAllClaims(token).get("role", String.class);
     }
 
+    /**
+     * Gets the token version from the JWT, used to invalidate old tokens
+     * when the user logs out or changes their password.
+     * @param token the JWT string
+     * @return the token version number, or null if not present
+     */
     public Integer extractTokenVersion(String token) {
         Number tokenVersion = extractAllClaims(token).get("tokenVersion", Number.class);
         return tokenVersion == null ? null : tokenVersion.intValue();
@@ -76,6 +89,11 @@ public class JwtUtil {
         return extractExpiration(token).before(new Date());
     }
 
+    /**
+     * Creates a new JWT containing the user's id, username, role, and token version.
+     * @param user the user to generate a token for
+     * @return the signed JWT string
+     */
     public String generateToken(User user) {
         Map<String, Object> claims = new HashMap<>();
         claims.put("username", user.getUsername());
@@ -94,6 +112,13 @@ public class JwtUtil {
                 .compact();
     }
 
+    /**
+     * Checks that the token belongs to this user, has the right role and version,
+     * and hasn't expired yet.
+     * @param token the JWT string
+     * @param user the user to validate against
+     * @return true if the token is valid for this user
+     */
     public Boolean validateToken(String token, User user) {
         Long userId = extractUserId(token);
         String role = extractRole(token);
diff --git a/backend/src/main/java/com/petshop/backend/security/RateLimitFilter.java b/backend/src/main/java/com/petshop/backend/security/RateLimitFilter.java
index 31f2434f..fd060f1c 100644
--- a/backend/src/main/java/com/petshop/backend/security/RateLimitFilter.java
+++ b/backend/src/main/java/com/petshop/backend/security/RateLimitFilter.java
@@ -1,3 +1,10 @@
+/*
+ * Filter that applies rate limiting to auth endpoints.
+ * Each rule defines max requests and window size in minutes.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.exception.ApiErrorResponder;
diff --git a/backend/src/main/java/com/petshop/backend/security/RateLimiterService.java b/backend/src/main/java/com/petshop/backend/security/RateLimiterService.java
index 4f6eb94f..a95bafd0 100644
--- a/backend/src/main/java/com/petshop/backend/security/RateLimiterService.java
+++ b/backend/src/main/java/com/petshop/backend/security/RateLimiterService.java
@@ -1,3 +1,10 @@
+/*
+ * Sliding-window rate limiter that tracks request timestamps per key.
+ * Used to limit login/register attempts by IP.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import org.springframework.scheduling.annotation.Scheduled;
@@ -15,12 +22,22 @@ public class RateLimiterService {
 
     private final Map<String, Deque<Instant>> buckets = new ConcurrentHashMap<>();
 
+    /**
+     * Checks whether a request identified by key is within the rate limit.
+     * Uses a sliding window: keeps a queue of timestamps per key, drops any
+     * that fall outside the window, then checks if there's room for one more.
+     * @param key identifier for the rate limit bucket (e.g. IP address)
+     * @param maxRequests max number of requests allowed in the window
+     * @param window the time window to count requests in
+     * @return true if the request is allowed, false if rate limited
+     */
     public boolean isAllowed(String key, int maxRequests, Duration window) {
         Instant now = Instant.now();
         Instant windowStart = now.minus(window);
 
         Deque<Instant> timestamps = buckets.computeIfAbsent(key, k -> new ArrayDeque<>());
         synchronized (timestamps) {
+            // Remove timestamps that are older than the window
             while (!timestamps.isEmpty() && timestamps.peekFirst().isBefore(windowStart)) {
                 timestamps.pollFirst();
             }
diff --git a/backend/src/main/java/com/petshop/backend/security/RestAccessDeniedHandler.java b/backend/src/main/java/com/petshop/backend/security/RestAccessDeniedHandler.java
index fcaa49bc..dc41867b 100644
--- a/backend/src/main/java/com/petshop/backend/security/RestAccessDeniedHandler.java
+++ b/backend/src/main/java/com/petshop/backend/security/RestAccessDeniedHandler.java
@@ -1,3 +1,10 @@
+/*
+ * Returns a JSON error when a logged-in user tries to access
+ * something they don't have permission for.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.exception.ApiErrorResponder;
diff --git a/backend/src/main/java/com/petshop/backend/security/RestAuthenticationEntryPoint.java b/backend/src/main/java/com/petshop/backend/security/RestAuthenticationEntryPoint.java
index fb28314b..ba95590f 100644
--- a/backend/src/main/java/com/petshop/backend/security/RestAuthenticationEntryPoint.java
+++ b/backend/src/main/java/com/petshop/backend/security/RestAuthenticationEntryPoint.java
@@ -1,3 +1,9 @@
+/*
+ * Returns a JSON error when an unauthenticated request hits a protected endpoint.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.exception.ApiErrorResponder;
diff --git a/backend/src/main/java/com/petshop/backend/security/SecurityConfig.java b/backend/src/main/java/com/petshop/backend/security/SecurityConfig.java
index f154ead1..4d83867c 100644
--- a/backend/src/main/java/com/petshop/backend/security/SecurityConfig.java
+++ b/backend/src/main/java/com/petshop/backend/security/SecurityConfig.java
@@ -1,3 +1,10 @@
+/*
+ * Security setup for the app. Defines which endpoints are public,
+ * which need login, and configures the filter chain.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import org.springframework.beans.factory.annotation.Value;
diff --git a/backend/src/main/java/com/petshop/backend/security/UserAuthCacheService.java b/backend/src/main/java/com/petshop/backend/security/UserAuthCacheService.java
index 69d39a9d..c67d7da9 100644
--- a/backend/src/main/java/com/petshop/backend/security/UserAuthCacheService.java
+++ b/backend/src/main/java/com/petshop/backend/security/UserAuthCacheService.java
@@ -1,3 +1,10 @@
+/*
+ * Caches user auth data (active status, token version) so the
+ * JWT filter doesn't hit the database on every request.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.repository.UserRepository;
diff --git a/backend/src/main/java/com/petshop/backend/security/UserDetailsServiceImpl.java b/backend/src/main/java/com/petshop/backend/security/UserDetailsServiceImpl.java
index f6956615..87b6463d 100644
--- a/backend/src/main/java/com/petshop/backend/security/UserDetailsServiceImpl.java
+++ b/backend/src/main/java/com/petshop/backend/security/UserDetailsServiceImpl.java
@@ -1,3 +1,9 @@
+/*
+ * Loads user details from the database for Spring Security login.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.security;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/service/ActivityLogService.java b/backend/src/main/java/com/petshop/backend/service/ActivityLogService.java
index 598d9f95..fd1efdda 100644
--- a/backend/src/main/java/com/petshop/backend/service/ActivityLogService.java
+++ b/backend/src/main/java/com/petshop/backend/service/ActivityLogService.java
@@ -1,3 +1,10 @@
+/*
+ * Records and retrieves user activity logs so admins can
+ * see who did what and when.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.activity.ActivityLogResponse;
diff --git a/backend/src/main/java/com/petshop/backend/service/AdoptionService.java b/backend/src/main/java/com/petshop/backend/service/AdoptionService.java
index b99be2e2..a5b122e8 100644
--- a/backend/src/main/java/com/petshop/backend/service/AdoptionService.java
+++ b/backend/src/main/java/com/petshop/backend/service/AdoptionService.java
@@ -1,3 +1,10 @@
+/*
+ * Handles the pet adoption workflow from application
+ * through to approval and completion.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.adoption.AdoptionRequest;
@@ -165,6 +172,10 @@ public class AdoptionService {
         return mapToResponse(adoption);
     }
 
+    /**
+     * Customer-facing adoption request. Validates the pet is at the claimed store
+     * and available, then creates a Pending adoption and marks the pet as Pending.
+     */
     @Transactional
     public AdoptionResponse requestAdoption(Long customerId, Long petId, Long employeeId, Long sourceStoreId, LocalDate adoptionDate) {
         Pet pet = petRepository.findByIdForUpdate(petId)
@@ -235,6 +246,10 @@ public class AdoptionService {
         }
     }
 
+    /**
+     * When a Pending adoption is deleted, resets the pet back to Available
+     * unless another completed adoption already exists for it.
+     */
     private void resetPetIfPending(Pet pet, String deletedAdoptionStatus) {
         if (!ADOPTION_STATUS_PENDING.equalsIgnoreCase(deletedAdoptionStatus)) {
             return;
@@ -309,6 +324,11 @@ public class AdoptionService {
         throw new BusinessException("Adoption status must be Pending, Completed, Cancelled, or Missed");
     }
 
+    /**
+     * Ensures a pet hasn't already been adopted and is in Available status.
+     * When updating an existing adoption, skips the status check if the pet
+     * is the same one already attached to this adoption record.
+     */
     private void validatePetAvailability(Pet pet, Long adoptionId, Long currentPetId) {
         boolean samePetAsCurrentAdoption = currentPetId != null && currentPetId.equals(pet.getPetId());
         boolean adoptedElsewhere = adoptionId == null
@@ -323,6 +343,10 @@ public class AdoptionService {
         }
     }
 
+    /**
+     * Creates a sale record when an adoption is marked Completed, using
+     * the pet's price as the sale amount. Skipped if no employee or store is set.
+     */
     private void createSaleForAdoption(Adoption adoption, String paymentMethod) {
         if (adoption.getEmployee() == null || adoption.getSourceStore() == null) {
             return;
@@ -345,6 +369,11 @@ public class AdoptionService {
         eventPublisher.publishEvent(new SaleReceiptEvent(savedSale.getSaleId()));
     }
 
+    /**
+     * Keeps the pet's status in sync with the adoption lifecycle.
+     * Completed -> Adopted (removed from store), Pending -> Pending (reserved),
+     * Cancelled/Missed -> Available (back on the floor).
+     */
     private void syncPetStatus(Pet pet, String adoptionStatus, Long adoptionId, User customer) {
         boolean completedElsewhere = adoptionId != null
                 && adoptionRepository.existsByPet_IdAndAdoptionStatusIgnoreCaseAndAdoptionIdNot(pet.getPetId(), ADOPTION_STATUS_COMPLETED, adoptionId);
diff --git a/backend/src/main/java/com/petshop/backend/service/AnalyticsService.java b/backend/src/main/java/com/petshop/backend/service/AnalyticsService.java
index eae169d0..c8772274 100644
--- a/backend/src/main/java/com/petshop/backend/service/AnalyticsService.java
+++ b/backend/src/main/java/com/petshop/backend/service/AnalyticsService.java
@@ -1,3 +1,10 @@
+/*
+ * Builds the dashboard data by pulling together sales totals,
+ * inventory levels, and top-selling products.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.analytics.DashboardResponse;
diff --git a/backend/src/main/java/com/petshop/backend/service/AppointmentService.java b/backend/src/main/java/com/petshop/backend/service/AppointmentService.java
index 048bdc37..5ad5d46e 100644
--- a/backend/src/main/java/com/petshop/backend/service/AppointmentService.java
+++ b/backend/src/main/java/com/petshop/backend/service/AppointmentService.java
@@ -1,3 +1,10 @@
+/*
+ * Manages appointment booking, availability checking, and
+ * scheduled status updates for grooming and vet visits.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.appointment.AppointmentRequest;
@@ -222,6 +229,15 @@ public class AppointmentService {
         appointmentRepository.deleteAllById(request.getIds());
     }
 
+    /**
+     * Returns all bookable time slots for a given store, service, and date.
+     * Iterates through the business hours in fixed intervals, checking each
+     * slot against every employee at the store to see if at least one is free.
+     * @param storeId store to check
+     * @param serviceId service being booked (determines slot duration)
+     * @param date the date to check availability for
+     * @return list of available start times as strings
+     */
     @Transactional(readOnly = true)
     public List<String> checkAvailability(Long storeId, Long serviceId, LocalDate date) {
         storeRepository.findById(storeId)
@@ -236,6 +252,7 @@ public class AppointmentService {
             return List.of();
         }
 
+        // Batch-load all appointments for the day to avoid N+1 queries per employee
         List<Long> employeeIds = assignableUsers.stream().map(User::getId).collect(Collectors.toList());
         List<Appointment> allAppointments = appointmentRepository.findByEmployeeIdInAndAppointmentDate(employeeIds, date);
 
@@ -245,6 +262,7 @@ public class AppointmentService {
         List<String> availableSlots = new ArrayList<>();
         LocalTime startTime = businessProperties.openTime();
         LocalTime endTime = businessProperties.closeTime();
+        // Last slot must leave enough time for the service to finish before closing
         LocalTime latestStart = endTime.minusMinutes(service.getServiceDuration());
 
         LocalTime currentTime = startTime;
@@ -264,7 +282,11 @@ public class AppointmentService {
         return availableSlots;
     }
 
-    //Update booked status to completed at every midnight, and send 24h reminders
+    /**
+     * Midnight cron job that marks past booked appointments as Completed,
+     * sends 24-hour reminder emails for tomorrow's appointments,
+     * and sends reminders for pending adoptions scheduled for tomorrow.
+     */
     @Scheduled(cron = "0 0 0 * * ?")
     @Transactional
     public void updatePastAppointmentsStatus() {
@@ -379,6 +401,10 @@ public class AppointmentService {
         }
     }
 
+    /**
+     * Checks if a time slot is open by looking for overlaps with existing appointments.
+     * Uses interval overlap detection: two ranges overlap when each starts before the other ends.
+     */
     private boolean isSlotAvailable(List<Appointment> existingAppointments, com.petshop.backend.entity.Service requestedService, LocalTime requestedStart, Long appointmentIdToIgnore) {
         LocalTime requestedEnd = requestedStart.plusMinutes(requestedService.getServiceDuration());
         for (Appointment existingAppointment : existingAppointments) {
diff --git a/backend/src/main/java/com/petshop/backend/service/AvatarStorageService.java b/backend/src/main/java/com/petshop/backend/service/AvatarStorageService.java
index 5ff61021..e700e562 100644
--- a/backend/src/main/java/com/petshop/backend/service/AvatarStorageService.java
+++ b/backend/src/main/java/com/petshop/backend/service/AvatarStorageService.java
@@ -1,3 +1,10 @@
+/*
+ * Stores and retrieves user profile avatar images, using
+ * either local disk or Azure Blob Storage.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.entity.User;
diff --git a/backend/src/main/java/com/petshop/backend/service/AzureBlobService.java b/backend/src/main/java/com/petshop/backend/service/AzureBlobService.java
index cbdfc62d..a8a7d6dd 100644
--- a/backend/src/main/java/com/petshop/backend/service/AzureBlobService.java
+++ b/backend/src/main/java/com/petshop/backend/service/AzureBlobService.java
@@ -1,3 +1,10 @@
+/*
+ * Low-level wrapper around the Azure Blob Storage SDK for
+ * uploading, downloading, and deleting files.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.azure.storage.blob.BlobContainerClient;
diff --git a/backend/src/main/java/com/petshop/backend/service/CartService.java b/backend/src/main/java/com/petshop/backend/service/CartService.java
index 305d5ef4..77e76f1a 100644
--- a/backend/src/main/java/com/petshop/backend/service/CartService.java
+++ b/backend/src/main/java/com/petshop/backend/service/CartService.java
@@ -1,3 +1,10 @@
+/*
+ * Handles shopping cart operations, checkout with Stripe payments,
+ * and loyalty points redemption.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.cart.*;
@@ -230,6 +237,14 @@ public class CartService {
         return toResponse(cart);
     }
 
+    /**
+     * Starts the checkout flow for a user's active cart at a given store.
+     * Handles free checkouts (points cover everything or total is $0) directly,
+     * otherwise creates a Stripe PaymentIntent for card payment.
+     * @param userId the customer checking out
+     * @param storeId the store the cart belongs to
+     * @return checkout response with client secret for Stripe or success status for free orders
+     */
     @Transactional
     public CheckoutResponse checkout(Long userId, Long storeId) {
         Cart cart = cartRepository
@@ -316,6 +331,13 @@ public class CartService {
         }
     }
 
+    /**
+     * Finalizes checkout after Stripe confirms payment succeeded.
+     * Validates the payment intent metadata, re-checks the cart total hasn't
+     * drifted since checkout started, and creates the sale record.
+     * @param userId the customer completing checkout
+     * @param paymentIntentId Stripe payment intent to verify
+     */
     @Transactional
     public void completeCheckout(Long userId, String paymentIntentId) {
         try {
@@ -376,11 +398,13 @@ public class CartService {
                 throw new BusinessException("Cart items were removed during checkout");
             }
 
+            // Recalculate to make sure prices/coupons haven't changed mid-checkout
             BigDecimal recalculatedTotal = recalculateTotalAmount(cart);
             if (recalculatedTotal.compareTo(cart.getCheckoutAmount()) != 0) {
                 throw new BusinessException("Cart total changed during checkout");
             }
 
+            // Cross-check that what Stripe actually charged matches our expected amount
             long storedAmountInCents = cart.getCheckoutAmount()
                     .multiply(BigDecimal.valueOf(100))
                     .setScale(0, RoundingMode.HALF_UP)
@@ -390,6 +414,7 @@ public class CartService {
                 throw new BusinessException("Stripe charged amount does not match expected amount");
             }
 
+            // Guard against duplicate sale creation if completeCheckout is called twice
             if (saleRepository.findByCartCartId(cart.getCartId()).isPresent()) {
                 cart.setCartStatus("CHECKED_OUT");
                 cart.setCheckoutPending(false);
@@ -438,6 +463,10 @@ public class CartService {
 
     private record CartTotals(BigDecimal subtotal, BigDecimal discount, BigDecimal pointsDiscount, BigDecimal total) {}
 
+    /**
+     * Computes subtotal, coupon discount, points discount, and final total for a cart.
+     * Discounts are applied in order: coupon first, then loyalty points on the remainder.
+     */
     private CartTotals computeTotals(Cart cart) {
         List<CartItem> items = cartItemRepository.findByCartCartId(cart.getCartId());
 
@@ -468,6 +497,11 @@ public class CartService {
         return computeTotals(cart).total();
     }
 
+    /**
+     * Converts the user's loyalty points into a dollar discount.
+     * Points are converted at the configured rate (e.g. 100 points = $1).
+     * The discount is capped at the remaining amount so the total never goes negative.
+     */
     private BigDecimal calculatePointsDiscount(User user, BigDecimal remainingAmount, boolean pointsApplied) {
         if (!pointsApplied || user == null || remainingAmount.compareTo(BigDecimal.ZERO) <= 0) {
             return BigDecimal.ZERO;
diff --git a/backend/src/main/java/com/petshop/backend/service/CatalogImageStorageService.java b/backend/src/main/java/com/petshop/backend/service/CatalogImageStorageService.java
index 229ac5ba..69e28837 100644
--- a/backend/src/main/java/com/petshop/backend/service/CatalogImageStorageService.java
+++ b/backend/src/main/java/com/petshop/backend/service/CatalogImageStorageService.java
@@ -1,3 +1,10 @@
+/*
+ * Stores and retrieves images for pets and products, using
+ * either local disk or Azure Blob Storage.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import org.slf4j.Logger;
diff --git a/backend/src/main/java/com/petshop/backend/service/CategoryService.java b/backend/src/main/java/com/petshop/backend/service/CategoryService.java
index ea08dc3d..327d7ba7 100644
--- a/backend/src/main/java/com/petshop/backend/service/CategoryService.java
+++ b/backend/src/main/java/com/petshop/backend/service/CategoryService.java
@@ -1,3 +1,9 @@
+/*
+ * Handles creating, updating, and deleting product categories.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.category.CategoryRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/ChatAttachmentStorageService.java b/backend/src/main/java/com/petshop/backend/service/ChatAttachmentStorageService.java
index 55932b92..20d94e88 100644
--- a/backend/src/main/java/com/petshop/backend/service/ChatAttachmentStorageService.java
+++ b/backend/src/main/java/com/petshop/backend/service/ChatAttachmentStorageService.java
@@ -1,3 +1,10 @@
+/*
+ * Stores and retrieves file attachments sent in chat messages,
+ * using either local disk or Azure Blob Storage.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import org.springframework.beans.factory.annotation.Autowired;
diff --git a/backend/src/main/java/com/petshop/backend/service/ChatRealtimeService.java b/backend/src/main/java/com/petshop/backend/service/ChatRealtimeService.java
index d6b9d380..4e9f1c63 100644
--- a/backend/src/main/java/com/petshop/backend/service/ChatRealtimeService.java
+++ b/backend/src/main/java/com/petshop/backend/service/ChatRealtimeService.java
@@ -1,3 +1,10 @@
+/*
+ * Sends real-time chat updates to connected clients
+ * through WebSocket messages.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.chat.ConversationResponse;
diff --git a/backend/src/main/java/com/petshop/backend/service/ChatService.java b/backend/src/main/java/com/petshop/backend/service/ChatService.java
index bf519f23..77b866d7 100644
--- a/backend/src/main/java/com/petshop/backend/service/ChatService.java
+++ b/backend/src/main/java/com/petshop/backend/service/ChatService.java
@@ -1,3 +1,10 @@
+/*
+ * Manages chat conversations and messages between
+ * customers and store staff.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.chat.ConversationRequest;
@@ -76,6 +83,11 @@ public class ChatService {
         return ConversationResponse.fromEntity(conversation, greeting, botUser.getId());
     }
 
+    /**
+     * Lists conversations visible to the user based on their role.
+     * Customers only see their own. Staff see conversations assigned to them
+     * plus unassigned ones. Admins see everything.
+     */
     public List<ConversationResponse> getConversations(Long userId, User.Role role, boolean mine) {
         List<Conversation> conversations;
 
@@ -165,6 +177,7 @@ public class ChatService {
         message.setIsRead(false);
         message = messageRepository.save(message);
 
+        // When staff replies, claim the conversation and switch from AI to human mode
         if (role == User.Role.STAFF && conversation.getStaffId() == null) {
             conversation.setStaffId(userId);
         }
@@ -376,6 +389,10 @@ public class ChatService {
         return hasConversationAccess(conversation, userId, role);
     }
 
+    /**
+     * Access rules: admins can see all conversations, customers only their own,
+     * and staff can see unassigned conversations or ones assigned to them.
+     */
     private boolean hasConversationAccess(Conversation conversation, Long userId, User.Role role) {
         if (role == User.Role.ADMIN) {
             return true;
diff --git a/backend/src/main/java/com/petshop/backend/service/CouponService.java b/backend/src/main/java/com/petshop/backend/service/CouponService.java
index cf56188f..87d28c6c 100644
--- a/backend/src/main/java/com/petshop/backend/service/CouponService.java
+++ b/backend/src/main/java/com/petshop/backend/service/CouponService.java
@@ -1,3 +1,10 @@
+/*
+ * Handles creating, updating, and validating discount coupons
+ * that can be applied to sales.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/EmailService.java b/backend/src/main/java/com/petshop/backend/service/EmailService.java
index 6e096285..043c3cb9 100644
--- a/backend/src/main/java/com/petshop/backend/service/EmailService.java
+++ b/backend/src/main/java/com/petshop/backend/service/EmailService.java
@@ -1,3 +1,10 @@
+/*
+ * Sends transactional emails like receipts and confirmations
+ * using the Resend API.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.entity.Adoption;
diff --git a/backend/src/main/java/com/petshop/backend/service/InventoryService.java b/backend/src/main/java/com/petshop/backend/service/InventoryService.java
index af133e68..c71dcc15 100644
--- a/backend/src/main/java/com/petshop/backend/service/InventoryService.java
+++ b/backend/src/main/java/com/petshop/backend/service/InventoryService.java
@@ -1,3 +1,10 @@
+/*
+ * Manages inventory records that track how much of each
+ * product is available at each store location.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/OpenRouterAiService.java b/backend/src/main/java/com/petshop/backend/service/OpenRouterAiService.java
index d2e007dc..84f699e6 100644
--- a/backend/src/main/java/com/petshop/backend/service/OpenRouterAiService.java
+++ b/backend/src/main/java/com/petshop/backend/service/OpenRouterAiService.java
@@ -1,3 +1,10 @@
+/*
+ * Manages the AI chatbot conversation flow, building context
+ * and coordinating responses from OpenRouter.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.fasterxml.jackson.databind.JsonNode;
@@ -67,6 +74,12 @@ public class OpenRouterAiService {
         CompletableFuture.runAsync(() -> generateReply(conversationId, triggerMessageId));
     }
 
+    /**
+     * Generates an AI reply for a conversation by calling the OpenRouter API.
+     * Checks conversation state at multiple points to avoid replying if the
+     * conversation was closed, handed off to a human, or a newer message arrived
+     * while the API call was in flight.
+     */
     private void generateReply(Long conversationId, Long triggerMessageId) {
         try {
             if (triggerMessageId == null) {
@@ -105,6 +118,7 @@ public class OpenRouterAiService {
                 return;
             }
 
+            // Only reply if the trigger is still the latest message (no newer messages came in)
             Message lastMessage = history.get(history.size() - 1);
             if (!triggerMessageId.equals(lastMessage.getId())) {
                 return;
@@ -167,6 +181,7 @@ public class OpenRouterAiService {
                 return;
             }
 
+            // Re-check conversation state after the API call in case anything changed while waiting
             Conversation latestConversation = chatService.getConversationEntity(conversationId);
             if (latestConversation.getStatus() == Conversation.ConversationStatus.CLOSED
                 || latestConversation.getHumanRequestedAt() != null
@@ -174,6 +189,7 @@ public class OpenRouterAiService {
                 return;
             }
 
+            // Also re-check that no new messages were sent while the API call was in progress
             List<Message> latestHistory = messageRepository.findByConversationIdOrderByTimestampAsc(conversationId);
             if (latestHistory.isEmpty() || !triggerMessageId.equals(latestHistory.get(latestHistory.size() - 1).getId())) {
                 return;
diff --git a/backend/src/main/java/com/petshop/backend/service/OpenRouterService.java b/backend/src/main/java/com/petshop/backend/service/OpenRouterService.java
index c3314994..60e416ac 100644
--- a/backend/src/main/java/com/petshop/backend/service/OpenRouterService.java
+++ b/backend/src/main/java/com/petshop/backend/service/OpenRouterService.java
@@ -1,3 +1,10 @@
+/*
+ * Sends chat messages to the OpenRouter API and parses
+ * the AI model response.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.fasterxml.jackson.databind.JsonNode;
diff --git a/backend/src/main/java/com/petshop/backend/service/PasswordResetService.java b/backend/src/main/java/com/petshop/backend/service/PasswordResetService.java
index 6c5c78f5..1080bc35 100644
--- a/backend/src/main/java/com/petshop/backend/service/PasswordResetService.java
+++ b/backend/src/main/java/com/petshop/backend/service/PasswordResetService.java
@@ -1,3 +1,10 @@
+/*
+ * Handles the forgot-password flow by generating a reset token,
+ * emailing it to the user, and verifying it when they reset.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.auth.ForgotPasswordResponse;
diff --git a/backend/src/main/java/com/petshop/backend/service/PetService.java b/backend/src/main/java/com/petshop/backend/service/PetService.java
index 1c4cf875..552fdb40 100644
--- a/backend/src/main/java/com/petshop/backend/service/PetService.java
+++ b/backend/src/main/java/com/petshop/backend/service/PetService.java
@@ -1,3 +1,10 @@
+/*
+ * Handles creating, updating, and listing pets with
+ * visibility rules based on user role.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
@@ -53,6 +60,11 @@ public class PetService {
         this.catalogImageStorageService = catalogImageStorageService;
     }
 
+    /**
+     * Lists pets with role-based visibility filtering.
+     * Unauthenticated users only see Available pets. Customers see Available
+     * pets plus their own Adopted/Owned ones. Staff and admins see all.
+     */
     @Transactional(readOnly = true)
     public Page<PetResponse> getAllPets(String query, String species, String breed, String status, Long storeId, Long customerId, Pageable pageable) {
         String normalizedQuery = StringUtils.trimToNull(query);
@@ -229,6 +241,10 @@ public class PetService {
         return "available".equalsIgnoreCase(normalizeStatus(pet.getPetStatus()));
     }
 
+    /**
+     * Visibility rules: Available pets are public. Staff/admins see everything.
+     * Customers can see pets they own or have adopted.
+     */
     private boolean canViewPet(Pet pet, CurrentViewer viewer) {
         if (isPubliclyVisible(pet)) {
             return true;
@@ -245,6 +261,9 @@ public class PetService {
         return isAdoptedByUser(pet, viewer.userId());
     }
 
+    /**
+     * Checks if the pet was adopted by this user by looking for a Completed adoption record.
+     */
     private boolean isAdoptedByUser(Pet pet, Long userId) {
         if (userId == null) {
             return false;
@@ -354,6 +373,11 @@ public class PetService {
         return trimmed.isEmpty() ? null : trimmed;
     }
 
+    /**
+     * Sets the owner and store based on pet status. Owned pets get an owner
+     * but no store. Available pets get a store but no owner. Other statuses
+     * can have both.
+     */
     private void applyOwnerAndStore(Pet pet, PetRequest request) {
         if ("owned".equalsIgnoreCase(request.getPetStatus())) {
             if (request.getCustomerId() != null) {
diff --git a/backend/src/main/java/com/petshop/backend/service/ProductService.java b/backend/src/main/java/com/petshop/backend/service/ProductService.java
index ad4524fe..b9061d0c 100644
--- a/backend/src/main/java/com/petshop/backend/service/ProductService.java
+++ b/backend/src/main/java/com/petshop/backend/service/ProductService.java
@@ -1,3 +1,10 @@
+/*
+ * Manages products in the catalog, including searching,
+ * creating, updating, and handling product images.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/ProductSupplierService.java b/backend/src/main/java/com/petshop/backend/service/ProductSupplierService.java
index 5adc79fb..25545918 100644
--- a/backend/src/main/java/com/petshop/backend/service/ProductSupplierService.java
+++ b/backend/src/main/java/com/petshop/backend/service/ProductSupplierService.java
@@ -1,3 +1,10 @@
+/*
+ * Manages the links between products and their suppliers,
+ * including the cost each supplier charges for a product.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.productsupplier.BulkDeleteProductSupplierRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/PurchaseOrderService.java b/backend/src/main/java/com/petshop/backend/service/PurchaseOrderService.java
index a6803d37..eaa712c2 100644
--- a/backend/src/main/java/com/petshop/backend/service/PurchaseOrderService.java
+++ b/backend/src/main/java/com/petshop/backend/service/PurchaseOrderService.java
@@ -1,3 +1,10 @@
+/*
+ * Provides read-only access to purchase orders, which track
+ * orders placed with suppliers for restocking stores.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.purchaseorder.PurchaseOrderResponse;
diff --git a/backend/src/main/java/com/petshop/backend/service/RefundService.java b/backend/src/main/java/com/petshop/backend/service/RefundService.java
index 6cfff23d..0716bd90 100644
--- a/backend/src/main/java/com/petshop/backend/service/RefundService.java
+++ b/backend/src/main/java/com/petshop/backend/service/RefundService.java
@@ -1,3 +1,10 @@
+/*
+ * Processes refunds for sales, calculating the refund amount
+ * and updating the original sale record.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.refund.RefundItemResponse;
diff --git a/backend/src/main/java/com/petshop/backend/service/SaleService.java b/backend/src/main/java/com/petshop/backend/service/SaleService.java
index d33d11b3..c21d2143 100644
--- a/backend/src/main/java/com/petshop/backend/service/SaleService.java
+++ b/backend/src/main/java/com/petshop/backend/service/SaleService.java
@@ -1,3 +1,10 @@
+/*
+ * Creates and manages sales records, including refunds and
+ * discount calculations.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.sale.SaleRequest;
@@ -62,6 +69,14 @@ public class SaleService {
         return mapToResponse(sale);
     }
 
+    /**
+     * Creates a sale or refund record. For regular sales, deducts inventory and
+     * applies coupon/employee/loyalty discounts in that order. For refunds,
+     * restores inventory and proportionally reverses discounts and loyalty points
+     * based on the refund-to-original subtotal ratio.
+     * @param request sale details including items, store, and discount info
+     * @return the created sale
+     */
     @Transactional
     public SaleResponse createSale(SaleRequest request) {
         User actor = AuthenticationHelper.getAuthenticatedUser(userRepository);
@@ -136,6 +151,7 @@ public class SaleService {
                             " for product: " + product.getProdName());
                 }
 
+                // Sum up quantities already refunded across all prior refunds for this product
                 int alreadyRefundedQuantity = saleRepository.findByOriginalSaleSaleId(sale.getOriginalSale().getSaleId()).stream()
                         .flatMap(existingRefund -> existingRefund.getItems().stream())
                         .filter(existingRefundItem -> existingRefundItem.getProduct().getProdId().equals(itemRequest.getProdId()))
@@ -176,6 +192,7 @@ public class SaleService {
             BigDecimal couponDiscountRefunded = BigDecimal.ZERO;
             BigDecimal refundTotal;
 
+            // Proportionally split discounts based on what fraction of the original order is being refunded
             if (originalSubtotal != null && originalSubtotal.compareTo(BigDecimal.ZERO) > 0) {
                 BigDecimal ratio = subtotalAmount.abs().divide(originalSubtotal, 10, RoundingMode.HALF_UP);
                 refundTotal = originalSale.getTotalAmount().abs().multiply(ratio).negate().setScale(2, RoundingMode.HALF_UP);
@@ -188,6 +205,7 @@ public class SaleService {
                 User refundCustomer = originalSale.getCustomer();
                 if (refundCustomer != null) {
                     sale.setCustomer(refundCustomer);
+                    // Give back the points that were spent, subtract the points that were earned
                     int pointsToRestore = toPointsUsed(loyaltyDiscountRefunded);
                     int pointsEarnedToReverse = originalSale.getPointsEarned() != null
                             ? ratio.multiply(BigDecimal.valueOf(originalSale.getPointsEarned())).setScale(0, RoundingMode.FLOOR).intValue()
@@ -245,6 +263,7 @@ public class SaleService {
             BigDecimal employeeDiscount = calculateEmployeeDiscount(customer, subtotalAmount.subtract(couponDiscount));
             sale.setEmployeeDiscountAmount(employeeDiscount);
 
+            // Loyalty discount is applied last, after coupon and employee discounts
             BigDecimal remainingAfterDiscounts = subtotalAmount.subtract(couponDiscount).subtract(employeeDiscount);
             BigDecimal loyaltyDiscount;
             int pointsDeducted;
@@ -265,6 +284,7 @@ public class SaleService {
             BigDecimal finalTotal = subtotalAmount.subtract(couponDiscount).subtract(employeeDiscount).subtract(loyaltyDiscount);
             sale.setTotalAmount(finalTotal.max(BigDecimal.ZERO));
 
+            // Earn 1 point per dollar spent (floor), then update the customer's balance
             sale.setPointsEarned(sale.getTotalAmount().setScale(0, RoundingMode.FLOOR).intValue());
             if (customer != null) {
                 int currentPoints = customer.getLoyaltyPoints() != null ? customer.getLoyaltyPoints() : 0;
@@ -314,6 +334,9 @@ public class SaleService {
                 .setScale(2, RoundingMode.HALF_UP);
     }
 
+    /**
+     * Converts a dollar discount back into the number of loyalty points it represents.
+     */
     private int toPointsUsed(BigDecimal loyaltyDiscount) {
         if (loyaltyDiscount == null || loyaltyDiscount.compareTo(BigDecimal.ZERO) <= 0) {
             return 0;
@@ -321,6 +344,10 @@ public class SaleService {
         return loyaltyDiscount.setScale(0, RoundingMode.DOWN).intValue() * businessProperties.loyaltyPointsPerDollar();
     }
 
+    /**
+     * Website sales need an employee on record. Picks a staff member at the
+     * store, or falls back to any admin if no staff is available.
+     */
     private User resolveWebsiteSaleEmployee(Long storeId) {
         return userRepository.findFirstByPrimaryStoreStoreIdAndRoleAndActiveTrueOrderByIdAsc(storeId, User.Role.STAFF)
                 .or(() -> userRepository.findFirstByRoleAndActiveTrueOrderByIdAsc(User.Role.ADMIN))
diff --git a/backend/src/main/java/com/petshop/backend/service/ServiceService.java b/backend/src/main/java/com/petshop/backend/service/ServiceService.java
index ecf644c2..f05b694f 100644
--- a/backend/src/main/java/com/petshop/backend/service/ServiceService.java
+++ b/backend/src/main/java/com/petshop/backend/service/ServiceService.java
@@ -1,3 +1,10 @@
+/*
+ * Manages pet services like grooming and veterinary care,
+ * including searching and filtering by species.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/StoreService.java b/backend/src/main/java/com/petshop/backend/service/StoreService.java
index d9c1bcd3..2dfb763e 100644
--- a/backend/src/main/java/com/petshop/backend/service/StoreService.java
+++ b/backend/src/main/java/com/petshop/backend/service/StoreService.java
@@ -1,3 +1,9 @@
+/*
+ * Handles creating, updating, and deleting store locations.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/SupplierService.java b/backend/src/main/java/com/petshop/backend/service/SupplierService.java
index 4bb79b5a..a1bb3955 100644
--- a/backend/src/main/java/com/petshop/backend/service/SupplierService.java
+++ b/backend/src/main/java/com/petshop/backend/service/SupplierService.java
@@ -1,3 +1,9 @@
+/*
+ * Handles creating, updating, and deleting suppliers.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
diff --git a/backend/src/main/java/com/petshop/backend/service/UserService.java b/backend/src/main/java/com/petshop/backend/service/UserService.java
index 99e25747..587ce9d6 100644
--- a/backend/src/main/java/com/petshop/backend/service/UserService.java
+++ b/backend/src/main/java/com/petshop/backend/service/UserService.java
@@ -1,3 +1,10 @@
+/*
+ * Handles creating, updating, and deleting user accounts
+ * and managing their roles and store assignments.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package com.petshop.backend.service;
 
 import com.petshop.backend.dto.common.BulkDeleteRequest;
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 {
diff --git a/desktop/src/main/java/module-info.java b/desktop/src/main/java/module-info.java
index 93a6704e..1a504108 100644
--- a/desktop/src/main/java/module-info.java
+++ b/desktop/src/main/java/module-info.java
@@ -1,3 +1,9 @@
+/*
+ * Module descriptor for the pet shop desktop application.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 module org.example.petshopdesktop {
     requires javafx.controls;
     requires javafx.fxml;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/DTOs/AppointmentDTO.java b/desktop/src/main/java/org/example/petshopdesktop/DTOs/AppointmentDTO.java
index 82b242b9..077d37df 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/DTOs/AppointmentDTO.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/DTOs/AppointmentDTO.java
@@ -1,3 +1,9 @@
+/*
+ * Table-friendly wrapper for appointment data using JavaFX properties.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.DTOs;
 
 import javafx.beans.property.SimpleIntegerProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductDTO.java b/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductDTO.java
index 3270d6ca..425403bc 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductDTO.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductDTO.java
@@ -1,3 +1,9 @@
+/*
+ * Table-friendly wrapper for product data using JavaFX properties.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.DTOs;
 
 import javafx.beans.property.SimpleDoubleProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductSupplierDTO.java b/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductSupplierDTO.java
index 8fb481b0..9e39a8fa 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductSupplierDTO.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/DTOs/ProductSupplierDTO.java
@@ -1,3 +1,9 @@
+/*
+ * Table-friendly wrapper for product-supplier data using JavaFX properties.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.DTOs;
 
 import javafx.beans.property.SimpleDoubleProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/DTOs/PurchaseOrderDTO.java b/desktop/src/main/java/org/example/petshopdesktop/DTOs/PurchaseOrderDTO.java
index d30053cb..c12dd359 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/DTOs/PurchaseOrderDTO.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/DTOs/PurchaseOrderDTO.java
@@ -1,3 +1,9 @@
+/*
+ * Table-friendly wrapper for purchase order data using JavaFX properties.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.DTOs;
 
 import javafx.beans.property.*;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/DTOs/SaleDTO.java b/desktop/src/main/java/org/example/petshopdesktop/DTOs/SaleDTO.java
index a20bf5fd..37f91e2d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/DTOs/SaleDTO.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/DTOs/SaleDTO.java
@@ -1,3 +1,9 @@
+/*
+ * Table-friendly wrapper for sale data using JavaFX properties.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.DTOs;
 
 import javafx.beans.property.*;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/DTOs/ServiceDTO.java b/desktop/src/main/java/org/example/petshopdesktop/DTOs/ServiceDTO.java
index c876cd3f..2b857bcd 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/DTOs/ServiceDTO.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/DTOs/ServiceDTO.java
@@ -1,3 +1,9 @@
+/*
+ * Table-friendly wrapper for service data using JavaFX properties.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.DTOs;
 
 import javafx.beans.property.SimpleDoubleProperty;
@@ -107,4 +113,4 @@ public class ServiceDTO {
 
         return service;
     }
-}
\ No newline at end of file
+}
diff --git a/desktop/src/main/java/org/example/petshopdesktop/Launcher.java b/desktop/src/main/java/org/example/petshopdesktop/Launcher.java
index 70456482..02c3c863 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/Launcher.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/Launcher.java
@@ -1,3 +1,9 @@
+/*
+ * Entry point that starts the JavaFX application.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop;
 
 import javafx.application.Application;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/PetShopApplication.java b/desktop/src/main/java/org/example/petshopdesktop/PetShopApplication.java
index 18296405..24bf8718 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/PetShopApplication.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/PetShopApplication.java
@@ -1,3 +1,9 @@
+/*
+ * Main JavaFX application that sets up and launches the window.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop;
 
 import javafx.application.Application;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/Validator.java b/desktop/src/main/java/org/example/petshopdesktop/Validator.java
index 1a453556..5b473da1 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/Validator.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/Validator.java
@@ -1,3 +1,9 @@
+/*
+ * Shared input validation methods used across the app.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop;
 
 public class Validator {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/ApiClient.java b/desktop/src/main/java/org/example/petshopdesktop/api/ApiClient.java
index baf1b99a..7317709c 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/ApiClient.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/ApiClient.java
@@ -1,3 +1,9 @@
+/*
+ * Handles sending HTTP requests to the backend server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -116,6 +122,15 @@ public class ApiClient {
         return handleResponse(response, responseClass);
     }
 
+    /**
+     * Uploads a single file as a multipart/form-data POST.
+     * Manually builds the multipart body since Java's HttpClient doesn't have built-in support.
+     * @param path API endpoint path
+     * @param partName the form field name for the file
+     * @param filePath local file to upload
+     * @param responseClass type to deserialize the response into
+     * @return the parsed response
+     */
     public <T> T postMultipart(String path, String partName, Path filePath, Class<T> responseClass) throws Exception {
         String boundary = "----PetShopDesktop" + UUID.randomUUID();
         String mimeType = Files.probeContentType(filePath);
@@ -146,6 +161,17 @@ public class ApiClient {
         return handleResponse(response, responseClass);
     }
 
+    /**
+     * Uploads a file along with an optional text field in a single multipart POST.
+     * Uses SequenceInputStream to stream the file instead of loading everything into one byte array.
+     * @param path API endpoint path
+     * @param filePartName form field name for the file
+     * @param filePath local file to upload
+     * @param textPartName form field name for the text
+     * @param textContent the text value to send alongside the file
+     * @param responseClass type to deserialize the response into
+     * @return the parsed response
+     */
     public <T> T postMultipartWithText(String path, String filePartName, Path filePath,
                                         String textPartName, String textContent,
                                         Class<T> responseClass) throws Exception {
@@ -218,6 +244,11 @@ public class ApiClient {
         }
     }
 
+    /**
+     * Sends a DELETE with a JSON body (used for batch deletes).
+     * @param path API endpoint path
+     * @param requestBody object to serialize as the request body
+     */
     public void deleteWithBody(String path, Object requestBody) throws Exception {
         String jsonBody = objectMapper.writeValueAsString(requestBody);
 
@@ -244,6 +275,12 @@ public class ApiClient {
         }
     }
 
+    /**
+     * Checks the HTTP status and either deserializes the body or throws a readable error.
+     * @param response the raw HTTP response
+     * @param responseClass type to deserialize into
+     * @return the parsed response body, or null for 204/empty
+     */
     private <T> T handleResponse(HttpResponse<String> response, Class<T> responseClass) throws Exception {
         int statusCode = response.statusCode();
 
@@ -263,6 +300,13 @@ public class ApiClient {
         }
     }
 
+    /**
+     * Tries to extract a human-readable error from the JSON response body.
+     * Looks for an "errors" map first (field validation), then a "message" field,
+     * and falls back to the raw status code.
+     * @param response the failed HTTP response
+     * @return a user-facing error string
+     */
     private String parseErrorMessage(HttpResponse<String> response) {
         try {
             if (response.body() != null && !response.body().isEmpty()) {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/ApiConfig.java b/desktop/src/main/java/org/example/petshopdesktop/api/ApiConfig.java
index 3394c653..8e6fd90d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/ApiConfig.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/ApiConfig.java
@@ -1,3 +1,9 @@
+/*
+ * Stores the base URL and connection settings for the API.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api;
 
 import java.io.IOException;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/ChatRealtimeClient.java b/desktop/src/main/java/org/example/petshopdesktop/api/ChatRealtimeClient.java
index a505c514..1042a0f3 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/ChatRealtimeClient.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/ChatRealtimeClient.java
@@ -1,3 +1,9 @@
+/*
+ * Manages a real-time WebSocket connection for the chat feature.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api;
 
 import org.example.petshopdesktop.api.dto.chat.ConversationResponse;
@@ -59,6 +65,10 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         return INSTANCE;
     }
 
+    /**
+     * Registers a listener that gets called when chat notification state changes.
+     * @param listener receives true if there are chats needing attention
+     */
     public void addNotificationListener(Consumer<Boolean> listener) {
         synchronized (lock) {
             notificationListeners.add(listener);
@@ -66,6 +76,11 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         }
     }
 
+    /**
+     * Seeds the global conversation map from a full list fetch.
+     * Called on first load and on refresh to sync local state with server.
+     * @param conversations the full list from the REST API
+     */
     public void initializeState(List<ConversationResponse> conversations) {
         synchronized (lock) {
             globalConversations.clear();
@@ -76,6 +91,12 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         updateNotificationState();
     }
 
+    /**
+     * Marks a conversation as replied to by updating the last sender and read state.
+     * Used after the current user sends a message so the badge clears.
+     * @param conversationId the conversation that was replied to
+     * @param senderId the user who sent the reply
+     */
     public void markConversationReplied(Long conversationId, Long senderId) {
         synchronized (lock) {
             ConversationResponse conv = globalConversations.get(conversationId);
@@ -100,6 +121,12 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         }
     }
 
+    /**
+     * Checks if any open conversation needs staff attention.
+     * Two cases count: unassigned chats waiting for pickup,
+     * and chats assigned to me where the customer sent the last message.
+     * @return true if there's at least one chat needing action
+     */
     public boolean hasActionableChats() {
         synchronized (lock) {
             UserSession session = UserSession.getInstance();
@@ -125,6 +152,9 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         }
     }
 
+    /**
+     * Recalculates the badge state and notifies listeners only if it changed.
+     */
     private void updateNotificationState() {
         boolean currentState = hasActionableChats();
         List<Consumer<Boolean>> listeners;
@@ -153,6 +183,10 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         }
     }
 
+    /**
+     * Opens the WebSocket and sends a STOMP CONNECT frame with the JWT.
+     * No-ops if already connected or mid-handshake.
+     */
     public void connect() {
         String token = UserSession.getInstance().getJwtToken();
         if (token == null || token.isBlank()) {
@@ -167,6 +201,7 @@ public class ChatRealtimeClient implements WebSocket.Listener {
             connecting = true;
         }
 
+        // Convert the REST base URL to a WebSocket URL
         String wsUrl = ApiConfig.getInstance().getBaseUrl()
                 .replaceFirst("^http://", "ws://")
                 .replaceFirst("^https://", "wss://") + "/ws/chat";
@@ -236,6 +271,13 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         }
     }
 
+    /**
+     * Sends a chat message over the WebSocket using a STOMP SEND frame.
+     * Falls back to reconnecting if the socket isn't ready.
+     * @param conversationId target conversation
+     * @param content the message text
+     * @return true if the frame was sent, false if not connected
+     */
     public boolean sendMessage(Long conversationId, String content) {
         String token = UserSession.getInstance().getJwtToken();
         if (token == null || token.isBlank()) {
@@ -287,6 +329,10 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         applySelectedConversationSubscriptionLocked();
     }
 
+    /**
+     * Subscribes to the currently selected conversation's message topic.
+     * Unsubscribes from the previous one first if it changed.
+     */
     private void applySelectedConversationSubscriptionLocked() {
         if (webSocket == null || !connected) {
             return;
@@ -324,6 +370,12 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         updateNotificationState();
     }
 
+    /**
+     * Parses a single STOMP frame and dispatches it.
+     * Handles CONNECTED (finish handshake), MESSAGE (deliver to listeners),
+     * and ERROR frames.
+     * @param frame the raw STOMP frame text without the null terminator
+     */
     private void handleFrame(String frame) {
         String normalized = frame.replace("\r\n", "\n");
         int separator = normalized.indexOf("\n\n");
@@ -354,11 +406,14 @@ public class ChatRealtimeClient implements WebSocket.Listener {
         }
 
         if ("MESSAGE".equals(command)) {
+            // Look up which topic this subscription maps to
             String destination;
             synchronized (lock) {
                 destination = destinationBySubscription.get(headers.get("subscription"));
             }
             try {
+                // Messages on a specific conversation topic are chat messages;
+                // messages on the general conversations topic are conversation updates
                 if (destination != null && destination.startsWith("/topic/chat/conversations/")) {
                     MessageResponse message = ApiClient.getInstance().getObjectMapper().readValue(bodyPart, MessageResponse.class);
                     if (messageListener != null) {
@@ -371,12 +426,14 @@ public class ChatRealtimeClient implements WebSocket.Listener {
                                 .notifyNewMessage(message.getSenderDisplayName(), message.getContent());
                     }
 
+                    // Keep the global map in sync for badge calculations
                     synchronized (lock) {
                         ConversationResponse conv = globalConversations.get(message.getConversationId());
                         if (conv != null) {
                             conv.setLastMessage(message.getContent());
                             conv.setLastSenderId(message.getSenderId());
                         }
+                        // Incoming message from someone else marks it unread again
                         if (message.getSenderId() != null && !message.getSenderId().equals(currentUserId)) {
                             readConversationIds.remove(message.getConversationId());
                         }
@@ -416,6 +473,11 @@ public class ChatRealtimeClient implements WebSocket.Listener {
     }
 
     @Override
+    /**
+     * Accumulates WebSocket text fragments and splits on the STOMP null delimiter.
+     * A single WebSocket message can contain partial frames, so we buffer until
+     * we see the \0 that marks the end of a STOMP frame.
+     */
     public CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last) {
         synchronized (lock) {
             frameBuffer.append(data);
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/activity/ActivityLogResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/activity/ActivityLogResponse.java
index 482476eb..8930c012 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/activity/ActivityLogResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/activity/ActivityLogResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for an activity log entry.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.activity;
 
 import java.time.LocalDateTime;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionRequest.java
index b1d56eab..2df613b0 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating an adoption.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.adoption;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionResponse.java
index 56134bff..7e3e6469 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/adoption/AdoptionResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for an adoption record.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.adoption;
 
 import java.time.LocalDate;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DailySales.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DailySales.java
index 320a8266..4647a4ca 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DailySales.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DailySales.java
@@ -1,3 +1,9 @@
+/*
+ * Holds daily sales total data returned from the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.analytics;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DashboardResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DashboardResponse.java
index 38b17b81..bd5cc464 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DashboardResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/DashboardResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds all the summary data shown on the dashboard.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.analytics;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/TopProduct.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/TopProduct.java
index a62ccce9..d6b82da8 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/TopProduct.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/analytics/TopProduct.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data for a top-selling product from the analytics endpoint.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.analytics;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentRequest.java
index e8166411..3d610486 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating an appointment.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.appointment;
 
 import java.time.LocalDate;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentResponse.java
index dd74554b..84c5dfc9 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/appointment/AppointmentResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for an appointment.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.appointment;
 
 import java.time.LocalDate;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/AvatarUploadResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/AvatarUploadResponse.java
index 24dadcca..7eae590c 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/AvatarUploadResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/AvatarUploadResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds the URL returned after uploading a user avatar.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.auth;
 
 public class AvatarUploadResponse {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginRequest.java
index 89d6a98f..57e03da5 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds the username and password sent when logging in.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.auth;
 
 public class LoginRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginResponse.java
index 50354d48..abb0e6f7 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/LoginResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds the token and user info returned after logging in.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.auth;
 
 public class LoginResponse {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/UserInfoResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/UserInfoResponse.java
index fe83893c..0a62318b 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/UserInfoResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/auth/UserInfoResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds the current user's profile information from the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.auth;
 
 public class UserInfoResponse {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationRequest.java
index cd5ef6ee..a5946bad 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when starting a new conversation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.chat;
 
 public class ConversationRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationResponse.java
index 30a24fbb..ee0887de 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/ConversationResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a conversation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.chat;
 
 import java.time.LocalDateTime;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageRequest.java
index a5c17ca4..9adfe551 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when sending a chat message.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.chat;
 
 public class MessageRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageResponse.java
index 7aecada0..b8026f96 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/MessageResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a chat message.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.chat;
 
 import java.time.LocalDateTime;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/UpdateConversationRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/UpdateConversationRequest.java
index 3bacbca9..17cd18fa 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/UpdateConversationRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/chat/UpdateConversationRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when updating a conversation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.chat;
 
 public class UpdateConversationRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/BulkDeleteRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/BulkDeleteRequest.java
index d95798ef..cc5f29b3 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/BulkDeleteRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/BulkDeleteRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds a list of IDs to delete multiple records at once.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.common;
 
 import java.util.List;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/DropdownOption.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/DropdownOption.java
index bacbad0b..d453fe0e 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/DropdownOption.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/DropdownOption.java
@@ -1,3 +1,9 @@
+/*
+ * Holds an ID and label pair used to fill dropdown menus.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.common;
 
 public class DropdownOption {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/PageResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/PageResponse.java
index 5a27e2e9..9c4b8df1 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/PageResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/common/PageResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds a page of results along with pagination details.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.common;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponRequest.java
index dc11d55c..f8708c5d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating a coupon.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.coupon;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponResponse.java
index e1c23f0d..0acf2698 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/coupon/CouponResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a coupon.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.coupon;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeRequest.java
index dd2a7271..9d4a0c29 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating an employee.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.employee;
 
 public class EmployeeRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeResponse.java
index c6a32d23..a3a59e63 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/employee/EmployeeResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for an employee.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.employee;
 
 import java.time.LocalDateTime;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryRequest.java
index 935a713e..4182b455 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when updating inventory.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.inventory;
 
 public class InventoryRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryResponse.java
index 176228b9..536d058a 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/inventory/InventoryResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for an inventory record.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.inventory;
 
 import java.time.LocalDateTime;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetRequest.java
index 4bb56185..c6e793dc 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating a pet.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.pet;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetResponse.java
index f0961a18..d850111c 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/pet/PetResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a pet.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.pet;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductRequest.java
index 020afca6..9e4c4461 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating a product.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.product;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductResponse.java
index 18f9b678..65901061 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/product/ProductResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a product.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.product;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierRequest.java
index 69f4ad61..ee862426 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when linking a product to a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.productsupplier;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierResponse.java
index b601efe3..cb31d536 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/productsupplier/ProductSupplierResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a product-supplier link.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.productsupplier;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/purchaseorder/PurchaseOrderResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/purchaseorder/PurchaseOrderResponse.java
index c928e649..a8aeb8a5 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/purchaseorder/PurchaseOrderResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/purchaseorder/PurchaseOrderResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a purchase order.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.purchaseorder;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemRequest.java
index 03401958..3e5de272 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data for a single item in a sale request.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.sale;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemResponse.java
index 8bed99b1..759a7f26 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleItemResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a single sale item.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.sale;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleRequest.java
index fe324bb5..fe9ff428 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating a sale.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.sale;
 
 import java.util.List;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleResponse.java
index f814cc17..aaf4facf 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/sale/SaleResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a sale.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.sale;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceRequest.java
index 8fd68a1b..2e68d972 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating a service.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.service;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceResponse.java
index caf2e3ff..374fc1fc 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/service/ServiceResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a service.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.service;
 
 import java.math.BigDecimal;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierRequest.java
index fb3dcd92..d437877f 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.supplier;
 
 public class SupplierRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierResponse.java
index 64db982f..7325b69e 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/supplier/SupplierResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.supplier;
 
 public class SupplierResponse {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserRequest.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserRequest.java
index e4dd940d..080ed678 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserRequest.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserRequest.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data sent to the server when creating or updating a user.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.user;
 
 public class UserRequest {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserResponse.java b/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserResponse.java
index 2e1daa0e..3df18650 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserResponse.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/dto/user/UserResponse.java
@@ -1,3 +1,9 @@
+/*
+ * Holds data returned from the server for a user.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.dto.user;
 
 import java.time.LocalDateTime;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ActivityLogApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ActivityLogApi.java
index 6c092b78..2bcf5c64 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ActivityLogApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ActivityLogApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to fetch activity logs from the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AdoptionApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AdoptionApi.java
index e9291e8f..a46cbad6 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AdoptionApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AdoptionApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage adoptions through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AnalyticsApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AnalyticsApi.java
index ebecd9c2..975d8725 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AnalyticsApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AnalyticsApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to fetch analytics and dashboard data from the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import org.example.petshopdesktop.api.ApiClient;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AppointmentApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AppointmentApi.java
index 0fe56661..25381423 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AppointmentApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AppointmentApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage appointments through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AuthApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AuthApi.java
index e45ead94..476d213c 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AuthApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/AuthApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods for logging in and managing authentication.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import org.example.petshopdesktop.api.ApiClient;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ChatApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ChatApi.java
index 3d58547e..f40a5998 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ChatApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ChatApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage chat conversations and messages.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CouponApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CouponApi.java
index a08e0016..652be9f3 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CouponApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CouponApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage coupons through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CustomerApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CustomerApi.java
index 54f89f66..0abd05e4 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CustomerApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/CustomerApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage customers through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/DropdownApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/DropdownApi.java
index 4f0d34b9..1ef3dcf8 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/DropdownApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/DropdownApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to fetch dropdown option lists from the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/EmployeeApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/EmployeeApi.java
index e3a8ad52..7505cc87 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/EmployeeApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/EmployeeApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage employees through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/InventoryApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/InventoryApi.java
index bf34cf22..0660c816 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/InventoryApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/InventoryApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage inventory through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PetApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PetApi.java
index 865bb1ea..79221563 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PetApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PetApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage pets through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductApi.java
index c5ec100d..d3a61f5f 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage products through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductSupplierApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductSupplierApi.java
index 74143c0f..4f95923a 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductSupplierApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ProductSupplierApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage product-supplier links through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PurchaseOrderApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PurchaseOrderApi.java
index 5ce083f9..5465ed64 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PurchaseOrderApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/PurchaseOrderApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage purchase orders through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SaleApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SaleApi.java
index ab1c4fa1..bb7b704b 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SaleApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SaleApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage sales through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ServiceApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ServiceApi.java
index 66b348dc..91008473 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ServiceApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/ServiceApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage services through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SupplierApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SupplierApi.java
index bcfb8acb..e8f3ea42 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SupplierApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/SupplierApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage suppliers through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/UserApi.java b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/UserApi.java
index 27439ee9..0d2da6d4 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/UserApi.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/api/endpoints/UserApi.java
@@ -1,3 +1,9 @@
+/*
+ * Provides methods to manage user accounts through the server.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.api.endpoints;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/auth/Role.java b/desktop/src/main/java/org/example/petshopdesktop/auth/Role.java
index 64f38459..3c9a1042 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/auth/Role.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/auth/Role.java
@@ -1,3 +1,9 @@
+/*
+ * Defines the roles a user can have in the system.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.auth;
 
 public enum Role {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/auth/UserSession.java b/desktop/src/main/java/org/example/petshopdesktop/auth/UserSession.java
index cd5646f4..095c7ae8 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/auth/UserSession.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/auth/UserSession.java
@@ -1,3 +1,9 @@
+/*
+ * Stores the currently logged-in user's session details.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.auth;
 
 public class UserSession {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/ActivityLogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/ActivityLogController.java
index 06f94874..25f89ecf 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/ActivityLogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/ActivityLogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the activity log screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/AdoptionController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/AdoptionController.java
index 3ab3c712..bd761459 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/AdoptionController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/AdoptionController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the pet adoption management screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/AnalyticsController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/AnalyticsController.java
index 830ff827..60b031d1 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/AnalyticsController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/AnalyticsController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the analytics and reporting screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/AppointmentController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/AppointmentController.java
index a5a40c39..8d8b55b1 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/AppointmentController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/AppointmentController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the appointment scheduling screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
@@ -132,6 +138,10 @@ public class AppointmentController {
         loadAppointments();
     }
 
+    /**
+     * Fetches appointments from the API (filtered by store and optionally by employee)
+     * and updates both the table and the calendar event dots.
+     */
     private void loadAppointments(){
         new Thread(() -> {
             try{
@@ -165,6 +175,11 @@ public class AppointmentController {
         }).start();
     }
 
+    /**
+     * Sends a server-side search query and replaces the local list with results.
+     * Also refreshes calendar dots to match the filtered set.
+     * @param text the search query text
+     */
     private void applyFilter(String text) {
         String query = text == null || text.trim().isEmpty() ? null : text.trim();
         new Thread(() -> {
@@ -334,6 +349,10 @@ public class AppointmentController {
         return (selected != null && selected.getId() != null) ? selected.getId() : null;
     }
 
+    /**
+     * Applies the client-side filters (calendar date selection and status dropdown)
+     * on top of whatever the server already returned.
+     */
     private void applyFilterPredicate() {
         String selectedStatus = cbStatusFilter.getValue();
         filtered.setPredicate(apt -> {
@@ -372,6 +391,12 @@ public class AppointmentController {
         );
     }
 
+    /**
+     * Normalizes the status string from the API to title case for display.
+     * Handles inconsistencies like "cancelled" vs "canceled".
+     * @param status raw status from the server
+     * @return normalized display string
+     */
     private String normalizeAppointmentStatus(String status) {
         if (status == null) {
             return "Booked";
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/ChatController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/ChatController.java
index 3ba9e995..66ef1f47 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/ChatController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/ChatController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the in-app messaging screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
@@ -105,6 +111,8 @@ public class ChatController {
         lvActiveConversations.setItems(activeConversations);
         lvClosedConversations.setItems(closedConversations);
 
+        // The two lists share a single selection — picking one clears the other.
+        // selectionChanging flag prevents the clear from triggering a feedback loop.
         lvActiveConversations.getSelectionModel().selectedItemProperty().addListener((obs, oldVal, newVal) -> {
             if (newVal != null && !selectionChanging) {
                 selectionChanging = true;
@@ -304,6 +312,11 @@ public class ChatController {
         btnAttachment.setStyle("-fx-background-color: #e2e8f0; -fx-background-radius: 12; -fx-text-fill: #475569; -fx-cursor: hand;");
     }
 
+    /**
+     * Configures a conversation list with custom cells showing title, preview, and status.
+     * Highlights conversations that need pickup or reply in red.
+     * @param lv the ListView to configure
+     */
     private void setupConversationListView(ListView<ConversationResponse> lv) {
         lv.setFixedCellSize(CHAT_CELL_HEIGHT);
         lv.setCellFactory(list -> new ListCell<>() {
@@ -453,6 +466,12 @@ public class ChatController {
         scrollMessagesToBottom();
     }
 
+    /**
+     * Handles an incoming message from the WebSocket.
+     * Only adds it to the view if it belongs to the currently selected conversation
+     * and hasn't already been rendered (dedup by message ID).
+     * @param message the incoming message
+     */
     private void appendMessageIfSelected(MessageResponse message) {
         try {
             upsertConversationForMessage(message);
@@ -474,6 +493,11 @@ public class ChatController {
         }
     }
 
+    /**
+     * Inserts or updates a conversation in the list and re-sorts by last activity.
+     * Called when the WebSocket pushes a conversation update (e.g. status change).
+     * @param conversation the updated conversation from the server
+     */
     private void upsertConversation(ConversationResponse conversation) {
         Optional<ConversationResponse> existing = conversations.stream()
                 .filter(item -> item.getId().equals(conversation.getId()))
@@ -507,6 +531,10 @@ public class ChatController {
                 });
     }
 
+    /**
+     * Re-selects the previously selected conversation after the list is rebuilt.
+     * Needed because refreshSections() replaces all items, which clears the selection.
+     */
     private void restoreSelection() {
         if (selectedConversation == null) {
             return;
@@ -528,6 +556,12 @@ public class ChatController {
                 });
     }
 
+    /**
+     * Builds a single chat bubble with avatar, author label, text, optional
+     * image/attachment preview, and timestamp. Own messages go right, others left.
+     * @param message the message to render
+     * @return the bubble wrapped in an HBox
+     */
     private HBox createMessageBubble(MessageResponse message) {
         boolean mine = message.getSenderId() != null && message.getSenderId().equals(UserSession.getInstance().getUserId());
 
@@ -609,6 +643,13 @@ public class ChatController {
         return container;
     }
 
+    /**
+     * Figures out the display label for a message sender.
+     * Shows "You" for own messages, "AI Bot" for bot messages, and
+     * "Staff" or "Customer" for everyone else.
+     * @param message the message to resolve
+     * @return the author display name
+     */
     private String resolveAuthorLabel(MessageResponse message) {
         if ("BOT".equalsIgnoreCase(message.getSenderRole())) {
             return message.getSenderDisplayName() != null && !message.getSenderDisplayName().isBlank()
@@ -630,6 +671,12 @@ public class ChatController {
         return customerLabel != null ? customerLabel : "Customer #" + conversation.getCustomerId();
     }
 
+    /**
+     * Builds the small status line under each conversation in the sidebar.
+     * Shows assignment state (Automated, Assigned, Takeover requested, etc.) and time.
+     * @param conversation the conversation to summarize
+     * @return a short status string like "Assigned · Apr 10, 14:30"
+     */
     private String buildConversationMeta(ConversationResponse conversation) {
         String updated = conversation.getUpdatedAt() == null ? "" : TIME_FORMATTER.format(conversation.getUpdatedAt());
         if ("CLOSED".equals(conversation.getStatus())) {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/CouponController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/CouponController.java
index af418826..3dd02612 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/CouponController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/CouponController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the coupon management screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/CustomerAccountsController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/CustomerAccountsController.java
index eddf0df9..3f87b773 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/CustomerAccountsController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/CustomerAccountsController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the customer accounts screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/InventoryController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/InventoryController.java
index a724a367..c95dd62d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/InventoryController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/InventoryController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the inventory management screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/LoginController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/LoginController.java
index 6c3427ea..f7988cf3 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/LoginController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/LoginController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the login screen and handles authentication.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/MainLayoutController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/MainLayoutController.java
index 11d8cceb..1ba56945 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/MainLayoutController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/MainLayoutController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the main layout with sidebar navigation.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
@@ -339,6 +345,10 @@ public class MainLayoutController {
         }
     }
 
+    /**
+     * Fetches the current user info from the server on a background thread
+     * and updates the sidebar avatar and display name.
+     */
     private void refreshProfileHeader() {
         new Thread(() -> {
             try {
@@ -376,6 +386,12 @@ public class MainLayoutController {
         }
     }
 
+    /**
+     * Renders the avatar in the sidebar. Shows the uploaded image if available,
+     * otherwise shows a colored circle with the user's initials.
+     * @param displayName used to generate initials as a fallback
+     * @param avatarImage the user's profile image, or null for the initials fallback
+     */
     private void renderAvatar(String displayName, Image avatarImage) {
         Circle border = new Circle(29);
         border.setFill(Color.web("#dbe4ee"));
@@ -427,6 +443,11 @@ public class MainLayoutController {
         alert.showAndWait();
     }
 
+    /**
+     * Shows or hides sidebar buttons based on the user's role.
+     * Admin gets inventory, suppliers, staff accounts, etc.
+     * Also kicks off chat WebSocket subscription in the background.
+     */
     private void applyRBAC() {
         UserSession session = UserSession.getInstance();
 
@@ -498,6 +519,10 @@ public class MainLayoutController {
         }).start();
     }
 
+    /**
+     * Swaps the main content area to a different view.
+     * @param fxmlFile the FXML filename inside the modelviews folder
+     */
     private void loadView(String fxmlFile) {
         try {
             FXMLLoader loader = new FXMLLoader(getClass().getResource("/org/example/petshopdesktop/modelviews/" + fxmlFile));
@@ -551,6 +576,11 @@ public class MainLayoutController {
         }
     }
 
+    /**
+     * Maps EXIF orientation tag values to rotation angles.
+     * @param orientation the EXIF orientation value (1-8)
+     * @return degrees to rotate the image
+     */
     private double exifOrientationToAngle(int orientation) {
         return switch (orientation) {
             case 3 -> 180;
@@ -560,6 +590,13 @@ public class MainLayoutController {
         };
     }
 
+    /**
+     * Manually reads the EXIF orientation tag from raw JPEG bytes.
+     * Walks the JPEG markers to find APP1 (Exif), then parses the TIFF IFD
+     * entries looking for tag 0x0112 (orientation).
+     * @param data raw JPEG image bytes
+     * @return the orientation value (1-8), defaults to 1 if not found
+     */
     private int readExifOrientation(byte[] data) {
         try {
             if (data.length < 2 || (data[0] & 0xFF) != 0xFF || (data[1] & 0xFF) != 0xD8) return 1;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/PetController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/PetController.java
index 35201c45..a0eaf3c5 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/PetController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/PetController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the pet listings screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductController.java
index 6a66c865..b5008eab 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the product catalog screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.animation.KeyFrame;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductSupplierController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductSupplierController.java
index 8060a68f..7a79ea82 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductSupplierController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/ProductSupplierController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the product-supplier linking screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/PurchaseOrderController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/PurchaseOrderController.java
index ca688856..29d40c89 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/PurchaseOrderController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/PurchaseOrderController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the purchase order management screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/SaleController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/SaleController.java
index 7e71dc32..dc5dadd3 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/SaleController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/SaleController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the sales and transactions screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.collections.FXCollections;
@@ -427,6 +433,10 @@ public class SaleController {
         new Thread(task).start();
     }
 
+    /**
+     * Shows or hides the create-sale panel based on role.
+     * Admins get read-only view; staff can create sales and process refunds.
+     */
     private void applyRoleMode() {
         boolean isAdmin = UserSession.getInstance().isAdmin();
         vbCreateSale.setVisible(!isAdmin);
@@ -440,6 +450,12 @@ public class SaleController {
         refreshSales(false);
     }
 
+    /**
+     * Fetches all sales from the API and flattens them into per-item line rows.
+     * Applies any active store filter. Discounts are distributed proportionally
+     * across line items using a ratio of total to subtotal.
+     * @param showErrorDialog whether to show error dialogs on failure
+     */
     private void refreshSales(boolean showErrorDialog) {
         btnRefresh.setDisable(true);
         Task<List<SaleLineItem>> task = new Task<List<SaleLineItem>>() {
@@ -456,6 +472,7 @@ public class SaleController {
                         : "";
 
                     if (sale.getItems() != null && !sale.getItems().isEmpty()) {
+                        // Spread the discount evenly across line items via a ratio
                         double saleSubtotal = sale.getSubtotalAmount() != null ? Math.abs(sale.getSubtotalAmount().doubleValue()) : 0;
                         double saleActualTotal = sale.getTotalAmount() != null ? Math.abs(sale.getTotalAmount().doubleValue()) : 0;
                         double discountRatio = saleSubtotal > 0 ? saleActualTotal / saleSubtotal : 1.0;
@@ -816,6 +833,12 @@ public class SaleController {
         new Thread(task).start();
     }
 
+    /**
+     * Converts a SaleResponse from the API into a SaleDetail for the detail dialog.
+     * Distributes discounts across line items the same way refreshSales does.
+     * @param sale the API response
+     * @return the mapped detail object
+     */
     private SaleDetail mapToSaleDetail(SaleResponse sale) {
         ObservableList<SaleDetail.SaleDetailItem> items = FXCollections.observableArrayList();
         double saleSubtotal = sale.getSubtotalAmount() != null ? Math.abs(sale.getSubtotalAmount().doubleValue()) : 0;
@@ -858,6 +881,10 @@ public class SaleController {
         );
     }
 
+    /**
+     * Recalculates the cart summary: subtotal, coupon discount, loyalty discount, and final total.
+     * Also updates the "points to earn" preview for the selected customer.
+     */
     private void updateCartTotal() {
         BigDecimal subtotal = BigDecimal.valueOf(cartItems.stream().mapToDouble(SaleCartItem::getTotal).sum());
         BigDecimal couponDiscount = calculateCouponDiscount(subtotal);
@@ -900,6 +927,12 @@ public class SaleController {
         }
     }
 
+    /**
+     * Calculates how much the coupon takes off. Percentage coupons use the
+     * subtotal; fixed-amount coupons are capped at the subtotal.
+     * @param subtotal the cart subtotal before discounts
+     * @return the discount amount
+     */
     private BigDecimal calculateCouponDiscount(BigDecimal subtotal) {
         if (appliedCoupon == null) {
             return BigDecimal.ZERO;
@@ -911,6 +944,11 @@ public class SaleController {
         }
     }
 
+    /**
+     * Calculates loyalty point discount. Each point is worth $0.05.
+     * @param subtotalAfterCoupon the amount after coupon discount
+     * @return the loyalty discount amount
+     */
     private BigDecimal calculateLoyaltyDiscount(BigDecimal subtotalAfterCoupon) {
         if (!chkUseLoyaltyPoints.isSelected() || selectedCustomerData == null) {
             return BigDecimal.ZERO;
@@ -919,6 +957,13 @@ public class SaleController {
         return BigDecimal.valueOf(pointsToUse).multiply(BigDecimal.valueOf(0.05));
     }
 
+    /**
+     * Figures out how many loyalty points to redeem. Uses up to the customer's
+     * full balance, but never more than would cover the remaining total.
+     * The multiplier of 20 means 20 points = $1.00 of discount.
+     * @param subtotalAfterCoupon amount left after coupon
+     * @return number of points to use
+     */
     private int calculatePointsToUse(BigDecimal subtotalAfterCoupon) {
         if (selectedCustomerData == null || selectedCustomerData.getLoyaltyPoints() == null) {
             return 0;
@@ -998,6 +1043,10 @@ public class SaleController {
         chkUseLoyaltyPoints.setDisable(disabled);
     }
 
+    /**
+     * Applies the combined text search, payment type, refund status, and customer filters.
+     * @param filter the text search input
+     */
     private void applySalesFilter(String filter) {
         String f = filter == null ? "" : filter.trim().toLowerCase();
         String selectedPayment = cbFilterPayment.getValue();
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/ServiceController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/ServiceController.java
index 10acb9ed..ccc7c309 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/ServiceController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/ServiceController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the services management screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/StaffAccountsController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/StaffAccountsController.java
index 36c7378b..b8abc026 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/StaffAccountsController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/StaffAccountsController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the staff accounts screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/SupplierController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/SupplierController.java
index c6120d15..132cd54f 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/SupplierController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/SupplierController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the supplier management screen.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AdoptionDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AdoptionDialogController.java
index 39947fcc..59ced6ac 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AdoptionDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AdoptionDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for creating or editing an adoption.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AppointmentDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AppointmentDialogController.java
index 1b5530cd..a3934850 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AppointmentDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/AppointmentDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for creating or editing an appointment.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CouponDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CouponDialogController.java
index 21fbc521..d477d543 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CouponDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CouponDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for creating or editing a coupon.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.collections.FXCollections;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CustomerEditDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CustomerEditDialogController.java
index 92c800e3..ddf4ffcf 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CustomerEditDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/CustomerEditDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for editing customer details.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/InventoryDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/InventoryDialogController.java
index 2aa797e4..1ee51acb 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/InventoryDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/InventoryDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for adjusting inventory levels.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PetDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PetDialogController.java
index ea4e853a..9ae1c11d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PetDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PetDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for adding or editing a pet.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductDialogController.java
index 2a51e42a..8027b863 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for adding or editing a product.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.collections.FXCollections;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductSupplierDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductSupplierDialogController.java
index 8e2ef094..b3738276 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductSupplierDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ProductSupplierDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for linking a product to a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PurchaseOrderDetailsDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PurchaseOrderDetailsDialogController.java
index ff597d36..b609ba9a 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PurchaseOrderDetailsDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/PurchaseOrderDetailsDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog that shows purchase order details.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.fxml.FXML;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/RefundDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/RefundDialogController.java
index 11a186db..3de67979 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/RefundDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/RefundDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for processing a refund.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.collections.FXCollections;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SaleDetailDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SaleDetailDialogController.java
index 4774c14d..144ae5e5 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SaleDetailDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SaleDetailDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog that shows sale details.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.fxml.FXML;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ServiceDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ServiceDialogController.java
index 26f13b0f..b69e008a 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ServiceDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/ServiceDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for creating or editing a service.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffEditDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffEditDialogController.java
index 86a8603a..12cd832c 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffEditDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffEditDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for editing staff member details.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffRegisterDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffRegisterDialogController.java
index 04fc74bf..b82bdcf5 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffRegisterDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/StaffRegisterDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for registering a new staff member.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SupplierDialogController.java b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SupplierDialogController.java
index 44131a6c..173f1194 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SupplierDialogController.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/controllers/dialogcontrollers/SupplierDialogController.java
@@ -1,3 +1,9 @@
+/*
+ * Controls the dialog for adding or editing a supplier.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.controllers.dialogcontrollers;
 
 import javafx.event.EventHandler;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Adoption.java b/desktop/src/main/java/org/example/petshopdesktop/models/Adoption.java
index 73f23afc..5575a26d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Adoption.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Adoption.java
@@ -1,3 +1,9 @@
+/*
+ * Represents an adoption record with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleDoubleProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Appointment.java b/desktop/src/main/java/org/example/petshopdesktop/models/Appointment.java
index 7ab54292..c3181a40 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Appointment.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Appointment.java
@@ -1,3 +1,9 @@
+/*
+ * Represents an appointment with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleIntegerProperty;
@@ -43,4 +49,4 @@ public class Appointment {
     public SimpleStringProperty appointmentDateProperty() { return appointmentDate; }
     public SimpleStringProperty appointmentTimeProperty() { return appointmentTime; }
     public SimpleStringProperty appointmentStatusProperty() { return appointmentStatus; }
-}
\ No newline at end of file
+}
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Category.java b/desktop/src/main/java/org/example/petshopdesktop/models/Category.java
index 1f28182b..647ff623 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Category.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Category.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a product category with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleIntegerProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Customer.java b/desktop/src/main/java/org/example/petshopdesktop/models/Customer.java
index 66602694..5103e0d3 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Customer.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Customer.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a customer with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleIntegerProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Inventory.java b/desktop/src/main/java/org/example/petshopdesktop/models/Inventory.java
index 53f77543..85d3943d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Inventory.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Inventory.java
@@ -1,3 +1,9 @@
+/*
+ * Represents an inventory entry with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleIntegerProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Pet.java b/desktop/src/main/java/org/example/petshopdesktop/models/Pet.java
index bc7e1a5c..bf983c36 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Pet.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Pet.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a pet with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleDoubleProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Product.java b/desktop/src/main/java/org/example/petshopdesktop/models/Product.java
index bf0913e5..dd5f96cb 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Product.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Product.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a product with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleDoubleProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/ProductSupplier.java b/desktop/src/main/java/org/example/petshopdesktop/models/ProductSupplier.java
index e674974d..d3603f0d 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/ProductSupplier.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/ProductSupplier.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a product-supplier relationship with JavaFX properties.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleDoubleProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/PurchaseOrder.java b/desktop/src/main/java/org/example/petshopdesktop/models/PurchaseOrder.java
index c13afe50..d2def56f 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/PurchaseOrder.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/PurchaseOrder.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a purchase order with fields for display in tables.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import java.math.BigDecimal;
@@ -49,4 +55,4 @@ public class PurchaseOrder {
     public BigDecimal getTotalAmount() {
         return totalAmount;
     }
-}
\ No newline at end of file
+}
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/SaleCartItem.java b/desktop/src/main/java/org/example/petshopdesktop/models/SaleCartItem.java
index 25c4da36..abd4e764 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/SaleCartItem.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/SaleCartItem.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a single item added to the sale cart.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 public class SaleCartItem {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/SaleDetail.java b/desktop/src/main/java/org/example/petshopdesktop/models/SaleDetail.java
index 63d3cf47..875a04c7 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/SaleDetail.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/SaleDetail.java
@@ -1,3 +1,9 @@
+/*
+ * Holds the full details of a completed sale for display.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.collections.ObservableList;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/SaleLineItem.java b/desktop/src/main/java/org/example/petshopdesktop/models/SaleLineItem.java
index f45938b0..014ced54 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/SaleLineItem.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/SaleLineItem.java
@@ -1,3 +1,9 @@
+/*
+ * Represents one line item within a sale.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 public class SaleLineItem {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Service.java b/desktop/src/main/java/org/example/petshopdesktop/models/Service.java
index b259fc21..5c5c4265 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Service.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Service.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a service offered by the pet shop.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleDoubleProperty;
@@ -95,4 +101,4 @@ public class Service {
     public String toString() {
         return getServiceName();
     }
-}
\ No newline at end of file
+}
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/StaffAccount.java b/desktop/src/main/java/org/example/petshopdesktop/models/StaffAccount.java
index 59923338..fca3aeb2 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/StaffAccount.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/StaffAccount.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a staff account used for login and permissions.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import java.sql.Timestamp;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/Supplier.java b/desktop/src/main/java/org/example/petshopdesktop/models/Supplier.java
index 1120670a..7e0386f4 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/Supplier.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/Supplier.java
@@ -1,3 +1,9 @@
+/*
+ * Represents a supplier with JavaFX properties for table binding.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import javafx.beans.property.SimpleIntegerProperty;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/User.java b/desktop/src/main/java/org/example/petshopdesktop/models/User.java
index 7d2199e9..d006d55f 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/User.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/User.java
@@ -1,3 +1,9 @@
+/*
+ * Represents the currently logged-in user.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models;
 
 import org.example.petshopdesktop.auth.Role;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/DailySalesData.java b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/DailySalesData.java
index 1f41b8f2..d4e2d572 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/DailySalesData.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/DailySalesData.java
@@ -1,3 +1,9 @@
+/*
+ * Holds sales data for a single day used in charts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models.analytics;
 
 import java.time.LocalDate;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/EmployeeSalesData.java b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/EmployeeSalesData.java
index a954d86b..94143f3e 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/EmployeeSalesData.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/EmployeeSalesData.java
@@ -1,3 +1,9 @@
+/*
+ * Holds sales data grouped by employee for charts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models.analytics;
 
 public class EmployeeSalesData {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/PaymentMethodData.java b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/PaymentMethodData.java
index de45c727..b3ba30a8 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/PaymentMethodData.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/PaymentMethodData.java
@@ -1,3 +1,9 @@
+/*
+ * Holds sales data grouped by payment method for charts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models.analytics;
 
 public class PaymentMethodData {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/ProductSalesData.java b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/ProductSalesData.java
index 3723eee6..2a802bca 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/ProductSalesData.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/ProductSalesData.java
@@ -1,3 +1,9 @@
+/*
+ * Holds sales data grouped by product for charts.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models.analytics;
 
 public class ProductSalesData {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/SalesSummary.java b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/SalesSummary.java
index 65e9f9c1..ca06fd18 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/models/analytics/SalesSummary.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/models/analytics/SalesSummary.java
@@ -1,3 +1,9 @@
+/*
+ * Holds overall sales totals for the analytics dashboard.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.models.analytics;
 
 public class SalesSummary {
diff --git a/desktop/src/main/java/org/example/petshopdesktop/ui/CalendarPane.java b/desktop/src/main/java/org/example/petshopdesktop/ui/CalendarPane.java
index 2b2afeab..321c8a03 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/ui/CalendarPane.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/ui/CalendarPane.java
@@ -1,3 +1,9 @@
+/*
+ * Custom calendar widget for picking and highlighting dates.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.ui;
 
 import javafx.geometry.Insets;
@@ -87,6 +93,10 @@ public class CalendarPane extends VBox {
         onDateSelected = handler;
     }
 
+    /**
+     * Moves the calendar forward or backward by one week or month depending on mode.
+     * @param direction +1 for forward, -1 for backward
+     */
     private void navigate(int direction) {
         if (weekMode) {
             currentDate = currentDate.plusWeeks(direction);
@@ -96,6 +106,11 @@ public class CalendarPane extends VBox {
         rebuild();
     }
 
+    /**
+     * Rebuilds the day grid from scratch. In week mode, shows 7 days starting
+     * from Sunday. In month mode, calculates how many rows are needed and offsets
+     * the first day to the correct column based on its day-of-week.
+     */
     private void rebuild() {
         dayGrid.getChildren().clear();
         dayGrid.getColumnConstraints().clear();
@@ -108,6 +123,7 @@ public class CalendarPane extends VBox {
         }
 
         if (weekMode) {
+            // getValue() gives Mon=1..Sun=7; mod 7 maps to Sun=0..Sat=6
             int dow = currentDate.getDayOfWeek().getValue() % 7;
             LocalDate startOfWeek = currentDate.minusDays(dow);
             lblHeader.setText("Week of " + startOfWeek.format(DateTimeFormatter.ofPattern("MMM d, yyyy")));
@@ -117,6 +133,7 @@ public class CalendarPane extends VBox {
         } else {
             YearMonth ym = YearMonth.of(currentDate.getYear(), currentDate.getMonthValue());
             lblHeader.setText(currentDate.format(DateTimeFormatter.ofPattern("MMMM yyyy")));
+            // Figure out which column the 1st falls on, then how many rows we need
             int firstDow = ym.atDay(1).getDayOfWeek().getValue() % 7;
             int daysInMonth = ym.lengthOfMonth();
             int rows = (int) Math.ceil((firstDow + daysInMonth) / 7.0);
@@ -136,6 +153,12 @@ public class CalendarPane extends VBox {
         }
     }
 
+    /**
+     * Creates a single day cell with appropriate styling for selected/today/normal states.
+     * Shows a red dot if the date has events. Clicking toggles selection.
+     * @param date the date this cell represents
+     * @return the styled cell
+     */
     private StackPane buildDayCell(LocalDate date) {
         boolean isSelected = date.equals(selectedDate);
         boolean isToday = date.equals(LocalDate.now());
diff --git a/desktop/src/main/java/org/example/petshopdesktop/ui/SvgWebViewFactory.java b/desktop/src/main/java/org/example/petshopdesktop/ui/SvgWebViewFactory.java
index 6243e901..9463df17 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/ui/SvgWebViewFactory.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/ui/SvgWebViewFactory.java
@@ -1,3 +1,9 @@
+/*
+ * Renders SVG files inside a WebView for display in the UI.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.ui;
 
 import javafx.scene.layout.StackPane;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/util/ActivityLogger.java b/desktop/src/main/java/org/example/petshopdesktop/util/ActivityLogger.java
index 6a104a39..09d34ac2 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/util/ActivityLogger.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/util/ActivityLogger.java
@@ -1,3 +1,9 @@
+/*
+ * Writes user actions to a local log file.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.util;
 
 import java.nio.charset.StandardCharsets;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/util/DesktopImageSupport.java b/desktop/src/main/java/org/example/petshopdesktop/util/DesktopImageSupport.java
index dba81e76..ae4af636 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/util/DesktopImageSupport.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/util/DesktopImageSupport.java
@@ -1,3 +1,9 @@
+/*
+ * Loads and caches images from the server for display.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.util;
 
 import javafx.application.Platform;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/util/DesktopNotificationService.java b/desktop/src/main/java/org/example/petshopdesktop/util/DesktopNotificationService.java
index 4f9da43f..b936e996 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/util/DesktopNotificationService.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/util/DesktopNotificationService.java
@@ -1,3 +1,9 @@
+/*
+ * Sends system tray notifications from the desktop app.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.util;
 
 import javafx.embed.swing.SwingFXUtils;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/util/FilePickerSupport.java b/desktop/src/main/java/org/example/petshopdesktop/util/FilePickerSupport.java
index b81c764a..d3584478 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/util/FilePickerSupport.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/util/FilePickerSupport.java
@@ -1,3 +1,9 @@
+/*
+ * Opens native file chooser dialogs for selecting files.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.util;
 
 import javafx.stage.FileChooser;
diff --git a/desktop/src/main/java/org/example/petshopdesktop/util/TableViewSupport.java b/desktop/src/main/java/org/example/petshopdesktop/util/TableViewSupport.java
index addf56ce..bb32fb3a 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/util/TableViewSupport.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/util/TableViewSupport.java
@@ -1,3 +1,9 @@
+/*
+ * Helper methods for setting up and formatting table views.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.util;
 
 import javafx.collections.transformation.FilteredList;
@@ -20,6 +26,12 @@ public final class TableViewSupport {
     private TableViewSupport() {
     }
 
+    /**
+     * Wraps a FilteredList in a SortedList and binds it to the table's sort order.
+     * This way clicking column headers sorts the already-filtered data.
+     * @param tableView the table to bind to
+     * @param filteredItems the filtered data source
+     */
     public static <T> void bindSortedItems(TableView<T> tableView, FilteredList<T> filteredItems) {
         SortedList<T> sortedItems = new SortedList<>(filteredItems);
         sortedItems.comparatorProperty().bind(tableView.comparatorProperty());
@@ -43,6 +55,10 @@ public final class TableViewSupport {
         delay.playFromStart();
     }
 
+    /**
+     * Formats a numeric column as Canadian currency (e.g. $12.50).
+     * @param column the table column to apply formatting to
+     */
     public static <S, T extends Number> void applyCurrencyColumn(TableColumn<S, T> column) {
         if (column == null) {
             return;
@@ -58,6 +74,11 @@ public final class TableViewSupport {
         });
     }
 
+    /**
+     * Adds a double-click handler to table rows that calls the given action with the row item.
+     * @param tableView the table to add the handler to
+     * @param action callback that receives the clicked row's item
+     */
     public static <T> void installDoubleClickAction(TableView<T> tableView, Consumer<T> action) {
         tableView.setRowFactory(tv -> {
             TableRow<T> row = new TableRow<>();
diff --git a/desktop/src/main/java/org/example/petshopdesktop/util/TextFieldFormatSupport.java b/desktop/src/main/java/org/example/petshopdesktop/util/TextFieldFormatSupport.java
index 7dba0d9f..0e86a0e9 100644
--- a/desktop/src/main/java/org/example/petshopdesktop/util/TextFieldFormatSupport.java
+++ b/desktop/src/main/java/org/example/petshopdesktop/util/TextFieldFormatSupport.java
@@ -1,3 +1,9 @@
+/*
+ * Applies input formatting like phone numbers to text fields.
+ *
+ * Author: Harkamal
+ * Date: April 2026
+ */
 package org.example.petshopdesktop.util;
 
 import javafx.application.Platform;