backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java

@@ -5,6 +5,15 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import java.time.LocalDate;
 import java.util.List;
 
+/**
+ * Result of the timeline density aggregation.
+ *
+ * <p>{@code minDate} / {@code maxDate} are intentionally not marked
+ * {@code @Schema(requiredMode = REQUIRED)} — the empty-result case (no
+ * documents match the filter) returns them as {@code null}, which surfaces in
+ * the generated TypeScript as {@code minDate?: string | null}. Frontend code
+ * must treat them as optional.
+ */
 public record DocumentDensityResult(
         @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
         List<MonthBucket> buckets,