Merge pull request #45 from Jalen-Stephens/35-chore---write-javadoc-comments-for-all-non-trivial-code

35 chore   write javadoc comments for all non trivial code

Author: ikeschmack

citations.md

@@ -7,7 +7,9 @@
 
 /**
  * Entry point for the MetaDetect AI Image Detection Service.
- * This class starts the Spring Boot application.
+ * Bootstraps the Spring Boot application and exposes shared infrastructure
+ * beans (such as {@link Clock}) used across the service for deterministic and
+ * testable timestamps.
  */
 @SpringBootApplication
 public class MetaDetectApplication {
@@ -16,6 +18,10 @@ public static void main(String[] args) {
     SpringApplication.run(MetaDetectApplication.class, args);
   }
 
+  /**
+   * System UTC clock used for consistent timestamp generation across
+   * services (injection-friendly for tests).
+   */
   @Bean
   public Clock clock() {
     return Clock.systemUTC();

src/main/java/dev/coms4156/project/metadetect/MetaDetectApplication.java

@@ -5,7 +5,6 @@
 import org.springframework.context.annotation.Configuration;
 
 /** Configuation class to provide constants to other processes. */
-
 @Configuration
 public class AppConfig {
 
@@ -16,7 +15,6 @@ public class AppConfig {
   *
   * @return a C2paToolInvoker instance configured with the tool path.
   */
-
   @Bean
   public C2paToolInvoker c2paToolInvoker() {
     // Path to the C2PA tool binary

src/main/java/dev/coms4156/project/metadetect/config/AppConfig.java

@@ -12,69 +12,115 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-
 /**
- * REST controller for image analysis operations.
- * Endpoints:
- *  - POST   /api/analyze/{imageId}               -> start an analysis (202 Accepted)
- *  - GET    /api/analyze/{analysisId}            -> status/score (polling)
- *  - GET    /api/analyze/{analysisId}/manifest   -> manifest JSON
- *  - GET    /api/analyze/compare                 -> stubbed compare (left & right image IDs)
- * Notes:
- *  - Ownership and RLS checks are enforced in AnalyzeService/ImageService.
- *  - Exceptions (Forbidden/NotFound/etc.)
- *    are expected to be mapped by global @RestControllerAdvice.
+ * HTTP API for starting and querying image analyses.
+ * Responsibilities
+ * - Accepts requests to start analysis on an already-uploaded image.
+ * - Exposes polling endpoints to retrieve analysis status, confidence scores, and stored manifests.
+ * - Delegates ownership/RLS checks and business logic to {@link AnalyzeService}.
+ * Contract
+ * - POST /api/analyze/{imageId} returns 202 Accepted with an analysis identifier.
+ * - GET  /api/analyze/{analysisId} returns current status and (optionally) a confidence score.
+ * - GET  /api/analyze/{analysisId}/manifest returns a captured C2PA manifest (if available).
+ * - GET  /api/analyze/compare?left=...&right=...
+ *     returns a lightweight comparison (Iteration 1 stub).
+ * Error Handling
+ * - Authorization, ownership, and not-found conditions are surfaced as exceptions from the service
+ *   layer and mapped by a global {@code @RestControllerAdvice}.
+ * Thread-safety
+ * - Controller is stateless; relies on Spring-managed, thread-safe collaborators.
  */
 @RestController
 @RequestMapping("/api/analyze")
 public class AnalyzeController {
 
   private final AnalyzeService analyzeService;
 
+  /**
+   * Constructs the controller with required collaborators.
+   *
+   * @param analyzeService domain service coordinating analysis lifecycle and access checks
+   */
   public AnalyzeController(AnalyzeService analyzeService) {
     this.analyzeService = analyzeService;
   }
 
   /**
-   * Starts analysis for an existing image that is already uploaded to Supabase Storage.
-   * Returns 202 with a body containing the new analysisId.
+   * Starts analysis for an existing image that is already persisted
+   *     and stored (e.g., in Supabase Storage).
+   * The service enqueues or triggers downstream processing and
+   *     returns an identifier used for polling.
+   * Response semantics
+   * - Returns HTTP 202 Accepted to indicate asynchronous processing has begun.
+   *
+   * @param imageId unique identifier of the previously uploaded image
+   * @return 202 Accepted with a body containing
+   *        {@link Dtos.AnalyzeStartResponse} and a new analysisId
+   * @throws org.springframework.web.server.ResponseStatusException if the image does not exist or
+   *         the caller is not authorized to analyze it (propagated from the service layer)
    */
   @PostMapping("/{imageId}")
   public ResponseEntity<Dtos.AnalyzeStartResponse> submit(@PathVariable UUID imageId) {
+    // Delegate to service: performs ownership checks, persists analysis row, and schedules work.
     Dtos.AnalyzeStartResponse resp = analyzeService.submitAnalysis(imageId);
-    // As per ticket: 202 Accepted with { analysisId }
+
+    // Per API contract, asynchronous start returns 202 Accepted rather than 200 OK.
     return ResponseEntity.status(HttpStatus.ACCEPTED).body(resp);
   }
 
   /**
-   * Returns current status (PENDING/COMPLETED/FAILED) and an optional score (stubbed).
-   * Suitable for client-side polling.
+   * Retrieves the current analysis status and (optionally) a confidence score suitable for polling.
+   * Typical states include PENDING, COMPLETED, and FAILED.
+   *
+   * @param analysisId unique identifier returned by {@link #submit(UUID)}
+   * @return 200 OK with {@link Dtos.AnalyzeConfidenceResponse}
+   * @throws org.springframework.web.server.ResponseStatusException
+   *         if the analysis does not exist or the
+   *         caller lacks access (propagated from the service layer)
    */
   @GetMapping("/{analysisId}")
   public ResponseEntity<Dtos.AnalyzeConfidenceResponse> getStatus(@PathVariable UUID analysisId) {
+    // Service encapsulates lookup and authorization; controller simply returns the DTO.
     Dtos.AnalyzeConfidenceResponse resp = analyzeService.getConfidence(analysisId);
     return ResponseEntity.ok(resp);
   }
 
   /**
-   * Returns the stored C2PA manifest JSON for a completed analysis.
+   * Returns the stored C2PA manifest for a completed analysis, when available.
+   * Clients should check analysis status before calling this endpoint
+   * to avoid unnecessary requests.
+   *
+   * @param analysisId unique identifier of the analysis
+   * @return 200 OK with {@link Dtos.AnalysisManifestResponse};
+   *     may be 404/403 via advice if not accessible
    */
   @GetMapping("/{analysisId}/manifest")
   public ResponseEntity<Dtos.AnalysisManifestResponse> getManifest(@PathVariable UUID analysisId) {
+    // The service is responsible for ensuring the analysis is complete and manifest exists or
+    // raising a mapped exception if it does not.
     Dtos.AnalysisManifestResponse resp = analyzeService.getMetadata(analysisId);
     return ResponseEntity.ok(resp);
   }
 
   /**
-   * Stubbed comparison endpoint (Iteration 1).
-   * Ownership of both images is validated by the service layer.
-   * Example: /api/analyze/compare?left={imageId}&right={imageId}
+   * Lightweight comparison endpoint (Iteration 1 stub) that
+   *  compares two images owned by the caller.
+   * The service validates ownership of both resources and returns a basic comparison DTO.
+   * Example
+   *   GET /api/analyze/compare?left={imageId}&right={imageId}
+   *
+   * @param leftImageId identifier of the left image to compare
+   * @param rightImageId identifier of the right image to compare
+   * @return 200 OK with {@link Dtos.AnalyzeCompareResponse}
+   * @throws org.springframework.web.server.ResponseStatusException
+   *     if either image is missing or unauthorized
    */
   @GetMapping("/compare")
   public ResponseEntity<Dtos.AnalyzeCompareResponse> compare(
       @RequestParam("left") UUID leftImageId,
       @RequestParam("right") UUID rightImageId) {
 
+    // Delegate comparison to the domain service; controller remains a thin transport layer.
     Dtos.AnalyzeCompareResponse resp = analyzeService.compare(leftImageId, rightImageId);
     return ResponseEntity.ok(resp);
   }

src/main/java/dev/coms4156/project/metadetect/controller/AnalyzeController.java

@@ -25,20 +25,53 @@ public class AuthController {
   private final UserService userService;
   private final AuthProxyService authProxy;
 
+  /**
+   * Constructs the controller with required collaborators.
+   *
+   * @param userService local user domain service
+   * @param authProxy adaptor that calls Supabase Auth endpoints
+   */
   public AuthController(UserService userService, AuthProxyService authProxy) {
     this.userService = userService;
     this.authProxy = authProxy;
   }
 
-  // --- Proxy endpoints (raw Supabase JSON passthrough) ---
+  // === Proxy endpoints (raw Supabase JSON passthrough) ========================
 
+  /**
+   * Proxies a sign-up request to Supabase Auth.
+   * Returns Supabase's JSON (e.g., user, session, error) as-is to the caller.
+   * Validation
+   * - Basic shape validation is provided by the DTO; deeper
+   *   validation and error shaping are
+   *   delegated to Supabase.
+   * Side effects
+   * - Supabase may create the user and return a session
+   *   depending on project config
+   *   (email confirmation, etc.).
+   *
+   * @param req register payload containing email and password
+   * @return upstream Supabase JSON wrapped in a {@link ResponseEntity}
+   */
   @PostMapping("/signup")
   public ResponseEntity<String> signup(@RequestBody Dtos.RegisterRequest req) {
+    // Pass-through: do not log raw passwords; the proxy handles HTTP and error codes.
     return authProxy.signup(req.email(), req.password());
   }
 
+  /**
+   * Proxies a login request to Supabase Auth.
+   * Returns Supabase's JSON (e.g., session/access token) as-is.
+   * Error handling
+   * - Incorrect credentials and account state errors are surfaced from Supabase and returned
+   *   unchanged so clients can rely on standard Supabase error formats.
+   *
+   * @param req login payload containing email and password
+   * @return upstream Supabase JSON wrapped in a {@link ResponseEntity}
+   */
   @PostMapping("/login")
   public ResponseEntity<String> login(@RequestBody Dtos.LoginRequest req) {
+    // Pass-through: credentials are forwarded to Supabase; no local auth happens here.
     return authProxy.login(req.email(), req.password());
   }
 

src/main/java/dev/coms4156/project/metadetect/controller/AuthController.java

@@ -5,33 +5,51 @@
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
+
 /**
- * Basic health/version for Iteration 1.
+ * Health and metadata endpoints for Iteration 1 readiness.
+ * Responsibilities:
+ * - Verifies DB connectivity with a minimal round-trip.
+ * - Exposes a static version endpoint for diagnostics.
+ * These endpoints are intentionally unauthenticated so platform probes (Kubernetes, Render,
+ * Fly.io, etc.) can detect whether the service is healthy at startup and runtime.
  */
-
 @RestController
 public class HealthController {
 
   private final JdbcTemplate jdbc;
 
+  /**
+   * Constructs the controller used for basic health checks.
+   *
+   * @param jdbc JDBC template used to verify DB connectivity.
+   */
   public HealthController(JdbcTemplate jdbc) {
     this.jdbc = jdbc;
   }
 
   /**
-   * Simple liveness endpoint for health checks.
+   * Performs a minimal DB liveness check using a simple `select 1`.
+   * Returns "UP" when the DB is reachable, otherwise "DOWN".
    *
-   * @return static JSON confirming the service is reachable
+   * @return a simple "UP" or "DOWN" status string
    */
   @GetMapping("/db/health")
   public String dbHealth() {
+    // No table lookup required: trivial round-trip ensures database is responsive.
     Integer one = jdbc.queryForObject("select 1", Integer.class);
     return one != null && one == 1 ? "UP" : "DOWN";
-
   }
 
+  /**
+   * Returns static version/service metadata for smoke tests or rollout tracing.
+   *
+   * @return JSON map containing service name and version
+   */
   @GetMapping("/db/version")
   public ResponseEntity<Map<String, String>> version() {
-    return ResponseEntity.ok(Map.of("service", "metadetect-service", "version", "0.1.0"));
+    return ResponseEntity.ok(
+      Map.of("service", "metadetect-service", "version", "0.1.0")
+    );
   }
 }