diff --git a/pom.xml b/pom.xml
index a394acb..effe110 100644
--- a/pom.xml
+++ b/pom.xml
@@ -189,6 +189,14 @@
 <!--                    <compilerArgs>&#45;&#45;enable-preview</compilerArgs>-->
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.6.3</version>
+                <configuration>
+                    <failOnError>false</failOnError>
+                </configuration>
+            </plugin>
 
             <plugin>
                 <groupId>org.springframework.boot</groupId>
diff --git a/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolutionResult.java b/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolutionResult.java
index 1246511..63c5bc2 100644
--- a/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolutionResult.java
+++ b/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolutionResult.java
@@ -2,7 +2,7 @@ package group.goforward.battlbuilder.catalog.classification;
 
 /**
  * Result returned by PlatformResolver.
- *
+ * <p>
  * Any of the fields may be null — the importer will only overwrite
  * product.platform, product.partRole, or product.configuration
  * when the returned value is non-null AND non-blank.
diff --git a/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolver.java b/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolver.java
index dddd39b..4d5c39f 100644
--- a/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolver.java
+++ b/src/main/java/group/goforward/battlbuilder/catalog/classification/PlatformResolver.java
@@ -15,7 +15,7 @@ import java.util.regex.Pattern;
 /**
  * Resolves a product's PLATFORM (e.g. AR-15, AR-10, NOT-SUPPORTED)
  * using explicit DB-backed rules.
- *
+ * <p>
  * Conservative approach:
  * - If a rule matches, return its target_platform
  * - If nothing matches, return null and let the caller decide fallback behavior
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/BuilderBootstrapController.java b/src/main/java/group/goforward/battlbuilder/controllers/BuilderBootstrapController.java
index 9203574..f60b42d 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/BuilderBootstrapController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/BuilderBootstrapController.java
@@ -26,7 +26,7 @@ public class BuilderBootstrapController {
 
     /**
      * Builder bootstrap payload.
-     *
+     * <p>
      * Returns:
      * - categories: ordered list for UI navigation
      * - partRoleMap: normalized partRole -> categorySlug (platform-scoped)
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/ImportController.java b/src/main/java/group/goforward/battlbuilder/controllers/ImportController.java
index 8dc878e..ae70ecd 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/ImportController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/ImportController.java
@@ -18,7 +18,7 @@ public class ImportController {
 
     /**
      * Full product + offer import for a merchant.
-     *
+     * <p>
      * POST /admin/imports/{merchantId}
      */
     @PostMapping("/{merchantId}")
@@ -29,7 +29,7 @@ public class ImportController {
 
     /**
      * Offers-only sync (price/stock) for a merchant.
-     *
+     * <p>
      * POST /admin/imports/{merchantId}/offers-only
      */
     @PostMapping("/{merchantId}/offers-only")
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/ProductController.java b/src/main/java/group/goforward/battlbuilder/controllers/ProductController.java
index de83357..ecbd36f 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/ProductController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/ProductController.java
@@ -10,14 +10,14 @@ import java.util.List;
 
 /**
  * LEGACY CONTROLLER (Deprecated)
- *
+ * <p>
  * Do not add new features here.
  * Canonical API lives in ProductV1Controller (/api/v1/products).
- *
+ * <p>
  * This exists only to keep older clients working temporarily.
  * Disable by default using:
  *   app.api.legacy.enabled=false
- *
+ * <p>
  * NOTE:
  * Even when disabled, Spring still compiles this class. So it must not reference
  * missing services/methods.
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminBetaInviteController.java b/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminBetaInviteController.java
index 5eb4a79..6584f87 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminBetaInviteController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminBetaInviteController.java
@@ -16,7 +16,14 @@ public class AdminBetaInviteController {
         this.betaInviteService = betaInviteService;
     }
 
-    // POST /api/v1/admin/beta/invites/send?limit=25&dryRun=true&tokenMinutes=30
+    /**
+     * //api/v1/admin/beta/invites/send?limit=25&dryRun=true&tokenMinutes=30
+     * @param limit
+     * @param dryRun
+     * @param tokenMinutes
+     * @return
+     */
+
     @PostMapping("/invites/send")
     public InviteBatchResponse sendInvites(
             @RequestParam(defaultValue = "0") int limit,
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminDashboardController.java b/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminDashboardController.java
index 384add2..ee4cbc7 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminDashboardController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminDashboardController.java
@@ -1,7 +1,7 @@
 package group.goforward.battlbuilder.controllers.admin;
 
 import group.goforward.battlbuilder.services.admin.impl.AdminDashboardService;
-import group.goforward.battlbuilder.web.dto.AdminDashboardOverviewDto;
+import group.goforward.battlbuilder.web.dto.admin.AdminDashboardOverviewDto;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminPlatformController.java b/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminPlatformController.java
index 307ef24..ad441b4 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminPlatformController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/admin/AdminPlatformController.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.controllers;
+package group.goforward.battlbuilder.controllers.admin;
 
 import group.goforward.battlbuilder.model.Platform;
 import group.goforward.battlbuilder.repos.PlatformRepository;
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/admin/MerchantAdminController.java b/src/main/java/group/goforward/battlbuilder/controllers/admin/MerchantAdminController.java
index fc9ed5d..b86fa06 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/admin/MerchantAdminController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/admin/MerchantAdminController.java
@@ -1,5 +1,5 @@
 // MerchantAdminController.java
-package group.goforward.battlbuilder.controllers;
+package group.goforward.battlbuilder.controllers.admin;
 
 import org.springframework.web.bind.annotation.CrossOrigin;
 import org.springframework.web.bind.annotation.GetMapping;
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/admin/PlatformViewController.java b/src/main/java/group/goforward/battlbuilder/controllers/admin/PlatformViewController.java
index 1ec28ef..6951c1c 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/admin/PlatformViewController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/admin/PlatformViewController.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.controllers;
+package group.goforward.battlbuilder.controllers.admin;
 
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/api/BrandController.java b/src/main/java/group/goforward/battlbuilder/controllers/api/BrandController.java
index f5ec691..8da32a3 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/api/BrandController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/api/BrandController.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.controllers;
+package group.goforward.battlbuilder.controllers.api;
 
 import group.goforward.battlbuilder.model.Brand;
 import group.goforward.battlbuilder.repos.BrandRepository;
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/api/StateController.java b/src/main/java/group/goforward/battlbuilder/controllers/api/StateController.java
index 3d8a6ef..5dd7c14 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/api/StateController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/api/StateController.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.controllers;
+package group.goforward.battlbuilder.controllers.api;
 
 import group.goforward.battlbuilder.model.State;
 import group.goforward.battlbuilder.repos.StateRepository;
diff --git a/src/main/java/group/goforward/battlbuilder/controllers/api/UserController.java b/src/main/java/group/goforward/battlbuilder/controllers/api/UserController.java
index 6088209..646dab4 100644
--- a/src/main/java/group/goforward/battlbuilder/controllers/api/UserController.java
+++ b/src/main/java/group/goforward/battlbuilder/controllers/api/UserController.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.controllers;
+package group.goforward.battlbuilder.controllers.api;
 
 import group.goforward.battlbuilder.model.User;
 import group.goforward.battlbuilder.repos.UserRepository;
diff --git a/src/main/java/group/goforward/battlbuilder/dto/package_info.java b/src/main/java/group/goforward/battlbuilder/dto/package_info.java
index ee9a48c..3dfe2b1 100644
--- a/src/main/java/group/goforward/battlbuilder/dto/package_info.java
+++ b/src/main/java/group/goforward/battlbuilder/dto/package_info.java
@@ -1,11 +1,11 @@
 
-/**
- * Web admin DTOs package for the BattlBuilder application.
- * <p>
- * Contains Data Transfer Objects specific to administrative
- * operations including user management, mappings, and platform configuration.
- * 
- * @author Forward Group, LLC
+/*
+  Web admin DTOs package for the BattlBuilder application.
+  <p>
+  Contains Data Transfer Objects specific to administrative
+  operations including user management, mappings, and platform configuration.
+
+  @author Forward Group, LLC
  * @version 1.0
  * @since 2025-12-10
  */
diff --git a/src/main/java/group/goforward/battlbuilder/model/BuildProfile.java b/src/main/java/group/goforward/battlbuilder/model/BuildProfile.java
index cfac638..2df0a74 100644
--- a/src/main/java/group/goforward/battlbuilder/model/BuildProfile.java
+++ b/src/main/java/group/goforward/battlbuilder/model/BuildProfile.java
@@ -8,7 +8,7 @@ import java.time.OffsetDateTime;
 /**
  * build_profiles
  * 1:1 with builds (build_id is both PK and FK)
- *
+ * <p>
  * Dev notes:
  * - This is the "feed/meta" table for Option B (caliber, class, cover image, tags, etc.)
  * - Keep it lightweight. Anything social (votes/comments/media) lives elsewhere.
diff --git a/src/main/java/group/goforward/battlbuilder/repos/ProductRepository.java b/src/main/java/group/goforward/battlbuilder/repos/ProductRepository.java
index 9c93a27..5da6193 100644
--- a/src/main/java/group/goforward/battlbuilder/repos/ProductRepository.java
+++ b/src/main/java/group/goforward/battlbuilder/repos/ProductRepository.java
@@ -32,7 +32,7 @@ public interface ProductRepository
      * Catalog mapping UI:
      * Returns raw categories for a given merchant + optional platform/q filter,
      * along with current merchant_category_map state and canonical category name.
-     *
+     * <p>
      * Row shape MUST match MappingAdminService mapping:
      *  r[0] merchantId (Integer)
      *  r[1] merchantName (String)
diff --git a/src/main/java/group/goforward/battlbuilder/repos/catalog/spec/CatalogProductSpecifications.java b/src/main/java/group/goforward/battlbuilder/repos/catalog/spec/CatalogProductSpecifications.java
index 8f92cf0..63c4f8f 100644
--- a/src/main/java/group/goforward/battlbuilder/repos/catalog/spec/CatalogProductSpecifications.java
+++ b/src/main/java/group/goforward/battlbuilder/repos/catalog/spec/CatalogProductSpecifications.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.repos.spec;
+package group.goforward.battlbuilder.repos.catalog.spec;
 
 import group.goforward.battlbuilder.model.Product;
 import group.goforward.battlbuilder.model.ProductStatus;
diff --git a/src/main/java/group/goforward/battlbuilder/services/CurrentUserService.java b/src/main/java/group/goforward/battlbuilder/services/CurrentUserService.java
index 0e0c926..d22d54b 100644
--- a/src/main/java/group/goforward/battlbuilder/services/CurrentUserService.java
+++ b/src/main/java/group/goforward/battlbuilder/services/CurrentUserService.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.security;
+package group.goforward.battlbuilder.services;
 
 import group.goforward.battlbuilder.model.User;
 import group.goforward.battlbuilder.repos.UserRepository;
diff --git a/src/main/java/group/goforward/battlbuilder/services/admin/impl/AdminDashboardService.java b/src/main/java/group/goforward/battlbuilder/services/admin/impl/AdminDashboardService.java
index d6f7f37..7cf2632 100644
--- a/src/main/java/group/goforward/battlbuilder/services/admin/impl/AdminDashboardService.java
+++ b/src/main/java/group/goforward/battlbuilder/services/admin/impl/AdminDashboardService.java
@@ -4,7 +4,7 @@ import group.goforward.battlbuilder.model.ImportStatus;
 import group.goforward.battlbuilder.repos.MerchantCategoryMapRepository;
 import group.goforward.battlbuilder.repos.MerchantRepository;
 import group.goforward.battlbuilder.repos.ProductRepository;
-import group.goforward.battlbuilder.web.dto.AdminDashboardOverviewDto;
+import group.goforward.battlbuilder.web.dto.admin.AdminDashboardOverviewDto;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
diff --git a/src/main/java/group/goforward/battlbuilder/services/impl/BuildServiceImpl.java b/src/main/java/group/goforward/battlbuilder/services/impl/BuildServiceImpl.java
index 7c666fb..07e80ed 100644
--- a/src/main/java/group/goforward/battlbuilder/services/impl/BuildServiceImpl.java
+++ b/src/main/java/group/goforward/battlbuilder/services/impl/BuildServiceImpl.java
@@ -8,7 +8,7 @@ import group.goforward.battlbuilder.repos.BuildItemRepository;
 import group.goforward.battlbuilder.repos.BuildProfileRepository;
 import group.goforward.battlbuilder.repos.BuildRepository;
 import group.goforward.battlbuilder.repos.ProductOfferRepository;
-import group.goforward.battlbuilder.security.CurrentUserService;
+import group.goforward.battlbuilder.services.CurrentUserService;
 import group.goforward.battlbuilder.services.BuildService;
 import group.goforward.battlbuilder.web.dto.BuildDto;
 import group.goforward.battlbuilder.web.dto.BuildFeedCardDto;
diff --git a/src/main/java/group/goforward/battlbuilder/services/impl/CatalogQueryServiceImpl.java b/src/main/java/group/goforward/battlbuilder/services/impl/CatalogQueryServiceImpl.java
index cd945ba..6b24e4d 100644
--- a/src/main/java/group/goforward/battlbuilder/services/impl/CatalogQueryServiceImpl.java
+++ b/src/main/java/group/goforward/battlbuilder/services/impl/CatalogQueryServiceImpl.java
@@ -4,7 +4,7 @@ import group.goforward.battlbuilder.model.Product;
 import group.goforward.battlbuilder.model.ProductOffer;
 import group.goforward.battlbuilder.repos.ProductOfferRepository;
 import group.goforward.battlbuilder.repos.ProductRepository;
-import group.goforward.battlbuilder.repos.spec.CatalogProductSpecifications;
+import group.goforward.battlbuilder.repos.catalog.spec.CatalogProductSpecifications;
 import group.goforward.battlbuilder.services.CatalogQueryService;
 import group.goforward.battlbuilder.web.dto.ProductSummaryDto;
 import group.goforward.battlbuilder.web.dto.catalog.CatalogProductIdsRequest;
diff --git a/src/main/java/group/goforward/battlbuilder/services/impl/MerchantFeedImportServiceImpl.java b/src/main/java/group/goforward/battlbuilder/services/impl/MerchantFeedImportServiceImpl.java
index 1e4d25e..8cfa159 100644
--- a/src/main/java/group/goforward/battlbuilder/services/impl/MerchantFeedImportServiceImpl.java
+++ b/src/main/java/group/goforward/battlbuilder/services/impl/MerchantFeedImportServiceImpl.java
@@ -40,14 +40,14 @@ import java.time.Instant;
 
 /**
  * MerchantFeedImportServiceImpl
- *
+ * <p>
  * RESPONSIBILITIES:
  * - Read merchant product feeds (CSV/TSV/etc)
  * - Normalize product data into Product entities
  * - Resolve PLATFORM (AR-15, AR-10, NOT-SUPPORTED)
  * - Infer part roles (temporary heuristic)
  * - Upsert Product + ProductOffer rows
- *
+ * <p>
  * NON-GOALS:
  * - Perfect classification (that’s iterative)
  * - UI-level filtering (handled later)
diff --git a/src/main/java/group/goforward/battlbuilder/services/utils/Snippet.java b/src/main/java/group/goforward/battlbuilder/services/utils/Snippet.java
new file mode 100644
index 0000000..88305b6
--- /dev/null
+++ b/src/main/java/group/goforward/battlbuilder/services/utils/Snippet.java
@@ -0,0 +1,11 @@
+/**
+ * Services package for the BattlBuilder application.
+ * <p>
+ * Contains business logic service classes for product management,
+ * category classification, mapping recommendations, and merchant operations.
+ * 
+ * @author Forward Group, LLC
+ * @version 1.0
+ * @since 2025-12-10
+ */
+package group.goforward.battlbuilder.services.utils;
diff --git a/src/main/java/group/goforward/battlbuilder/utils/ApiResponse.java b/src/main/java/group/goforward/battlbuilder/utils/ApiResponse.java
index a97bcb6..22fd2b7 100644
--- a/src/main/java/group/goforward/battlbuilder/utils/ApiResponse.java
+++ b/src/main/java/group/goforward/battlbuilder/utils/ApiResponse.java
@@ -3,7 +3,9 @@ package group.goforward.battlbuilder.utils;
 import java.time.LocalDateTime;
 
 /**
- * @param <T>
+ * Standard API response wrapper.
+ *
+ * @param <T> the type of the data payload
  */
 public class ApiResponse<T> {
 
diff --git a/src/main/java/group/goforward/battlbuilder/web/dto/BuildFeedCardDto.java b/src/main/java/group/goforward/battlbuilder/web/dto/BuildFeedCardDto.java
index c2828af..9c13be3 100644
--- a/src/main/java/group/goforward/battlbuilder/web/dto/BuildFeedCardDto.java
+++ b/src/main/java/group/goforward/battlbuilder/web/dto/BuildFeedCardDto.java
@@ -6,7 +6,7 @@ import java.util.UUID;
 /**
  * Contract for /builds feed cards.
  * Matches the Next.js BuildsPage expectations.
- *
+ * <p>
  * Dev Notes:
  * - We are using Option 2 for money: price is INTEGER CENTS (not dollars).
  *   Example: $19.99 -> 1999
@@ -38,7 +38,7 @@ public class BuildFeedCardDto {
     /**
      * Estimated build price in CENTS (Option 2).
      * Example: 245000 == $2,450.00
-     *
+     * <p>
      * IMPORTANT:
      * - UI must divide by 100 for display.
      * - Keep nullable optional; treat null as 0 in the UI.
diff --git a/src/main/java/group/goforward/battlbuilder/web/dto/UpdateBuildRequest.java b/src/main/java/group/goforward/battlbuilder/web/dto/UpdateBuildRequest.java
index bfc1cf1..98435a3 100644
--- a/src/main/java/group/goforward/battlbuilder/web/dto/UpdateBuildRequest.java
+++ b/src/main/java/group/goforward/battlbuilder/web/dto/UpdateBuildRequest.java
@@ -5,7 +5,7 @@ import java.util.List;
 /**
  * Request DTO for creating/updating Build + items.
  * Keeps entity fields protected from client-side overposting.
- *
+ * <p>
  * NOTE:
  * - We reuse this for BOTH create (POST /me) and update (PUT /me/{uuid}) for MVP speed.
  */
diff --git a/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminDashboardOverviewDto.java b/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminDashboardOverviewDto.java
index 130cdd1..67e87c4 100644
--- a/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminDashboardOverviewDto.java
+++ b/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminDashboardOverviewDto.java
@@ -1,4 +1,4 @@
-package group.goforward.battlbuilder.web.dto;
+package group.goforward.battlbuilder.web.dto.admin;
 
 public class AdminDashboardOverviewDto {
 
diff --git a/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminProductSearchRequest.java b/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminProductSearchRequest.java
index fde9bfe..d2faf99 100644
--- a/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminProductSearchRequest.java
+++ b/src/main/java/group/goforward/battlbuilder/web/dto/admin/AdminProductSearchRequest.java
@@ -5,8 +5,10 @@ import group.goforward.battlbuilder.model.ProductStatus;
 import group.goforward.battlbuilder.model.ProductVisibility;
 
 /**
- * Bound from query params on:
- * GET /api/v1/admin/products?platform=AR-15&q=mini&visibility=PUBLIC...
+ * Request DTO for searching products in the admin panel.
+ * <p>
+ * Example:
+ * GET /api/v1/admin/products?platform=AR-15&amp;q=mini&amp;visibility=PUBLIC
  */
 public class AdminProductSearchRequest {
 
diff --git a/src/main/java/group/goforward/battlbuilder/web/dto/auth/package_info.java b/src/main/java/group/goforward/battlbuilder/web/dto/auth/package_info.java
index 1d802b6..53f6d38 100644
--- a/src/main/java/group/goforward/battlbuilder/web/dto/auth/package_info.java
+++ b/src/main/java/group/goforward/battlbuilder/web/dto/auth/package_info.java
@@ -1,11 +1,11 @@
 
-/**
- * Web authentication DTOs package for the BattlBuilder application.
- * <p>
- * Contains Data Transfer Objects for authentication operations
- * including login requests, registration, and authentication responses.
- * 
- * @author Forward Group, LLC
+/*
+  Web authentication DTOs package for the BattlBuilder application.
+  <p>
+  Contains Data Transfer Objects for authentication operations
+  including login requests, registration, and authentication responses.
+
+  @author Forward Group, LLC
  * @version 1.0
  * @since 2025-12-10
  */