From e8f158aeceff41b8678882ae75967d74053ca914 Mon Sep 17 00:00:00 2001
From: Dave the Dev <davethedev@hithomelabs.com>
Date: Tue, 14 Apr 2026 11:51:39 +0000
Subject: [PATCH] Hithomelabs/CFTunnels#114: Add JavaDoc to Request entity

---
 .../hithomelabs/CFTunnels/Entity/Request.java | 77 ++++++++++++++++++-
 1 file changed, 76 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/hithomelabs/CFTunnels/Entity/Request.java b/src/main/java/com/hithomelabs/CFTunnels/Entity/Request.java
index 8d73de8..c66bcb4 100644
--- a/src/main/java/com/hithomelabs/CFTunnels/Entity/Request.java
+++ b/src/main/java/com/hithomelabs/CFTunnels/Entity/Request.java
@@ -8,6 +8,31 @@ import lombok.Setter;
 
 import java.util.UUID;
 
+/**
+ * JPA Entity representing a mapping change request in the approval workflow.
+ * 
+ * <p>This entity tracks requests to add or modify tunnel ingress mappings.
+ * It implements an approval workflow where:</p>
+ * <ul>
+ *   <li>Users create requests (status: PENDING)</li>
+ *   <li>Approvers review and approve/reject (status: APPROVED/REJECTED)</li>
+ * </ul>
+ * 
+ * <p><b>Database Table:</b> {@code requests}</p>
+ * 
+ * <p><b>Workflow:</b></p>
+ * <pre>
+ * 1. User submits mapping request via REST API
+ * 2. Request is created with PENDING status
+ * 3. APPROVER role reviews the request
+ * 4. If approved: mapping is applied to Cloudflare tunnel
+ * 5. If rejected: request is marked REJECTED
+ * </pre>
+ * 
+ * @see Mapping
+ * @see User
+ * @see RequestStatus
+ */
 @Entity
 @Getter
 @Setter
@@ -16,30 +41,80 @@ import java.util.UUID;
 @Table(name = "requests")
 public class Request {
 
+    /**
+     * Unique identifier for this request (auto-generated UUID).
+     */
     @Id
     @GeneratedValue
     @Column(columnDefinition = "uuid", unique = true, nullable = false)
     private UUID id;
 
+    /**
+     * The mapping configuration being requested.
+     * 
+     * <p>This is a one-to-one relationship - each request
+     * contains exactly one mapping configuration.</p>
+     * 
+     * @see Mapping
+     */
     @OneToOne
     @JoinColumn(name = "mapping_id", unique = true, nullable = false)
     private Mapping mapping;
 
+    /**
+     * User who created this request.
+     * 
+     * <p>This field is required and tracks accountability.</p>
+     * 
+     * @see User
+     */
     @ManyToOne
     @JoinColumn(name = "created_by", nullable = false)
     private User createdBy;
 
+    /**
+     * User who approved or rejected this request.
+     * 
+     * <p>This is null until the request is processed.</p>
+     * 
+     * @see User
+     */
     @ManyToOne
     @JoinColumn(name = "accepted_by")
     private User acceptedBy;
 
+    /**
+     * Status of the mapping request in the workflow.
+     * 
+     * @see RequestStatus
+     */
     public enum RequestStatus {
+        /**
+         * Request is waiting for approval.
+         */
         PENDING,
+
+        /**
+         * Request has been approved.
+         * The mapping should now be applied to the tunnel.
+         */
         APPROVED,
+
+        /**
+         * Request has been rejected.
+         * No changes will be made to the tunnel.
+         */
         REJECTED
     }
 
+    /**
+     * Current status of this request.
+     * 
+     * <p>Initially set to PENDING when created.</p>
+     * 
+     * @see RequestStatus
+     */
     @Enumerated(EnumType.STRING)
     @Column(length = 10, nullable = false)
     private RequestStatus status;
-}
+}
\ No newline at end of file