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,29 +41,79 @@ 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;