diff --git a/backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java b/backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java
index 5c246113..521feca5 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java
+++ b/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,