cleanup

src/main/java/group/goforward/battlbuilder/controller/BuilderBootstrapController.java

@@ -8,6 +8,10 @@ import org.springframework.web.bind.annotation.*;
 
 import java.util.*;
 
+/**
+ * REST controller responsible for providing bootstrap data for the builder platform.
+ * This controller aggregates and normalizes data required to initialize builder-related UI components.
+ */
 @RestController
 @RequestMapping({"/api/builder", "/api/v1/builder"})
 @CrossOrigin

src/main/java/group/goforward/battlbuilder/controller/CategoryController.java

@@ -6,6 +6,27 @@ import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+/**
+ * REST controller for managing part categories.
+ *
+ * This controller provides endpoints for retrieving and interacting with
+ * part category data through its associated repository. Part categories are
+ * sorted based on their group name, sort order, and name in ascending order.
+ *
+ * Annotations:
+ * - {@code @RestController}: Indicates that this class is a REST controller.
+ * - {@code @RequestMapping}: Maps HTTP requests to specific endpoints. Supported
+ *   paths are "/api/categories" and "/api/v1/categories".
+ * - {@code @CrossOrigin}: Enables cross-origin requests.
+ *
+ * Constructor:
+ * - {@code CategoryController(PartCategoryRepository partCategories)}: Initializes
+ *   the controller with the specified repository for accessing part category data.
+ *
+ * Methods:
+ * - {@code List<PartCategoryDto> list()}: Retrieves a list of part categories from
+ *   the repository, sorts them, and maps them to DTO objects for output.
+ */
 @RestController
 @RequestMapping({"/api/categories", "/api/v1/categories"})
 @CrossOrigin // you can tighten origins later

src/main/java/group/goforward/battlbuilder/controller/EmailTrackingController.java

@@ -7,6 +7,18 @@ import org.springframework.web.bind.annotation.*;
 import java.net.URI;
 import java.time.LocalDateTime;
 
+/**
+ * The EmailTrackingController handles tracking of email-related events such as
+ * email opens and link clicks. This controller provides endpoints to record
+ * these events and return appropriate responses.
+ *
+ * The tracking of email opens is achieved through a transparent 1x1 GIF image,
+ * and link clicks are redirected to the intended URL while capturing relevant metadata.
+ *
+ * Request mappings:
+ * 1. "/api/email/open/{id}" - Tracks email open events.
+ * 2. "/api/email/click/{id}" - Tracks email link click events.
+ */
 @RestController
 @RequestMapping("/api/email")
 public class EmailTrackingController {

src/main/java/group/goforward/battlbuilder/controller/ImportController.java

@@ -4,6 +4,15 @@ import group.goforward.battlbuilder.service.MerchantFeedImportService;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
+/**
+ * REST controller responsible for handling import operations for merchants.
+ * Supports full product and offer imports as well as offers-only synchronization.
+ *
+ * Mapped to the following base endpoints:
+ * /api/admin/imports and /api/v1/admin/imports
+ *
+ * Cross-origin requests are permitted from http://localhost:3000.
+ */
 @RestController
 @RequestMapping({"/api/admin/imports", "/api/v1/admin/imports"})
 

src/main/java/group/goforward/battlbuilder/controller/MerchantDebugController.java

@@ -8,6 +8,12 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+/**
+ * REST controller for debugging merchant-related functionalities in the admin API.
+ * Provides endpoints for retrieving merchant data for administrative purposes.
+ *
+ * Mapped to both "/api/admin" and "/api/v1/admin" base paths.
+ */
 @RestController
 @RequestMapping({"/api/admin", "/api/v1/admin"})
 public class MerchantDebugController {

src/main/java/group/goforward/battlbuilder/controller/api/v1/BrandController.java

@@ -11,6 +11,27 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 
 
+/**
+ * REST controller for managing brand entities.
+ * Provides endpoints for performing CRUD operations on brands.
+ *
+ * The controller exposes REST APIs to:
+ * - Retrieve a list of all brands.
+ * - Fetch a single brand by its ID.
+ * - Create a new brand.
+ * - Delete a brand by its ID.
+ *
+ * This controller interacts with the persistence layer through `BrandRepository` and with the
+ * business logic through `BrandService`.
+ *
+ * Mapped base endpoints:
+ * - `/api/v1/brands`
+ * - `/api/brands`
+ *
+ * Dependencies:
+ * - `BrandRepository` for direct database access.
+ * - `BrandService` for handling the business logic of brands.
+ */
 @RestController
 @RequestMapping({"/api/v1/brands", "/api/brands"})
 public class BrandController {

src/main/java/group/goforward/battlbuilder/web/mapper/package-info.java

@@ -0,0 +1 @@
+package group.goforward.battlbuilder.web.mapper;