refactor(e2e): extract reusable captureProofshots helper

Any future feature spec now just calls:
  captureProofshots('/my-route', 'feature-name')

to get 6 screenshots (3 viewports × 2 themes) saved to
proofshot-artifacts/{feature-name}/.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/pom.xml

@@ -65,6 +65,16 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-jetty</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-testcontainers</artifactId>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.testcontainers</groupId>
+			<artifactId>testcontainers-postgresql</artifactId>
+			<scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-actuator-test</artifactId>
@@ -161,6 +171,50 @@
 
 	<build>
 		<plugins>
+			<plugin>
+				<groupId>org.jacoco</groupId>
+				<artifactId>jacoco-maven-plugin</artifactId>
+				<version>0.8.12</version>
+				<configuration>
+					<excludes>
+						<exclude>**/dto/**</exclude>
+						<exclude>**/config/**</exclude>
+						<exclude>**/exception/ErrorCode*</exclude>
+						<exclude>**/model/**</exclude>
+					</excludes>
+				</configuration>
+				<executions>
+					<execution>
+						<id>prepare-agent</id>
+						<goals><goal>prepare-agent</goal></goals>
+					</execution>
+					<execution>
+						<id>report</id>
+						<phase>verify</phase>
+						<goals><goal>report</goal></goals>
+					</execution>
+					<!-- Gate: baseline 89.4% overall / service 90.2% / controller 80.0% -->
+					<execution>
+						<id>check</id>
+						<phase>verify</phase>
+						<goals><goal>check</goal></goals>
+						<configuration>
+							<rules>
+								<rule>
+									<element>BUNDLE</element>
+									<limits>
+										<limit>
+											<counter>BRANCH</counter>
+											<value>COVEREDRATIO</value>
+											<minimum>0.88</minimum>
+										</limit>
+									</limits>
+								</rule>
+							</rules>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
 			<plugin>
 				<groupId>org.springframework.boot</groupId>
 				<artifactId>spring-boot-maven-plugin</artifactId>

backend/src/main/java/org/raddatz/familienarchiv/controller/AnnotationController.java

@@ -35,7 +35,7 @@ public class AnnotationController {
 
     @PostMapping
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentAnnotation createAnnotation(
             @PathVariable UUID documentId,
             @RequestBody CreateAnnotationDTO dto,
@@ -47,7 +47,7 @@ public class AnnotationController {
 
     @DeleteMapping("/{annotationId}")
     @ResponseStatus(HttpStatus.NO_CONTENT)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public void deleteAnnotation(
             @PathVariable UUID documentId,
             @PathVariable UUID annotationId,

backend/src/main/java/org/raddatz/familienarchiv/controller/CommentController.java

@@ -33,25 +33,25 @@ public class CommentController {
 
     @PostMapping("/api/documents/{documentId}/comments")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment postDocumentComment(
             @PathVariable UUID documentId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.postComment(documentId, null, dto.getContent(), author);
+        return commentService.postComment(documentId, null, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     @PostMapping("/api/documents/{documentId}/comments/{commentId}/replies")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment replyToDocumentComment(
             @PathVariable UUID documentId,
             @PathVariable UUID commentId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.replyToComment(documentId, commentId, dto.getContent(), author);
+        return commentService.replyToComment(documentId, commentId, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     // ─── Annotation comments ──────────────────────────────────────────────────
@@ -63,32 +63,32 @@ public class CommentController {
 
     @PostMapping("/api/documents/{documentId}/annotations/{annotationId}/comments")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment postAnnotationComment(
             @PathVariable UUID documentId,
             @PathVariable UUID annotationId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.postComment(documentId, annotationId, dto.getContent(), author);
+        return commentService.postComment(documentId, annotationId, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     @PostMapping("/api/documents/{documentId}/annotations/{annotationId}/comments/{commentId}/replies")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment replyToAnnotationComment(
             @PathVariable UUID documentId,
             @PathVariable UUID commentId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.replyToComment(documentId, commentId, dto.getContent(), author);
+        return commentService.replyToComment(documentId, commentId, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     // ─── Edit and delete (shared) ─────────────────────────────────────────────
 
     @PatchMapping("/api/documents/{documentId}/comments/{commentId}")
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment editComment(
             @PathVariable UUID documentId,
             @PathVariable UUID commentId,

backend/src/main/java/org/raddatz/familienarchiv/controller/DocumentController.java

@@ -13,9 +13,11 @@ import java.util.UUID;
 
 import org.raddatz.familienarchiv.dto.DocumentUpdateDTO;
 import org.raddatz.familienarchiv.dto.DocumentVersionSummary;
+import org.raddatz.familienarchiv.dto.IncompleteDocumentDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.DocumentVersion;
 import org.raddatz.familienarchiv.security.Permission;
 import org.raddatz.familienarchiv.security.RequirePermission;
@@ -164,8 +166,9 @@ public class DocumentController {
     }
 
     @GetMapping("/incomplete")
-    public List<Document> getIncomplete() {
-        return documentService.findIncompleteDocuments();
+    public List<IncompleteDocumentDTO> getIncomplete(
+            @RequestParam(defaultValue = "10") int size) {
+        return documentService.findIncompleteDocuments(size);
     }
 
     @GetMapping("/incomplete/next")
@@ -182,8 +185,9 @@ public class DocumentController {
             @RequestParam(required = false) LocalDate to,
             @RequestParam(required = false) UUID senderId,
             @RequestParam(required = false) UUID receiverId,
-            @RequestParam(required = false, name = "tag") List<String> tags) {
-        return ResponseEntity.ok(documentService.searchDocuments(q, from, to, senderId, receiverId, tags));
+            @RequestParam(required = false, name = "tag") List<String> tags,
+            @RequestParam(required = false) DocumentStatus status) {
+        return ResponseEntity.ok(documentService.searchDocuments(q, from, to, senderId, receiverId, tags, status));
     }
 
     // --- VERSIONS ---

backend/src/main/java/org/raddatz/familienarchiv/controller/GlobalExceptionHandler.java

@@ -8,6 +8,8 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+import org.springframework.web.server.ResponseStatusException;
 
 import lombok.extern.slf4j.Slf4j;
 
@@ -30,6 +32,18 @@ public class GlobalExceptionHandler {
         return ResponseEntity.badRequest().body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, message));
     }
 
+    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
+    public ResponseEntity<ErrorResponse> handleTypeMismatch(MethodArgumentTypeMismatchException ex) {
+        String message = "Invalid value '" + ex.getValue() + "' for parameter '" + ex.getName() + "'";
+        return ResponseEntity.badRequest().body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, message));
+    }
+
+    @ExceptionHandler(ResponseStatusException.class)
+    public ResponseEntity<ErrorResponse> handleResponseStatus(ResponseStatusException ex) {
+        return ResponseEntity.status(ex.getStatusCode())
+                .body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, ex.getReason()));
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ErrorResponse> handleGeneric(Exception ex) {
         log.error("Unhandled exception", ex);

backend/src/main/java/org/raddatz/familienarchiv/controller/NotificationController.java

@@ -0,0 +1,100 @@
+package org.raddatz.familienarchiv.controller;
+
+import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.dto.NotificationDTO;
+import org.raddatz.familienarchiv.dto.NotificationPreferenceDTO;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.service.NotificationService;
+import org.raddatz.familienarchiv.service.SseEmitterRegistry;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+import java.util.Map;
+
+import java.util.UUID;
+
+@RestController
+@RequiredArgsConstructor
+public class NotificationController {
+
+    private final NotificationService notificationService;
+    private final UserService userService;
+    private final SseEmitterRegistry sseEmitterRegistry;
+
+    // These endpoints are intentionally open to any authenticated user —
+    // they return and mutate only the current user's own notifications, scoped
+    // by the resolved user identity. No additional permission check is required.
+
+    @GetMapping(value = "/api/notifications/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+    public SseEmitter stream(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return sseEmitterRegistry.register(user.getId());
+    }
+
+    @GetMapping("/api/notifications")
+    public Page<NotificationDTO> getNotifications(
+            @RequestParam(defaultValue = "0") int page,
+            @RequestParam(defaultValue = "10") int size,
+            @RequestParam(required = false) NotificationType type,
+            @RequestParam(required = false) Boolean read,
+            Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        PageRequest pageable = PageRequest.of(page, size, Sort.by("createdAt").descending());
+        return notificationService.getNotifications(user.getId(), type, read, pageable);
+    }
+
+    @GetMapping("/api/notifications/unread-count")
+    public Map<String, Long> countUnread(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return Map.of("count", notificationService.countUnread(user.getId()));
+    }
+
+    @PostMapping("/api/notifications/read-all")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    public void markAllRead(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        notificationService.markAllRead(user.getId());
+    }
+
+    @PatchMapping("/api/notifications/{id}/read")
+    public NotificationDTO markOneRead(
+            @PathVariable UUID id,
+            Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return notificationService.markRead(id, user.getId());
+    }
+
+    @GetMapping("/api/users/me/notification-preferences")
+    @RequirePermission({Permission.READ_ALL, Permission.WRITE_ALL, Permission.ANNOTATE_ALL})
+    public NotificationPreferenceDTO getPreferences(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return new NotificationPreferenceDTO(user.isNotifyOnReply(), user.isNotifyOnMention());
+    }
+
+    @PutMapping("/api/users/me/notification-preferences")
+    @RequirePermission({Permission.READ_ALL, Permission.WRITE_ALL, Permission.ANNOTATE_ALL})
+    public NotificationPreferenceDTO updatePreferences(
+            @RequestBody NotificationPreferenceDTO dto,
+            Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        AppUser updated = notificationService.updatePreferences(
+                user.getId(), dto.notifyOnReply(), dto.notifyOnMention());
+        return new NotificationPreferenceDTO(updated.isNotifyOnReply(), updated.isNotifyOnMention());
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private AppUser resolveUser(Authentication authentication) {
+        return userService.findByUsername(authentication.getName());
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/controller/UserSearchController.java

@@ -0,0 +1,32 @@
+package org.raddatz.familienarchiv.controller;
+
+import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.dto.MentionDTO;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.service.UserSearchService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+@RestController
+@RequiredArgsConstructor
+@RequirePermission({Permission.READ_ALL, Permission.WRITE_ALL, Permission.ANNOTATE_ALL})
+public class UserSearchController {
+
+    private final UserSearchService userSearchService;
+
+    @GetMapping("/api/users/search")
+    public List<MentionDTO> search(@RequestParam(defaultValue = "") String q) {
+        return userSearchService.search(q).stream()
+                .map(this::toMentionDTO)
+                .toList();
+    }
+
+    private MentionDTO toMentionDTO(AppUser user) {
+        return new MentionDTO(user.getId(), user.getFirstName(), user.getLastName());
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/CreateCommentDTO.java

@@ -2,7 +2,12 @@ package org.raddatz.familienarchiv.dto;
 
 import lombok.Data;
 
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
 @Data
 public class CreateCommentDTO {
     private String content;
+    private List<UUID> mentionedUserIds = new ArrayList<>();
 }

backend/src/main/java/org/raddatz/familienarchiv/dto/IncompleteDocumentDTO.java

@@ -0,0 +1,10 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.UUID;
+
+public record IncompleteDocumentDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String title
+) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/MentionDTO.java

@@ -0,0 +1,11 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.UUID;
+
+public record MentionDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String firstName,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String lastName
+) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/NotificationDTO.java

@@ -0,0 +1,18 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.raddatz.familienarchiv.model.NotificationType;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+public record NotificationDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) NotificationType type,
+        UUID documentId,
+        UUID referenceId,
+        UUID annotationId,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) boolean read,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDateTime createdAt,
+        String actorName
+) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/NotificationPreferenceDTO.java

@@ -0,0 +1,3 @@
+package org.raddatz.familienarchiv.dto;
+
+public record NotificationPreferenceDTO(boolean notifyOnReply, boolean notifyOnMention) {}

backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java

@@ -50,6 +50,10 @@ public enum ErrorCode {
     /** The comment with the given ID does not exist. 404 */
     COMMENT_NOT_FOUND,
 
+    // --- Notifications ---
+    /** The notification with the given ID does not exist. 404 */
+    NOTIFICATION_NOT_FOUND,
+
     // --- Generic ---
     /** Request validation failed (missing or malformed fields). 400 */
     VALIDATION_ERROR,

backend/src/main/java/org/raddatz/familienarchiv/model/AppUser.java

@@ -51,6 +51,16 @@ public class AppUser {
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private boolean enabled = true; // Um User zu sperren ohne sie zu löschen
 
+    @Column(nullable = false)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private boolean notifyOnReply = false;
+
+    @Column(nullable = false)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private boolean notifyOnMention = false;
+
     // Ein User kann in mehreren Gruppen sein
     @ManyToMany(fetch = FetchType.EAGER)
     @JoinTable(name = "users_groups", joinColumns = @JoinColumn(name = "user_id"), inverseJoinColumns = @JoinColumn(name = "group_id"))

backend/src/main/java/org/raddatz/familienarchiv/model/DocumentComment.java

@@ -1,10 +1,12 @@
 package org.raddatz.familienarchiv.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.persistence.*;
 import lombok.*;
 import org.hibernate.annotations.CreationTimestamp;
 import org.hibernate.annotations.UpdateTimestamp;
+import org.raddatz.familienarchiv.dto.MentionDTO;
 
 import java.time.LocalDateTime;
 import java.util.ArrayList;
@@ -60,4 +62,21 @@ public class DocumentComment {
     @Builder.Default
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private List<DocumentComment> replies = new ArrayList<>();
+
+    // JPA join table for structured mention references — not serialized directly
+    @ManyToMany(fetch = FetchType.EAGER)
+    @JoinTable(
+            name = "comment_mentions",
+            joinColumns = @JoinColumn(name = "comment_id"),
+            inverseJoinColumns = @JoinColumn(name = "user_id")
+    )
+    @JsonIgnore
+    @Builder.Default
+    private List<AppUser> mentions = new ArrayList<>();
+
+    // Populated by CommentService before serialization — not persisted.
+    @Transient
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private List<MentionDTO> mentionDTOs = new ArrayList<>();
 }

backend/src/main/java/org/raddatz/familienarchiv/model/Notification.java

@@ -0,0 +1,55 @@
+package org.raddatz.familienarchiv.model;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.CreationTimestamp;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Entity
+@Table(name = "notifications")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class Notification {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "recipient_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private AppUser recipient;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private NotificationType type;
+
+    @Column(name = "document_id")
+    private UUID documentId;
+
+    @Column(name = "reference_id")
+    private UUID referenceId;
+
+    @Column(name = "annotation_id")
+    private UUID annotationId;
+
+    @Column(nullable = false)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private boolean read = false;
+
+    @CreationTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime createdAt;
+
+    @Column(name = "actor_name")
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String actorName;
+}

backend/src/main/java/org/raddatz/familienarchiv/model/NotificationType.java

@@ -0,0 +1,6 @@
+package org.raddatz.familienarchiv.model;
+
+public enum NotificationType {
+    REPLY,
+    MENTION
+}

backend/src/main/java/org/raddatz/familienarchiv/repository/AppUserRepository.java

@@ -1,10 +1,13 @@
 package org.raddatz.familienarchiv.repository;
 
-
 import org.raddatz.familienarchiv.model.AppUser;
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
+import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -12,4 +15,9 @@ import java.util.UUID;
 public interface AppUserRepository extends JpaRepository<AppUser, UUID> {
     Optional<AppUser> findByUsername(String username);
     Optional<AppUser> findByEmail(String email);
+
+    @Query("SELECT u FROM AppUser u WHERE " +
+            "LOWER(COALESCE(u.firstName, '') || ' ' || COALESCE(u.lastName, '')) LIKE LOWER(CONCAT('%', :q, '%')) " +
+            "OR LOWER(u.username) LIKE LOWER(CONCAT('%', :q, '%'))")
+    List<AppUser> searchByNameOrUsername(@Param("q") String q, Pageable pageable);
 }

backend/src/main/java/org/raddatz/familienarchiv/repository/DocumentRepository.java

@@ -2,6 +2,8 @@ package org.raddatz.familienarchiv.repository;
 
 import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
@@ -46,6 +48,8 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
 
     List<Document> findByMetadataCompleteFalse(Sort sort);
 
+    Page<Document> findByMetadataCompleteFalse(Pageable pageable);
+
     Optional<Document> findFirstByMetadataCompleteFalseAndIdNot(UUID id, Sort sort);
 
     @Query("SELECT DISTINCT d FROM Document d " +

backend/src/main/java/org/raddatz/familienarchiv/repository/DocumentSpecifications.java

@@ -7,6 +7,7 @@ import java.util.List;
 import java.util.UUID;
 
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.Tag;
 import org.springframework.data.jpa.domain.Specification;
 import org.springframework.util.StringUtils;
@@ -55,6 +56,11 @@ public class DocumentSpecifications {
         };
     }
     
+    // Filtert nach Status
+    public static Specification<Document> hasStatus(DocumentStatus status) {
+        return (root, query, cb) -> status == null ? null : cb.equal(root.get("status"), status);
+    }
+
     // Filtert nach Schlagworten (UND-Verknüpfung)
     public static Specification<Document> hasTags(List<String> tags) {
         return (root, query, cb) -> {

backend/src/main/java/org/raddatz/familienarchiv/repository/NotificationRepository.java

@@ -0,0 +1,29 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.Notification;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.UUID;
+
+public interface NotificationRepository extends JpaRepository<Notification, UUID> {
+
+    Page<Notification> findByRecipientIdOrderByCreatedAtDesc(UUID recipientId, Pageable pageable);
+
+    Page<Notification> findByRecipientIdAndTypeOrderByCreatedAtDesc(
+            UUID recipientId, NotificationType type, Pageable pageable);
+
+    Page<Notification> findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+            UUID recipientId, NotificationType type, Pageable pageable);
+
+    long countByRecipientIdAndReadFalse(UUID recipientId);
+
+    @Modifying
+    @Query("UPDATE Notification n SET n.read = true WHERE n.recipient.id = :userId")
+    void markAllReadByRecipientId(@Param("userId") UUID userId);
+}

backend/src/main/java/org/raddatz/familienarchiv/security/PermissionAspect.java

@@ -23,7 +23,7 @@ public class PermissionAspect {
         RequirePermission permission = getAnnotation(joinPoint);
 
         if (permission != null) {
-            validateUserAccess(permission.value());
+            validateUserAccess(permission.value()); // value() is now Permission[]
         }
 
         return joinPoint.proceed();
@@ -43,18 +43,23 @@ public class PermissionAspect {
         return joinPoint.getTarget().getClass().getAnnotation(RequirePermission.class);
     }
 
-    private void validateUserAccess(Permission requiredPerm) {
+    private void validateUserAccess(Permission[] requiredPerms) {
         Authentication auth = SecurityContextHolder.getContext().getAuthentication();
 
         if (auth == null || !auth.isAuthenticated()) {
             throw DomainException.unauthorized("Not authenticated");
         }
 
-        boolean hasPermission = auth.getAuthorities().stream()
-                .anyMatch(a -> a.getAuthority().equals(requiredPerm.name()));
+        boolean hasAny = auth.getAuthorities().stream()
+                .anyMatch(a -> {
+                    for (Permission p : requiredPerms) {
+                        if (a.getAuthority().equals(p.name())) return true;
+                    }
+                    return false;
+                });
 
-        if (!hasPermission) {
-            throw DomainException.forbidden("Missing required permission: " + requiredPerm.name());
+        if (!hasAny) {
+            throw DomainException.forbidden("Missing required permission");
         }
     }
 }

backend/src/main/java/org/raddatz/familienarchiv/security/RequirePermission.java

@@ -8,5 +8,5 @@ import java.lang.annotation.Target;
 @Target({ElementType.METHOD, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface RequirePermission {
-    Permission value(); // e.g. "ADMIN" or "WRITE_ALL"
+    Permission[] value(); // one or more — user needs any of the listed permissions
 }

backend/src/main/java/org/raddatz/familienarchiv/service/CommentService.java

@@ -1,6 +1,7 @@
 package org.raddatz.familienarchiv.service;
 
 import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.dto.MentionDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.model.AppUser;
@@ -9,7 +10,9 @@ import org.raddatz.familienarchiv.repository.CommentRepository;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Set;
 import java.util.UUID;
 
 @Service
@@ -17,20 +20,23 @@ import java.util.UUID;
 public class CommentService {
 
     private final CommentRepository commentRepository;
+    private final UserService userService;
+    private final NotificationService notificationService;
 
     public List<DocumentComment> getCommentsForDocument(UUID documentId) {
         List<DocumentComment> roots =
                 commentRepository.findByDocumentIdAndAnnotationIdIsNullAndParentIdIsNull(documentId);
-        return withReplies(roots);
+        return withRepliesAndMentions(roots);
     }
 
     public List<DocumentComment> getCommentsForAnnotation(UUID annotationId) {
         List<DocumentComment> roots = commentRepository.findByAnnotationIdAndParentIdIsNull(annotationId);
-        return withReplies(roots);
+        return withRepliesAndMentions(roots);
     }
 
     @Transactional
-    public DocumentComment postComment(UUID documentId, UUID annotationId, String content, AppUser author) {
+    public DocumentComment postComment(UUID documentId, UUID annotationId, String content,
+                                       List<UUID> mentionedUserIds, AppUser author) {
         DocumentComment comment = DocumentComment.builder()
                 .documentId(documentId)
                 .annotationId(annotationId)
@@ -38,11 +44,16 @@ public class CommentService {
                 .authorId(author.getId())
                 .authorName(resolveAuthorName(author))
                 .build();
-        return commentRepository.save(comment);
+        saveMentions(comment, mentionedUserIds);
+        DocumentComment saved = commentRepository.save(comment);
+        withMentionDTOs(saved);
+        notificationService.notifyMentions(mentionedUserIds, saved);
+        return saved;
     }
 
     @Transactional
-    public DocumentComment replyToComment(UUID documentId, UUID commentId, String content, AppUser author) {
+    public DocumentComment replyToComment(UUID documentId, UUID commentId, String content,
+                                          List<UUID> mentionedUserIds, AppUser author) {
         DocumentComment target = commentRepository.findById(commentId)
                 .orElseThrow(() -> DomainException.notFound(
                         ErrorCode.COMMENT_NOT_FOUND, "Comment not found: " + commentId));
@@ -60,7 +71,15 @@ public class CommentService {
                 .authorId(author.getId())
                 .authorName(resolveAuthorName(author))
                 .build();
-        return commentRepository.save(reply);
+        saveMentions(reply, mentionedUserIds);
+        DocumentComment saved = commentRepository.save(reply);
+        withMentionDTOs(saved);
+
+        Set<UUID> participantIds = collectParticipantIds(root);
+        participantIds.remove(author.getId());
+        notificationService.notifyReply(saved, participantIds);
+        notificationService.notifyMentions(mentionedUserIds, saved);
+        return saved;
     }
 
     @Transactional
@@ -84,13 +103,45 @@ public class CommentService {
         commentRepository.delete(comment);
     }
 
+    public List<DocumentComment> findReplies(UUID parentId) {
+        return commentRepository.findByParentId(parentId);
+    }
+
     // ─── private helpers ──────────────────────────────────────────────────────
 
-    private List<DocumentComment> withReplies(List<DocumentComment> roots) {
-        roots.forEach(root -> root.setReplies(commentRepository.findByParentId(root.getId())));
+    private List<DocumentComment> withRepliesAndMentions(List<DocumentComment> roots) {
+        roots.forEach(root -> {
+            List<DocumentComment> replies = commentRepository.findByParentId(root.getId());
+            replies.forEach(this::withMentionDTOs);
+            root.setReplies(replies);
+            withMentionDTOs(root);
+        });
         return roots;
     }
 
+    private void saveMentions(DocumentComment comment, List<UUID> mentionedUserIds) {
+        if (mentionedUserIds == null || mentionedUserIds.isEmpty()) return;
+        List<AppUser> users = userService.findAllById(mentionedUserIds);
+        comment.setMentions(users);
+    }
+
+    private void withMentionDTOs(DocumentComment comment) {
+        List<MentionDTO> dtos = comment.getMentions().stream()
+                .map(u -> new MentionDTO(u.getId(), u.getFirstName(), u.getLastName()))
+                .toList();
+        comment.setMentionDTOs(dtos);
+    }
+
+    private Set<UUID> collectParticipantIds(DocumentComment root) {
+        Set<UUID> ids = new LinkedHashSet<>();
+        if (root.getAuthorId() != null) ids.add(root.getAuthorId());
+        commentRepository.findByParentId(root.getId())
+                .forEach(reply -> {
+                    if (reply.getAuthorId() != null) ids.add(reply.getAuthorId());
+                });
+        return ids;
+    }
+
     private DocumentComment findComment(UUID documentId, UUID commentId) {
         return commentRepository.findById(commentId)
                 .filter(c -> documentId.equals(c.getDocumentId()))

backend/src/main/java/org/raddatz/familienarchiv/service/DocumentService.java

@@ -4,11 +4,13 @@ import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
 import org.raddatz.familienarchiv.dto.DocumentUpdateDTO;
+import org.raddatz.familienarchiv.dto.IncompleteDocumentDTO;
 import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.Person;
 import org.raddatz.familienarchiv.model.Tag;
 import org.raddatz.familienarchiv.repository.DocumentRepository;
+import org.springframework.data.domain.PageRequest;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.jpa.domain.Specification;
 import org.raddatz.familienarchiv.exception.DomainException;
@@ -108,9 +110,13 @@ public class DocumentService {
                     || (dto.getReceiverIds() != null && !dto.getReceiverIds().isEmpty());
         }
 
+        String titleToUse = (dto.getTitle() != null && !dto.getTitle().isBlank())
+                ? dto.getTitle()
+                : titleFromFilename(filename);
+
         Document doc = Document.builder()
                 .originalFilename(filename)
-                .title(dto.getTitle())
+                .title(titleToUse)
                 .documentDate(dto.getDocumentDate())
                 .location(dto.getLocation())
                 .documentLocation(dto.getDocumentLocation())
@@ -255,12 +261,13 @@ public class DocumentService {
     }
 
     // 1. Allgemeine Suche (für das Suchfeld im Frontend)
-    public List<Document> searchDocuments(String text, LocalDate from, LocalDate to, UUID sender, UUID receiver, List<String> tags) {
+    public List<Document> searchDocuments(String text, LocalDate from, LocalDate to, UUID sender, UUID receiver, List<String> tags, DocumentStatus status) {
         Specification<Document> spec = Specification.where(hasText(text))
                 .and(isBetween(from, to))
                 .and(hasSender(sender))
                 .and(hasReceiver(receiver))
-                .and(hasTags(tags));
+                .and(hasTags(tags))
+                .and(hasStatus(status));
 
         // Neueste zuerst (nach Erstellungsdatum)
         return documentRepository.findAll(spec, Sort.by(Sort.Direction.DESC, "createdAt"));
@@ -309,8 +316,12 @@ public class DocumentService {
         return documentRepository.countByMetadataCompleteFalse();
     }
 
-    public List<Document> findIncompleteDocuments() {
-        return documentRepository.findByMetadataCompleteFalse(Sort.by(Sort.Direction.DESC, "createdAt"));
+    public List<IncompleteDocumentDTO> findIncompleteDocuments(int size) {
+        PageRequest pageable = PageRequest.of(0, size, Sort.by(Sort.Direction.DESC, "createdAt"));
+        return documentRepository.findByMetadataCompleteFalse(pageable)
+                .stream()
+                .map(doc -> new IncompleteDocumentDTO(doc.getId(), doc.getTitle()))
+                .toList();
     }
 
     public Optional<Document> findNextIncompleteDocument(UUID currentId) {

backend/src/main/java/org/raddatz/familienarchiv/service/NotificationService.java

@@ -0,0 +1,195 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.dto.NotificationDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.DocumentComment;
+import org.raddatz.familienarchiv.model.Notification;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.raddatz.familienarchiv.repository.NotificationRepository;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.mail.MailException;
+import org.springframework.mail.SimpleMailMessage;
+import org.springframework.mail.javamail.JavaMailSender;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class NotificationService {
+
+    private final NotificationRepository notificationRepository;
+    private final UserService userService;
+    private final Optional<JavaMailSender> mailSender;
+    private final SseEmitterRegistry sseEmitterRegistry;
+
+    @Value("${app.mail.from:noreply@familienarchiv.local}")
+    private String mailFrom;
+
+    @Value("${app.base-url:http://localhost:3000}")
+    private String baseUrl;
+
+    /**
+     * Creates REPLY notifications for all participants in the thread, excluding the replier.
+     * Runs in a separate transaction so a notification failure cannot roll back the parent comment.
+     */
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void notifyReply(DocumentComment reply, Set<UUID> participantIds) {
+        if (participantIds.isEmpty()) return;
+
+        List<AppUser> recipients = userService.findAllById(participantIds);
+        for (AppUser recipient : recipients) {
+            Notification notification = Notification.builder()
+                    .recipient(recipient)
+                    .type(NotificationType.REPLY)
+                    .documentId(reply.getDocumentId())
+                    .referenceId(reply.getId())
+                    .annotationId(reply.getAnnotationId())
+                    .actorName(reply.getAuthorName())
+                    .build();
+            saveAndPush(notification);
+
+            if (recipient.isNotifyOnReply()) {
+                sendNotificationEmail(recipient, reply, NotificationType.REPLY);
+            }
+        }
+    }
+
+    /**
+     * Creates MENTION notifications for each mentioned user.
+     * Runs in a separate transaction so a notification failure cannot roll back the parent comment.
+     */
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void notifyMentions(List<UUID> mentionedUserIds, DocumentComment comment) {
+        if (mentionedUserIds == null || mentionedUserIds.isEmpty()) return;
+
+        List<AppUser> recipients = userService.findAllById(mentionedUserIds);
+        for (AppUser recipient : recipients) {
+            Notification notification = Notification.builder()
+                    .recipient(recipient)
+                    .type(NotificationType.MENTION)
+                    .documentId(comment.getDocumentId())
+                    .referenceId(comment.getId())
+                    .annotationId(comment.getAnnotationId())
+                    .actorName(comment.getAuthorName())
+                    .build();
+            saveAndPush(notification);
+
+            if (recipient.isNotifyOnMention()) {
+                sendNotificationEmail(recipient, comment, NotificationType.MENTION);
+            }
+        }
+    }
+
+    public Page<NotificationDTO> getNotifications(UUID userId, NotificationType type, Boolean read, Pageable pageable) {
+        if (type != null && Boolean.FALSE.equals(read)) {
+            return notificationRepository.findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(userId, type, pageable)
+                    .map(this::toDTO);
+        }
+        if (type != null) {
+            return notificationRepository.findByRecipientIdAndTypeOrderByCreatedAtDesc(userId, type, pageable)
+                    .map(this::toDTO);
+        }
+        return notificationRepository.findByRecipientIdOrderByCreatedAtDesc(userId, pageable)
+                .map(this::toDTO);
+    }
+
+    public long countUnread(UUID userId) {
+        return notificationRepository.countByRecipientIdAndReadFalse(userId);
+    }
+
+    @Transactional
+    public void markAllRead(UUID userId) {
+        notificationRepository.markAllReadByRecipientId(userId);
+    }
+
+    @Transactional
+    public NotificationDTO markRead(UUID notificationId, UUID userId) {
+        Notification notification = notificationRepository.findById(notificationId)
+                .orElseThrow(() -> DomainException.notFound(
+                        ErrorCode.NOTIFICATION_NOT_FOUND, "Notification not found: " + notificationId));
+        if (!notification.getRecipient().getId().equals(userId)) {
+            throw DomainException.forbidden("Notification belongs to a different user");
+        }
+        notification.setRead(true);
+        return toDTO(notificationRepository.save(notification));
+    }
+
+    @Transactional
+    public AppUser updatePreferences(UUID userId, boolean notifyOnReply, boolean notifyOnMention) {
+        return userService.updateNotificationPreferences(userId, notifyOnReply, notifyOnMention);
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private void saveAndPush(Notification notification) {
+        Notification saved = notificationRepository.save(notification);
+        sseEmitterRegistry.send(saved.getRecipient().getId(), toDTO(saved));
+    }
+
+    private NotificationDTO toDTO(Notification n) {
+        return new NotificationDTO(
+                n.getId(),
+                n.getType(),
+                n.getDocumentId(),
+                n.getReferenceId(),
+                n.getAnnotationId(),
+                n.isRead(),
+                n.getCreatedAt(),
+                n.getActorName()
+        );
+    }
+
+    private void buildCommentPath(DocumentComment comment, StringBuilder sb) {
+        sb.append("?commentId=").append(comment.getId());
+        if (comment.getAnnotationId() != null) {
+            sb.append("&annotationId=").append(comment.getAnnotationId());
+        }
+    }
+
+    private void sendNotificationEmail(AppUser recipient, DocumentComment comment, NotificationType type) {
+        if (mailSender.isEmpty()) {
+            log.warn("Mail sender not configured — skipping notification email to {}", recipient.getEmail());
+            return;
+        }
+        if (recipient.getEmail() == null || recipient.getEmail().isBlank()) return;
+
+        StringBuilder path = new StringBuilder("/documents/").append(comment.getDocumentId());
+        buildCommentPath(comment, path);
+        String link = baseUrl + path;
+
+        String subject = type == NotificationType.REPLY
+                ? "Neue Antwort auf deinen Kommentar — Familienarchiv"
+                : "Du wurdest in einem Kommentar erwähnt — Familienarchiv";
+
+        String body = type == NotificationType.REPLY
+                ? "Hallo,\n\njemand hat auf einen Kommentar geantwortet, an dem du beteiligt warst.\n\n"
+                + "Zum Kommentar:\n" + link + "\n\nDein Familienarchiv-Team"
+                : "Hallo,\n\njemand hat dich in einem Kommentar erwähnt.\n\n"
+                + "Zum Kommentar:\n" + link + "\n\nDein Familienarchiv-Team";
+
+        SimpleMailMessage message = new SimpleMailMessage();
+        message.setFrom(mailFrom);
+        message.setTo(recipient.getEmail());
+        message.setSubject(subject);
+        message.setText(body);
+
+        try {
+            mailSender.get().send(message);
+        } catch (MailException e) {
+            log.error("Failed to send notification email to {}: {}", recipient.getEmail(), e.getMessage());
+        }
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/service/SseEmitterRegistry.java

@@ -0,0 +1,36 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+import java.io.IOException;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Component
+@Slf4j
+public class SseEmitterRegistry {
+
+    private final ConcurrentHashMap<UUID, SseEmitter> emitters = new ConcurrentHashMap<>();
+
+    public SseEmitter register(UUID userId) {
+        SseEmitter emitter = new SseEmitter(0L); // 0 = no timeout; EventSource reconnects automatically
+        emitters.put(userId, emitter);
+        emitter.onCompletion(() -> emitters.remove(userId, emitter));
+        emitter.onTimeout(()    -> emitters.remove(userId, emitter));
+        emitter.onError(e  ->    emitters.remove(userId, emitter));
+        return emitter;
+    }
+
+    public void send(UUID userId, Object data) {
+        SseEmitter emitter = emitters.get(userId);
+        if (emitter == null) return;
+        try {
+            emitter.send(SseEmitter.event().name("notification").data(data));
+        } catch (IOException e) {
+            log.debug("SSE send failed for user {} — removing emitter", userId);
+            emitters.remove(userId, emitter);
+        }
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/service/UserSearchService.java

@@ -0,0 +1,23 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.repository.AppUserRepository;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+
+@Service
+@RequiredArgsConstructor
+public class UserSearchService {
+
+    private static final int MAX_RESULTS = 10;
+
+    private final AppUserRepository userRepository;
+
+    public List<AppUser> search(String query) {
+        if (query == null || query.isBlank()) return List.of();
+        return userRepository.searchByNameOrUsername(query.trim(), PageRequest.of(0, MAX_RESULTS));
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/service/UserService.java

@@ -18,6 +18,7 @@ import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.util.Collection;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Optional;
@@ -78,6 +79,18 @@ public class UserService {
                 .orElseThrow(() -> DomainException.notFound(ErrorCode.USER_NOT_FOUND, "No user found for id: " + id));
     }
 
+    public List<AppUser> findAllById(Collection<UUID> ids) {
+        return userRepository.findAllById(ids);
+    }
+
+    @Transactional
+    public AppUser updateNotificationPreferences(UUID userId, boolean notifyOnReply, boolean notifyOnMention) {
+        AppUser user = getById(userId);
+        user.setNotifyOnReply(notifyOnReply);
+        user.setNotifyOnMention(notifyOnMention);
+        return userRepository.save(user);
+    }
+
     @Transactional
     public AppUser updateProfile(UUID userId, UpdateProfileDTO dto) {
         AppUser user = getById(userId);

backend/src/main/resources/db/migration/V16__notifications_and_preferences.sql

@@ -0,0 +1,18 @@
+-- Notification preferences on the user record — no separate entity needed
+ALTER TABLE users ADD COLUMN notify_on_reply   BOOLEAN NOT NULL DEFAULT false;
+ALTER TABLE users ADD COLUMN notify_on_mention BOOLEAN NOT NULL DEFAULT false;
+
+-- In-app notifications
+CREATE TABLE notifications (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    recipient_id  UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    type          VARCHAR(32) NOT NULL,  -- 'REPLY' | 'MENTION'
+    document_id   UUID,
+    reference_id  UUID,                  -- commentId that triggered this notification
+    annotation_id UUID,
+    read          BOOLEAN NOT NULL DEFAULT false,
+    created_at    TIMESTAMP NOT NULL DEFAULT now(),
+    actor_name    VARCHAR(255)
+);
+
+CREATE INDEX idx_notifications_recipient ON notifications(recipient_id, read, created_at DESC);

backend/src/main/resources/db/migration/V17__comment_mentions.sql

@@ -0,0 +1,5 @@
+CREATE TABLE comment_mentions (
+    comment_id UUID NOT NULL REFERENCES document_comments(id) ON DELETE CASCADE,
+    user_id    UUID NOT NULL REFERENCES users(id)             ON DELETE CASCADE,
+    PRIMARY KEY (comment_id, user_id)
+);

backend/src/test/java/org/raddatz/familienarchiv/ApplicationContextTest.java

@@ -0,0 +1,25 @@
+package org.raddatz.familienarchiv;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.annotation.Import;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.testcontainers.containers.PostgreSQLContainer;
+import software.amazon.awssdk.services.s3.S3Client;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@ActiveProfiles("test")
+@Import(PostgresContainerConfig.class)
+class ApplicationContextTest {
+
+    @MockitoBean
+    S3Client s3Client;
+
+    @Test
+    void contextLoads() {
+        // verifies that the Spring context starts successfully with all beans wired,
+        // Flyway migrations applied, and no configuration errors
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/PostgresContainerConfig.java

@@ -0,0 +1,16 @@
+package org.raddatz.familienarchiv;
+
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.annotation.Bean;
+import org.testcontainers.containers.PostgreSQLContainer;
+
+@TestConfiguration(proxyBeanMethods = false)
+public class PostgresContainerConfig {
+
+    @Bean
+    @ServiceConnection
+    PostgreSQLContainer<?> postgresContainer() {
+        return new PostgreSQLContainer<>("postgres:16-alpine");
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/AnnotationControllerTest.java

@@ -81,6 +81,29 @@ class AnnotationControllerTest {
                 .andExpect(status().isForbidden());
     }
 
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createAnnotation_returns201_whenHasWriteAllPermission() throws Exception {
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation saved = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.1).y(0.1).width(0.2).height(0.2).color("#ff0000").build();
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + docId + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void deleteAnnotation_returns204_whenHasWriteAllPermission() throws Exception {
+        mockMvc.perform(delete("/api/documents/" + UUID.randomUUID() + "/annotations/" + UUID.randomUUID()))
+                .andExpect(status().isNoContent());
+    }
+
     @Test
     @WithMockUser(authorities = "ANNOTATE_ALL")
     void createAnnotation_returns201_whenHasAnnotatePermission() throws Exception {
@@ -132,4 +155,51 @@ class AnnotationControllerTest {
         mockMvc.perform(delete("/api/documents/" + UUID.randomUUID() + "/annotations/" + UUID.randomUUID()))
                 .andExpect(status().isNoContent());
     }
+
+    // ─── resolveUserId — unauthenticated / null user / exception branches ─────
+
+    @Test
+    void createAnnotation_returns401_whenUnauthenticated_resolveUserIdReturnsNull() throws Exception {
+        // authentication == null → resolveUserId returns null
+        mockMvc.perform(post("/api/documents/" + UUID.randomUUID() + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void createAnnotation_resolvesNullUserId_whenUserServiceThrows() throws Exception {
+        // findByUsername throws → catch block → resolveUserId returns null
+        UUID docId = UUID.randomUUID();
+        when(userService.findByUsername(any())).thenThrow(new RuntimeException("DB error"));
+        DocumentAnnotation saved = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.1).y(0.1).width(0.2).height(0.2).color("#ff0000").build();
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + docId + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void createAnnotation_resolvesNullUserId_whenUserServiceReturnsNull() throws Exception {
+        // findByUsername returns null → user != null = false → resolveUserId returns null
+        UUID docId = UUID.randomUUID();
+        when(userService.findByUsername(any())).thenReturn(null);
+        DocumentAnnotation saved = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.1).y(0.1).width(0.2).height(0.2).color("#ff0000").build();
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + docId + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isCreated());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/controller/CommentControllerTest.java

@@ -81,7 +81,7 @@ class CommentControllerTest {
     void postDocumentComment_returns201_whenHasPermission() throws Exception {
         DocumentComment saved = DocumentComment.builder()
                 .id(COMMENT_ID).documentId(DOC_ID).authorName("Hans").content("Test comment").build();
-        when(commentService.postComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
@@ -89,6 +89,18 @@ class CommentControllerTest {
                 .andExpect(jsonPath("$.content").value("Test comment"));
     }
 
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void postDocumentComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(COMMENT_ID).documentId(DOC_ID).authorName("Hans").content("Test comment").build();
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
     // ─── POST /api/documents/{documentId}/comments/{commentId}/replies ────────
 
     @Test
@@ -104,7 +116,20 @@ class CommentControllerTest {
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(DOC_ID).parentId(COMMENT_ID)
                 .authorName("Anna").content("Test comment").build();
-        when(commentService.replyToComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID + "/replies")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void replyToComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).parentId(COMMENT_ID)
+                .authorName("Anna").content("Test comment").build();
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID + "/replies")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
@@ -163,6 +188,18 @@ class CommentControllerTest {
                 .andExpect(status().isOk());
     }
 
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void editComment_returns200_whenHasWriteAllPermission() throws Exception {
+        DocumentComment updated = DocumentComment.builder()
+                .id(COMMENT_ID).documentId(DOC_ID).authorName("Hans").content("Test comment").build();
+        when(commentService.editComment(any(), any(), any(), any())).thenReturn(updated);
+
+        mockMvc.perform(patch("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID)
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isOk());
+    }
+
     // ─── POST /api/documents/{documentId}/annotations/{annId}/comments ────────
 
     @Test
@@ -179,7 +216,20 @@ class CommentControllerTest {
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
                 .authorName("Hans").content("Test comment").build();
-        when(commentService.postComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void postAnnotationComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
+                .authorName("Hans").content("Test comment").build();
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
@@ -194,10 +244,39 @@ class CommentControllerTest {
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
                 .parentId(COMMENT_ID).authorName("Anna").content("Test comment").build();
-        when(commentService.replyToComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments/" + COMMENT_ID + "/replies")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
                 .andExpect(status().isCreated());
     }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void replyToAnnotationComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
+                .parentId(COMMENT_ID).authorName("Anna").content("Test comment").build();
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments/" + COMMENT_ID + "/replies")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    // ─── resolveUser — exception branch ──────────────────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void postDocumentComment_stillSucceeds_whenUserServiceThrows() throws Exception {
+        // findByUsername throws → catch block in resolveUser → author null, saves anyway
+        when(userService.findByUsername(any())).thenThrow(new RuntimeException("DB error"));
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).content("Test comment").build();
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/controller/DocumentControllerTest.java

@@ -2,7 +2,9 @@ package org.raddatz.familienarchiv.controller;
 
 import org.junit.jupiter.api.Test;
 import org.raddatz.familienarchiv.dto.DocumentVersionSummary;
+import org.raddatz.familienarchiv.dto.IncompleteDocumentDTO;
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.DocumentVersion;
 import org.raddatz.familienarchiv.security.PermissionAspect;
 import org.raddatz.familienarchiv.service.CustomUserDetailsService;
@@ -25,6 +27,9 @@ import java.util.Optional;
 import java.util.UUID;
 
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.multipart;
@@ -53,13 +58,32 @@ class DocumentControllerTest {
     @Test
     @WithMockUser
     void search_returns200_whenAuthenticated() throws Exception {
-        when(documentService.searchDocuments(any(), any(), any(), any(), any(), any()))
+        when(documentService.searchDocuments(any(), any(), any(), any(), any(), any(), any()))
                 .thenReturn(Collections.emptyList());
 
         mockMvc.perform(get("/api/documents/search"))
                 .andExpect(status().isOk());
     }
 
+    @Test
+    @WithMockUser
+    void search_withStatusParam_passesItToService() throws Exception {
+        when(documentService.searchDocuments(any(), any(), any(), any(), any(), any(), eq(DocumentStatus.REVIEWED)))
+                .thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/documents/search").param("status", "REVIEWED"))
+                .andExpect(status().isOk());
+
+        verify(documentService).searchDocuments(any(), any(), any(), any(), any(), any(), eq(DocumentStatus.REVIEWED));
+    }
+
+    @Test
+    @WithMockUser
+    void search_withInvalidStatus_returns400() throws Exception {
+        mockMvc.perform(get("/api/documents/search").param("status", "INVALID"))
+                .andExpect(status().isBadRequest());
+    }
+
     // ─── POST /api/documents ─────────────────────────────────────────────────
 
     @Test
@@ -213,6 +237,80 @@ class DocumentControllerTest {
                 .andExpect(jsonPath("$.errors[0].code").value("UNSUPPORTED_FILE_TYPE"));
     }
 
+    // ─── GET /api/documents/{id}/file ────────────────────────────────────────
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns404_whenDocHasNoFilePath() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief").build(); // filePath == null
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isNotFound());
+    }
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns200_withContentTypeFromDoc() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief")
+                .filePath("docs/brief.pdf").contentType("application/pdf")
+                .originalFilename("brief.pdf").build();
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+        java.io.InputStream stream = new java.io.ByteArrayInputStream(new byte[]{1, 2, 3});
+        when(fileService.downloadFile("docs/brief.pdf"))
+                .thenReturn(new FileService.S3FileDownload(
+                        new org.springframework.core.io.InputStreamResource(stream), "application/octet-stream"));
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns200_withContentTypeFromStorage_whenDocContentTypeIsBlank() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief")
+                .filePath("docs/brief.pdf").contentType("  ") // blank → falls back to storage type
+                .originalFilename("brief.pdf").build();
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+        java.io.InputStream stream = new java.io.ByteArrayInputStream(new byte[]{1, 2, 3});
+        when(fileService.downloadFile("docs/brief.pdf"))
+                .thenReturn(new FileService.S3FileDownload(
+                        new org.springframework.core.io.InputStreamResource(stream), "application/pdf"));
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns404_whenStorageFileNotFound() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief")
+                .filePath("docs/missing.pdf").contentType("application/pdf")
+                .originalFilename("missing.pdf").build();
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+        when(fileService.downloadFile("docs/missing.pdf"))
+                .thenThrow(new FileService.StorageFileNotFoundException("not found"));
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isNotFound());
+    }
+
+    // ─── POST /api/documents/quick-upload — null/empty files ─────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_returnsEmptyResult_whenNoFilesPartProvided() throws Exception {
+        mockMvc.perform(multipart("/api/documents/quick-upload"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created").isEmpty())
+                .andExpect(jsonPath("$.updated").isEmpty())
+                .andExpect(jsonPath("$.errors").isEmpty());
+    }
+
     // ─── GET /api/documents/incomplete-count ─────────────────────────────────
 
     @Test
@@ -241,16 +339,39 @@ class DocumentControllerTest {
 
     @Test
     @WithMockUser
-    void getIncomplete_returns200_withList() throws Exception {
-        Document doc = Document.builder()
-                .id(UUID.randomUUID()).title("Unvollständig").originalFilename("scan.pdf").build();
-        when(documentService.findIncompleteDocuments()).thenReturn(List.of(doc));
+    void getIncomplete_returns200_withDTOList() throws Exception {
+        UUID id = UUID.randomUUID();
+        IncompleteDocumentDTO dto = new IncompleteDocumentDTO(id, "Unvollständig");
+        when(documentService.findIncompleteDocuments(anyInt())).thenReturn(List.of(dto));
 
         mockMvc.perform(get("/api/documents/incomplete"))
                 .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].id").value(id.toString()))
                 .andExpect(jsonPath("$[0].title").value("Unvollständig"));
     }
 
+    @Test
+    @WithMockUser
+    void getIncomplete_withSizeParam_passesItToService() throws Exception {
+        when(documentService.findIncompleteDocuments(5)).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/documents/incomplete").param("size", "5"))
+                .andExpect(status().isOk());
+
+        verify(documentService).findIncompleteDocuments(5);
+    }
+
+    @Test
+    @WithMockUser
+    void getIncomplete_usesDefaultSizeWhenNotSpecified() throws Exception {
+        when(documentService.findIncompleteDocuments(anyInt())).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/documents/incomplete"))
+                .andExpect(status().isOk());
+
+        verify(documentService).findIncompleteDocuments(10);
+    }
+
     // ─── GET /api/documents/incomplete/next ──────────────────────────────────
 
     @Test

backend/src/test/java/org/raddatz/familienarchiv/controller/NotificationControllerTest.java

@@ -0,0 +1,329 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.dto.NotificationDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.NotificationService;
+import org.raddatz.familienarchiv.service.SseEmitterRegistry;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.http.MediaType;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.UUID;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.springframework.http.MediaType.TEXT_EVENT_STREAM_VALUE;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@WebMvcTest(NotificationController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class NotificationControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean NotificationService notificationService;
+    @MockitoBean UserService userService;
+    @MockitoBean SseEmitterRegistry sseEmitterRegistry;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    private static final UUID USER_ID = UUID.randomUUID();
+
+    // ─── GET /api/notifications ───────────────────────────────────────────────
+
+    @Test
+    void getNotifications_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser")
+    void getNotifications_returns200_whenAuthenticatedWithNoPermissions() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_returns200WithList_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        NotificationDTO dto = new NotificationDTO(
+                UUID.randomUUID(), NotificationType.REPLY, UUID.randomUUID(),
+                UUID.randomUUID(), null, false, LocalDateTime.now(), "Anna Smith");
+
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of(dto), PageRequest.of(0, 10), 1));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.content").isArray());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_returnsOnlyCurrentUsersNotifications() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk());
+
+        verify(notificationService).getNotifications(eq(USER_ID), any(), any(), any());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_withTypeAndReadFalse_passesFiltersToService() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), eq(NotificationType.MENTION), eq(false), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications")
+                        .param("type", "MENTION")
+                        .param("read", "false"))
+                .andExpect(status().isOk());
+
+        verify(notificationService).getNotifications(eq(USER_ID), eq(NotificationType.MENTION), eq(false), any());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_withInvalidType_returns400() throws Exception {
+        mockMvc.perform(get("/api/notifications").param("type", "INVALID_TYPE"))
+                .andExpect(status().isBadRequest());
+    }
+
+    // ─── POST /api/notifications/read-all ────────────────────────────────────
+
+    @Test
+    void markAllRead_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/notifications/read-all"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void markAllRead_returns204_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(post("/api/notifications/read-all"))
+                .andExpect(status().isNoContent());
+
+        verify(notificationService).markAllRead(USER_ID);
+    }
+
+    // ─── PATCH /api/notifications/{id}/read ──────────────────────────────────
+
+    @Test
+    void markOneRead_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(patch("/api/notifications/" + UUID.randomUUID() + "/read"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void markOneRead_returns403_whenNotificationBelongsToDifferentUser() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        UUID notifId = UUID.randomUUID();
+
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        org.mockito.Mockito.doThrow(
+                org.raddatz.familienarchiv.exception.DomainException.forbidden("not yours"))
+                .when(notificationService).markRead(notifId, USER_ID);
+
+        mockMvc.perform(patch("/api/notifications/" + notifId + "/read"))
+                .andExpect(status().isForbidden());
+    }
+
+    // ─── GET /api/users/me/notification-preferences ──────────────────────────
+
+    @Test
+    void getPreferences_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser")
+    void getPreferences_returns403_whenUserHasNoPermission() throws Exception {
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getPreferences_returns200_whenUserHasReadAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(true).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnReply").value(true))
+                .andExpect(jsonPath("$.notifyOnMention").value(false));
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void getPreferences_returns200_whenUserHasWriteAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(true).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnMention").value(true));
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"ANNOTATE_ALL"})
+    void getPreferences_returns200_whenUserHasAnnotateAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void getNotifications_returns200_whenUserHasOnlyWriteAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk());
+    }
+
+    // ─── PUT /api/users/me/notification-preferences ──────────────────────────
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void updatePreferences_persistsBothBooleans() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        AppUser updated = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(true).notifyOnMention(true).build();
+        when(notificationService.updatePreferences(USER_ID, true, true)).thenReturn(updated);
+
+        mockMvc.perform(put("/api/users/me/notification-preferences")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"notifyOnReply\":true,\"notifyOnMention\":true}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnReply").value(true))
+                .andExpect(jsonPath("$.notifyOnMention").value(true));
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void updatePreferences_returns200_whenUserHasWriteAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        AppUser updated = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(true).notifyOnMention(false).build();
+        when(notificationService.updatePreferences(USER_ID, true, false)).thenReturn(updated);
+
+        mockMvc.perform(put("/api/users/me/notification-preferences")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"notifyOnReply\":true,\"notifyOnMention\":false}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnReply").value(true));
+    }
+
+    // ─── GET /api/notifications/unread-count ─────────────────────────────────
+
+    @Test
+    void countUnread_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/notifications/unread-count"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void countUnread_returns200WithCount_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.countUnread(USER_ID)).thenReturn(3L);
+
+        mockMvc.perform(get("/api/notifications/unread-count"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.count").value(3));
+    }
+
+    // ─── PATCH /api/notifications/{id}/read — additional cases ───────────────
+
+    // ─── GET /api/notifications/stream ───────────────────────────────────────
+
+    @Test
+    void stream_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/notifications/stream")
+                        .accept(TEXT_EVENT_STREAM_VALUE))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void stream_returns200_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(sseEmitterRegistry.register(USER_ID)).thenReturn(new org.springframework.web.servlet.mvc.method.annotation.SseEmitter());
+
+        mockMvc.perform(get("/api/notifications/stream")
+                        .accept(TEXT_EVENT_STREAM_VALUE))
+                .andExpect(status().isOk());
+    }
+
+    // ─── PATCH /api/notifications/{id}/read — additional cases ───────────────
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void markOneRead_returns404_whenNotificationDoesNotExist() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        UUID notifId = UUID.randomUUID();
+
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        doThrow(DomainException.notFound(ErrorCode.NOTIFICATION_NOT_FOUND, "Notification not found: " + notifId))
+                .when(notificationService).markRead(notifId, USER_ID);
+
+        mockMvc.perform(patch("/api/notifications/" + notifId + "/read"))
+                .andExpect(status().isNotFound());
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/PersonControllerTest.java

@@ -2,6 +2,7 @@ package org.raddatz.familienarchiv.controller;
 
 import org.junit.jupiter.api.Test;
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.Person;
 import org.raddatz.familienarchiv.security.PermissionAspect;
 import org.raddatz.familienarchiv.service.CustomUserDetailsService;
 import org.raddatz.familienarchiv.service.DocumentService;
@@ -11,15 +12,20 @@ import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
 import org.raddatz.familienarchiv.config.SecurityConfig;
 import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
 import org.springframework.context.annotation.Import;
+import org.springframework.http.MediaType;
 import org.springframework.security.test.context.support.WithMockUser;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.springframework.test.web.servlet.MockMvc;
 
 import java.util.Collections;
+import java.util.List;
 import java.util.UUID;
 
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.when;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 @WebMvcTest(PersonController.class)
@@ -32,6 +38,101 @@ class PersonControllerTest {
     @MockitoBean DocumentService documentService;
     @MockitoBean CustomUserDetailsService customUserDetailsService;
 
+    // ─── GET /api/persons ─────────────────────────────────────────────────────
+
+    @Test
+    void getPersons_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getPersons_returns200_withEmptyList() throws Exception {
+        when(personService.findAll(null)).thenReturn(Collections.emptyList());
+        mockMvc.perform(get("/api/persons"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getPersons_delegatesQueryParam_toService() throws Exception {
+        Person person = Person.builder().id(UUID.randomUUID()).firstName("Hans").lastName("Müller").build();
+        when(personService.findAll("Hans")).thenReturn(List.of(person));
+
+        mockMvc.perform(get("/api/persons").param("q", "Hans"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].firstName").value("Hans"));
+    }
+
+    // ─── GET /api/persons/{id} ────────────────────────────────────────────────
+
+    @Test
+    void getPerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons/{id}", UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getPerson_returns200_whenFound() throws Exception {
+        UUID id = UUID.randomUUID();
+        Person person = Person.builder().id(id).firstName("Anna").lastName("Schmidt").build();
+        when(personService.getById(id)).thenReturn(person);
+
+        mockMvc.perform(get("/api/persons/{id}", id))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.firstName").value("Anna"));
+    }
+
+    // ─── GET /api/persons/{id}/correspondents ─────────────────────────────────
+
+    @Test
+    void getCorrespondents_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons/{id}/correspondents", UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getCorrespondents_returns200_withoutFilter() throws Exception {
+        UUID personId = UUID.randomUUID();
+        when(personService.findCorrespondents(personId, null)).thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/persons/{id}/correspondents", personId))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getCorrespondents_returns200_withFilter() throws Exception {
+        UUID personId = UUID.randomUUID();
+        Person correspondent = Person.builder().id(UUID.randomUUID()).firstName("Walter").lastName("Gruyter").build();
+        when(personService.findCorrespondents(personId, "Walter")).thenReturn(List.of(correspondent));
+
+        mockMvc.perform(get("/api/persons/{id}/correspondents", personId).param("q", "Walter"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].firstName").value("Walter"));
+    }
+
+    // ─── GET /api/persons/{id}/documents ──────────────────────────────────────
+
+    @Test
+    void getPersonDocuments_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons/{id}/documents", UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getPersonDocuments_returns200_whenAuthenticated() throws Exception {
+        UUID personId = UUID.randomUUID();
+        when(documentService.getDocumentsBySender(personId)).thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/persons/{id}/documents", personId))
+                .andExpect(status().isOk());
+    }
+
     // ─── GET /api/persons/{id}/received-documents ─────────────────────────────
 
     @Test
@@ -49,4 +150,158 @@ class PersonControllerTest {
         mockMvc.perform(get("/api/persons/{id}/received-documents", personId))
                 .andExpect(status().isOk());
     }
+
+    // ─── POST /api/persons ────────────────────────────────────────────────────
+
+    @Test
+    void createPerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void createPerson_returns400_whenFirstNameIsMissing() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"lastName\":\"Müller\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void createPerson_returns400_whenFirstNameIsBlank() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"  \",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void createPerson_returns400_whenLastNameIsMissing() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void createPerson_returns400_whenLastNameIsBlank() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"  \"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void createPerson_returns200_whenValid() throws Exception {
+        Person saved = Person.builder().id(UUID.randomUUID()).firstName("Hans").lastName("Müller").build();
+        when(personService.createPerson(eq("Hans"), eq("Müller"), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.firstName").value("Hans"));
+    }
+
+    // ─── PUT /api/persons/{id} ────────────────────────────────────────────────
+
+    @Test
+    void updatePerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void updatePerson_returns400_whenFirstNameIsBlank() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void updatePerson_returns400_whenLastNameIsNull() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void updatePerson_returns200_whenValid() throws Exception {
+        UUID id = UUID.randomUUID();
+        Person updated = Person.builder().id(id).firstName("Hans").lastName("Müller").build();
+        when(personService.updatePerson(eq(id), any())).thenReturn(updated);
+
+        mockMvc.perform(put("/api/persons/{id}", id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.lastName").value("Müller"));
+    }
+
+    // ─── POST /api/persons/{id}/merge ─────────────────────────────────────────
+
+    @Test
+    void mergePerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/merge", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetPersonId\":\"" + UUID.randomUUID() + "\"}"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void mergePerson_returns400_whenTargetPersonIdIsMissing() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/merge", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void mergePerson_returns400_whenTargetPersonIdIsBlank() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/merge", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetPersonId\":\"  \"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void mergePerson_returns204_whenValid() throws Exception {
+        UUID sourceId = UUID.randomUUID();
+        UUID targetId = UUID.randomUUID();
+
+        mockMvc.perform(post("/api/persons/{id}/merge", sourceId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetPersonId\":\"" + targetId + "\"}"))
+                .andExpect(status().isNoContent());
+    }
+
+    // ─── PUT /api/persons/{id} — lastName blank branch ────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updatePerson_returns400_whenLastNameIsBlank() throws Exception {
+        // firstName valid, lastName blank → second || operand = true → 400
+        UUID id = UUID.randomUUID();
+        mockMvc.perform(put("/api/persons/{id}", id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"   \"}"))
+                .andExpect(status().isBadRequest());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/controller/UserControllerTest.java

@@ -0,0 +1,53 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.UUID;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(UserController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class UserControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean UserService userService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    // ─── GET /api/users/me ────────────────────────────────────────────────────
+
+    @Test
+    void getCurrentUser_returns401_whenUnauthenticated() throws Exception {
+        // authentication == null → returns 401 (covers null/!isAuthenticated branch)
+        mockMvc.perform(get("/api/users/me"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "anna")
+    void getCurrentUser_returns200_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+        when(userService.findByUsername("anna")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.username").value("anna"));
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/UserSearchControllerTest.java

@@ -0,0 +1,94 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.UserSearchService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+import java.util.UUID;
+import java.util.stream.IntStream;
+
+import static org.hamcrest.Matchers.lessThanOrEqualTo;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(UserSearchController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class UserSearchControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean UserSearchService userSearchService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    @Test
+    void search_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void search_returns403_whenUserLacksPermission() throws Exception {
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = {"ANNOTATE_ALL"})
+    void search_returns200_whenUserHasAnnotateAll() throws Exception {
+        when(userSearchService.search("Hans")).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser(authorities = {"READ_ALL"})
+    void search_returns200_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .firstName("Hans").lastName("Mueller").username("hans").build();
+        when(userSearchService.search("Hans")).thenReturn(List.of(user));
+
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].firstName").value("Hans"));
+    }
+
+    @Test
+    @WithMockUser(authorities = {"READ_ALL"})
+    void search_returnsEmptyList_whenQueryIsEmpty() throws Exception {
+        when(userSearchService.search("")).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/users/search").param("q", ""))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$").isEmpty());
+    }
+
+    @Test
+    @WithMockUser(authorities = {"READ_ALL"})
+    void search_returnsAtMostTenResults() throws Exception {
+        List<AppUser> elevenUsers = IntStream.range(0, 11)
+                .mapToObj(i -> AppUser.builder().id(UUID.randomUUID())
+                        .firstName("User").lastName(String.valueOf(i)).username("u" + i).build())
+                .toList();
+        when(userSearchService.search(anyString())).thenReturn(elevenUsers.subList(0, 10));
+
+        mockMvc.perform(get("/api/users/search").param("q", "a"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.length()").value(lessThanOrEqualTo(10)));
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/DocumentRepositoryTest.java

@@ -0,0 +1,175 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+
+import java.util.List;
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class DocumentRepositoryTest {
+
+    @Autowired
+    private DocumentRepository documentRepository;
+
+    @Autowired
+    private PersonRepository personRepository;
+
+    // ─── save and findById ────────────────────────────────────────────────────
+
+    @Test
+    void save_persistsDocument_andFindByIdReturnsSameDocument() {
+        Document document = Document.builder()
+                .title("Testbrief")
+                .originalFilename("testbrief.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build();
+
+        Document saved = documentRepository.save(document);
+        Optional<Document> found = documentRepository.findById(saved.getId());
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getTitle()).isEqualTo("Testbrief");
+        assertThat(found.get().getStatus()).isEqualTo(DocumentStatus.PLACEHOLDER);
+    }
+
+    // ─── findByStatus ─────────────────────────────────────────────────────────
+
+    @Test
+    void findByStatus_returnsOnlyDocumentsWithMatchingStatus() {
+        documentRepository.save(Document.builder()
+                .title("Placeholder Doc")
+                .originalFilename("placeholder.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+        documentRepository.save(Document.builder()
+                .title("Uploaded Doc")
+                .originalFilename("uploaded.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .build());
+
+        List<Document> placeholders = documentRepository.findByStatus(DocumentStatus.PLACEHOLDER);
+
+        assertThat(placeholders).extracting(Document::getStatus)
+                .containsOnly(DocumentStatus.PLACEHOLDER);
+    }
+
+    // ─── findByOriginalFilename ───────────────────────────────────────────────
+
+    @Test
+    void findByOriginalFilename_returnsDocument_whenFilenameMatches() {
+        documentRepository.save(Document.builder()
+                .title("Omas Brief")
+                .originalFilename("omas_brief.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+
+        Optional<Document> found = documentRepository.findByOriginalFilename("omas_brief.pdf");
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getTitle()).isEqualTo("Omas Brief");
+    }
+
+    @Test
+    void findByOriginalFilename_returnsEmpty_whenFilenameDoesNotExist() {
+        Optional<Document> found = documentRepository.findByOriginalFilename("does_not_exist.pdf");
+
+        assertThat(found).isEmpty();
+    }
+
+    // ─── existsByOriginalFilename ─────────────────────────────────────────────
+
+    @Test
+    void existsByOriginalFilename_returnsTrue_whenDocumentExists() {
+        documentRepository.save(Document.builder()
+                .title("Brief")
+                .originalFilename("brief.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+
+        assertThat(documentRepository.existsByOriginalFilename("brief.pdf")).isTrue();
+    }
+
+    @Test
+    void existsByOriginalFilename_returnsFalse_whenDocumentDoesNotExist() {
+        assertThat(documentRepository.existsByOriginalFilename("nonexistent.pdf")).isFalse();
+    }
+
+    // ─── findBySenderId ───────────────────────────────────────────────────────
+
+    @Test
+    void findBySenderId_returnsDocuments_whereSenderIdMatches() {
+        Person sender = personRepository.save(Person.builder()
+                .firstName("Hans")
+                .lastName("Müller")
+                .build());
+        documentRepository.save(Document.builder()
+                .title("Brief von Hans")
+                .originalFilename("brief_hans.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender)
+                .build());
+
+        List<Document> docs = documentRepository.findBySenderId(sender.getId());
+
+        assertThat(docs).hasSize(1);
+        assertThat(docs.get(0).getSender().getId()).isEqualTo(sender.getId());
+    }
+
+    // ─── countByMetadataCompleteFalse ─────────────────────────────────────────
+
+    @Test
+    void countByMetadataCompleteFalse_returnsNumberOfIncompleteDocuments() {
+        documentRepository.save(Document.builder()
+                .title("Incomplete")
+                .originalFilename("incomplete.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .metadataComplete(false)
+                .build());
+        documentRepository.save(Document.builder()
+                .title("Complete")
+                .originalFilename("complete.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .metadataComplete(true)
+                .build());
+
+        assertThat(documentRepository.countByMetadataCompleteFalse()).isEqualTo(1);
+    }
+
+    // ─── findByMetadataCompleteFalse (Pageable) ───────────────────────────────
+
+    @Test
+    void findByMetadataCompleteFalse_withPageable_returnsOnlyIncompleteAndRespectsSizeCap() {
+        for (int i = 0; i < 5; i++) {
+            documentRepository.save(Document.builder()
+                    .title("Incomplete " + i).originalFilename("inc" + i + ".pdf")
+                    .status(DocumentStatus.UPLOADED).metadataComplete(false).build());
+        }
+        documentRepository.save(Document.builder()
+                .title("Complete").originalFilename("complete.pdf")
+                .status(DocumentStatus.REVIEWED).metadataComplete(true).build());
+
+        Page<Document> result = documentRepository.findByMetadataCompleteFalse(
+                PageRequest.of(0, 3, Sort.by(Sort.Direction.DESC, "createdAt")));
+
+        assertThat(result.getContent()).hasSize(3);
+        assertThat(result.getTotalElements()).isEqualTo(5);
+        assertThat(result.getContent()).allMatch(d -> !d.isMetadataComplete());
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/DocumentSpecificationsTest.java

@@ -0,0 +1,272 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.Tag;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.jpa.domain.Specification;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.raddatz.familienarchiv.repository.DocumentSpecifications.*;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class DocumentSpecificationsTest {
+
+    @Autowired DocumentRepository documentRepository;
+    @Autowired PersonRepository personRepository;
+    @Autowired TagRepository tagRepository;
+
+    private Person sender;
+    private Person receiver;
+    private Document briefEarly;
+    private Document briefLate;
+    private Document photoDoc;
+
+    @BeforeEach
+    void setUp() {
+        documentRepository.deleteAll();
+        personRepository.deleteAll();
+        tagRepository.deleteAll();
+
+        sender   = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        receiver = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        Tag tagFamilie = tagRepository.save(Tag.builder().name("Familie").build());
+        Tag tagUrlaub  = tagRepository.save(Tag.builder().name("Urlaub").build());
+
+        briefEarly = documentRepository.save(Document.builder()
+                .title("Alter Brief")
+                .originalFilename("brief_early.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .documentDate(LocalDate.of(1940, 5, 1))
+                .transcription("Liebe Anna, ich schreibe dir aus dem Krieg")
+                .location("Berlin")
+                .sender(sender)
+                .receivers(Set.of(receiver))
+                .tags(Set.of(tagFamilie))
+                .build());
+
+        briefLate = documentRepository.save(Document.builder()
+                .title("Neuerer Brief")
+                .originalFilename("brief_late.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .documentDate(LocalDate.of(1960, 8, 15))
+                .sender(sender)
+                .tags(Set.of(tagUrlaub))
+                .build());
+
+        photoDoc = documentRepository.save(Document.builder()
+                .title("Familienfoto")
+                .originalFilename("familienfoto.jpg")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+    }
+
+    // ─── hasText ──────────────────────────────────────────────────────────────
+
+    @Test
+    void hasText_returnsAllDocuments_whenTextIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasText_returnsAllDocuments_whenTextIsBlank() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("   ")));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasText_filtersOnTitle() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("familienfoto")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Familienfoto");
+    }
+
+    @Test
+    void hasText_filtersOnOriginalFilename() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("brief_late")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Neuerer Brief");
+    }
+
+    @Test
+    void hasText_filtersOnTranscription() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("schreibe dir")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasText_filtersOnLocation() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("berlin")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasText_isCaseInsensitive() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("BRIEF")));
+        assertThat(result).extracting(Document::getTitle).containsExactlyInAnyOrder("Alter Brief", "Neuerer Brief");
+    }
+
+    @Test
+    void hasText_returnsEmpty_whenNoMatch() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("xyznotexist")));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasSender ────────────────────────────────────────────────────────────
+
+    @Test
+    void hasSender_returnsAllDocuments_whenPersonIdIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasSender(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasSender_filtersDocumentsBySender() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasSender(sender.getId())));
+        assertThat(result).extracting(Document::getTitle)
+                .containsExactlyInAnyOrder("Alter Brief", "Neuerer Brief");
+    }
+
+    @Test
+    void hasSender_returnsEmpty_whenSenderHasNoDocuments() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasSender(receiver.getId())));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasReceiver ──────────────────────────────────────────────────────────
+
+    @Test
+    void hasReceiver_returnsAllDocuments_whenPersonIdIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasReceiver(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasReceiver_filtersDocumentsByReceiver() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasReceiver(receiver.getId())));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasReceiver_returnsEmpty_whenReceiverHasNoDocuments() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasReceiver(sender.getId())));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── isBetween ────────────────────────────────────────────────────────────
+
+    @Test
+    void isBetween_returnsAllDocuments_whenBothDatesAreNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(isBetween(null, null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void isBetween_filtersByBothDates() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(LocalDate.of(1939, 1, 1), LocalDate.of(1945, 12, 31))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void isBetween_filtersByStartDateOnly() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(LocalDate.of(1950, 1, 1), null)));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Neuerer Brief");
+    }
+
+    @Test
+    void isBetween_filtersByEndDateOnly() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(null, LocalDate.of(1945, 12, 31))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void isBetween_returnsEmpty_whenNoDatesInRange() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(LocalDate.of(1970, 1, 1), LocalDate.of(1980, 12, 31))));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasTags ──────────────────────────────────────────────────────────────
+
+    @Test
+    void hasTags_returnsAllDocuments_whenTagListIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasTags_returnsAllDocuments_whenTagListIsEmpty() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of())));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasTags_filtersDocumentsByTag() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("Familie"))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasTags_isCaseInsensitive() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("familie"))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasTags_requiresAllTagsToBePresent_andLogic() {
+        // briefEarly has "Familie" but not "Urlaub" — should be excluded
+        List<Document> result = documentRepository.findAll(
+                Specification.where(hasTags(List.of("Familie", "Urlaub"))));
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void hasTags_skipsEmptyTagNames() {
+        // An empty string in the tag list should be ignored
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("  ", "Familie"))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasTags_returnsEmpty_whenTagDoesNotExist() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("Unbekannt"))));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasStatus ────────────────────────────────────────────────────────────
+
+    @Test
+    void hasStatus_returnsAllDocuments_whenStatusIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasStatus(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasStatus_returnsOnlyMatchingDocuments_whenStatusIsSet() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasStatus(DocumentStatus.PLACEHOLDER)));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Familienfoto");
+    }
+
+    @Test
+    void hasStatus_returnsEmpty_whenNoDocumentMatchesStatus() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasStatus(DocumentStatus.REVIEWED)));
+        assertThat(result).isEmpty();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/NotificationRepositoryTest.java

@@ -0,0 +1,119 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.Notification;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class NotificationRepositoryTest {
+
+    @Autowired NotificationRepository notificationRepository;
+    @Autowired AppUserRepository appUserRepository;
+
+    private AppUser userA;
+    private AppUser userB;
+
+    @BeforeEach
+    void setUp() {
+        notificationRepository.deleteAll();
+        appUserRepository.deleteAll();
+        userA = appUserRepository.save(AppUser.builder().username("userA").password("pw").build());
+        userB = appUserRepository.save(AppUser.builder().username("userB").password("pw").build());
+    }
+
+    // ─── findByRecipientIdAndTypeAndReadFalse ─────────────────────────────────
+
+    @Test
+    void returnsOnlyUnreadMentions_forTargetUser() {
+        notificationRepository.save(mention(userA, false)); // ✓ match
+        notificationRepository.save(mention(userA, true));  // read — excluded
+        notificationRepository.save(reply(userA, false));   // REPLY — excluded
+        notificationRepository.save(mention(userB, false)); // different user — excluded
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(10));
+
+        assertThat(result.getContent()).hasSize(1);
+        assertThat(result.getContent().get(0).getRecipient().getId()).isEqualTo(userA.getId());
+        assertThat(result.getContent().get(0).getType()).isEqualTo(NotificationType.MENTION);
+        assertThat(result.getContent().get(0).isRead()).isFalse();
+    }
+
+    @Test
+    void returnsEmpty_whenAllMentionsAreRead() {
+        notificationRepository.save(mention(userA, true));
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(10));
+
+        assertThat(result.getContent()).isEmpty();
+    }
+
+    @Test
+    void respectsSizeLimit() {
+        for (int i = 0; i < 5; i++) {
+            notificationRepository.save(mention(userA, false));
+        }
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(3));
+
+        assertThat(result.getContent()).hasSize(3);
+        assertThat(result.getTotalElements()).isEqualTo(5);
+    }
+
+    // ─── findByRecipientIdAndType (without read filter) ──────────────────────
+
+    @Test
+    void findByType_returnsBothReadAndUnreadMentions() {
+        notificationRepository.save(mention(userA, false)); // unread
+        notificationRepository.save(mention(userA, true));  // read — should also be included
+        notificationRepository.save(reply(userA, false));   // REPLY — excluded
+        notificationRepository.save(mention(userB, false)); // different user — excluded
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(10));
+
+        assertThat(result.getContent()).hasSize(2);
+        assertThat(result.getContent()).allMatch(n -> n.getType() == NotificationType.MENTION);
+        assertThat(result.getContent()).allMatch(n -> n.getRecipient().getId().equals(userA.getId()));
+    }
+
+    // ─── helpers ─────────────────────────────────────────────────────────────
+
+    private Notification mention(AppUser recipient, boolean read) {
+        return Notification.builder()
+                .recipient(recipient)
+                .type(NotificationType.MENTION)
+                .actorName("Tester")
+                .read(read)
+                .build();
+    }
+
+    private Notification reply(AppUser recipient, boolean read) {
+        return Notification.builder()
+                .recipient(recipient)
+                .type(NotificationType.REPLY)
+                .actorName("Tester")
+                .read(read)
+                .build();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/PersonRepositoryTest.java

@@ -0,0 +1,314 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.PersistenceContext;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class PersonRepositoryTest {
+
+    @Autowired
+    private PersonRepository personRepository;
+
+    @Autowired
+    private DocumentRepository documentRepository;
+
+    @PersistenceContext
+    private EntityManager entityManager;
+
+    // ─── save and findById ────────────────────────────────────────────────────
+
+    @Test
+    void save_persistsPerson_andFindByIdReturnsSamePerson() {
+        Person person = Person.builder()
+                .firstName("Anna")
+                .lastName("Schmidt")
+                .build();
+
+        Person saved = personRepository.save(person);
+        Optional<Person> found = personRepository.findById(saved.getId());
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getFirstName()).isEqualTo("Anna");
+        assertThat(found.get().getLastName()).isEqualTo("Schmidt");
+    }
+
+    // ─── searchByName ─────────────────────────────────────────────────────────
+
+    @Test
+    void searchByName_findsByFirstName() {
+        personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+        personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        List<Person> results = personRepository.searchByName("Hans");
+
+        assertThat(results).hasSize(1);
+        assertThat(results.get(0).getFirstName()).isEqualTo("Hans");
+    }
+
+    @Test
+    void searchByName_findsByLastName() {
+        personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+        personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        List<Person> results = personRepository.searchByName("Schmidt");
+
+        assertThat(results).hasSize(1);
+        assertThat(results.get(0).getLastName()).isEqualTo("Schmidt");
+    }
+
+    @Test
+    void searchByName_isCaseInsensitive() {
+        personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+
+        List<Person> results = personRepository.searchByName("hans");
+
+        assertThat(results).hasSize(1);
+    }
+
+    @Test
+    void searchByName_findsByAlias() {
+        personRepository.save(Person.builder()
+                .firstName("Hans").lastName("Müller").alias("Opa Hans").build());
+
+        List<Person> results = personRepository.searchByName("Opa Hans");
+
+        assertThat(results).hasSize(1);
+    }
+
+    // ─── findAllByOrderByLastNameAscFirstNameAsc ──────────────────────────────
+
+    @Test
+    void findAllByOrderByLastNameAscFirstNameAsc_returnsSortedByLastNameThenFirstName() {
+        personRepository.save(Person.builder().firstName("Bernd").lastName("Ziegler").build());
+        personRepository.save(Person.builder().firstName("Anna").lastName("Müller").build());
+        personRepository.save(Person.builder().firstName("Clara").lastName("Müller").build());
+
+        List<Person> sorted = personRepository.findAllByOrderByLastNameAscFirstNameAsc();
+
+        assertThat(sorted).extracting(Person::getLastName)
+                .startsWith("Müller", "Müller");
+        assertThat(sorted.stream()
+                .filter(p -> p.getLastName().equals("Müller"))
+                .map(Person::getFirstName)
+                .toList())
+                .containsExactly("Anna", "Clara");
+    }
+
+    // ─── findByAliasIgnoreCase ────────────────────────────────────────────────
+
+    @Test
+    void findByAliasIgnoreCase_returnsMatchingPerson() {
+        personRepository.save(Person.builder()
+                .firstName("Karl").lastName("Brandt").alias("Opa Karl").build());
+
+        Optional<Person> found = personRepository.findByAliasIgnoreCase("opa karl");
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getFirstName()).isEqualTo("Karl");
+    }
+
+    @Test
+    void findByAliasIgnoreCase_returnsEmpty_whenAliasDoesNotMatch() {
+        Optional<Person> found = personRepository.findByAliasIgnoreCase("nobody");
+
+        assertThat(found).isEmpty();
+    }
+
+    // ─── findByFirstNameIgnoreCaseAndLastNameIgnoreCase ───────────────────────
+
+    @Test
+    void findByFirstNameIgnoreCaseAndLastNameIgnoreCase_returnsMatch() {
+        personRepository.save(Person.builder().firstName("Maria").lastName("Raddatz").build());
+
+        Optional<Person> found = personRepository.findByFirstNameIgnoreCaseAndLastNameIgnoreCase(
+                "maria", "raddatz");
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getFirstName()).isEqualTo("Maria");
+    }
+
+    // ─── findCorrespondents ───────────────────────────────────────────────────
+
+    @Test
+    void findCorrespondents_returnsPersonsWhoSharedDocumentsWith() {
+        Person walter = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        Person anna   = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+        Person clara  = personRepository.save(Person.builder().firstName("Clara").lastName("Cram").build());
+
+        // Walter sends to Anna (1 document)
+        documentRepository.save(Document.builder()
+                .title("Brief 1").originalFilename("brief1.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+
+        // Walter sends to Clara (2 documents — Clara should rank higher)
+        documentRepository.save(Document.builder()
+                .title("Brief 2").originalFilename("brief2.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(clara)).build());
+        documentRepository.save(Document.builder()
+                .title("Brief 3").originalFilename("brief3.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(clara)).build());
+
+        List<Person> correspondents = personRepository.findCorrespondents(walter.getId());
+
+        assertThat(correspondents).extracting(Person::getFirstName)
+                .containsExactly("Clara", "Anna"); // Clara ranks first (2 documents)
+    }
+
+    @Test
+    void findCorrespondents_returnsEmpty_whenPersonHasNoDocuments() {
+        Person solo = personRepository.save(Person.builder().firstName("Solo").lastName("Mensch").build());
+
+        List<Person> correspondents = personRepository.findCorrespondents(solo.getId());
+
+        assertThat(correspondents).isEmpty();
+    }
+
+    // ─── findCorrespondentsWithFilter ─────────────────────────────────────────
+
+    @Test
+    void findCorrespondentsWithFilter_returnsOnlyMatchingCorrespondents() {
+        Person walter = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        Person anna   = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+        Person bernd  = personRepository.save(Person.builder().firstName("Bernd").lastName("Braun").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief an Anna").originalFilename("anna.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+        documentRepository.save(Document.builder()
+                .title("Brief an Bernd").originalFilename("bernd.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(bernd)).build());
+
+        List<Person> filtered = personRepository.findCorrespondentsWithFilter(walter.getId(), "Anna");
+
+        assertThat(filtered).extracting(Person::getFirstName).containsExactly("Anna");
+    }
+
+    @Test
+    void findCorrespondentsWithFilter_isCaseInsensitive() {
+        Person walter = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        Person anna   = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+
+        List<Person> filtered = personRepository.findCorrespondentsWithFilter(walter.getId(), "schmidt");
+
+        assertThat(filtered).hasSize(1);
+        assertThat(filtered.get(0).getLastName()).isEqualTo("Schmidt");
+    }
+
+    // ─── reassignSender ───────────────────────────────────────────────────────
+
+    @Test
+    void reassignSender_updatesDocumentsSenderFromSourceToTarget() {
+        Person source = personRepository.save(Person.builder().firstName("Alt").lastName("Person").build());
+        Person target = personRepository.save(Person.builder().firstName("Neu").lastName("Person").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(source).build());
+
+        personRepository.reassignSender(source.getId(), target.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        List<Document> docs = documentRepository.findBySenderId(target.getId());
+        assertThat(docs).hasSize(1);
+        assertThat(documentRepository.findBySenderId(source.getId())).isEmpty();
+    }
+
+    // ─── insertMissingReceiverReference ──────────────────────────────────────
+
+    @Test
+    void insertMissingReceiverReference_addsTargetWhereSourceWasReceiver() {
+        Person source = personRepository.save(Person.builder().firstName("Alt").lastName("Person").build());
+        Person target = personRepository.save(Person.builder().firstName("Neu").lastName("Person").build());
+        Person sender = personRepository.save(Person.builder().firstName("Send").lastName("Er").build());
+
+        Document doc = documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(source)).build());
+
+        personRepository.insertMissingReceiverReference(source.getId(), target.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        Document reloaded = documentRepository.findById(doc.getId()).orElseThrow();
+        assertThat(reloaded.getReceivers())
+                .extracting(Person::getId)
+                .contains(target.getId());
+    }
+
+    @Test
+    void insertMissingReceiverReference_doesNotCreateDuplicate_whenTargetAlreadyReceiver() {
+        Person source = personRepository.save(Person.builder().firstName("Alt").lastName("Person").build());
+        Person target = personRepository.save(Person.builder().firstName("Neu").lastName("Person").build());
+        Person sender = personRepository.save(Person.builder().firstName("Send").lastName("Er").build());
+
+        // target is already a receiver together with source
+        Document doc = documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(source, target)).build());
+
+        personRepository.insertMissingReceiverReference(source.getId(), target.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        Document reloaded = documentRepository.findById(doc.getId()).orElseThrow();
+        long targetCount = reloaded.getReceivers().stream()
+                .filter(p -> p.getId().equals(target.getId())).count();
+        assertThat(targetCount).isEqualTo(1); // no duplicate
+    }
+
+    // ─── deleteReceiverReferences ─────────────────────────────────────────────
+
+    @Test
+    void deleteReceiverReferences_removesPersonFromAllDocumentReceivers() {
+        Person toDelete = personRepository.save(Person.builder().firstName("Weg").lastName("Person").build());
+        Person sender   = personRepository.save(Person.builder().firstName("Send").lastName("Er").build());
+
+        Document doc1 = documentRepository.save(Document.builder()
+                .title("Brief 1").originalFilename("b1.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(toDelete)).build());
+        Document doc2 = documentRepository.save(Document.builder()
+                .title("Brief 2").originalFilename("b2.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(toDelete)).build());
+
+        personRepository.deleteReceiverReferences(toDelete.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        assertThat(documentRepository.findById(doc1.getId()).orElseThrow().getReceivers()).isEmpty();
+        assertThat(documentRepository.findById(doc2.getId()).orElseThrow().getReceivers()).isEmpty();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/AnnotationServiceTest.java

@@ -183,4 +183,100 @@ class AnnotationServiceTest {
 
         verify(annotationRepository, never()).save(any());
     }
+
+    // ─── deleteAnnotation — null userId ───────────────────────────────────────
+
+    @Test
+    void deleteAnnotation_throwsForbidden_whenUserIdIsNull() {
+        UUID docId = UUID.randomUUID();
+        UUID annotId = UUID.randomUUID();
+        UUID ownerId = UUID.randomUUID();
+
+        DocumentAnnotation annotation = DocumentAnnotation.builder()
+                .id(annotId).documentId(docId).createdBy(ownerId).build();
+        when(annotationRepository.findByIdAndDocumentId(annotId, docId))
+                .thenReturn(Optional.of(annotation));
+
+        assertThatThrownBy(() -> annotationService.deleteAnnotation(docId, annotId, null))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getStatus()).isEqualTo(FORBIDDEN));
+    }
+
+    // ─── overlaps — partial overlap cases ────────────────────────────────────
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsToTheLeft() {
+        // existing: x=0.5, w=0.3 (x2=0.8); dto: x=0.0, w=0.4 (dx2=0.4)
+        // existing.getX() < dx2 → 0.5 < 0.4 → FALSE → no overlap (first && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.5).y(0.0).width(0.3).height(0.5).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.0, 0.0, 0.4, 0.5, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsToTheRight() {
+        // existing: x=0.0, w=0.1 (ex2=0.1); dto: x=0.2, w=0.3 (dx2=0.5)
+        // existing.getX() < dx2 → 0.0 < 0.5 → TRUE
+        // ex2 > dto.getX() → 0.1 > 0.2 → FALSE → no overlap (second && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.0).y(0.0).width(0.1).height(0.5).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.2, 0.0, 0.3, 0.5, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsBelow() {
+        // x ranges overlap, but y ranges don't
+        // existing: x=0.0, w=0.5, y=0.5, h=0.2 (ey2=0.7)
+        // dto: x=0.1, w=0.3 (dx2=0.4), y=0.0, h=0.4 (dy2=0.4)
+        // existing.getX() < dx2 → 0.0 < 0.4 → TRUE
+        // ex2 > dto.getX() → 0.5 > 0.1 → TRUE
+        // existing.getY() < dy2 → 0.5 < 0.4 → FALSE → no overlap (third && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.0).y(0.5).width(0.5).height(0.2).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.1, 0.0, 0.3, 0.4, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsAbove() {
+        // x ranges overlap, y ranges don't — existing is ABOVE the new annotation
+        // existing: x=0.0, w=0.5, y=0.0, h=0.1 (ey2=0.1)
+        // dto: x=0.1, w=0.3 (dx2=0.4), y=0.2, h=0.3 (dy2=0.5)
+        // A: 0.0 < 0.4 → TRUE, B: 0.5 > 0.1 → TRUE, C: 0.0 < 0.5 → TRUE
+        // D: ey2 > dto.getY() → 0.1 > 0.2 → FALSE → no overlap (fourth && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.0).y(0.0).width(0.5).height(0.1).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.1, 0.2, 0.3, 0.3, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/service/CommentServiceTest.java

@@ -20,6 +20,9 @@ import java.util.UUID;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.ArgumentMatchers.anySet;
+import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -30,6 +33,8 @@ import static org.springframework.http.HttpStatus.NOT_FOUND;
 class CommentServiceTest {
 
     @Mock CommentRepository commentRepository;
+    @Mock UserService userService;
+    @Mock NotificationService notificationService;
     @InjectMocks CommentService commentService;
 
     // ─── postComment ──────────────────────────────────────────────────────────
@@ -43,7 +48,7 @@ class CommentServiceTest {
                 .id(UUID.randomUUID()).documentId(docId).authorName("Hans Müller").content("Test").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.postComment(docId, null, "Test", author);
+        DocumentComment result = commentService.postComment(docId, null, "Test", List.of(), author);
 
         assertThat(result.getAuthorName()).isEqualTo("Hans Müller");
     }
@@ -56,11 +61,28 @@ class CommentServiceTest {
                 .id(UUID.randomUUID()).documentId(docId).authorName("hans42").content("Test").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.postComment(docId, null, "Test", author);
+        DocumentComment result = commentService.postComment(docId, null, "Test", List.of(), author);
 
         assertThat(result.getAuthorName()).isEqualTo("hans42");
     }
 
+    @Test
+    void postComment_triggersNotifyMentions_whenMentionedUserIdsProvided() {
+        UUID docId = UUID.randomUUID();
+        UUID mentionedId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("hans").firstName("Hans").lastName("M").build();
+        AppUser mentioned = AppUser.builder().id(mentionedId).username("anna").firstName("Anna").lastName("S").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Hans M").content("Hey @Anna S").build();
+
+        when(userService.findAllById(List.of(mentionedId))).thenReturn(List.of(mentioned));
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hey @Anna S", List.of(mentionedId), author);
+
+        verify(notificationService).notifyMentions(eq(List.of(mentionedId)), eq(saved));
+    }
+
     // ─── replyToComment ───────────────────────────────────────────────────────
 
     @Test
@@ -70,7 +92,7 @@ class CommentServiceTest {
         AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
         when(commentRepository.findById(commentId)).thenReturn(Optional.empty());
 
-        assertThatThrownBy(() -> commentService.replyToComment(docId, commentId, "Reply", author))
+        assertThatThrownBy(() -> commentService.replyToComment(docId, commentId, "Reply", List.of(), author))
                 .isInstanceOf(DomainException.class)
                 .satisfies(e -> assertThat(((DomainException) e).getStatus()).isEqualTo(NOT_FOUND));
 
@@ -91,11 +113,12 @@ class CommentServiceTest {
 
         when(commentRepository.findById(replyId)).thenReturn(Optional.of(existingReply));
         when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of(existingReply));
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply2").authorName("anna").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.replyToComment(docId, replyId, "Reply2", author);
+        DocumentComment result = commentService.replyToComment(docId, replyId, "Reply2", List.of(), author);
 
         assertThat(result.getParentId()).isEqualTo(rootId);
     }
@@ -110,15 +133,59 @@ class CommentServiceTest {
                 .id(rootId).documentId(docId).parentId(null).content("Root").authorName("Hans").build();
 
         when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply").authorName("anna").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.replyToComment(docId, rootId, "Reply", author);
+        DocumentComment result = commentService.replyToComment(docId, rootId, "Reply", List.of(), author);
 
         assertThat(result.getParentId()).isEqualTo(rootId);
     }
 
+    @Test
+    void replyToComment_triggersNotifyReply_afterSave() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).content("Root").authorName("Hans").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply").authorName("anna").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "Reply", List.of(), author);
+
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    @Test
+    void replyToComment_triggersNotifyMentions_whenMentionedUserIdsProvided() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        UUID mentionedId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+        AppUser mentioned = AppUser.builder().id(mentionedId).username("bob").firstName("Bob").lastName("J").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).content("Root").authorName("Hans").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Hey @Bob J").authorName("anna").build();
+
+        when(userService.findAllById(List.of(mentionedId))).thenReturn(List.of(mentioned));
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "Hey @Bob J", List.of(mentionedId), author);
+
+        verify(notificationService).notifyMentions(eq(List.of(mentionedId)), eq(saved));
+    }
+
     // ─── editComment ──────────────────────────────────────────────────────────
 
     @Test
@@ -233,6 +300,181 @@ class CommentServiceTest {
         assertThat(result.get(0).getReplies()).containsExactly(reply);
     }
 
+    // ─── replyToComment — reply with null authorId in thread ─────────────────
+
+    @Test
+    void replyToComment_handlesNullAuthorId_inExistingReply() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").firstName("Anna").lastName("S").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).authorId(UUID.randomUUID()).content("Root").authorName("Root").build();
+        // Existing reply with null authorId
+        DocumentComment nullAuthorReply = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).authorId(null).content("Anon reply").authorName("anon").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("New reply").authorName("Anna S").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of(nullAuthorReply));
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "New reply", List.of(), author);
+
+        // Must not throw NullPointerException; only non-null authorIds collected
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    // ─── resolveAuthorName edge cases ─────────────────────────────────────────
+
+    @Test
+    void postComment_fallsBackToUsername_whenFirstNameBlankAndLastNameNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName("   ").lastName(null).build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("user42").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        DocumentComment result = commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        assertThat(result.getAuthorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void postComment_fallsBackToUsername_whenFirstNameNullAndLastNameBlank() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName(null).lastName("  ").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("user42").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        DocumentComment result = commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        assertThat(result.getAuthorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void postComment_includesOnlyFirstName_whenLastNameIsNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName("Hans").lastName(null).build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Hans").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        // first != null && !blank → true; last == null → entire condition false → returns stripped first
+        verify(commentRepository).save(any());
+    }
+
+    @Test
+    void postComment_includesOnlyLastName_whenFirstNameIsNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName(null).lastName("Müller").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Müller").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        // No exception — name resolution with null first name strips cleanly
+        verify(commentRepository).save(any());
+    }
+
+    // ─── saveMentions — null/empty guard ─────────────────────────────────────
+
+    @Test
+    void postComment_doesNotCallUserService_whenMentionedUserIdsIsNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("hans")
+                .firstName("Hans").lastName("M").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Hans M").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hi", null, author);
+
+        verify(userService, never()).findAllById(anyList());
+    }
+
+    // ─── collectParticipantIds — non-null authorId in reply ──────────────────
+
+    @Test
+    void replyToComment_includesNonNullAuthorId_fromExistingReply() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        UUID existingReplyAuthorId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).authorId(UUID.randomUUID())
+                .content("Root").authorName("root").build();
+        // Existing reply WITH a non-null authorId — covers true branch of reply.getAuthorId() != null
+        DocumentComment existingReply = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId)
+                .authorId(existingReplyAuthorId).content("Existing").authorName("someone").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId)
+                .content("New reply").authorName("anna").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of(existingReply));
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "New reply", List.of(), author);
+
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    // ─── collectParticipantIds — null authorId ────────────────────────────────
+
+    @Test
+    void replyToComment_excludesNullAuthorIds_fromParticipantSet() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+
+        // Root with null authorId
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).authorId(null).content("Root").authorName("anon").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply").authorName("anna").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        // Must not throw NullPointerException
+        commentService.replyToComment(docId, rootId, "Reply", List.of(), author);
+
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    // ─── getCommentsForAnnotation ─────────────────────────────────────────────
+
+    @Test
+    void getCommentsForAnnotation_returnsRootsForAnnotation() {
+        UUID annotationId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).annotationId(annotationId).authorName("Hans").content("Root").build();
+
+        when(commentRepository.findByAnnotationIdAndParentIdIsNull(annotationId))
+                .thenReturn(List.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+
+        List<DocumentComment> result = commentService.getCommentsForAnnotation(annotationId);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getAnnotationId()).isEqualTo(annotationId);
+    }
+
     // ─── helpers ──────────────────────────────────────────────────────────────
 
     private AppUser buildAdmin() {

backend/src/test/java/org/raddatz/familienarchiv/service/CustomUserDetailsServiceTest.java

@@ -0,0 +1,120 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.UserGroup;
+import org.raddatz.familienarchiv.repository.AppUserRepository;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UsernameNotFoundException;
+
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class CustomUserDetailsServiceTest {
+
+    @Mock AppUserRepository userRepository;
+    @InjectMocks CustomUserDetailsService service;
+
+    // ─── loadUserByUsername — not found ──────────────────────────────────────
+
+    @Test
+    void loadUserByUsername_throwsUsernameNotFoundException_whenUserNotFound() {
+        when(userRepository.findByUsername("ghost")).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> service.loadUserByUsername("ghost"))
+                .isInstanceOf(UsernameNotFoundException.class)
+                .hasMessageContaining("ghost");
+    }
+
+    // ─── loadUserByUsername — happy path ─────────────────────────────────────
+
+    @Test
+    void loadUserByUsername_returnsUserDetails_withMappedAuthorities() {
+        UserGroup group = UserGroup.builder().id(UUID.randomUUID()).name("Admins")
+                .permissions(Set.of("READ_ALL", "WRITE_ALL")).build();
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("admin").password("hashed").enabled(true)
+                .groups(Set.of(group)).build();
+        when(userRepository.findByUsername("admin")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("admin");
+
+        assertThat(details.getUsername()).isEqualTo("admin");
+        assertThat(details.getAuthorities()).extracting("authority")
+                .contains("READ_ALL", "WRITE_ALL");
+    }
+
+    @Test
+    void loadUserByUsername_returnsEmptyAuthorities_whenUserHasNoGroups() {
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("viewer").password("hashed").enabled(true)
+                .groups(Set.of()).build();
+        when(userRepository.findByUsername("viewer")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("viewer");
+
+        assertThat(details.getAuthorities()).isEmpty();
+    }
+
+    // ─── loadUserByUsername — unknown permission ──────────────────────────────
+
+    @Test
+    void loadUserByUsername_grantsUnknownPermission_butLogsWarning() {
+        // Unknown permissions should still be granted (logged as warning, not silently dropped)
+        UserGroup group = UserGroup.builder().id(UUID.randomUUID()).name("CustomGroup")
+                .permissions(Set.of("UNKNOWN_CUSTOM_PERM")).build();
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("custom").password("hashed").enabled(true)
+                .groups(Set.of(group)).build();
+        when(userRepository.findByUsername("custom")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("custom");
+
+        assertThat(details.getAuthorities()).extracting("authority")
+                .contains("UNKNOWN_CUSTOM_PERM");
+    }
+
+    // ─── loadUserByUsername — disabled user ───────────────────────────────────
+
+    @Test
+    void loadUserByUsername_returnsDisabledUser_whenUserIsDisabled() {
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("disabled").password("hashed").enabled(false)
+                .groups(Set.of()).build();
+        when(userRepository.findByUsername("disabled")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("disabled");
+
+        assertThat(details.isEnabled()).isFalse();
+    }
+
+    // ─── loadUserByUsername — multi-group permission merge ────────────────────
+
+    @Test
+    void loadUserByUsername_mergesPermissionsFromMultipleGroups() {
+        UserGroup g1 = UserGroup.builder().id(UUID.randomUUID()).name("Readers")
+                .permissions(Set.of("READ_ALL")).build();
+        UserGroup g2 = UserGroup.builder().id(UUID.randomUUID()).name("Writers")
+                .permissions(Set.of("WRITE_ALL")).build();
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("multi").password("hashed").enabled(true)
+                .groups(Set.of(g1, g2)).build();
+        when(userRepository.findByUsername("multi")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("multi");
+
+        assertThat(details.getAuthorities()).extracting("authority")
+                .containsExactlyInAnyOrder("READ_ALL", "WRITE_ALL");
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/DocumentServiceTest.java

@@ -7,12 +7,16 @@ import org.mockito.InjectMocks;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.raddatz.familienarchiv.dto.DocumentUpdateDTO;
+import org.raddatz.familienarchiv.dto.IncompleteDocumentDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.Person;
 import org.raddatz.familienarchiv.model.Tag;
 import org.raddatz.familienarchiv.repository.DocumentRepository;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.mock.web.MockMultipartFile;
 
@@ -360,12 +364,30 @@ class DocumentServiceTest {
     // ─── findIncompleteDocuments ──────────────────────────────────────────────
 
     @Test
-    void findIncompleteDocuments_returnsDocumentsOrderedByCreatedAtDesc() {
-        Document doc = Document.builder().id(UUID.randomUUID()).title("Test").build();
-        when(documentRepository.findByMetadataCompleteFalse(any(Sort.class))).thenReturn(List.of(doc));
+    void findIncompleteDocuments_returnsDTOsWithIdAndTitle() {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Unvollständig").build();
+        when(documentRepository.findByMetadataCompleteFalse(any(Pageable.class)))
+                .thenReturn(new PageImpl<>(List.of(doc)));
 
-        assertThat(documentService.findIncompleteDocuments()).containsExactly(doc);
-        verify(documentRepository).findByMetadataCompleteFalse(Sort.by(Sort.Direction.DESC, "createdAt"));
+        List<IncompleteDocumentDTO> result = documentService.findIncompleteDocuments(3);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).id()).isEqualTo(id);
+        assertThat(result.get(0).title()).isEqualTo("Unvollständig");
+    }
+
+    @Test
+    void findIncompleteDocuments_passesSizeToPageable() {
+        when(documentRepository.findByMetadataCompleteFalse(any(Pageable.class)))
+                .thenReturn(Page.empty());
+
+        documentService.findIncompleteDocuments(3);
+
+        ArgumentCaptor<Pageable> captor = ArgumentCaptor.forClass(Pageable.class);
+        verify(documentRepository).findByMetadataCompleteFalse(captor.capture());
+        assertThat(captor.getValue().getPageSize()).isEqualTo(3);
+        assertThat(captor.getValue().getSort()).isEqualTo(Sort.by(Sort.Direction.DESC, "createdAt"));
     }
 
     // ─── findNextIncompleteDocument ───────────────────────────────────────────
@@ -467,6 +489,62 @@ class DocumentServiceTest {
         assertThat(captor.getValue().getSender()).isNull();
     }
 
+    // ─── createDocument title fallback ────────────────────────────────────────
+
+    @Test
+    void createDocument_usesTitleFromFilename_whenDtoTitleIsNull() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        // dto.title is null
+        MockMultipartFile file = new MockMultipartFile("file", "Brief_1965.pdf", "application/pdf", new byte[]{1});
+        Document saved = Document.builder().id(UUID.randomUUID()).title("Brief_1965")
+                .originalFilename("Brief_1965.pdf").status(DocumentStatus.PLACEHOLDER).build();
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(documentRepository.findById(any())).thenReturn(Optional.of(saved));
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.createDocument(dto, file);
+
+        verify(documentRepository, atLeastOnce()).save(captor.capture());
+        assertThat(captor.getAllValues().get(0).getTitle()).isEqualTo("Brief_1965");
+    }
+
+    @Test
+    void createDocument_usesTitleFromFilename_whenDtoTitleIsBlank() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("   ");
+        MockMultipartFile file = new MockMultipartFile("file", "Rechnung_1980.pdf", "application/pdf", new byte[]{1});
+        Document saved = Document.builder().id(UUID.randomUUID()).title("Rechnung_1980")
+                .originalFilename("Rechnung_1980.pdf").status(DocumentStatus.PLACEHOLDER).build();
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(documentRepository.findById(any())).thenReturn(Optional.of(saved));
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.createDocument(dto, file);
+
+        verify(documentRepository, atLeastOnce()).save(captor.capture());
+        assertThat(captor.getAllValues().get(0).getTitle()).isEqualTo("Rechnung_1980");
+    }
+
+    @Test
+    void createDocument_keepsDtoTitle_whenProvided() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Mein Titel");
+        MockMultipartFile file = new MockMultipartFile("file", "scan.pdf", "application/pdf", new byte[]{1});
+        Document saved = Document.builder().id(UUID.randomUUID()).title("Mein Titel")
+                .originalFilename("scan.pdf").status(DocumentStatus.PLACEHOLDER).build();
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(documentRepository.findById(any())).thenReturn(Optional.of(saved));
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.createDocument(dto, file);
+
+        verify(documentRepository, atLeastOnce()).save(captor.capture());
+        assertThat(captor.getAllValues().get(0).getTitle()).isEqualTo("Mein Titel");
+    }
+
     // ─── createDocument metadataComplete ─────────────────────────────────────
 
     @Test
@@ -614,4 +692,525 @@ class DocumentServiceTest {
     void titleFromFilename_null_returnsNull() {
         assertThat(DocumentService.titleFromFilename(null)).isNull();
     }
+
+    // ─── titleFromFilename — tryParseDate invalid cases ───────────────────────
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenIsoDateHasInvalidMonth() {
+        // 1965-13-12 → month 13 is invalid → tryParseDate returns null → fallback
+        assertThat(DocumentService.titleFromFilename("1965-13-12_Mueller_Hans.pdf"))
+                .isEqualTo("1965-13-12_Mueller_Hans");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenIsoDateHasInvalidDay() {
+        // 1965-03-00 → day 0 is invalid → tryParseDate returns null → fallback
+        assertThat(DocumentService.titleFromFilename("1965-03-00_Mueller_Hans.pdf"))
+                .isEqualTo("1965-03-00_Mueller_Hans");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenCompactDateHasInvalidMonth() {
+        // 19651312 → month 13 → invalid
+        assertThat(DocumentService.titleFromFilename("19651312_Mueller_Hans.pdf"))
+                .isEqualTo("19651312_Mueller_Hans");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenCompactDateHasInvalidDay() {
+        // 19650300 → day 0 → invalid
+        assertThat(DocumentService.titleFromFilename("19650300_Mueller_Hans.pdf"))
+                .isEqualTo("19650300_Mueller_Hans");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenStemHasNoExtension() {
+        // No dot → parseFilenameData returns null → titleFromFilename returns null? No,
+        // actually it returns null when filename is null, otherwise stripExtension is called.
+        // Without a dot, dot = -1, strip returns the whole string.
+        assertThat(DocumentService.titleFromFilename("Mueller_Hans_19650312"))
+                .isEqualTo("Mueller_Hans_19650312");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenNamePartsContainNonLetters() {
+        // Parts with numbers/hyphens fail the \p{L}+ regex → returns null → fallback
+        assertThat(DocumentService.titleFromFilename("1965-03-12_Mueller_H4ns.pdf"))
+                .isEqualTo("1965-03-12_Mueller_H4ns");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenOnlyTwoParts() {
+        // "1965-03-12_Mueller.pdf" → less than 2 name parts → null → fallback
+        assertThat(DocumentService.titleFromFilename("1965-03-12_Mueller.pdf"))
+                .isEqualTo("1965-03-12_Mueller");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenIsoDateHasMonthZero() {
+        // 1965-00-12 → month 0 → m >= 1 is false → tryParseDate returns null
+        assertThat(DocumentService.titleFromFilename("1965-00-12_Mueller_Hans.pdf"))
+                .isEqualTo("1965-00-12_Mueller_Hans");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenIsoDateHasDayAbove31() {
+        // 1965-03-32 → day 32 > 31 → d <= 31 is false → tryParseDate returns null
+        assertThat(DocumentService.titleFromFilename("1965-03-32_Mueller_Hans.pdf"))
+                .isEqualTo("1965-03-32_Mueller_Hans");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenCompactDateHasMonthZero() {
+        // 19650012 → month 0 → m >= 1 is false
+        assertThat(DocumentService.titleFromFilename("19650012_Mueller_Hans.pdf"))
+                .isEqualTo("19650012_Mueller_Hans");
+    }
+
+    @Test
+    void titleFromFilename_returnsStrippedName_whenCompactDateHasDayAbove31() {
+        // 19650332 → day 32 > 31
+        assertThat(DocumentService.titleFromFilename("19650332_Mueller_Hans.pdf"))
+                .isEqualTo("19650332_Mueller_Hans");
+    }
+
+    // ─── getConversationFiltered ───────────────────────────────────────────────
+
+    @Test
+    void getConversationFiltered_passesGivenDates_whenFromAndToAreProvided() {
+        UUID senderId = UUID.randomUUID();
+        UUID receiverId = UUID.randomUUID();
+        LocalDate from = LocalDate.of(1940, 1, 1);
+        LocalDate to = LocalDate.of(1960, 12, 31);
+        Sort sort = Sort.by(Sort.Direction.ASC, "documentDate");
+        when(documentRepository.findConversation(senderId, receiverId, from, to, sort))
+                .thenReturn(List.of());
+
+        documentService.getConversationFiltered(senderId, receiverId, from, to, sort);
+
+        verify(documentRepository).findConversation(senderId, receiverId, from, to, sort);
+    }
+
+    @Test
+    void getConversationFiltered_usesMinDateForFrom_whenFromIsNull() {
+        UUID senderId = UUID.randomUUID();
+        UUID receiverId = UUID.randomUUID();
+        Sort sort = Sort.by(Sort.Direction.ASC, "documentDate");
+        when(documentRepository.findConversation(eq(senderId), eq(receiverId), any(LocalDate.class), any(LocalDate.class), eq(sort)))
+                .thenReturn(List.of());
+
+        documentService.getConversationFiltered(senderId, receiverId, null, null, sort);
+
+        ArgumentCaptor<LocalDate> fromCaptor = ArgumentCaptor.forClass(LocalDate.class);
+        verify(documentRepository).findConversation(eq(senderId), eq(receiverId), fromCaptor.capture(), any(LocalDate.class), eq(sort));
+        assertThat(fromCaptor.getValue()).isEqualTo(LocalDate.parse("0000-01-01"));
+    }
+
+    @Test
+    void getConversationFiltered_usesTodayForTo_whenToIsNull() {
+        UUID senderId = UUID.randomUUID();
+        UUID receiverId = UUID.randomUUID();
+        Sort sort = Sort.by(Sort.Direction.ASC, "documentDate");
+        when(documentRepository.findConversation(eq(senderId), eq(receiverId), any(LocalDate.class), any(LocalDate.class), eq(sort)))
+                .thenReturn(List.of());
+
+        documentService.getConversationFiltered(senderId, receiverId, null, null, sort);
+
+        ArgumentCaptor<LocalDate> toCaptor = ArgumentCaptor.forClass(LocalDate.class);
+        verify(documentRepository).findConversation(eq(senderId), eq(receiverId), any(LocalDate.class), toCaptor.capture(), eq(sort));
+        assertThat(toCaptor.getValue()).isEqualTo(LocalDate.now());
+    }
+
+    // ─── updateDocumentTags — empty tag in list ───────────────────────────────
+
+    @Test
+    void updateDocumentTags_skipsEmptyTagNames() {
+        UUID id = UUID.randomUUID();
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+        Document doc = Document.builder().id(id).title("T").build();
+
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(tagService.findOrCreate("Familie")).thenReturn(tag);
+
+        // List with empty string element — cleanName.isEmpty() branch hit
+        documentService.updateDocumentTags(id, List.of("Familie", "  ", ""));
+
+        verify(tagService).findOrCreate("Familie");
+        verify(tagService, times(1)).findOrCreate(any()); // only "Familie" — others skipped
+    }
+
+    // ─── createDocument — with empty tag segment ──────────────────────────────
+
+    @Test
+    void createDocument_filtersEmptyTagSegments() throws Exception {
+        UUID docId = UUID.randomUUID();
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Test");
+        dto.setTags("Familie,  ,"); // middle and trailing blank segments
+
+        when(documentRepository.save(any())).thenAnswer(inv -> {
+            Document d = inv.getArgument(0);
+            if (d.getId() == null) {
+                return Document.builder().id(docId).title(d.getTitle()).build();
+            }
+            return d;
+        });
+        when(documentRepository.findById(docId)).thenReturn(Optional.of(
+                Document.builder().id(docId).title("Test").build()));
+        when(tagService.findOrCreate("Familie")).thenReturn(tag);
+
+        documentService.createDocument(dto, null);
+
+        verify(tagService).findOrCreate("Familie");
+        verify(tagService, times(1)).findOrCreate(any());
+    }
+
+    // ─── createDocument — with sender and receivers ───────────────────────────
+
+    @Test
+    void createDocument_setsSender_whenSenderIdIsProvided() throws Exception {
+        UUID senderId = UUID.randomUUID();
+        Person sender = Person.builder().id(senderId).firstName("Hans").lastName("M").build();
+        UUID docId = UUID.randomUUID();
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Test");
+        dto.setSenderId(senderId);
+
+        when(documentRepository.save(any())).thenAnswer(inv -> {
+            Document d = inv.getArgument(0);
+            if (d.getId() == null) {
+                Document saved = Document.builder().id(docId).title(d.getTitle()).build();
+                return saved;
+            }
+            return d;
+        });
+        when(documentRepository.findById(docId)).thenReturn(Optional.of(
+                Document.builder().id(docId).title("Test").build()));
+        when(personService.getById(senderId)).thenReturn(sender);
+
+        documentService.createDocument(dto, null);
+
+        verify(personService).getById(senderId);
+    }
+
+    @Test
+    void createDocument_setsReceivers_whenReceiverIdsAreProvided() throws Exception {
+        UUID r1Id = UUID.randomUUID();
+        UUID r2Id = UUID.randomUUID();
+        UUID docId = UUID.randomUUID();
+        Person r1 = Person.builder().id(r1Id).firstName("A").lastName("B").build();
+        Person r2 = Person.builder().id(r2Id).firstName("C").lastName("D").build();
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Test");
+        dto.setReceiverIds(List.of(r1Id, r2Id));
+
+        when(documentRepository.save(any())).thenAnswer(inv -> {
+            Document d = inv.getArgument(0);
+            if (d.getId() == null) {
+                return Document.builder().id(docId).title(d.getTitle()).build();
+            }
+            return d;
+        });
+        when(documentRepository.findById(docId)).thenReturn(Optional.of(
+                Document.builder().id(docId).title("Test").build()));
+        when(personService.getAllById(List.of(r1Id, r2Id))).thenReturn(List.of(r1, r2));
+
+        documentService.createDocument(dto, null);
+
+        verify(personService).getAllById(List.of(r1Id, r2Id));
+    }
+
+    // ─── createDocument — empty file fallback and blank tags ─────────────────
+
+    @Test
+    void createDocument_usesUnbenanntesDocument_whenFileIsEmptyAndTitleIsNull() throws Exception {
+        // file != null but isEmpty() = true → falls through to title ternary
+        // title == null → "Unbenanntes Dokument"
+        MockMultipartFile emptyFile = new MockMultipartFile("file", "scan.pdf", "application/pdf", new byte[0]);
+        DocumentUpdateDTO dto = new DocumentUpdateDTO(); // title = null
+
+        Document saved = Document.builder().id(UUID.randomUUID()).title("Unbenanntes Dokument")
+                .originalFilename("Unbenanntes Dokument").status(DocumentStatus.PLACEHOLDER).build();
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(documentRepository.findById(any())).thenReturn(Optional.of(saved));
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.createDocument(dto, emptyFile);
+
+        verify(documentRepository, atLeastOnce()).save(captor.capture());
+        assertThat(captor.getAllValues().get(0).getOriginalFilename()).isEqualTo("Unbenanntes Dokument");
+    }
+
+    @Test
+    void createDocument_skipsTagProcessing_whenTagsIsBlank() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Doc");
+        dto.setTags("   "); // not null but blank → condition false
+
+        Document saved = Document.builder().id(UUID.randomUUID()).title("Doc")
+                .originalFilename("Doc").status(DocumentStatus.PLACEHOLDER).build();
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(documentRepository.findById(any())).thenReturn(Optional.of(saved));
+
+        documentService.createDocument(dto, null);
+
+        verify(tagService, never()).findOrCreate(any());
+    }
+
+    @Test
+    void createDocument_setsMetadataCompleteFalse_whenReceiverIdsIsEmptyList() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Doc");
+        dto.setReceiverIds(List.of()); // not null but empty → !isEmpty() = false → false
+
+        Document saved = Document.builder().id(UUID.randomUUID()).title("Doc")
+                .originalFilename("Doc").status(DocumentStatus.PLACEHOLDER).build();
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(documentRepository.findById(any())).thenReturn(Optional.of(saved));
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.createDocument(dto, null);
+
+        verify(documentRepository, atLeastOnce()).save(captor.capture());
+        assertThat(captor.getAllValues().get(0).isMetadataComplete()).isFalse();
+    }
+
+    // ─── updateDocument — empty file, blank tags, empty receivers ────────────
+
+    @Test
+    void updateDocument_skipsTagProcessing_whenTagsIsBlank() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("T").receivers(new HashSet<>()).build();
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+        dto.setTags("  "); // not null but blank
+
+        documentService.updateDocument(id, dto, null);
+
+        verify(tagService, never()).findOrCreate(any());
+    }
+
+    @Test
+    void updateDocument_clearsReceivers_whenReceiverIdsIsEmptyList() throws Exception {
+        UUID id = UUID.randomUUID();
+        Person r1 = Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build();
+        Document doc = Document.builder().id(id).title("T").receivers(new HashSet<>(Set.of(r1))).build();
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+        dto.setReceiverIds(List.of()); // not null but empty → else → clear
+
+        documentService.updateDocument(id, dto, null);
+
+        assertThat(doc.getReceivers()).isEmpty();
+    }
+
+    @Test
+    void updateDocument_skipsFileUpload_whenNewFileIsEmpty() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("T").receivers(new HashSet<>()).build();
+        MockMultipartFile emptyFile = new MockMultipartFile("file", "scan.pdf", "application/pdf", new byte[0]);
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+
+        documentService.updateDocument(id, dto, emptyFile);
+
+        verify(fileService, never()).uploadFile(any(), any());
+    }
+
+    // ─── titleFromFilename — no date in any position ──────────────────────────
+
+    @Test
+    void titleFromFilename_returnsStripped_whenNeitherFirstNorLastPartIsDate() {
+        // "Mueller_Hans_Schmitt.pdf" → 3 parts, none is a date → dateFromLast == null → null → stripExtension
+        assertThat(DocumentService.titleFromFilename("Mueller_Hans_Schmitt.pdf"))
+                .isEqualTo("Mueller_Hans_Schmitt");
+    }
+
+    @Test
+    void updateDocument_setsTags_withEmptySegmentsFiltered() throws Exception {
+        // Tags string with blank segment: "Familie,  ,Reise" → only "Familie" and "Reise" used
+        UUID id = UUID.randomUUID();
+        Tag t1 = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+        Tag t2 = Tag.builder().id(UUID.randomUUID()).name("Reise").build();
+        Document doc = Document.builder().id(id).title("T").receivers(new HashSet<>()).build();
+
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(tagService.findOrCreate("Familie")).thenReturn(t1);
+        when(tagService.findOrCreate("Reise")).thenReturn(t2);
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+        dto.setTags("Familie,  ,Reise"); // blank middle segment filtered
+
+        documentService.updateDocument(id, dto, null);
+
+        verify(tagService).findOrCreate("Familie");
+        verify(tagService).findOrCreate("Reise");
+        verify(tagService, times(2)).findOrCreate(any());
+    }
+
+    @Test
+    void createDocument_setsTags_whenTagsStringIsProvided() throws Exception {
+        UUID docId = UUID.randomUUID();
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Test");
+        dto.setTags("Familie");
+
+        when(documentRepository.save(any())).thenAnswer(inv -> {
+            Document d = inv.getArgument(0);
+            if (d.getId() == null) {
+                return Document.builder().id(docId).title(d.getTitle()).build();
+            }
+            return d;
+        });
+        when(documentRepository.findById(docId)).thenReturn(Optional.of(
+                Document.builder().id(docId).title("Test").build()));
+        when(tagService.findOrCreate("Familie")).thenReturn(tag);
+
+        documentService.createDocument(dto, null);
+
+        verify(tagService).findOrCreate("Familie");
+    }
+
+    // ─── updateDocument — with sender / clear receivers ──────────────────────
+
+    @Test
+    void updateDocument_clearsSender_whenSenderIdIsNull() throws Exception {
+        UUID id = UUID.randomUUID();
+        Person existingSender = Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build();
+        Document doc = Document.builder().id(id).title("T").sender(existingSender).receivers(new HashSet<>()).build();
+
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc)); // also for updateDocumentTags
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+        // senderId is null — should clear sender
+
+        documentService.updateDocument(id, dto, null);
+
+        verify(documentRepository, atLeastOnce()).save(argThat(d -> d.getSender() == null));
+    }
+
+    @Test
+    void updateDocument_setsReceivers_whenReceiverIdsAreProvided() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID r1Id = UUID.randomUUID();
+        Person r1 = Person.builder().id(r1Id).firstName("A").lastName("B").build();
+        Document doc = Document.builder().id(id).title("T").receivers(new HashSet<>()).build();
+
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(personService.getAllById(List.of(r1Id))).thenReturn(List.of(r1));
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+        dto.setReceiverIds(List.of(r1Id));
+
+        documentService.updateDocument(id, dto, null);
+
+        verify(personService).getAllById(List.of(r1Id));
+    }
+
+    @Test
+    void updateDocument_setsTags_whenTagsStringIsProvided() throws Exception {
+        UUID id = UUID.randomUUID();
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Reise").build();
+        Document doc = Document.builder().id(id).title("T").receivers(new HashSet<>()).build();
+
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(tagService.findOrCreate("Reise")).thenReturn(tag);
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+        dto.setTags("Reise");
+
+        documentService.updateDocument(id, dto, null);
+
+        verify(tagService).findOrCreate("Reise");
+    }
+
+    @Test
+    void updateDocument_setsSender_whenSenderIdIsProvided() throws Exception {
+        // dto.getSenderId() != null → true branch: sets sender via personService
+        UUID id = UUID.randomUUID();
+        UUID senderId = UUID.randomUUID();
+        Person sender = Person.builder().id(senderId).firstName("Hans").lastName("M").build();
+        Document doc = Document.builder().id(id).title("T").receivers(new HashSet<>()).build();
+        when(documentRepository.findById(id)).thenReturn(Optional.of(doc));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(personService.getById(senderId)).thenReturn(sender);
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("T");
+        dto.setSenderId(senderId);
+
+        documentService.updateDocument(id, dto, null);
+
+        verify(personService).getById(senderId);
+        assertThat(doc.getSender()).isEqualTo(sender);
+    }
+
+    // ─── stripExtension / parseFilenameData — null guard branches ────────────
+
+    @Test
+    void stripExtension_returnsNull_whenFilenameIsNull() throws Exception {
+        // filename == null = true → null guard branch in private static method
+        java.lang.reflect.Method method = DocumentService.class
+                .getDeclaredMethod("stripExtension", String.class);
+        method.setAccessible(true);
+        String result = (String) method.invoke(null, (String) null);
+        assertThat(result).isNull();
+    }
+
+    @Test
+    void parseFilenameData_returnsNull_whenFilenameIsNull() throws Exception {
+        // filename == null = true → null guard branch in private static method
+        java.lang.reflect.Method method = DocumentService.class
+                .getDeclaredMethod("parseFilenameData", String.class);
+        method.setAccessible(true);
+        Object result = method.invoke(null, (String) null);
+        assertThat(result).isNull();
+    }
+
+    // ─── searchDocuments — status filter ─────────────────────────────────────
+
+    @Test
+    void searchDocuments_passesStatusSpecificationToRepository() {
+        when(documentRepository.findAll(any(org.springframework.data.jpa.domain.Specification.class), any(Sort.class)))
+                .thenReturn(List.of());
+
+        documentService.searchDocuments(null, null, null, null, null, null, DocumentStatus.REVIEWED);
+
+        verify(documentRepository).findAll(any(org.springframework.data.jpa.domain.Specification.class), any(Sort.class));
+    }
+
+    @Test
+    void searchDocuments_withNullStatus_doesNotFilterByStatus() {
+        when(documentRepository.findAll(any(org.springframework.data.jpa.domain.Specification.class), any(Sort.class)))
+                .thenReturn(List.of());
+
+        documentService.searchDocuments(null, null, null, null, null, null, null);
+
+        verify(documentRepository).findAll(any(org.springframework.data.jpa.domain.Specification.class), any(Sort.class));
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/service/DocumentVersionServiceTest.java

@@ -374,6 +374,366 @@ class DocumentVersionServiceTest {
         assertThat(count).isEqualTo(2);
     }
 
+    // ─── recordVersion — no auth / user not found ─────────────────────────────
+
+    @Test
+    void recordVersion_usesUnknown_whenSecurityContextHasNoAuthentication() {
+        // No call to authenticateAs — context is cleared
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("Unknown");
+        assertThat(captor.getValue().getEditorId()).isNull();
+    }
+
+    @Test
+    void recordVersion_usesUnknown_whenAuthenticationIsNotAuthenticated() {
+        // Auth present but isAuthenticated() = false — use TestingAuthenticationToken
+        org.springframework.security.authentication.TestingAuthenticationToken notAuth =
+                new org.springframework.security.authentication.TestingAuthenticationToken("user", null);
+        notAuth.setAuthenticated(false);
+        SecurityContextHolder.getContext().setAuthentication(notAuth);
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("Unknown");
+    }
+
+    @Test
+    void recordVersion_usesUnknown_whenUserServiceThrows() {
+        authenticateAs("missinguser");
+        when(userService.findByUsername("missinguser")).thenThrow(new RuntimeException("not found"));
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("Unknown");
+    }
+
+    // ─── recordVersion — buildEditorName edge cases ───────────────────────────
+
+    @Test
+    void recordVersion_usesUsername_whenFirstNameIsNotBlankButLastNameIsNull() {
+        authenticateAs("user42");
+        when(userService.findByUsername("user42")).thenReturn(
+                AppUser.builder().id(UUID.randomUUID()).username("user42")
+                        .firstName("Hans").lastName(null).build());
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void recordVersion_usesUsername_whenFirstNameIsBlankButLastNameIsPresent() {
+        authenticateAs("user42");
+        when(userService.findByUsername("user42")).thenReturn(
+                AppUser.builder().id(UUID.randomUUID()).username("user42")
+                        .firstName("  ").lastName("Müller").build());
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void recordVersion_usesUsername_whenLastNameIsBlankButFirstNameIsPresent() {
+        authenticateAs("user42");
+        when(userService.findByUsername("user42")).thenReturn(
+                AppUser.builder().id(UUID.randomUUID()).username("user42")
+                        .firstName("Hans").lastName("  ").build());
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("user42");
+    }
+
+    // ─── recordVersion — computeChangedFields with corrupt snapshot ──────────
+
+    @Test
+    void recordVersion_returnsEmptyChangedFields_whenPreviousSnapshotIsInvalidJson() {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot("INVALID JSON")
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(Document.builder().id(docId).title("T").build());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).isEqualTo("[]");
+    }
+
+    // ─── recordVersion — checkSender/checkReceivers/checkTags with no previous ─
+
+    @Test
+    void recordVersion_tracksSenderAdded_whenPreviousHadNoSender() throws Exception {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no sender
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person newSender = Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build();
+        Document updated = Document.builder().id(docId).title("T").sender(newSender).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("sender");
+    }
+
+    @Test
+    void recordVersion_tracksReceiversAdded_whenPreviousHadNone() throws Exception {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no receivers
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person r = Person.builder().id(UUID.randomUUID()).firstName("C").lastName("D").build();
+        Document updated = Document.builder().id(docId).title("T").receivers(Set.of(r)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("receivers");
+    }
+
+    @Test
+    void recordVersion_tracksTagsAdded_whenPreviousHadNone() throws Exception {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no tags
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+        Document updated = Document.builder().id(docId).title("T").tags(Set.of(tag)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("tags");
+    }
+
+    // ─── checkSender — sender map with null id ───────────────────────────────
+
+    @Test
+    void recordVersion_senderChangedToPresent_whenPreviousSenderHasNullId() throws Exception {
+        // Covers: prevSender instanceof Map = true, but id == null → prevId = null
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        // Manually craft a JSON where sender object exists but id is null
+        String oldSnapshot = "{\"id\":\"" + docId + "\",\"title\":\"T\","
+                + "\"sender\":{\"id\":null,\"firstName\":\"A\",\"lastName\":\"B\"},"
+                + "\"receivers\":[],\"tags\":[]}";
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person newSender = Person.builder().id(UUID.randomUUID()).firstName("B").lastName("C").build();
+        Document updated = Document.builder().id(docId).title("T").sender(newSender).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("sender");
+    }
+
+    // ─── checkSender — sender unchanged → not in changedFields ───────────────
+
+    @Test
+    void recordVersion_doesNotTrackSender_whenSenderUnchanged() throws Exception {
+        // Covers: !Objects.equals(currentId, prevId) = false → don't add "sender"
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        UUID senderId = UUID.randomUUID();
+        Person sender = Person.builder().id(senderId).firstName("A").lastName("B").build();
+        Document oldDoc = Document.builder().id(docId).title("T").sender(sender).build();
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        // Same sender — should NOT be in changedFields
+        Document updated = Document.builder().id(docId).title("T").sender(sender).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).doesNotContain("sender");
+    }
+
+    // ─── computeChangedFields — documentDate ternary true branch ─────────────
+
+    @Test
+    void recordVersion_tracksDocumentDate_whenCurrentDocHasNonNullDate() throws Exception {
+        // current.getDocumentDate() != null = true → ternary true branch in computeChangedFields
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no date in previous
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        // Current doc has a non-null documentDate → ternary evaluates its true branch
+        Document updated = Document.builder().id(docId).title("T")
+                .documentDate(LocalDate.of(1965, 3, 12)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("documentDate");
+    }
+
+    // ─── checkReceivers / checkTags — when previous snapshot has null values ───
+
+    @Test
+    void recordVersion_tracksReceivers_whenPreviousSnapshotHasNullReceivers() throws Exception {
+        // prevReceivers NOT instanceof List<?> → prevIds = Set.of() → if currentIds differ → added
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        // Craft snapshot where "receivers" is JSON null → deserialized as null, NOT a List
+        String oldSnapshot = "{\"id\":\"" + docId + "\",\"title\":\"T\",\"receivers\":null,\"tags\":[]}";
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person r = Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build();
+        Document updated = Document.builder().id(docId).title("T").receivers(Set.of(r)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("receivers");
+    }
+
+    @Test
+    void recordVersion_tracksTags_whenPreviousSnapshotHasNullTags() throws Exception {
+        // prevTags NOT instanceof List<?> → prevNames = Set.of() → if currentNames differ → added
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        // Craft snapshot where "tags" is JSON null → deserialized as null, NOT a List
+        String oldSnapshot = "{\"id\":\"" + docId + "\",\"title\":\"T\",\"receivers\":[],\"tags\":null}";
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+        Document updated = Document.builder().id(docId).title("T").tags(Set.of(tag)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("tags");
+    }
+
+    // ─── backfill — uses LocalDateTime.now() when createdAt is null ──────────
+
+    @Test
+    void backfill_usesNow_whenDocumentCreatedAtIsNull() {
+        Document doc = Document.builder().id(UUID.randomUUID()).title("T").createdAt(null).build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(doc.getId())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.backfillMissingVersions(List.of(doc));
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getSavedAt()).isNotNull();
+    }
+
     // ─── helpers ──────────────────────────────────────────────────────────────
 
     private void authenticateAs(String username) {

backend/src/test/java/org/raddatz/familienarchiv/service/FileServiceTest.java

@@ -4,15 +4,23 @@ import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.mockito.ArgumentCaptor;
 import org.springframework.mock.web.MockMultipartFile;
+import software.amazon.awssdk.core.ResponseInputStream;
 import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.http.AbortableInputStream;
 import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.GetObjectResponse;
+import software.amazon.awssdk.services.s3.model.NoSuchKeyException;
 import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+import software.amazon.awssdk.services.s3.model.S3Exception;
 
+import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.*;
 
@@ -82,4 +90,111 @@ class FileServiceTest {
 
         assertThat(r1.fileHash()).isEqualTo(r2.fileHash());
     }
+
+    @Test
+    void uploadFile_throwsIOException_whenS3Throws() {
+        MockMultipartFile file = new MockMultipartFile("f", "fail.pdf", "application/pdf", new byte[]{1});
+        S3Exception s3ex = (S3Exception) S3Exception.builder().message("bucket error").statusCode(500).build();
+        when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class))).thenThrow(s3ex);
+
+        assertThatThrownBy(() -> fileService.uploadFile(file, "fail.pdf"))
+                .isInstanceOf(IOException.class)
+                .hasMessageContaining("Failed to upload");
+    }
+
+    // ─── downloadFile ─────────────────────────────────────────────────────────
+
+    @Test
+    void downloadFile_returnsResourceWithContentType() {
+        byte[] content = "pdf content".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().contentType("application/pdf").build();
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        FileService.S3FileDownload result = fileService.downloadFile("documents/test.pdf");
+
+        assertThat(result.contentType()).isEqualTo("application/pdf");
+        assertThat(result.resource()).isNotNull();
+    }
+
+    @Test
+    void downloadFile_fallsBackToOctetStream_whenContentTypeIsBlank() {
+        byte[] content = "data".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().contentType("   ").build();
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        FileService.S3FileDownload result = fileService.downloadFile("documents/file");
+
+        assertThat(result.contentType()).isEqualTo("application/octet-stream");
+    }
+
+    @Test
+    void downloadFile_fallsBackToOctetStream_whenContentTypeIsNull() {
+        byte[] content = "data".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().build(); // no contentType
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        FileService.S3FileDownload result = fileService.downloadFile("documents/file");
+
+        assertThat(result.contentType()).isEqualTo("application/octet-stream");
+    }
+
+    @Test
+    void downloadFile_throwsStorageFileNotFoundException_whenNoSuchKey() {
+        NoSuchKeyException ex = NoSuchKeyException.builder().message("not found").statusCode(404).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFile("missing/key.pdf"))
+                .isInstanceOf(FileService.StorageFileNotFoundException.class)
+                .hasMessageContaining("missing/key.pdf");
+    }
+
+    @Test
+    void downloadFile_throwsRuntimeException_whenS3Exception() {
+        S3Exception ex = (S3Exception) S3Exception.builder().message("storage error").statusCode(503).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFile("documents/file.pdf"))
+                .isInstanceOf(RuntimeException.class)
+                .hasMessageContaining("Storage Error");
+    }
+
+    // ─── downloadFileBytes ────────────────────────────────────────────────────
+
+    @Test
+    void downloadFileBytes_returnsRawBytes() throws IOException {
+        byte[] content = "raw bytes".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().build();
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        byte[] result = fileService.downloadFileBytes("documents/file.pdf");
+
+        assertThat(result).isEqualTo(content);
+    }
+
+    @Test
+    void downloadFileBytes_throwsStorageFileNotFoundException_whenNoSuchKey() {
+        NoSuchKeyException ex = NoSuchKeyException.builder().message("not found").statusCode(404).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFileBytes("missing/key.pdf"))
+                .isInstanceOf(FileService.StorageFileNotFoundException.class);
+    }
+
+    @Test
+    void downloadFileBytes_throwsIOException_whenS3Exception() {
+        S3Exception ex = (S3Exception) S3Exception.builder().message("storage error").statusCode(503).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFileBytes("documents/file.pdf"))
+                .isInstanceOf(IOException.class)
+                .hasMessageContaining("Failed to download");
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/service/MassImportServiceTest.java

@@ -0,0 +1,504 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.Tag;
+import org.raddatz.familienarchiv.repository.DocumentRepository;
+import org.springframework.test.util.ReflectionTestUtils;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+
+import java.io.File;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class MassImportServiceTest {
+
+    @Mock DocumentRepository documentRepository;
+    @Mock PersonService personService;
+    @Mock TagService tagService;
+    @Mock S3Client s3Client;
+
+    MassImportService service;
+
+    @BeforeEach
+    void setUp() {
+        service = new MassImportService(documentRepository, personService, tagService, s3Client);
+        ReflectionTestUtils.setField(service, "bucketName", "test-bucket");
+        ReflectionTestUtils.setField(service, "colIndex", 0);
+        ReflectionTestUtils.setField(service, "colBox", 1);
+        ReflectionTestUtils.setField(service, "colFolder", 2);
+        ReflectionTestUtils.setField(service, "colSender", 3);
+        ReflectionTestUtils.setField(service, "colReceivers", 5);
+        ReflectionTestUtils.setField(service, "colDate", 7);
+        ReflectionTestUtils.setField(service, "colLocation", 9);
+        ReflectionTestUtils.setField(service, "colTags", 10);
+        ReflectionTestUtils.setField(service, "colSummary", 11);
+        ReflectionTestUtils.setField(service, "colTranscription", 13);
+    }
+
+    // ─── getStatus ────────────────────────────────────────────────────────────
+
+    @Test
+    void getStatus_returnsIdleByDefault() {
+        assertThat(service.getStatus().state()).isEqualTo(MassImportService.State.IDLE);
+    }
+
+    // ─── runImportAsync ───────────────────────────────────────────────────────
+
+    @Test
+    void runImportAsync_setsFailedStatus_whenImportDirectoryDoesNotExist() {
+        // /import directory doesn't exist in test environment → findSpreadsheetFile throws
+        service.runImportAsync();
+
+        assertThat(service.getStatus().state()).isEqualTo(MassImportService.State.FAILED);
+    }
+
+    @Test
+    void runImportAsync_throwsConflict_whenAlreadyRunning() {
+        MassImportService.ImportStatus running = new MassImportService.ImportStatus(
+                MassImportService.State.RUNNING, "Running...", 0, LocalDateTime.now());
+        ReflectionTestUtils.setField(service, "currentStatus", running);
+
+        assertThatThrownBy(() -> service.runImportAsync())
+                .isInstanceOf(DomainException.class)
+                .hasMessageContaining("already in progress");
+    }
+
+    // ─── importSingleDocument — skip already uploaded ─────────────────────────
+
+    @Test
+    void importSingleDocument_skips_whenDocumentAlreadyUploadedNotPlaceholder() {
+        Document existing = Document.builder()
+                .id(UUID.randomUUID())
+                .originalFilename("doc001.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .build();
+        when(documentRepository.findByOriginalFilename("doc001.pdf")).thenReturn(Optional.of(existing));
+
+        service.importSingleDocument(minimalCells("doc001.pdf"), Optional.empty(), "doc001.pdf", "doc001");
+
+        verify(documentRepository, never()).save(any());
+    }
+
+    // ─── importSingleDocument — create new document (metadata only) ───────────
+
+    @Test
+    void importSingleDocument_createsNewDocument_whenNotExists() {
+        when(documentRepository.findByOriginalFilename("doc002.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        service.importSingleDocument(minimalCells("doc002.pdf"), Optional.empty(), "doc002.pdf", "doc002");
+
+        verify(documentRepository).save(argThat(d ->
+                d.getOriginalFilename().equals("doc002.pdf")
+                        && d.getStatus() == DocumentStatus.PLACEHOLDER));
+    }
+
+    // ─── importSingleDocument — update existing placeholder ──────────────────
+
+    @Test
+    void importSingleDocument_updatesExistingPlaceholder() {
+        Document placeholder = Document.builder()
+                .id(UUID.randomUUID())
+                .originalFilename("existing.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build();
+        when(documentRepository.findByOriginalFilename("existing.pdf")).thenReturn(Optional.of(placeholder));
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        service.importSingleDocument(minimalCells("existing.pdf"), Optional.empty(), "existing.pdf", "existing");
+
+        verify(documentRepository).save(same(placeholder));
+    }
+
+    // ─── importSingleDocument — with file (S3 upload) ─────────────────────────
+
+    @Test
+    void importSingleDocument_uploadsFileToS3_andSetsStatusUploaded(@TempDir Path tempDir) throws Exception {
+        Path tempFile = tempDir.resolve("doc003.pdf");
+        Files.write(tempFile, "PDF content".getBytes());
+
+        when(documentRepository.findByOriginalFilename("doc003.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        service.importSingleDocument(
+                minimalCells("doc003.pdf"), Optional.of(tempFile.toFile()), "doc003.pdf", "doc003");
+
+        verify(s3Client).putObject(any(PutObjectRequest.class), any(RequestBody.class));
+        verify(documentRepository).save(argThat(d -> d.getStatus() == DocumentStatus.UPLOADED));
+    }
+
+    @Test
+    void importSingleDocument_returnsEarly_whenS3UploadFails(@TempDir Path tempDir) throws Exception {
+        Path tempFile = tempDir.resolve("fail.pdf");
+        Files.write(tempFile, "data".getBytes());
+
+        when(documentRepository.findByOriginalFilename("fail.pdf")).thenReturn(Optional.empty());
+        doThrow(new RuntimeException("S3 error"))
+                .when(s3Client).putObject(any(PutObjectRequest.class), any(RequestBody.class));
+
+        service.importSingleDocument(
+                minimalCells("fail.pdf"), Optional.of(tempFile.toFile()), "fail.pdf", "fail");
+
+        verify(documentRepository, never()).save(any());
+    }
+
+    // ─── importSingleDocument — sender handling ───────────────────────────────
+
+    @Test
+    void importSingleDocument_setsNullSender_whenSenderCellIsBlank() {
+        when(documentRepository.findByOriginalFilename("nosender.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        List<String> cells = buildCells("nosender.pdf", "", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "nosender.pdf", "nosender");
+
+        verify(documentRepository).save(argThat(d -> d.getSender() == null));
+        verify(personService, never()).findOrCreateByAlias(any());
+    }
+
+    @Test
+    void importSingleDocument_createsSender_whenSenderCellIsNonBlank() {
+        Person sender = Person.builder().id(UUID.randomUUID()).firstName("Walter").lastName("Müller").build();
+        when(documentRepository.findByOriginalFilename("withsender.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(personService.findOrCreateByAlias("Walter Müller")).thenReturn(sender);
+
+        List<String> cells = buildCells("withsender.pdf", "Walter Müller", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "withsender.pdf", "withsender");
+
+        verify(personService).findOrCreateByAlias("Walter Müller");
+        verify(documentRepository).save(argThat(d -> d.getSender() == sender));
+    }
+
+    // ─── importSingleDocument — tag handling ─────────────────────────────────
+
+    @Test
+    void importSingleDocument_createsTag_whenTagCellIsNonBlank() {
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+        when(documentRepository.findByOriginalFilename("tagged.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(tagService.findOrCreate("Familie")).thenReturn(tag);
+
+        List<String> cells = buildCells("tagged.pdf", "", "", "Familie");
+        service.importSingleDocument(cells, Optional.empty(), "tagged.pdf", "tagged");
+
+        verify(tagService).findOrCreate("Familie");
+    }
+
+    @Test
+    void importSingleDocument_doesNotCreateTag_whenTagCellIsBlank() {
+        when(documentRepository.findByOriginalFilename("notag.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        List<String> cells = buildCells("notag.pdf", "", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "notag.pdf", "notag");
+
+        verify(tagService, never()).findOrCreate(any());
+    }
+
+    // ─── importSingleDocument — metadataComplete heuristic ───────────────────
+
+    @Test
+    void importSingleDocument_metadataComplete_whenSenderPresent() {
+        Person sender = Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build();
+        when(documentRepository.findByOriginalFilename("meta.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(personService.findOrCreateByAlias("A B")).thenReturn(sender);
+
+        List<String> cells = buildCells("meta.pdf", "A B", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "meta.pdf", "meta");
+
+        verify(documentRepository).save(argThat(Document::isMetadataComplete));
+    }
+
+    @Test
+    void importSingleDocument_metadataIncomplete_whenNoKeyFieldsPresent() {
+        when(documentRepository.findByOriginalFilename("nometa.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        List<String> cells = buildCells("nometa.pdf", "", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "nometa.pdf", "nometa");
+
+        verify(documentRepository).save(argThat(d -> !d.isMetadataComplete()));
+    }
+
+    // ─── importSingleDocument — blank fields set to null ─────────────────────
+
+    @Test
+    void importSingleDocument_setsBlankFieldsToNull() {
+        when(documentRepository.findByOriginalFilename("blank.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        List<String> cells = buildCells("blank.pdf", "", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "blank.pdf", "blank");
+
+        verify(documentRepository).save(argThat(d ->
+                d.getLocation() == null &&
+                d.getSummary() == null &&
+                d.getTranscription() == null &&
+                d.getArchiveBox() == null &&
+                d.getArchiveFolder() == null));
+    }
+
+    // ─── processRows — via ReflectionTestUtils ────────────────────────────────
+
+    @Test
+    void processRows_returnsZero_whenOnlyHeaderRow() {
+        List<List<String>> rows = List.of(List.of("header", "col1"));
+        Integer result = ReflectionTestUtils.invokeMethod(service, "processRows", rows);
+        assertThat(result).isEqualTo(0);
+    }
+
+    @Test
+    void processRows_skipsRowWithBlankIndex() {
+        List<List<String>> rows = List.of(
+                List.of("header"),
+                minimalCells("")  // blank index
+        );
+        Integer result = ReflectionTestUtils.invokeMethod(service, "processRows", rows);
+        assertThat(result).isEqualTo(0);
+        verify(documentRepository, never()).findByOriginalFilename(any());
+    }
+
+    @Test
+    void processRows_addsExtension_whenIndexHasNoDot() {
+        when(documentRepository.findByOriginalFilename("doc001.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        List<List<String>> rows = List.of(
+                List.of("header"),
+                minimalCells("doc001")  // no dot → appends ".pdf"
+        );
+        Integer result = ReflectionTestUtils.invokeMethod(service, "processRows", rows);
+
+        assertThat(result).isEqualTo(1);
+        verify(documentRepository).findByOriginalFilename("doc001.pdf");
+    }
+
+    @Test
+    void processRows_usesFilenameAsIs_whenIndexHasDot() {
+        when(documentRepository.findByOriginalFilename("doc002.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        List<List<String>> rows = List.of(
+                List.of("header"),
+                minimalCells("doc002.pdf")  // has dot → used as-is
+        );
+        Integer result = ReflectionTestUtils.invokeMethod(service, "processRows", rows);
+
+        assertThat(result).isEqualTo(1);
+        verify(documentRepository).findByOriginalFilename("doc002.pdf");
+    }
+
+    // ─── importSingleDocument — non-blank optional fields ────────────────────
+
+    @Test
+    void importSingleDocument_setsNonNullOptionalFields_whenPresent() {
+        when(documentRepository.findByOriginalFilename("rich.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        // box=1, folder=2, location=9, summary=11, transcription=13
+        List<String> cells = List.of(
+                "rich.pdf",      // 0: index
+                "Box A",         // 1: box
+                "Folder B",      // 2: folder
+                "",              // 3: sender
+                "",              // 4: unused
+                "",              // 5: receivers
+                "",              // 6: unused
+                "",              // 7: date
+                "",              // 8: unused
+                "Hamburg",       // 9: location
+                "",              // 10: tags
+                "A summary",     // 11: summary
+                "",              // 12: unused
+                "A transcript"   // 13: transcription
+        );
+
+        service.importSingleDocument(cells, Optional.empty(), "rich.pdf", "rich");
+
+        verify(documentRepository).save(argThat(d ->
+                "Box A".equals(d.getArchiveBox()) &&
+                "Folder B".equals(d.getArchiveFolder()) &&
+                "Hamburg".equals(d.getLocation()) &&
+                "A summary".equals(d.getSummary()) &&
+                "A transcript".equals(d.getTranscription())));
+    }
+
+    @Test
+    void importSingleDocument_setsMetadataComplete_whenReceiversArePresent() {
+        Person receiver = Person.builder().id(UUID.randomUUID()).firstName("Walter").lastName("Müller").build();
+        when(documentRepository.findByOriginalFilename("rcv.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(personService.findOrCreateByAlias("Walter Müller")).thenReturn(receiver);
+
+        List<String> cells = List.of(
+                "rcv.pdf", "", "", "", "", "Walter Müller", "", "", "", "", "", "", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "rcv.pdf", "rcv");
+
+        verify(documentRepository).save(argThat(Document::isMetadataComplete));
+    }
+
+    @Test
+    void importSingleDocument_setsMetadataComplete_whenDateIsPresent() {
+        when(documentRepository.findByOriginalFilename("dated.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        List<String> cells = List.of(
+                "dated.pdf", "", "", "", "", "", "", "2024-03-15", "", "", "", "", "", "");
+        service.importSingleDocument(cells, Optional.empty(), "dated.pdf", "dated");
+
+        verify(documentRepository).save(argThat(Document::isMetadataComplete));
+    }
+
+    // ─── buildTitle — null location ───────────────────────────────────────────
+
+    @Test
+    void buildTitle_withNullLocation_skipsLocationPart() {
+        String result = ReflectionTestUtils.invokeMethod(service, "buildTitle",
+                "doc005", LocalDate.of(1940, 5, 1), (String) null);
+        assertThat(result).contains("doc005").contains("1940");
+        assertThat(result).doesNotContain("Berlin");
+    }
+
+    // ─── parseDate — via ReflectionTestUtils ─────────────────────────────────
+
+    @Test
+    void parseDate_returnsNull_whenValueIsNull() {
+        LocalDate result = ReflectionTestUtils.invokeMethod(service, "parseDate", (String) null);
+        assertThat(result).isNull();
+    }
+
+    @Test
+    void parseDate_returnsNull_whenValueIsBlank() {
+        LocalDate result = ReflectionTestUtils.invokeMethod(service, "parseDate", "   ");
+        assertThat(result).isNull();
+    }
+
+    @Test
+    void parseDate_returnsDate_whenValidIsoFormat() {
+        LocalDate result = ReflectionTestUtils.invokeMethod(service, "parseDate", "2024-03-15");
+        assertThat(result).isEqualTo(LocalDate.of(2024, 3, 15));
+    }
+
+    @Test
+    void parseDate_returnsNull_whenInvalidDateString() {
+        LocalDate result = ReflectionTestUtils.invokeMethod(service, "parseDate", "15.03.2024");
+        assertThat(result).isNull();
+    }
+
+    // ─── buildTitle — via ReflectionTestUtils ────────────────────────────────
+
+    @Test
+    void buildTitle_withDateAndLocation() {
+        String result = ReflectionTestUtils.invokeMethod(service, "buildTitle",
+                "doc001", LocalDate.of(1940, 5, 1), "Berlin");
+        assertThat(result).contains("doc001").contains("Berlin").contains("1940");
+    }
+
+    @Test
+    void buildTitle_withDateOnly() {
+        String result = ReflectionTestUtils.invokeMethod(service, "buildTitle",
+                "doc002", LocalDate.of(1960, 8, 15), "");
+        assertThat(result).contains("doc002").contains("1960");
+        assertThat(result).doesNotContain("Berlin");
+    }
+
+    @Test
+    void buildTitle_withIndexOnly_whenDateAndLocationAreNull() {
+        String result = ReflectionTestUtils.invokeMethod(service, "buildTitle",
+                "doc003", null, "");
+        assertThat(result).isEqualTo("doc003");
+    }
+
+    @Test
+    void buildTitle_withLocationOnly_whenDateIsNull() {
+        // date=null, location present → date part skipped, location appended
+        String result = ReflectionTestUtils.invokeMethod(service, "buildTitle",
+                "doc004", null, "Berlin");
+        assertThat(result).contains("doc004").contains("Berlin");
+        assertThat(result).doesNotContain("("); // no date part
+    }
+
+    // ─── getCell — via ReflectionTestUtils ───────────────────────────────────
+
+    @Test
+    void getCell_returnsEmptyString_whenColBeyondListSize() {
+        List<String> cells = List.of("a", "b");
+        String result = ReflectionTestUtils.invokeMethod(service, "getCell", cells, 5);
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void getCell_returnsEmptyString_whenValueIsNull() {
+        List<String> cells = new ArrayList<>();
+        cells.add(null);
+        cells.add("b");
+        String result = ReflectionTestUtils.invokeMethod(service, "getCell", cells, 0);
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void getCell_returnsTrimmedValue() {
+        List<String> cells = List.of("  hello  ", "world");
+        String result = ReflectionTestUtils.invokeMethod(service, "getCell", cells, 0);
+        assertThat(result).isEqualTo("hello");
+    }
+
+    // ─── helpers ──────────────────────────────────────────────────────────────
+
+    /**
+     * Builds a minimal 14-element cell row with the given filename at index 0
+     * and blanks for all optional fields.
+     */
+    private List<String> minimalCells(String filename) {
+        return buildCells(filename, "", "", "");
+    }
+
+    /**
+     * Builds a cell row with sender, receiver, and tag controls.
+     * Layout matches the default column indices set in setUp().
+     */
+    private List<String> buildCells(String filename, String sender, String receivers, String tag) {
+        // 14 elements: index=0,box=1,folder=2,sender=3,[4],receivers=5,[6],date=7,[8],location=9,tag=10,summary=11,[12],transcription=13
+        return List.of(
+                filename,  // 0: index
+                "",        // 1: box
+                "",        // 2: folder
+                sender,    // 3: sender
+                "",        // 4: (unused)
+                receivers, // 5: receivers
+                "",        // 6: (unused)
+                "",        // 7: date
+                "",        // 8: (unused)
+                "",        // 9: location
+                tag,       // 10: tags
+                "",        // 11: summary
+                "",        // 12: (unused)
+                ""         // 13: transcription
+        );
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/NotificationServiceTest.java

@@ -0,0 +1,416 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.dto.NotificationDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.model.*;
+import org.raddatz.familienarchiv.repository.NotificationRepository;
+import org.springframework.mail.MailException;
+import org.springframework.mail.MailSendException;
+import org.springframework.mail.SimpleMailMessage;
+import org.springframework.mail.javamail.JavaMailSender;
+
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class NotificationServiceTest {
+
+    @Mock NotificationRepository notificationRepository;
+    @Mock UserService userService;
+    @Mock JavaMailSender mailSender;
+    @Mock SseEmitterRegistry sseEmitterRegistry;
+
+    NotificationService notificationService;
+
+    private AppUser userA;
+    private AppUser userB;
+    private AppUser userC;
+
+    @BeforeEach
+    void setUp() {
+        notificationService = new NotificationService(notificationRepository, userService, Optional.of(mailSender), sseEmitterRegistry);
+
+        userA = AppUser.builder().id(UUID.randomUUID()).username("userA")
+                .firstName("Anna").lastName("Smith").email("a@test.com")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        userB = AppUser.builder().id(UUID.randomUUID()).username("userB")
+                .firstName("Bob").lastName("Jones").email("b@test.com")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        userC = AppUser.builder().id(UUID.randomUUID()).username("userC")
+                .firstName("Clara").lastName("Doe").email("c@test.com")
+                .notifyOnReply(false).notifyOnMention(false).build();
+    }
+
+    // ─── notifyReply ──────────────────────────────────────────────────────────
+
+    @Test
+    void notifyReply_createsNotificationForThreadParticipants() {
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(Set.of(userA.getId(), userB.getId()))).thenReturn(List.of(userA, userB));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyReply(reply, Set.of(userA.getId(), userB.getId()));
+
+        ArgumentCaptor<Notification> captor = ArgumentCaptor.forClass(Notification.class);
+        verify(notificationRepository, times(2)).save(captor.capture());
+
+        List<Notification> saved = captor.getAllValues();
+        assertThat(saved).extracting(n -> n.getRecipient().getId())
+                .containsExactlyInAnyOrder(userA.getId(), userB.getId());
+        assertThat(saved).allMatch(n -> n.getType() == NotificationType.REPLY);
+        assertThat(saved).allMatch(n -> !n.isRead());
+        assertThat(saved).allMatch(n -> "Clara Doe".equals(n.getActorName()));
+    }
+
+    @Test
+    void notifyReply_doesNothing_whenParticipantSetIsEmpty() {
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userA.getId(), "Anna Smith");
+
+        notificationService.notifyReply(reply, Set.of());
+
+        verify(notificationRepository, never()).save(any());
+    }
+
+    @Test
+    void notifyReply_sendsEmailOnlyToUsersWithReplyNotificationsEnabled() {
+        userA.setNotifyOnReply(true);
+        userB.setNotifyOnReply(false);
+
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(Set.of(userA.getId(), userB.getId()))).thenReturn(List.of(userA, userB));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyReply(reply, Set.of(userA.getId(), userB.getId()));
+
+        verify(mailSender, times(1)).send(any(SimpleMailMessage.class));
+    }
+
+    // ─── notifyMentions ───────────────────────────────────────────────────────
+
+    @Test
+    void notifyMentions_createsNotificationPerMentionedUser() {
+        DocumentComment comment = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+        when(userService.findAllById(List.of(userA.getId(), userB.getId()))).thenReturn(List.of(userA, userB));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyMentions(List.of(userA.getId(), userB.getId()), comment);
+
+        ArgumentCaptor<Notification> captor = ArgumentCaptor.forClass(Notification.class);
+        verify(notificationRepository, times(2)).save(captor.capture());
+
+        List<Notification> saved = captor.getAllValues();
+        assertThat(saved).extracting(n -> n.getRecipient().getId())
+                .containsExactlyInAnyOrder(userA.getId(), userB.getId());
+        assertThat(saved).allMatch(n -> n.getType() == NotificationType.MENTION);
+        assertThat(saved).allMatch(n -> "Clara Doe".equals(n.getActorName()));
+    }
+
+    @Test
+    void notifyMentions_doesNothing_whenListIsEmpty() {
+        DocumentComment comment = commentWithAuthor(UUID.randomUUID(), null, userA.getId(), "Anna Smith");
+
+        notificationService.notifyMentions(List.of(), comment);
+
+        verify(notificationRepository, never()).save(any());
+    }
+
+    @Test
+    void notifyMentions_sendsEmailOnlyToUsersWithMentionNotificationsEnabled() {
+        userA.setNotifyOnMention(true);
+        userB.setNotifyOnMention(false);
+
+        DocumentComment comment = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+        when(userService.findAllById(List.of(userA.getId(), userB.getId()))).thenReturn(List.of(userA, userB));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyMentions(List.of(userA.getId(), userB.getId()), comment);
+
+        verify(mailSender, times(1)).send(any(SimpleMailMessage.class));
+    }
+
+    // ─── SSE push ─────────────────────────────────────────────────────────────
+
+    @Test
+    void notifyReply_pushesEventToRegistry_forEachRecipient() {
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(Set.of(userA.getId(), userB.getId()))).thenReturn(List.of(userA, userB));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyReply(reply, Set.of(userA.getId(), userB.getId()));
+
+        verify(sseEmitterRegistry).send(eq(userA.getId()), any(NotificationDTO.class));
+        verify(sseEmitterRegistry).send(eq(userB.getId()), any(NotificationDTO.class));
+    }
+
+    @Test
+    void notifyMentions_pushesEventToRegistry_forEachMentionedUser() {
+        DocumentComment comment = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(List.of(userA.getId(), userB.getId()))).thenReturn(List.of(userA, userB));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyMentions(List.of(userA.getId(), userB.getId()), comment);
+
+        verify(sseEmitterRegistry).send(eq(userA.getId()), any(NotificationDTO.class));
+        verify(sseEmitterRegistry).send(eq(userB.getId()), any(NotificationDTO.class));
+    }
+
+    // ─── markRead ─────────────────────────────────────────────────────────────
+
+    @Test
+    void markRead_throwsNotFound_whenNotificationDoesNotExist() {
+        UUID notifId = UUID.randomUUID();
+        when(notificationRepository.findById(notifId)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> notificationService.markRead(notifId, userA.getId()))
+                .isInstanceOf(DomainException.class)
+                .hasMessageContaining("Notification not found");
+    }
+
+    @Test
+    void markRead_throwsForbidden_whenNotificationBelongsToDifferentUser() {
+        Notification notification = Notification.builder()
+                .id(UUID.randomUUID())
+                .recipient(userA)
+                .type(NotificationType.REPLY)
+                .read(false)
+                .build();
+
+        when(notificationRepository.findById(notification.getId())).thenReturn(Optional.of(notification));
+
+        assertThatThrownBy(() -> notificationService.markRead(notification.getId(), userB.getId()))
+                .isInstanceOf(DomainException.class)
+                .hasMessageContaining("different user");
+    }
+
+    // ─── markAllRead ──────────────────────────────────────────────────────────
+
+    @Test
+    void markAllRead_delegatesToRepository() {
+        notificationService.markAllRead(userA.getId());
+
+        verify(notificationRepository).markAllReadByRecipientId(userA.getId());
+    }
+
+    // ─── markRead — happy path ────────────────────────────────────────────────
+
+    @Test
+    void markRead_marksNotificationAsRead_whenRecipientMatches() {
+        Notification notification = Notification.builder()
+                .id(UUID.randomUUID())
+                .recipient(userA)
+                .type(NotificationType.REPLY)
+                .documentId(UUID.randomUUID())
+                .referenceId(UUID.randomUUID())
+                .read(false)
+                .build();
+        when(notificationRepository.findById(notification.getId())).thenReturn(Optional.of(notification));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        NotificationDTO result = notificationService.markRead(notification.getId(), userA.getId());
+
+        assertThat(result).isNotNull();
+        assertThat(notification.isRead()).isTrue();
+    }
+
+    // ─── countUnread ──────────────────────────────────────────────────────────
+
+    @Test
+    void countUnread_delegatesToRepository() {
+        when(notificationRepository.countByRecipientIdAndReadFalse(userA.getId())).thenReturn(3L);
+
+        assertThat(notificationService.countUnread(userA.getId())).isEqualTo(3L);
+    }
+
+    // ─── notifyMentions — null list ───────────────────────────────────────────
+
+    @Test
+    void notifyMentions_doesNothing_whenMentionedUserIdsIsNull() {
+        DocumentComment comment = commentWithAuthor(UUID.randomUUID(), null, userA.getId(), "Anna Smith");
+
+        notificationService.notifyMentions(null, comment);
+
+        verify(notificationRepository, never()).save(any());
+    }
+
+    // ─── email — no mailSender ────────────────────────────────────────────────
+
+    @Test
+    void notifyReply_skipsEmail_whenMailSenderIsAbsent() {
+        NotificationService serviceWithoutMail = new NotificationService(
+                notificationRepository, userService, Optional.empty(), sseEmitterRegistry);
+
+        userA.setNotifyOnReply(true);
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(Set.of(userA.getId()))).thenReturn(List.of(userA));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        serviceWithoutMail.notifyReply(reply, Set.of(userA.getId()));
+
+        verify(mailSender, never()).send(any(SimpleMailMessage.class));
+    }
+
+    @Test
+    void notifyMentions_skipsEmail_whenMailSenderIsAbsent() {
+        NotificationService serviceWithoutMail = new NotificationService(
+                notificationRepository, userService, Optional.empty(), sseEmitterRegistry);
+
+        userA.setNotifyOnMention(true);
+        DocumentComment comment = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(List.of(userA.getId()))).thenReturn(List.of(userA));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        serviceWithoutMail.notifyMentions(List.of(userA.getId()), comment);
+
+        verify(mailSender, never()).send(any(SimpleMailMessage.class));
+    }
+
+    // ─── email — recipient email missing ─────────────────────────────────────
+
+    @Test
+    void notifyReply_skipsEmail_whenRecipientEmailIsNull() {
+        userA.setNotifyOnReply(true);
+        userA.setEmail(null);
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(Set.of(userA.getId()))).thenReturn(List.of(userA));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyReply(reply, Set.of(userA.getId()));
+
+        verify(mailSender, never()).send(any(SimpleMailMessage.class));
+    }
+
+    @Test
+    void notifyReply_skipsEmail_whenRecipientEmailIsBlank() {
+        userA.setNotifyOnReply(true);
+        userA.setEmail("   ");
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(Set.of(userA.getId()))).thenReturn(List.of(userA));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyReply(reply, Set.of(userA.getId()));
+
+        verify(mailSender, never()).send(any(SimpleMailMessage.class));
+    }
+
+    // ─── email — MailException swallowed ─────────────────────────────────────
+
+    @Test
+    void notifyReply_doesNotThrow_whenMailExceptionOccurs() {
+        userA.setNotifyOnReply(true);
+        DocumentComment reply = commentWithAuthor(UUID.randomUUID(), null, userC.getId(), "Clara Doe");
+
+        when(userService.findAllById(Set.of(userA.getId()))).thenReturn(List.of(userA));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        doThrow(new MailSendException("SMTP down")).when(mailSender).send(any(SimpleMailMessage.class));
+
+        // Must not throw — MailException is caught and logged
+        notificationService.notifyReply(reply, Set.of(userA.getId()));
+
+        verify(mailSender).send(any(SimpleMailMessage.class));
+    }
+
+    // ─── email — annotationId included in link ────────────────────────────────
+
+    @Test
+    void notifyReply_includesAnnotationIdInEmailLink_whenAnnotationPresent() {
+        userA.setNotifyOnReply(true);
+        UUID annotationId = UUID.randomUUID();
+        DocumentComment reply = DocumentComment.builder()
+                .id(UUID.randomUUID())
+                .documentId(UUID.randomUUID())
+                .annotationId(annotationId)
+                .authorId(userC.getId())
+                .authorName("Clara Doe")
+                .content("reply")
+                .build();
+
+        when(userService.findAllById(Set.of(userA.getId()))).thenReturn(List.of(userA));
+        when(notificationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        notificationService.notifyReply(reply, Set.of(userA.getId()));
+
+        ArgumentCaptor<SimpleMailMessage> captor = ArgumentCaptor.forClass(SimpleMailMessage.class);
+        verify(mailSender).send(captor.capture());
+        assertThat(captor.getValue().getText()).contains("annotationId=" + annotationId);
+    }
+
+    // ─── getNotifications — filter dispatch ──────────────────────────────────
+
+    @Test
+    void getNotifications_withNoFilters_usesUnfilteredRepoMethod() {
+        when(notificationRepository.findByRecipientIdOrderByCreatedAtDesc(eq(userA.getId()), any()))
+                .thenReturn(Page.empty());
+
+        notificationService.getNotifications(userA.getId(), null, null, Pageable.ofSize(10));
+
+        verify(notificationRepository).findByRecipientIdOrderByCreatedAtDesc(eq(userA.getId()), any());
+        verify(notificationRepository, never())
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(any(), any(), any());
+    }
+
+    @Test
+    void getNotifications_withTypeAndReadFalse_usesFilteredRepoMethod() {
+        when(notificationRepository.findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                eq(userA.getId()), eq(NotificationType.MENTION), any()))
+                .thenReturn(Page.empty());
+
+        notificationService.getNotifications(userA.getId(), NotificationType.MENTION, false, Pageable.ofSize(3));
+
+        verify(notificationRepository).findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                eq(userA.getId()), eq(NotificationType.MENTION), any());
+        verify(notificationRepository, never()).findByRecipientIdOrderByCreatedAtDesc(any(), any());
+    }
+
+    @Test
+    void getNotifications_withTypeOnly_usesTypeFilteredRepoMethod() {
+        when(notificationRepository.findByRecipientIdAndTypeOrderByCreatedAtDesc(
+                eq(userA.getId()), eq(NotificationType.MENTION), any()))
+                .thenReturn(Page.empty());
+
+        notificationService.getNotifications(userA.getId(), NotificationType.MENTION, null, Pageable.ofSize(5));
+
+        verify(notificationRepository).findByRecipientIdAndTypeOrderByCreatedAtDesc(
+                eq(userA.getId()), eq(NotificationType.MENTION), any());
+        verify(notificationRepository, never()).findByRecipientIdOrderByCreatedAtDesc(any(), any());
+        verify(notificationRepository, never())
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(any(), any(), any());
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private DocumentComment commentWithAuthor(UUID id, UUID parentId, UUID authorId, String authorName) {
+        return DocumentComment.builder()
+                .id(id)
+                .documentId(UUID.randomUUID())
+                .parentId(parentId)
+                .authorId(authorId)
+                .authorName(authorName)
+                .content("content")
+                .build();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/PasswordResetServiceTest.java

@@ -7,6 +7,7 @@ import static org.mockito.ArgumentMatchers.argThat;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.doThrow;
 
 import java.time.LocalDateTime;
 import java.util.Optional;
@@ -23,8 +24,11 @@ import org.raddatz.familienarchiv.model.AppUser;
 import org.raddatz.familienarchiv.model.PasswordResetToken;
 import org.raddatz.familienarchiv.repository.AppUserRepository;
 import org.raddatz.familienarchiv.repository.PasswordResetTokenRepository;
+import org.springframework.mail.MailSendException;
+import org.springframework.mail.SimpleMailMessage;
 import org.springframework.mail.javamail.JavaMailSender;
 import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.test.util.ReflectionTestUtils;
 
 @ExtendWith(MockitoExtension.class)
 class PasswordResetServiceTest {
@@ -123,4 +127,62 @@ class PasswordResetServiceTest {
         assertThatThrownBy(() -> service.resetPassword(req))
                 .isInstanceOf(DomainException.class);
     }
+
+    @Test
+    void resetPassword_throwsForAlreadyUsedToken() {
+        AppUser user = makeUser("user@example.com");
+        PasswordResetToken token = PasswordResetToken.builder()
+                .token("usedtoken")
+                .user(user)
+                .expiresAt(LocalDateTime.now().plusHours(1))
+                .used(true) // already used
+                .build();
+        when(tokenRepository.findByToken("usedtoken")).thenReturn(Optional.of(token));
+
+        ResetPasswordRequest req = new ResetPasswordRequest();
+        req.setToken("usedtoken");
+        req.setNewPassword("newpass");
+
+        assertThatThrownBy(() -> service.resetPassword(req))
+                .isInstanceOf(DomainException.class);
+    }
+
+    // ─── requestReset — mail sending branches ─────────────────────────────────
+
+    @Test
+    void requestReset_skipsEmail_whenMailSenderIsNull() {
+        ReflectionTestUtils.setField(service, "mailSender", null);
+        AppUser user = makeUser("user@example.com");
+        when(userRepository.findByEmail("user@example.com")).thenReturn(Optional.of(user));
+
+        // Must not throw even without mail sender
+        service.requestReset("user@example.com", "http://localhost:3000");
+
+        verify(tokenRepository).save(any());
+        verify(mailSender, never()).send(any(SimpleMailMessage.class));
+    }
+
+    @Test
+    void requestReset_logsError_whenMailExceptionThrown() {
+        // mailSender is @Autowired(required=false) — not in constructor, so needs explicit injection
+        ReflectionTestUtils.setField(service, "mailSender", mailSender);
+        AppUser user = makeUser("user@example.com");
+        when(userRepository.findByEmail("user@example.com")).thenReturn(Optional.of(user));
+        doThrow(new MailSendException("SMTP error")).when(mailSender).send(any(SimpleMailMessage.class));
+
+        // Must not propagate the MailException
+        service.requestReset("user@example.com", "http://localhost:3000");
+
+        verify(tokenRepository).save(any());
+        verify(mailSender).send(any(SimpleMailMessage.class));
+    }
+
+    // ─── cleanupExpiredTokens ─────────────────────────────────────────────────
+
+    @Test
+    void cleanupExpiredTokens_delegatesToRepository() {
+        service.cleanupExpiredTokens();
+
+        verify(tokenRepository).deleteExpiredAndUsed(any(LocalDateTime.class));
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/service/PersonNameParserTest.java

@@ -117,4 +117,50 @@ class PersonNameParserTest {
         assertThat(result.firstName()).isEqualTo("?");
         assertThat(result.lastName()).isEqualTo("?");
     }
+
+    @Test
+    void split_blank_returnsPlaceholder() {
+        PersonNameParser.SplitName result = PersonNameParser.split("   ");
+        assertThat(result.firstName()).isEqualTo("?");
+        assertThat(result.lastName()).isEqualTo("?");
+    }
+
+    @Test
+    void split_onlyKnownLastName_firstNameFallsBackToCleaned() {
+        // "de Gruyter" alone → firstName would be blank after removing last name, so cleaned is used
+        PersonNameParser.SplitName result = PersonNameParser.split("de Gruyter");
+        assertThat(result.firstName()).isEqualTo("de Gruyter");
+        assertThat(result.lastName()).isEqualTo("de Gruyter");
+    }
+
+    // --- parseReceivers — shared last name with full-name part ─────────────────
+
+    @Test
+    void parseReceivers_partWithSpace_notAppended_whenParenLastNamePresent() {
+        // "Clara Cram und Hans (Müller)": Clara Cram already has a space → keep as-is
+        List<String> result = PersonNameParser.parseReceivers("Clara Cram und Hans (Müller)");
+        assertThat(result).containsExactlyInAnyOrder("Clara Cram", "Hans Müller");
+    }
+
+    @Test
+    void parseReceivers_partAlreadyFullName_notDistributed_fromLastSegmentLastName() {
+        // "Clara Cram und Eugenie de Gruyter": first part has its own name, no distribution
+        List<String> result = PersonNameParser.parseReceivers("Clara Cram und Eugenie de Gruyter");
+        assertThat(result).containsExactlyInAnyOrder("Clara Cram", "Eugenie de Gruyter");
+    }
+
+    @Test
+    void parseReceivers_returnsEmpty_whenAllPartsAreFamilie() {
+        // All parts filtered out → nameParts.isEmpty() = true → return List.of()
+        assertThat(PersonNameParser.parseReceivers("Familie und Familie")).isEmpty();
+    }
+
+    @Test
+    void parseReceivers_singleTokenKnownLastName_notDistributed() {
+        // "Müller und Herbert de Gruyter":
+        //   last segment = "Herbert de Gruyter" → detectedLastName = "de Gruyter"
+        //   "Müller": !contains(" ") = true BUT findKnownLastName("Müller") != null → else branch → kept as-is
+        List<String> result = PersonNameParser.parseReceivers("Müller und Herbert de Gruyter");
+        assertThat(result).containsExactlyInAnyOrder("Müller", "Herbert de Gruyter");
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/service/PersonServiceTest.java

@@ -47,6 +47,98 @@ class PersonServiceTest {
         assertThat(personService.getById(id)).isEqualTo(person);
     }
 
+    // ─── findAll ─────────────────────────────────────────────────────────────
+
+    @Test
+    void findAll_returnsAll_whenQueryIsNull() {
+        List<Person> expected = List.of(Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build());
+        when(personRepository.findAllByOrderByLastNameAscFirstNameAsc()).thenReturn(expected);
+
+        assertThat(personService.findAll(null)).isEqualTo(expected);
+        verify(personRepository).findAllByOrderByLastNameAscFirstNameAsc();
+        verify(personRepository, never()).searchByName(any());
+    }
+
+    @Test
+    void findAll_returnsAll_whenQueryIsBlank() {
+        List<Person> expected = List.of();
+        when(personRepository.findAllByOrderByLastNameAscFirstNameAsc()).thenReturn(expected);
+
+        assertThat(personService.findAll("   ")).isEqualTo(expected);
+        verify(personRepository).findAllByOrderByLastNameAscFirstNameAsc();
+        verify(personRepository, never()).searchByName(any());
+    }
+
+    @Test
+    void findAll_searchesByName_whenQueryIsNonBlank() {
+        List<Person> expected = List.of(Person.builder().id(UUID.randomUUID()).firstName("Anna").lastName("Müller").build());
+        when(personRepository.searchByName("Anna")).thenReturn(expected);
+
+        assertThat(personService.findAll("Anna")).isEqualTo(expected);
+        verify(personRepository).searchByName("Anna");
+        verify(personRepository, never()).findAllByOrderByLastNameAscFirstNameAsc();
+    }
+
+    // ─── createPerson ─────────────────────────────────────────────────────────
+
+    @Test
+    void createPerson_savesPersonWithNullAlias_whenAliasIsNull() {
+        when(personRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person result = personService.createPerson("Hans", "Müller", null);
+
+        assertThat(result.getAlias()).isNull();
+        verify(personRepository).save(argThat(p -> p.getFirstName().equals("Hans") && p.getAlias() == null));
+    }
+
+    @Test
+    void createPerson_savesPersonWithNullAlias_whenAliasIsBlank() {
+        when(personRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person result = personService.createPerson("Hans", "Müller", "   ");
+
+        assertThat(result.getAlias()).isNull();
+    }
+
+    @Test
+    void createPerson_savesTrimmedAlias_whenAliasIsNonBlank() {
+        when(personRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person result = personService.createPerson("Hans", "Müller", "  Hans Müller  ");
+
+        assertThat(result.getAlias()).isEqualTo("Hans Müller");
+    }
+
+    // ─── updatePerson (alias) ─────────────────────────────────────────────────
+
+    @Test
+    void updatePerson_setsNullAlias_whenAliasIsBlank() {
+        UUID id = UUID.randomUUID();
+        Person person = Person.builder().id(id).firstName("Anna").lastName("Alt").alias("old alias").build();
+        when(personRepository.findById(id)).thenReturn(Optional.of(person));
+        when(personRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        PersonUpdateDTO dto = new PersonUpdateDTO();
+        dto.setFirstName("Anna"); dto.setLastName("Alt"); dto.setAlias("   ");
+        Person result = personService.updatePerson(id, dto);
+
+        assertThat(result.getAlias()).isNull();
+    }
+
+    @Test
+    void updatePerson_setsTrimmedAlias_whenAliasIsNonBlank() {
+        UUID id = UUID.randomUUID();
+        Person person = Person.builder().id(id).firstName("Anna").lastName("Alt").build();
+        when(personRepository.findById(id)).thenReturn(Optional.of(person));
+        when(personRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        PersonUpdateDTO dto = new PersonUpdateDTO();
+        dto.setFirstName("Anna"); dto.setLastName("Alt"); dto.setAlias("  Anna Alt  ");
+        Person result = personService.updatePerson(id, dto);
+
+        assertThat(result.getAlias()).isEqualTo("Anna Alt");
+    }
+
     // ─── findOrCreateByAlias ─────────────────────────────────────────────────
 
     @Test
@@ -144,6 +236,22 @@ class PersonServiceTest {
                 .isEqualTo(400);
     }
 
+    @Test
+    void updatePerson_doesNotThrow_whenBirthYearNonNullButDeathYearIsNull() {
+        // Covers A && B short-circuit: birthYear != null (true) but deathYear == null (false) → no throw
+        UUID id = UUID.randomUUID();
+        Person person = Person.builder().id(id).firstName("Anna").lastName("Alt").build();
+        when(personRepository.findById(id)).thenReturn(Optional.of(person));
+        when(personRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        PersonUpdateDTO dto = new PersonUpdateDTO();
+        dto.setFirstName("Anna"); dto.setLastName("Alt"); dto.setBirthYear(1890); dto.setDeathYear(null);
+        Person result = personService.updatePerson(id, dto);
+
+        assertThat(result.getBirthYear()).isEqualTo(1890);
+        assertThat(result.getDeathYear()).isNull();
+    }
+
     @Test
     void updatePerson_allowsSameYear() {
         UUID id = UUID.randomUUID();

backend/src/test/java/org/raddatz/familienarchiv/service/SseEmitterRegistryTest.java

@@ -0,0 +1,47 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+
+class SseEmitterRegistryTest {
+
+    private final SseEmitterRegistry registry = new SseEmitterRegistry();
+
+    @Test
+    void register_returnsEmitter() {
+        SseEmitter emitter = registry.register(UUID.randomUUID());
+
+        assertThat(emitter).isNotNull();
+    }
+
+    @Test
+    void send_doesNothing_whenNoEmitterRegistered() {
+        assertThatCode(() -> registry.send(UUID.randomUUID(), "data"))
+                .doesNotThrowAnyException();
+    }
+
+    @Test
+    void register_replacesExistingEmitter_forSameUser() {
+        UUID userId = UUID.randomUUID();
+
+        SseEmitter first = registry.register(userId);
+        SseEmitter second = registry.register(userId);
+
+        assertThat(first).isNotSameAs(second);
+    }
+
+    @Test
+    void send_doesNotThrow_whenEmitterRegistered_andSendFails() {
+        // Registering an emitter without an active HTTP connection causes IOException on send
+        UUID userId = UUID.randomUUID();
+        registry.register(userId);
+
+        // Must not propagate the IOException — it's caught and the emitter is removed
+        assertThatCode(() -> registry.send(userId, "data")).doesNotThrowAnyException();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/UserSearchServiceTest.java

@@ -0,0 +1,67 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.repository.AppUserRepository;
+import org.springframework.data.domain.PageRequest;
+
+import java.util.List;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class UserSearchServiceTest {
+
+    @Mock AppUserRepository userRepository;
+    @InjectMocks UserSearchService userSearchService;
+
+    // ─── search ───────────────────────────────────────────────────────────────
+
+    @Test
+    void search_returnsEmpty_whenQueryIsNull() {
+        List<AppUser> result = userSearchService.search(null);
+
+        assertThat(result).isEmpty();
+        verify(userRepository, never()).searchByNameOrUsername(any(), any());
+    }
+
+    @Test
+    void search_returnsEmpty_whenQueryIsBlank() {
+        List<AppUser> result = userSearchService.search("   ");
+
+        assertThat(result).isEmpty();
+        verify(userRepository, never()).searchByNameOrUsername(any(), any());
+    }
+
+    @Test
+    void search_delegatesToRepository_whenQueryIsNonBlank() {
+        AppUser user = AppUser.builder().id(UUID.randomUUID()).username("hans").build();
+        when(userRepository.searchByNameOrUsername(eq("hans"), any(PageRequest.class)))
+                .thenReturn(List.of(user));
+
+        List<AppUser> result = userSearchService.search("hans");
+
+        assertThat(result).containsExactly(user);
+        verify(userRepository).searchByNameOrUsername(eq("hans"), any(PageRequest.class));
+    }
+
+    @Test
+    void search_trimsQuery_beforeDelegating() {
+        when(userRepository.searchByNameOrUsername(eq("hans"), any(PageRequest.class)))
+                .thenReturn(List.of());
+
+        userSearchService.search("  hans  ");
+
+        verify(userRepository).searchByNameOrUsername(eq("hans"), any(PageRequest.class));
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/UserServiceTest.java

@@ -5,17 +5,20 @@ import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.dto.AdminUpdateUserRequest;
 import org.raddatz.familienarchiv.dto.ChangePasswordDTO;
 import org.raddatz.familienarchiv.dto.CreateUserRequest;
 import org.raddatz.familienarchiv.dto.UpdateProfileDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.UserGroup;
 import org.raddatz.familienarchiv.repository.AppUserRepository;
 import org.raddatz.familienarchiv.repository.UserGroupRepository;
 import org.springframework.security.crypto.password.PasswordEncoder;
 
 import java.util.List;
 import java.util.Optional;
+import java.util.Set;
 import java.util.UUID;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -216,6 +219,78 @@ class UserServiceTest {
         verify(userRepository).save(argThat(u -> "newHash".equals(u.getPassword())));
     }
 
+    // ─── adminUpdateUser ──────────────────────────────────────────────────────
+
+    @Test
+    void adminUpdateUser_updatesNameFields() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setFirstName("Ada"); dto.setLastName("Lovelace");
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getFirstName()).isEqualTo("Ada");
+        assertThat(result.getLastName()).isEqualTo("Lovelace");
+    }
+
+    @Test
+    void adminUpdateUser_preservesGroups_whenGroupIdsIsNull() {
+        UUID id = UUID.randomUUID();
+        UserGroup adminGroup = UserGroup.builder().id(UUID.randomUUID()).name("Administrators").build();
+        AppUser user = AppUser.builder().id(id).username("admin").groups(Set.of(adminGroup)).build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setFirstName("Ada"); // groupIds left null → don't change groups
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getGroups()).containsExactly(adminGroup);
+    }
+
+    @Test
+    void adminUpdateUser_updatesGroups_whenGroupIdsProvided() {
+        UUID id = UUID.randomUUID();
+        UserGroup oldGroup = UserGroup.builder().id(UUID.randomUUID()).name("Viewers").build();
+        UserGroup newGroup = UserGroup.builder().id(UUID.randomUUID()).name("Editors").build();
+        AppUser user = AppUser.builder().id(id).username("max").groups(Set.of(oldGroup)).build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(groupRepository.findAllById(List.of(newGroup.getId()))).thenReturn(List.of(newGroup));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setGroupIds(List.of(newGroup.getId()));
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getGroups()).containsExactly(newGroup);
+    }
+
+    @Test
+    void adminUpdateUser_clearsGroups_whenGroupIdsIsEmptyList() {
+        // Sending groupIds:[] is the explicit "remove from all groups" signal.
+        // The frontend must NEVER send [] accidentally — it must always include
+        // the currently-selected group checkboxes.
+        UUID id = UUID.randomUUID();
+        UserGroup adminGroup = UserGroup.builder().id(UUID.randomUUID()).name("Administrators").build();
+        AppUser user = AppUser.builder().id(id).username("admin").groups(Set.of(adminGroup)).build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(groupRepository.findAllById(List.of())).thenReturn(List.of());
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setGroupIds(List.of()); // empty list → intentional "remove all groups"
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getGroups()).isEmpty();
+    }
+
     // ─── getGroupById ─────────────────────────────────────────────────────────
 
     @Test
@@ -226,4 +301,378 @@ class UserServiceTest {
         assertThatThrownBy(() -> userService.getGroupById(id))
                 .isInstanceOf(DomainException.class);
     }
+
+    // ─── createUserOrUpdate — groups loaded ───────────────────────────────────
+
+    @Test
+    void createUserOrUpdate_loadsGroups_whenGroupIdsNonEmpty() {
+        UserGroup group = UserGroup.builder().id(UUID.randomUUID()).name("Admins").build();
+        CreateUserRequest req = new CreateUserRequest();
+        req.setUsername("newuser");
+        req.setEmail("u@example.com");
+        req.setInitialPassword("pass");
+        req.setGroupIds(List.of(group.getId()));
+
+        when(userRepository.findByUsername("newuser")).thenReturn(Optional.empty());
+        when(groupRepository.findAllById(List.of(group.getId()))).thenReturn(List.of(group));
+        when(passwordEncoder.encode("pass")).thenReturn("encoded");
+        AppUser saved = AppUser.builder().id(UUID.randomUUID()).username("newuser").build();
+        when(userRepository.save(any())).thenReturn(saved);
+
+        AppUser result = userService.createUserOrUpdate(req);
+
+        assertThat(result).isEqualTo(saved);
+        verify(groupRepository).findAllById(List.of(group.getId()));
+    }
+
+    // ─── updateProfile — email edge cases ─────────────────────────────────────
+
+    @Test
+    void updateProfile_setsEmailToNull_whenEmailIsBlank() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("max").email("old@example.com").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        UpdateProfileDTO dto = new UpdateProfileDTO();
+        dto.setEmail("   "); // blank — should clear email
+
+        AppUser result = userService.updateProfile(id, dto);
+
+        assertThat(result.getEmail()).isNull();
+    }
+
+    @Test
+    void updateProfile_doesNotChangeEmail_whenEmailDtoIsNull() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("max").email("keep@example.com").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        UpdateProfileDTO dto = new UpdateProfileDTO();
+        dto.setEmail(null); // null — no change
+
+        AppUser result = userService.updateProfile(id, dto);
+
+        assertThat(result.getEmail()).isEqualTo("keep@example.com");
+    }
+
+    @Test
+    void updateProfile_setsContactToNull_whenContactIsBlank() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("max").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        UpdateProfileDTO dto = new UpdateProfileDTO();
+        dto.setContact("  ");
+
+        AppUser result = userService.updateProfile(id, dto);
+
+        assertThat(result.getContact()).isNull();
+    }
+
+    // ─── adminUpdateUser — password and email branches ────────────────────────
+
+    @Test
+    void adminUpdateUser_setsPassword_whenNewPasswordProvided() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").password("old").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(passwordEncoder.encode("newSecret")).thenReturn("newHashed");
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setNewPassword("newSecret");
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getPassword()).isEqualTo("newHashed");
+    }
+
+    @Test
+    void adminUpdateUser_doesNotChangePassword_whenNewPasswordIsBlank() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").password("original").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setNewPassword("  ");
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getPassword()).isEqualTo("original");
+        verify(passwordEncoder, never()).encode(any());
+    }
+
+    @Test
+    void adminUpdateUser_setsEmailToNull_whenEmailIsBlank() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").email("old@example.com").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setEmail("   ");
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getEmail()).isNull();
+    }
+
+    @Test
+    void adminUpdateUser_throwsConflict_whenEmailTakenByAnotherUser() {
+        UUID id = UUID.randomUUID();
+        UUID otherId = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").build();
+        AppUser other = AppUser.builder().id(otherId).username("anna").email("taken@example.com").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.findByEmail("taken@example.com")).thenReturn(Optional.of(other));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setEmail("taken@example.com");
+
+        assertThatThrownBy(() -> userService.adminUpdateUser(id, dto))
+                .isInstanceOf(DomainException.class)
+                .hasMessageContaining("E-Mail");
+    }
+
+    // ─── updateGroup ──────────────────────────────────────────────────────────
+
+    @Test
+    void updateGroup_updatesNameAndPermissions_whenBothProvided() {
+        UUID id = UUID.randomUUID();
+        UserGroup group = UserGroup.builder().id(id).name("OldName")
+                .permissions(Set.of("READ_ALL")).build();
+        when(groupRepository.findById(id)).thenReturn(Optional.of(group));
+        when(groupRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        org.raddatz.familienarchiv.dto.GroupDTO dto = new org.raddatz.familienarchiv.dto.GroupDTO();
+        dto.setName("NewName");
+        dto.setPermissions(Set.of("WRITE_ALL"));
+
+        UserGroup result = userService.updateGroup(id, dto);
+
+        assertThat(result.getName()).isEqualTo("NewName");
+        assertThat(result.getPermissions()).containsExactly("WRITE_ALL");
+    }
+
+    @Test
+    void updateGroup_keepsExistingName_whenNameIsNull() {
+        UUID id = UUID.randomUUID();
+        UserGroup group = UserGroup.builder().id(id).name("Existing").build();
+        when(groupRepository.findById(id)).thenReturn(Optional.of(group));
+        when(groupRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        org.raddatz.familienarchiv.dto.GroupDTO dto = new org.raddatz.familienarchiv.dto.GroupDTO();
+        dto.setName(null);
+        dto.setPermissions(Set.of("ADMIN"));
+
+        UserGroup result = userService.updateGroup(id, dto);
+
+        assertThat(result.getName()).isEqualTo("Existing");
+    }
+
+    @Test
+    void updateGroup_keepsExistingPermissions_whenPermissionsAreNull() {
+        UUID id = UUID.randomUUID();
+        UserGroup group = UserGroup.builder().id(id).name("Group")
+                .permissions(Set.of("READ_ALL")).build();
+        when(groupRepository.findById(id)).thenReturn(Optional.of(group));
+        when(groupRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        org.raddatz.familienarchiv.dto.GroupDTO dto = new org.raddatz.familienarchiv.dto.GroupDTO();
+        dto.setName("NewName");
+        dto.setPermissions(null);
+
+        UserGroup result = userService.updateGroup(id, dto);
+
+        assertThat(result.getPermissions()).containsExactly("READ_ALL");
+    }
+
+    // ─── createUserOrUpdate — empty groupIds ──────────────────────────────────
+
+    @Test
+    void createUserOrUpdate_doesNotLoadGroups_whenGroupIdsIsEmpty() {
+        CreateUserRequest req = new CreateUserRequest();
+        req.setUsername("newuser");
+        req.setEmail("u@example.com");
+        req.setInitialPassword("pass");
+        req.setGroupIds(List.of()); // empty, not null
+
+        when(userRepository.findByUsername("newuser")).thenReturn(Optional.empty());
+        when(passwordEncoder.encode("pass")).thenReturn("encoded");
+        AppUser saved = AppUser.builder().id(UUID.randomUUID()).username("newuser").build();
+        when(userRepository.save(any())).thenReturn(saved);
+
+        userService.createUserOrUpdate(req);
+
+        verify(groupRepository, never()).findAllById(any());
+    }
+
+    // ─── updateProfile — contact null ─────────────────────────────────────────
+
+    @Test
+    void updateProfile_setsTrimmedContact_whenContactIsNonBlank() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("max").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        UpdateProfileDTO dto = new UpdateProfileDTO();
+        dto.setContact("  phone: 999  ");
+
+        AppUser result = userService.updateProfile(id, dto);
+
+        assertThat(result.getContact()).isEqualTo("phone: 999");
+    }
+
+    @Test
+    void updateProfile_setsNullContact_whenContactIsNull() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("max").contact("old contact").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        UpdateProfileDTO dto = new UpdateProfileDTO();
+        dto.setContact(null);
+
+        AppUser result = userService.updateProfile(id, dto);
+
+        assertThat(result.getContact()).isNull();
+    }
+
+    @Test
+    void updateProfile_allowsSameEmail_whenEmailBelongsToSameUser() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("max").email("me@example.com").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.findByEmail("me@example.com")).thenReturn(Optional.of(user)); // same user
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        UpdateProfileDTO dto = new UpdateProfileDTO();
+        dto.setEmail("me@example.com");
+
+        // Must not throw
+        AppUser result = userService.updateProfile(id, dto);
+        assertThat(result.getEmail()).isEqualTo("me@example.com");
+    }
+
+    // ─── adminUpdateUser — contact null and email null ────────────────────────
+
+    @Test
+    void adminUpdateUser_setsNullContact_whenContactIsNull() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").contact("old contact").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setContact(null);
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getContact()).isNull();
+    }
+
+    @Test
+    void adminUpdateUser_setsNullContact_whenContactIsBlank() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").contact("old").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setContact("   ");
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getContact()).isNull();
+    }
+
+    @Test
+    void adminUpdateUser_setsTrimmedContact_whenContactIsNonBlank() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setContact("  phone: 555  ");
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getContact()).isEqualTo("phone: 555");
+    }
+
+    @Test
+    void adminUpdateUser_doesNotModifyEmail_whenEmailIsNull() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").email("keep@example.com").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setEmail(null);
+
+        AppUser result = userService.adminUpdateUser(id, dto);
+
+        assertThat(result.getEmail()).isEqualTo("keep@example.com");
+    }
+
+    @Test
+    void adminUpdateUser_allowsSameEmail_whenEmailBelongsToSameUser() {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("admin").email("me@example.com").build();
+        when(userRepository.findById(id)).thenReturn(Optional.of(user));
+        when(userRepository.findByEmail("me@example.com")).thenReturn(Optional.of(user)); // same user
+        when(userRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        AdminUpdateUserRequest dto = new AdminUpdateUserRequest();
+        dto.setEmail("me@example.com");
+
+        // Must not throw
+        AppUser result = userService.adminUpdateUser(id, dto);
+        assertThat(result.getEmail()).isEqualTo("me@example.com");
+    }
+
+    // ─── createUserOrUpdate — null groupIds ──────────────────────────────────
+
+    @Test
+    void createUserOrUpdate_doesNotLoadGroups_whenGroupIdsIsNull() {
+        // request.getGroupIds() == null → short-circuit (A=false), groupRepository never called
+        CreateUserRequest req = new CreateUserRequest();
+        req.setUsername("nullgroups");
+        req.setEmail("ng@example.com");
+        req.setInitialPassword("pass");
+        req.setGroupIds(null); // null → first condition false → short-circuit
+
+        when(userRepository.findByUsername("nullgroups")).thenReturn(Optional.empty());
+        when(passwordEncoder.encode("pass")).thenReturn("encoded");
+        AppUser saved = AppUser.builder().id(UUID.randomUUID()).username("nullgroups").build();
+        when(userRepository.save(any())).thenReturn(saved);
+
+        userService.createUserOrUpdate(req);
+
+        verify(groupRepository, never()).findAllById(any());
+    }
+
+    // ─── createGroup ──────────────────────────────────────────────────────────
+
+    @Test
+    void createGroup_createsGroupWithNameAndPermissions() {
+        org.raddatz.familienarchiv.dto.GroupDTO dto = new org.raddatz.familienarchiv.dto.GroupDTO();
+        dto.setName("Familie");
+        dto.setPermissions(Set.of("READ_ALL", "WRITE_ALL"));
+
+        UserGroup saved = UserGroup.builder().id(UUID.randomUUID()).name("Familie")
+                .permissions(Set.of("READ_ALL", "WRITE_ALL")).build();
+        when(groupRepository.save(any())).thenReturn(saved);
+
+        UserGroup result = userService.createGroup(dto);
+
+        assertThat(result.getName()).isEqualTo("Familie");
+        assertThat(result.getPermissions()).containsExactlyInAnyOrder("READ_ALL", "WRITE_ALL");
+    }
 }

backend/src/test/resources/application-test.yaml

@@ -0,0 +1,15 @@
+app:
+  s3:
+    endpoint: http://localhost:9000
+    access-key: dummy
+    secret-key: dummy
+    bucket: test-bucket
+    region: us-east-1
+
+spring:
+  datasource:
+    url: will-be-overridden-by-testcontainers
+    username: test
+    password: test
+  mail:
+    host: localhost

frontend/.gitignore

@@ -29,3 +29,4 @@ src/lib/paraglide
 # (committed as a stub; overwritten by the real spec after generation)
 # src/lib/generated/api.ts
 src/lib/paraglide_bak*
+/coverage

frontend/.prettierignore

@@ -16,3 +16,4 @@ bun.lockb
 # Test artifacts
 /test-results/
 /e2e/.auth/
+/coverage/

frontend/e2e/accessibility.spec.ts

@@ -0,0 +1,58 @@
+import AxeBuilder from '@axe-core/playwright';
+import { test, expect } from '@playwright/test';
+
+/**
+ * Automated accessibility checks using axe-core (wcag2a + wcag2aa).
+ * Authenticated pages use the stored admin session from playwright.config.ts.
+ * The login page test overrides to an unauthenticated context.
+ */
+
+const AUTHENTICATED_PAGES = [
+	{ name: 'home', path: '/' },
+	{ name: 'persons', path: '/persons' },
+	{ name: 'admin', path: '/admin' }
+];
+
+function buildAxe(page: Parameters<typeof AxeBuilder>[0]['page']) {
+	return new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']);
+}
+
+test.describe('Accessibility — authenticated pages', () => {
+	for (const { name, path } of AUTHENTICATED_PAGES) {
+		test(`${name} page has no critical wcag2a/wcag2aa violations`, async ({ page }) => {
+			await page.goto(path);
+			await page.waitForSelector('[data-hydrated]');
+
+			const results = await buildAxe(page).analyze();
+
+			if (results.violations.length > 0) {
+				const summary = results.violations
+					.map((v) => `[${v.impact}] ${v.id}: ${v.description} (${v.nodes.length} node(s))`)
+					.join('\n');
+				console.log(`\nAccessibility violations on ${name}:\n${summary}`);
+			}
+
+			expect(results.violations).toEqual([]);
+		});
+	}
+});
+
+test.describe('Accessibility — login page', () => {
+	test.use({ storageState: { cookies: [], origins: [] } });
+
+	test('login page has no critical wcag2a/wcag2aa violations', async ({ page }) => {
+		await page.goto('/login');
+		await expect(page.getByLabel('Benutzername')).toBeVisible();
+
+		const results = await buildAxe(page).analyze();
+
+		if (results.violations.length > 0) {
+			const summary = results.violations
+				.map((v) => `[${v.impact}] ${v.id}: ${v.description} (${v.nodes.length} node(s))`)
+				.join('\n');
+			console.log(`\nAccessibility violations on login:\n${summary}`);
+		}
+
+		expect(results.violations).toEqual([]);
+	});
+});

frontend/e2e/dashboard-screenshots.spec.ts

@@ -0,0 +1,3 @@
+import { captureProofshots } from './proofshots';
+
+captureProofshots('/', 'dashboard');

frontend/e2e/documents.spec.ts

@@ -25,7 +25,7 @@ test.describe('Document list', () => {
 
 	test('navigation bar shows active state for Dokumente', async ({ page }) => {
 		const navLink = page.getByRole('navigation').getByRole('link', { name: 'Dokumente' });
-		await expect(navLink).toHaveClass(/text-brand-navy/);
+		await expect(navLink).toHaveClass(/bg-nav-active/);
 	});
 
 	test('text search filters the document list', async ({ page }) => {
@@ -77,12 +77,49 @@ test.describe('Document detail', () => {
 });
 
 test.describe('New document', () => {
-	test('renders the upload form', async ({ page }) => {
+	test('renders the upload form with file input first', async ({ page }) => {
 		await page.goto('/documents/new');
+		await page.waitForSelector('[data-hydrated]');
 		await expect(page.getByRole('heading', { name: /Neues Dokument/i })).toBeVisible();
-		await expect(page.getByLabel('Titel')).toBeVisible();
+		// File input comes before the title field in DOM order
+		const fileInput = page.locator('input[type="file"]');
+		const titleInput = page.getByLabel('Titel');
+		await expect(fileInput).toBeVisible();
+		await expect(titleInput).toBeVisible();
+		const fileBox = await fileInput.boundingBox();
+		const titleBox = await titleInput.boundingBox();
+		expect(fileBox!.y).toBeLessThan(titleBox!.y);
 		await page.screenshot({ path: 'test-results/e2e/document-new.png' });
 	});
+
+	test('title field is pre-filled from filename when a file is selected', async ({ page }) => {
+		await page.goto('/documents/new');
+		await page.waitForSelector('[data-hydrated]');
+		const PDF_FIXTURE = path.resolve(__dirname, 'fixtures/minimal.pdf');
+		const fileInput = page.locator('input[type="file"]');
+		await fileInput.setInputFiles({
+			name: 'Brief_1965.pdf',
+			mimeType: 'application/pdf',
+			buffer: fs.readFileSync(PDF_FIXTURE)
+		});
+		await expect(page.getByLabel('Titel')).toHaveValue('Brief_1965');
+		await page.screenshot({ path: 'test-results/e2e/document-new-filename-prefill.png' });
+	});
+
+	test('typed title is not overwritten when a file is selected', async ({ page }) => {
+		await page.goto('/documents/new');
+		await page.waitForSelector('[data-hydrated]');
+		await page.getByLabel('Titel').fill('Weihnachtsbrief 1965');
+		const PDF_FIXTURE = path.resolve(__dirname, 'fixtures/minimal.pdf');
+		const fileInput = page.locator('input[type="file"]');
+		await fileInput.setInputFiles({
+			name: 'Brief_1965.pdf',
+			mimeType: 'application/pdf',
+			buffer: fs.readFileSync(PDF_FIXTURE)
+		});
+		await expect(page.getByLabel('Titel')).toHaveValue('Weihnachtsbrief 1965');
+		await page.screenshot({ path: 'test-results/e2e/document-new-title-not-overwritten.png' });
+	});
 });
 
 test.describe('Document creation', () => {
@@ -91,12 +128,27 @@ test.describe('Document creation', () => {
 		await page.waitForSelector('[data-hydrated]');
 
 		await page.getByLabel('Titel').fill('E2E Testbrief');
-		await page.getByRole('button', { name: /Speichern/i }).click();
+		await page.getByRole('button', { name: 'Speichern', exact: true }).click();
 
 		await expect(page).toHaveURL(/\/documents\/[^/]+$/);
 		await expect(page.getByRole('heading', { name: 'E2E Testbrief' })).toBeVisible();
 		await page.screenshot({ path: 'test-results/e2e/document-create.png' });
 	});
+
+	test('user saves a document with only a file — title comes from filename', async ({ page }) => {
+		await page.goto('/documents/new');
+		await page.waitForSelector('[data-hydrated]');
+		const PDF_FIXTURE = path.resolve(__dirname, 'fixtures/minimal.pdf');
+		await page.locator('input[type="file"]').setInputFiles({
+			name: 'Brief_1965.pdf',
+			mimeType: 'application/pdf',
+			buffer: fs.readFileSync(PDF_FIXTURE)
+		});
+		await page.getByRole('button', { name: 'Speichern', exact: true }).click();
+		await expect(page).toHaveURL(/\/documents\/[^/]+$/);
+		await expect(page.getByRole('heading', { name: 'Brief_1965' })).toBeVisible();
+		await page.screenshot({ path: 'test-results/e2e/document-create-file-only.png' });
+	});
 });
 
 test.describe('Document editing', () => {
@@ -112,10 +164,10 @@ test.describe('Document editing', () => {
 		await page.waitForSelector('[data-hydrated]');
 
 		await page.getByLabel('Titel').fill('E2E Testbrief (überarbeitet)');
-		await page.getByRole('button', { name: /Speichern/i }).click();
+		await page.getByRole('button', { name: 'Speichern', exact: true }).click();
 
 		await expect(page).toHaveURL(/\/documents\/[^/]+$/);
-		await expect(page.getByText('E2E Testbrief (überarbeitet)')).toBeVisible();
+		await expect(page.getByRole('heading', { name: 'E2E Testbrief (überarbeitet)' })).toBeVisible();
 		await page.screenshot({ path: 'test-results/e2e/document-edit-save.png' });
 	});
 });
@@ -327,10 +379,12 @@ test.describe('PDF annotations — admin', () => {
 		await page.waitForSelector('[data-hydrated]');
 		await page.locator('canvas').first().waitFor({ state: 'visible', timeout: 20000 });
 
-		// Ensure annotation is visible before enabling annotate mode
+		// Ensure at least one annotation is visible before enabling annotate mode
 		await expect(page.locator('[data-testid^="annotation-"]').first()).toBeVisible({
 			timeout: 8000
 		});
+		// Record count now — the draw test may have created more than one annotation
+		const countBefore = await page.locator('[data-testid^="annotation-"]').count();
 
 		// Enable annotate mode to show delete buttons
 		await page.getByRole('button', { name: /^annotieren$/i }).click();
@@ -339,7 +393,7 @@ test.describe('PDF annotations — admin', () => {
 		await expect(deleteBtn).toBeVisible({ timeout: 8000 });
 		await deleteBtn.click();
 
-		await expect(page.locator('[data-testid^="annotation-"]')).toHaveCount(0, {
+		await expect(page.locator('[data-testid^="annotation-"]')).toHaveCount(countBefore - 1, {
 			timeout: 8000
 		});
 
@@ -407,7 +461,10 @@ test.describe('PDF annotations — file hash versioning', () => {
 		await page.waitForSelector('[data-hydrated]');
 		await page.locator('canvas').first().waitFor({ state: 'visible', timeout: 20000 });
 
-		await expect(page.locator('[data-testid^="annotation-"]')).toHaveCount(0, { timeout: 8000 });
+		// Use :not() to exclude the outdated-notice element whose testid also starts with "annotation-"
+		await expect(
+			page.locator('[data-testid^="annotation-"]:not([data-testid="annotation-outdated-notice"])')
+		).toHaveCount(0, { timeout: 8000 });
 		await expect(page.locator('[data-testid="annotation-outdated-notice"]')).toBeVisible({
 			timeout: 5000
 		});

frontend/e2e/history.spec.ts

@@ -25,7 +25,7 @@ test.describe('Document history panel', () => {
 		await page.goto('/documents/new');
 		await page.waitForSelector('[data-hydrated]');
 		await page.getByLabel('Titel').fill('E2E History Test Dokument');
-		await page.getByRole('button', { name: /Speichern/i }).click();
+		await page.getByRole('button', { name: 'Speichern', exact: true }).click();
 		// Wait for redirect to the new document's UUID-based URL (not /documents/new)
 		await page.waitForURL(/\/documents\/[0-9a-f-]{36}$/);
 		docPath = new URL(page.url()).pathname;
@@ -34,7 +34,7 @@ test.describe('Document history panel', () => {
 		await page.goto(`${docPath}/edit`);
 		await page.waitForSelector('[data-hydrated]');
 		await page.getByLabel('Titel').fill('E2E History Test Dokument (bearbeitet)');
-		await page.getByRole('button', { name: /Speichern/i }).click();
+		await page.getByRole('button', { name: 'Speichern', exact: true }).click();
 		await page.waitForURL(/\/documents\/[0-9a-f-]{36}$/);
 
 		await context.close();

frontend/e2e/persons.spec.ts

@@ -212,7 +212,7 @@ test.describe('Conversations', () => {
 	test('nav link is active on the conversations page', async ({ page }) => {
 		await page.goto('/conversations');
 		const navLink = page.getByRole('link', { name: 'Konversationen' });
-		await expect(navLink).toHaveClass(/text-brand-navy/);
+		await expect(navLink).toHaveClass(/bg-nav-active/);
 	});
 
 	test('sort toggle changes the button label', async ({ page }) => {

frontend/e2e/proofshots.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared proofshot helper for Playwright.
+ *
+ * Usage in any spec file:
+ *   import { captureProofshots } from './proofshots';
+ *   captureProofshots('/persons', 'persons');
+ *
+ * This registers one test per viewport × theme combination.
+ * Screenshots are saved to proofshot-artifacts/{featureName}/.
+ */
+import { test } from '@playwright/test';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const viewports = [
+	{ name: 'mobile', width: 390, height: 844 },
+	{ name: 'tablet', width: 768, height: 1024 },
+	{ name: 'desktop', width: 1440, height: 900 }
+];
+
+/**
+ * Registers Playwright tests that navigate to `url`, apply each theme,
+ * and capture full-page screenshots at all standard viewports.
+ *
+ * @param url         The path to screenshot (e.g. '/', '/persons', '/admin')
+ * @param featureName Used as the output directory name and screenshot file prefix
+ */
+export function captureProofshots(url: string, featureName: string): void {
+	const outDir = path.join(__dirname, '../../proofshot-artifacts', featureName);
+	fs.mkdirSync(outDir, { recursive: true });
+
+	for (const vp of viewports) {
+		for (const theme of ['light', 'dark'] as const) {
+			test(`${featureName} – ${vp.name} – ${theme}`, async ({ page }) => {
+				await page.setViewportSize({ width: vp.width, height: vp.height });
+				await page.goto(url);
+
+				// Apply theme via data-theme attribute and localStorage
+				await page.evaluate((t) => {
+					document.documentElement.setAttribute('data-theme', t);
+					localStorage.setItem('theme', t);
+				}, theme);
+
+				// 'networkidle' is unreliable in SvelteKit dev mode due to the HMR WebSocket.
+				await page.waitForLoadState('domcontentloaded');
+				await page.waitForSelector('main', { state: 'visible' });
+
+				await page.screenshot({
+					path: path.join(outDir, `${featureName}-${vp.name}-${theme}.png`),
+					fullPage: true
+				});
+			});
+		}
+	}
+}

frontend/messages/de.json

@@ -39,7 +39,7 @@
 	"form_placeholder_location": "z.B. Berlin, Wien…",
 	"form_label_sender": "Absender",
 	"form_label_receivers": "Empfänger",
-	"form_label_title": "Titel *",
+	"form_label_title": "Titel",
 	"form_label_tags": "Schlagworte",
 	"form_label_content": "Inhalt",
 	"form_placeholder_content": "Kurze Beschreibung des Inhalts…",
@@ -75,6 +75,7 @@
 	"doc_file_replace_label": "Neue Datei hochladen",
 	"doc_file_replace_note": "(ersetzt die aktuelle Datei)",
 	"doc_current_file_label": "Aktuelle Datei:",
+	"doc_more_details": "Weitere Details",
 	"doc_new_heading": "Neues Dokument",
 	"doc_edit_heading": "Bearbeiten",
 	"doc_section_details": "Details",
@@ -293,5 +294,31 @@
 	"enrich_done_body": "Alle Dokumente wurden bearbeitet.",
 	"enrich_back_to_list": "Zurück zur Liste",
 	"comment_empty_hint": "Noch keine Kommentare – starte die Diskussion!",
-	"comment_start_discussion": "Diskussion starten →"
+	"comment_start_discussion": "Diskussion starten →",
+	"notification_bell_label": "Benachrichtigungen",
+	"notification_bell_unread_label": "{count} ungelesene Benachrichtigungen",
+	"notification_mark_all_read": "Alle gelesen",
+	"notification_empty": "Keine neuen Benachrichtigungen",
+	"notification_type_reply": "{actor} hat auf deinen Kommentar geantwortet",
+	"notification_type_mention": "{actor} hat dich in einem Kommentar erwähnt",
+	"notification_prefs_heading": "Benachrichtigungen",
+	"notification_pref_reply": "E-Mail, wenn jemand auf meinen Kommentar antwortet",
+	"notification_pref_mention": "E-Mail, wenn jemand mich in einem Kommentar erwähnt",
+	"notification_prefs_no_email": "Bitte trage zuerst eine E-Mail-Adresse ein, um Benachrichtigungen zu erhalten.",
+	"notification_unread": "ungelesen",
+	"mention_btn_label": "Person erwähnen",
+	"mention_popup_empty": "Keine Nutzer gefunden",
+	"page_title_home": "Archiv",
+	"page_title_persons": "Personen",
+	"page_title_admin": "Administration",
+	"page_title_login": "Anmelden",
+	"page_title_error": "Fehler – Familienarchiv",
+	"dashboard_notifications_heading": "Benachrichtigungen",
+	"dashboard_notification_mentioned": "erwähnt Sie",
+	"dashboard_notification_replied": "hat geantwortet",
+	"dashboard_needs_metadata_heading": "Metadaten fehlen",
+	"dashboard_needs_metadata_show_all": "Alle anzeigen",
+	"dashboard_recent_heading": "Zuletzt hinzugefügt",
+	"dashboard_resume_label": "Zuletzt geöffnet:",
+	"dashboard_resume_fallback": "Unbekanntes Dokument"
 }

frontend/messages/en.json

@@ -39,7 +39,7 @@
 	"form_placeholder_location": "e.g. Berlin, Vienna…",
 	"form_label_sender": "Sender",
 	"form_label_receivers": "Recipients",
-	"form_label_title": "Title *",
+	"form_label_title": "Title",
 	"form_label_tags": "Tags",
 	"form_label_content": "Content",
 	"form_placeholder_content": "Brief description of the content…",
@@ -75,6 +75,7 @@
 	"doc_file_replace_label": "Upload new file",
 	"doc_file_replace_note": "(replaces the current file)",
 	"doc_current_file_label": "Current file:",
+	"doc_more_details": "More details",
 	"doc_new_heading": "New document",
 	"doc_edit_heading": "Edit",
 	"doc_section_details": "Details",
@@ -293,5 +294,31 @@
 	"enrich_done_body": "All documents have been processed.",
 	"enrich_back_to_list": "Back to list",
 	"comment_empty_hint": "No comments yet – start the discussion!",
-	"comment_start_discussion": "Start discussion →"
+	"comment_start_discussion": "Start discussion →",
+	"notification_bell_label": "Notifications",
+	"notification_bell_unread_label": "{count} unread notifications",
+	"notification_mark_all_read": "Mark all read",
+	"notification_empty": "No new notifications",
+	"notification_type_reply": "{actor} replied to your comment",
+	"notification_type_mention": "{actor} mentioned you in a comment",
+	"notification_prefs_heading": "Notifications",
+	"notification_pref_reply": "Email when someone replies to my comment",
+	"notification_pref_mention": "Email when someone mentions me in a comment",
+	"notification_prefs_no_email": "Please add an email address above to receive notifications.",
+	"notification_unread": "unread",
+	"mention_btn_label": "Mention person",
+	"mention_popup_empty": "No users found",
+	"page_title_home": "Archive",
+	"page_title_persons": "Persons",
+	"page_title_admin": "Administration",
+	"page_title_login": "Sign in",
+	"page_title_error": "Error – Family Archive",
+	"dashboard_notifications_heading": "Notifications",
+	"dashboard_notification_mentioned": "mentioned you",
+	"dashboard_notification_replied": "replied",
+	"dashboard_needs_metadata_heading": "Missing Metadata",
+	"dashboard_needs_metadata_show_all": "Show all",
+	"dashboard_recent_heading": "Recently Added",
+	"dashboard_resume_label": "Last opened:",
+	"dashboard_resume_fallback": "Unknown document"
 }

frontend/messages/es.json

@@ -39,7 +39,7 @@
 	"form_placeholder_location": "p.ej. Berlín, Viena…",
 	"form_label_sender": "Remitente",
 	"form_label_receivers": "Destinatarios",
-	"form_label_title": "Título *",
+	"form_label_title": "Título",
 	"form_label_tags": "Etiquetas",
 	"form_label_content": "Contenido",
 	"form_placeholder_content": "Breve descripción del contenido…",
@@ -75,6 +75,7 @@
 	"doc_file_replace_label": "Subir nuevo archivo",
 	"doc_file_replace_note": "(reemplaza el archivo actual)",
 	"doc_current_file_label": "Archivo actual:",
+	"doc_more_details": "Más detalles",
 	"doc_new_heading": "Nuevo documento",
 	"doc_edit_heading": "Editar",
 	"doc_section_details": "Detalles",
@@ -293,5 +294,31 @@
 	"enrich_done_body": "Todos los documentos han sido procesados.",
 	"enrich_back_to_list": "Volver a la lista",
 	"comment_empty_hint": "Aún no hay comentarios – ¡inicia la discusión!",
-	"comment_start_discussion": "Iniciar discusión →"
+	"comment_start_discussion": "Iniciar discusión →",
+	"notification_bell_label": "Notificaciones",
+	"notification_bell_unread_label": "{count} notificaciones sin leer",
+	"notification_mark_all_read": "Marcar todo como leído",
+	"notification_empty": "No hay notificaciones nuevas",
+	"notification_type_reply": "{actor} respondió a tu comentario",
+	"notification_type_mention": "{actor} te mencionó en un comentario",
+	"notification_prefs_heading": "Notificaciones",
+	"notification_pref_reply": "Correo cuando alguien responde a mi comentario",
+	"notification_pref_mention": "Correo cuando alguien me menciona en un comentario",
+	"notification_prefs_no_email": "Por favor, añade una dirección de correo electrónico para recibir notificaciones.",
+	"notification_unread": "no leído",
+	"mention_btn_label": "Mencionar persona",
+	"mention_popup_empty": "No se encontraron usuarios",
+	"page_title_home": "Archivo",
+	"page_title_persons": "Personas",
+	"page_title_admin": "Administración",
+	"page_title_login": "Iniciar sesión",
+	"page_title_error": "Error – Archivo familiar",
+	"dashboard_notifications_heading": "Notificaciones",
+	"dashboard_notification_mentioned": "te mencionó",
+	"dashboard_notification_replied": "respondió",
+	"dashboard_needs_metadata_heading": "Metadatos incompletos",
+	"dashboard_needs_metadata_show_all": "Ver todos",
+	"dashboard_recent_heading": "Añadidos recientemente",
+	"dashboard_resume_label": "Último abierto:",
+	"dashboard_resume_fallback": "Documento desconocido"
 }

frontend/package-lock.json

@@ -13,6 +13,7 @@
 				"pdfjs-dist": "^5.5.207"
 			},
 			"devDependencies": {
+				"@axe-core/playwright": "^4.11.1",
 				"@eslint/compat": "^1.4.0",
 				"@eslint/js": "^9.39.1",
 				"@inlang/paraglide-js": "^2.5.0",
@@ -26,6 +27,7 @@
 				"@types/diff": "^7.0.2",
 				"@types/node": "^24",
 				"@vitest/browser-playwright": "^4.0.10",
+				"@vitest/coverage-v8": "^4.1.0",
 				"eslint": "^9.39.1",
 				"eslint-config-prettier": "^10.1.8",
 				"eslint-plugin-svelte": "^3.13.0",
@@ -46,6 +48,19 @@
 				"vitest-browser-svelte": "^2.0.1"
 			}
 		},
+		"node_modules/@axe-core/playwright": {
+			"version": "4.11.1",
+			"resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.11.1.tgz",
+			"integrity": "sha512-mKEfoUIB1MkVTht0BGZFXtSAEKXMJoDkyV5YZ9jbBmZCcWDz71tegNsdTkIN8zc/yMi5Gm2kx7Z5YQ9PfWNAWw==",
+			"dev": true,
+			"license": "MPL-2.0",
+			"dependencies": {
+				"axe-core": "~4.11.1"
+			},
+			"peerDependencies": {
+				"playwright-core": ">= 1.0.0"
+			}
+		},
 		"node_modules/@babel/code-frame": {
 			"version": "7.29.0",
 			"resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",
@@ -61,6 +76,16 @@
 				"node": ">=6.9.0"
 			}
 		},
+		"node_modules/@babel/helper-string-parser": {
+			"version": "7.27.1",
+			"resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
+			"integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
 		"node_modules/@babel/helper-validator-identifier": {
 			"version": "7.28.5",
 			"resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz",
@@ -71,6 +96,46 @@
 				"node": ">=6.9.0"
 			}
 		},
+		"node_modules/@babel/parser": {
+			"version": "7.29.2",
+			"resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.2.tgz",
+			"integrity": "sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/types": "^7.29.0"
+			},
+			"bin": {
+				"parser": "bin/babel-parser.js"
+			},
+			"engines": {
+				"node": ">=6.0.0"
+			}
+		},
+		"node_modules/@babel/types": {
+			"version": "7.29.0",
+			"resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz",
+			"integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/helper-string-parser": "^7.27.1",
+				"@babel/helper-validator-identifier": "^7.28.5"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@bcoe/v8-coverage": {
+			"version": "1.0.2",
+			"resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-1.0.2.tgz",
+			"integrity": "sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			}
+		},
 		"node_modules/@blazediff/core": {
 			"version": "1.9.1",
 			"resolved": "https://registry.npmjs.org/@blazediff/core/-/core-1.9.1.tgz",
@@ -2522,6 +2587,37 @@
 				}
 			}
 		},
+		"node_modules/@vitest/coverage-v8": {
+			"version": "4.1.0",
+			"resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.0.tgz",
+			"integrity": "sha512-nDWulKeik2bL2Va/Wl4x7DLuTKAXa906iRFooIRPR+huHkcvp9QDkPQ2RJdmjOFrqOqvNfoSQLF68deE3xC3CQ==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@bcoe/v8-coverage": "^1.0.2",
+				"@vitest/utils": "4.1.0",
+				"ast-v8-to-istanbul": "^1.0.0",
+				"istanbul-lib-coverage": "^3.2.2",
+				"istanbul-lib-report": "^3.0.1",
+				"istanbul-reports": "^3.2.0",
+				"magicast": "^0.5.2",
+				"obug": "^2.1.1",
+				"std-env": "^4.0.0-rc.1",
+				"tinyrainbow": "^3.0.3"
+			},
+			"funding": {
+				"url": "https://opencollective.com/vitest"
+			},
+			"peerDependencies": {
+				"@vitest/browser": "4.1.0",
+				"vitest": "4.1.0"
+			},
+			"peerDependenciesMeta": {
+				"@vitest/browser": {
+					"optional": true
+				}
+			}
+		},
 		"node_modules/@vitest/expect": {
 			"version": "4.1.0",
 			"resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.0.tgz",
@@ -2755,6 +2851,45 @@
 				"node": ">=12"
 			}
 		},
+		"node_modules/ast-v8-to-istanbul": {
+			"version": "1.0.0",
+			"resolved": "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-1.0.0.tgz",
+			"integrity": "sha512-1fSfIwuDICFA4LKkCzRPO7F0hzFf0B7+Xqrl27ynQaa+Rh0e1Es0v6kWHPott3lU10AyAr7oKHa65OppjLn3Rg==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@jridgewell/trace-mapping": "^0.3.31",
+				"estree-walker": "^3.0.3",
+				"js-tokens": "^10.0.0"
+			}
+		},
+		"node_modules/ast-v8-to-istanbul/node_modules/estree-walker": {
+			"version": "3.0.3",
+			"resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+			"integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@types/estree": "^1.0.0"
+			}
+		},
+		"node_modules/ast-v8-to-istanbul/node_modules/js-tokens": {
+			"version": "10.0.0",
+			"resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
+			"integrity": "sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==",
+			"dev": true,
+			"license": "MIT"
+		},
+		"node_modules/axe-core": {
+			"version": "4.11.1",
+			"resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.11.1.tgz",
+			"integrity": "sha512-BASOg+YwO2C+346x3LZOeoovTIoTrRqEsqMa6fmfAV0P+U9mFr9NsyOEpiYvFjbc64NMrSswhV50WdXzdb/Z5A==",
+			"dev": true,
+			"license": "MPL-2.0",
+			"engines": {
+				"node": ">=4"
+			}
+		},
 		"node_modules/axobject-query": {
 			"version": "4.1.0",
 			"resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz",
@@ -3549,6 +3684,13 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/html-escaper": {
+			"version": "2.0.2",
+			"resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
+			"integrity": "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/https-proxy-agent": {
 			"version": "7.0.6",
 			"resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
@@ -3686,6 +3828,45 @@
 			"dev": true,
 			"license": "ISC"
 		},
+		"node_modules/istanbul-lib-coverage": {
+			"version": "3.2.2",
+			"resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
+			"integrity": "sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==",
+			"dev": true,
+			"license": "BSD-3-Clause",
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/istanbul-lib-report": {
+			"version": "3.0.1",
+			"resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
+			"integrity": "sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==",
+			"dev": true,
+			"license": "BSD-3-Clause",
+			"dependencies": {
+				"istanbul-lib-coverage": "^3.0.0",
+				"make-dir": "^4.0.0",
+				"supports-color": "^7.1.0"
+			},
+			"engines": {
+				"node": ">=10"
+			}
+		},
+		"node_modules/istanbul-reports": {
+			"version": "3.2.0",
+			"resolved": "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz",
+			"integrity": "sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==",
+			"dev": true,
+			"license": "BSD-3-Clause",
+			"dependencies": {
+				"html-escaper": "^2.0.0",
+				"istanbul-lib-report": "^3.0.0"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/jiti": {
 			"version": "2.6.1",
 			"resolved": "https://registry.npmjs.org/jiti/-/jiti-2.6.1.tgz",
@@ -4129,6 +4310,34 @@
 				"@jridgewell/sourcemap-codec": "^1.5.5"
 			}
 		},
+		"node_modules/magicast": {
+			"version": "0.5.2",
+			"resolved": "https://registry.npmjs.org/magicast/-/magicast-0.5.2.tgz",
+			"integrity": "sha512-E3ZJh4J3S9KfwdjZhe2afj6R9lGIN5Pher1pF39UGrXRqq/VDaGVIGN13BjHd2u8B61hArAGOnso7nBOouW3TQ==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/parser": "^7.29.0",
+				"@babel/types": "^7.29.0",
+				"source-map-js": "^1.2.1"
+			}
+		},
+		"node_modules/make-dir": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
+			"integrity": "sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"semver": "^7.5.3"
+			},
+			"engines": {
+				"node": ">=10"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/mini-svg-data-uri": {
 			"version": "1.4.4",
 			"resolved": "https://registry.npmjs.org/mini-svg-data-uri/-/mini-svg-data-uri-1.4.4.tgz",

frontend/package.json

@@ -14,6 +14,7 @@
 		"lint": "prettier --check . && eslint .",
 		"test:unit": "vitest",
 		"test": "npm run test:unit -- --run",
+		"test:coverage": "vitest run --coverage --project=server",
 		"test:e2e": "playwright test",
 		"test:e2e:headed": "playwright test --headed",
 		"test:e2e:ui": "playwright test --ui",
@@ -25,6 +26,7 @@
 		"pdfjs-dist": "^5.5.207"
 	},
 	"devDependencies": {
+		"@axe-core/playwright": "^4.11.1",
 		"@eslint/compat": "^1.4.0",
 		"@eslint/js": "^9.39.1",
 		"@inlang/paraglide-js": "^2.5.0",
@@ -38,6 +40,7 @@
 		"@types/diff": "^7.0.2",
 		"@types/node": "^24",
 		"@vitest/browser-playwright": "^4.0.10",
+		"@vitest/coverage-v8": "^4.1.0",
 		"eslint": "^9.39.1",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-svelte": "^3.13.0",

frontend/src/demo.spec.ts

@@ -1,7 +0,0 @@
-import { describe, it, expect } from 'vitest';
-
-describe('sum test', () => {
-	it('adds 1 + 2 to equal 3', () => {
-		expect(1 + 2).toBe(3);
-	});
-});

frontend/src/lib/components/AnnotationLayer.svelte

@@ -93,7 +93,7 @@ function handlePointerUp(event: PointerEvent) {
 let hoveredId = $state<string | null>(null);
 
 const containerStyle = $derived(
-	`position: absolute; top: 0; left: 0; width: 100%; height: 100%;${canAnnotate ? ' cursor: crosshair;' : ''}`
+	`position: absolute; top: 0; left: 0; width: 100%; height: 100%;${canAnnotate ? ' cursor: crosshair; touch-action: none;' : ''}`
 );
 </script>
 
@@ -113,8 +113,8 @@ const containerStyle = $derived(
 			aria-label="Kommentare anzeigen"
 			onclick={() => onAnnotationClick?.(annotation.id)}
 			onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') onAnnotationClick?.(annotation.id); }}
-			onmouseenter={() => (hoveredId = annotation.id)}
-			onmouseleave={() => (hoveredId = null)}
+			onpointerenter={() => (hoveredId = annotation.id)}
+			onpointerleave={() => (hoveredId = null)}
 			style="
 				position: absolute;
 				left: {annotation.x * 100}%;

frontend/src/lib/components/AnnotationSidePanel.svelte

@@ -9,6 +9,7 @@ type Props = {
 	canComment: boolean;
 	currentUserId: string | null;
 	canAdmin: boolean;
+	targetCommentId?: string | null;
 	onClose: () => void;
 };
 
@@ -19,6 +20,7 @@ let {
 	canComment,
 	currentUserId,
 	canAdmin,
+	targetCommentId = null,
 	onClose
 }: Props = $props();
 
@@ -57,6 +59,7 @@ const visible = $derived(activeAnnotationId !== null);
 					canComment={canComment}
 					currentUserId={currentUserId}
 					canAdmin={canAdmin}
+					targetCommentId={targetCommentId}
 					loadOnMount={true}
 				/>
 			{/key}

frontend/src/lib/components/AnnotationSidePanel.svelte.spec.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+import AnnotationSidePanel from './AnnotationSidePanel.svelte';
+
+afterEach(() => {
+	cleanup();
+	vi.restoreAllMocks();
+});
+
+vi.stubGlobal(
+	'fetch',
+	vi.fn().mockResolvedValue({
+		ok: true,
+		json: async () => []
+	})
+);
+
+const baseProps = {
+	documentId: 'doc-1',
+	activeAnnotationPage: 1,
+	canComment: true,
+	currentUserId: 'user-1',
+	canAdmin: false,
+	onClose: vi.fn()
+};
+
+describe('AnnotationSidePanel – visibility', () => {
+	it('is hidden (translated off-screen) when activeAnnotationId is null', async () => {
+		render(AnnotationSidePanel, { ...baseProps, activeAnnotationId: null });
+		const panel = document.querySelector('[data-testid="annotation-side-panel"]');
+		expect(panel?.classList.contains('translate-x-full')).toBe(true);
+		expect(panel?.classList.contains('translate-x-0')).toBe(false);
+	});
+
+	it('is visible when activeAnnotationId is set', async () => {
+		render(AnnotationSidePanel, { ...baseProps, activeAnnotationId: 'ann-1' });
+		const panel = document.querySelector('[data-testid="annotation-side-panel"]');
+		expect(panel?.classList.contains('translate-x-0')).toBe(true);
+		expect(panel?.classList.contains('translate-x-full')).toBe(false);
+	});
+});
+
+describe('AnnotationSidePanel – close button', () => {
+	it('calls onClose when the close button is clicked', async () => {
+		const onClose = vi.fn();
+		render(AnnotationSidePanel, { ...baseProps, activeAnnotationId: 'ann-1', onClose });
+		await page.getByRole('button', { name: /schließen/i }).click();
+		expect(onClose).toHaveBeenCalledOnce();
+	});
+});
+
+describe('AnnotationSidePanel – targetCommentId forwarding', () => {
+	it('renders CommentThread when annotation is active', async () => {
+		render(AnnotationSidePanel, {
+			...baseProps,
+			activeAnnotationId: 'ann-1',
+			targetCommentId: 'comment-42'
+		});
+		// CommentThread renders inside the panel when activeAnnotationId is set
+		const panel = document.querySelector('[data-testid="annotation-side-panel"]');
+		expect(panel).not.toBeNull();
+		expect(panel?.classList.contains('translate-x-0')).toBe(true);
+	});
+
+	it('does not render CommentThread when annotation is null', async () => {
+		render(AnnotationSidePanel, {
+			...baseProps,
+			activeAnnotationId: null,
+			targetCommentId: 'comment-42'
+		});
+		// Panel is hidden and no fetch should have been triggered for comments
+		const panel = document.querySelector('[data-testid="annotation-side-panel"]');
+		expect(panel?.classList.contains('translate-x-full')).toBe(true);
+	});
+});

frontend/src/lib/components/CommentThread.svelte

@@ -1,7 +1,10 @@
 <script lang="ts">
-import { onMount, untrack } from 'svelte';
+import { onMount, tick, untrack } from 'svelte';
 import { m } from '$lib/paraglide/messages.js';
 import type { Comment, CommentReply } from '$lib/types';
+import MentionEditor from '$lib/components/MentionEditor.svelte';
+import { renderBody, extractContent } from '$lib/utils/mention';
+import type { MentionDTO } from '$lib/types';
 
 type Props = {
 	documentId: string;
@@ -11,6 +14,7 @@ type Props = {
 	canComment: boolean;
 	currentUserId: string | null;
 	canAdmin: boolean;
+	targetCommentId?: string | null;
 	onCountChange?: (count: number) => void;
 };
 
@@ -22,16 +26,21 @@ let {
 	canComment,
 	currentUserId,
 	canAdmin,
+	targetCommentId = null,
 	onCountChange
 }: Props = $props();
 
 let comments: Comment[] = $state(untrack(() => [...initialComments]));
+let highlightedCommentId: string | null = $state(untrack(() => targetCommentId ?? null));
 let newText: string = $state('');
 let replyingTo: string | null = $state(null);
 let replyText: string = $state('');
 let editingId: string | null = $state(null);
 let editText: string = $state('');
 let posting: boolean = $state(false);
+let newMentionCandidates: MentionDTO[] = $state([]);
+let replyMentionCandidates: MentionDTO[] = $state([]);
+let editMentionCandidates: MentionDTO[] = $state([]);
 
 const commentsBase = $derived(
 	annotationId
@@ -76,13 +85,15 @@ async function postComment() {
 	if (!text || posting) return;
 	posting = true;
 	try {
+		const { content, mentionedUserIds } = extractContent(text, newMentionCandidates);
 		const res = await fetch(commentsBase, {
 			method: 'POST',
 			headers: { 'Content-Type': 'application/json' },
-			body: JSON.stringify({ content: text })
+			body: JSON.stringify({ content, mentionedUserIds })
 		});
 		if (res.ok) {
 			newText = '';
+			newMentionCandidates = [];
 			await reload();
 		}
 	} finally {
@@ -95,13 +106,15 @@ async function postReply(threadId: string) {
 	if (!text || posting) return;
 	posting = true;
 	try {
+		const { content, mentionedUserIds } = extractContent(text, replyMentionCandidates);
 		const res = await fetch(`${commentsBase}/${threadId}/replies`, {
 			method: 'POST',
 			headers: { 'Content-Type': 'application/json' },
-			body: JSON.stringify({ content: text })
+			body: JSON.stringify({ content, mentionedUserIds })
 		});
 		if (res.ok) {
 			replyText = '';
+			replyMentionCandidates = [];
 			replyingTo = null;
 			await reload();
 		}
@@ -115,13 +128,15 @@ async function saveEdit(commentId: string) {
 	if (!text || posting) return;
 	posting = true;
 	try {
+		const { content, mentionedUserIds } = extractContent(text, editMentionCandidates);
 		const res = await fetch(`/api/documents/${documentId}/comments/${commentId}`, {
 			method: 'PATCH',
 			headers: { 'Content-Type': 'application/json' },
-			body: JSON.stringify({ content: text })
+			body: JSON.stringify({ content, mentionedUserIds })
 		});
 		if (res.ok) {
 			editingId = null;
+			editMentionCandidates = [];
 			await reload();
 		}
 	} finally {
@@ -147,6 +162,7 @@ async function deleteComment(commentId: string) {
 function startEdit(comment: Comment | CommentReply) {
 	editingId = comment.id;
 	editText = comment.content;
+	editMentionCandidates = [];
 }
 
 function cancelEdit() {
@@ -164,13 +180,32 @@ function cancelReply() {
 	replyText = '';
 }
 
-onMount(() => {
+onMount(async () => {
 	if (loadOnMount) {
 		reload();
 	} else {
 		const total = initialComments.reduce((s, c) => s + 1 + c.replies.length, 0);
 		onCountChange?.(total);
 	}
+
+	if (targetCommentId) {
+		await tick();
+		requestAnimationFrame(() => {
+			const el = document.querySelector(`[data-comment-id="${targetCommentId}"]`);
+			el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+		});
+
+		// Remove highlight on first user interaction
+		const clearHighlight = () => {
+			highlightedCommentId = null;
+			document.removeEventListener('click', clearHighlight, true);
+			document.removeEventListener('keydown', clearHighlight, true);
+			document.removeEventListener('scroll', clearHighlight, true);
+		};
+		document.addEventListener('click', clearHighlight, true);
+		document.addEventListener('keydown', clearHighlight, true);
+		document.addEventListener('scroll', clearHighlight, true);
+	}
 });
 </script>
 
@@ -181,14 +216,16 @@ onMount(() => {
 {#snippet commentEntry(comment: Comment | CommentReply, threadId: string, showReplyButton: boolean)}
 	{#if editingId === comment.id}
 		<div class="flex flex-col gap-2">
-			<textarea
-				class="w-full resize-none rounded border border-line px-3 py-2 font-serif text-sm text-ink focus:ring-1 focus:ring-accent focus:outline-none"
-				rows={3}
+			<MentionEditor
 				bind:value={editText}
-			></textarea>
+				bind:mentionCandidates={editMentionCandidates}
+				rows={3}
+				disabled={posting}
+				onsubmit={() => saveEdit(comment.id)}
+			/>
 			<div class="flex items-center gap-3">
 				<button
-					class="rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-white hover:bg-primary/80 disabled:opacity-40"
+					class="rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-primary-fg hover:bg-primary/80 disabled:opacity-40"
 					disabled={posting}
 					onclick={() => saveEdit(comment.id)}
 				>
@@ -215,7 +252,10 @@ onMount(() => {
 						</span>
 					{/if}
 				</div>
-				<p class="mt-1 font-serif text-sm leading-relaxed text-ink-2">{comment.content}</p>
+				<p class="mt-1 font-serif text-sm leading-relaxed text-ink-2">
+					<!-- eslint-disable-next-line svelte/no-at-html-tags -- renderBody escapes all HTML before injecting mention links -->
+					{@html renderBody(comment.content, comment.mentionDTOs ?? [])}
+				</p>
 			</div>
 			{#if canModify(comment)}
 				<div class="flex shrink-0 items-center gap-2">
@@ -237,7 +277,7 @@ onMount(() => {
 		{#if showReplyButton && canComment}
 			<div class="mt-1">
 				<button
-					class="font-sans text-xs font-medium text-accent transition-colors hover:text-ink"
+					class="font-sans text-xs font-medium text-primary transition-colors hover:text-ink-2"
 					onclick={() => startReply(threadId)}
 				>
 					{m.comment_btn_reply()}
@@ -269,13 +309,23 @@ onMount(() => {
 	{#each comments as thread, ti (thread.id)}
 		<div class={ti > 0 ? 'border-t border-line pt-4' : ''}>
 			<!-- Root comment -->
-			<div>
+			<div
+				data-comment-id={thread.id}
+				class={highlightedCommentId === thread.id
+					? 'rounded ring-2 ring-accent ring-offset-1 transition-shadow'
+					: ''}
+			>
 				{@render commentEntry(thread, thread.id, thread.replies.length === 0)}
 			</div>
 
 			<!-- Replies -->
 			{#each thread.replies as reply, ri (reply.id)}
-				<div class="mt-3 ml-6 border-l-2 border-line pl-4">
+				<div
+					data-comment-id={reply.id}
+					class="mt-3 ml-6 border-l-2 border-line pl-4 {highlightedCommentId === reply.id
+						? 'rounded ring-2 ring-accent ring-offset-1 transition-shadow'
+						: ''}"
+				>
 					{@render commentEntry(reply, thread.id, ri === thread.replies.length - 1)}
 				</div>
 			{/each}
@@ -283,15 +333,17 @@ onMount(() => {
 			<!-- Reply compose box -->
 			{#if replyingTo === thread.id}
 				<div class="mt-3 ml-6 flex flex-col gap-2">
-					<textarea
-						class="w-full resize-none rounded border border-line px-3 py-2 font-serif text-sm text-ink focus:ring-1 focus:ring-accent focus:outline-none"
+					<MentionEditor
+						bind:value={replyText}
+						bind:mentionCandidates={replyMentionCandidates}
 						rows={3}
 						placeholder={m.comment_placeholder()}
-						bind:value={replyText}
-					></textarea>
+						disabled={posting}
+						onsubmit={() => postReply(thread.id)}
+					/>
 					<div class="flex items-center gap-3">
 						<button
-							class="rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-white hover:bg-primary/80 disabled:opacity-40"
+							class="rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-primary-fg hover:bg-primary/80 disabled:opacity-40"
 							disabled={posting}
 							onclick={() => postReply(thread.id)}
 						>
@@ -313,15 +365,17 @@ onMount(() => {
 	{#if canComment}
 		<div class={comments.length > 0 ? 'border-t border-line pt-4' : ''}>
 			<div class="flex flex-col gap-2">
-				<textarea
-					class="w-full resize-none rounded border border-line px-3 py-2 font-serif text-sm text-ink focus:ring-1 focus:ring-accent focus:outline-none"
+				<MentionEditor
+					bind:value={newText}
+					bind:mentionCandidates={newMentionCandidates}
 					rows={3}
 					placeholder={m.comment_placeholder()}
-					bind:value={newText}
-				></textarea>
+					disabled={posting}
+					onsubmit={postComment}
+				/>
 				<div>
 					<button
-						class="rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-white hover:bg-primary/80 disabled:opacity-40"
+						class="rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-primary-fg hover:bg-primary/80 disabled:opacity-40"
 						disabled={posting || !newText.trim()}
 						onclick={postComment}
 					>

frontend/src/lib/components/DashboardMentions.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+import * as m from '$lib/paraglide/messages.js';
+
+type NotificationDTO = {
+	id: string;
+	type: 'REPLY' | 'MENTION';
+	documentId?: string;
+	referenceId?: string;
+	annotationId?: string;
+	read: boolean;
+	createdAt: string;
+	actorName?: string;
+};
+
+interface Props {
+	mentions: NotificationDTO[];
+}
+
+let { mentions }: Props = $props();
+</script>
+
+{#if mentions.length > 0}
+	<div data-testid="dashboard-mentions" class="rounded-sm border border-line bg-surface p-6">
+		<h2 class="mb-4 font-sans text-xs font-bold tracking-widest text-gray-400 uppercase">
+			{m.dashboard_notifications_heading()}
+		</h2>
+		{#each mentions as mention (mention.id)}
+			<div class="flex items-center gap-3 border-b border-line py-2 last:border-0">
+				{#if mention.documentId}
+					<a
+						href={mention.annotationId
+							? `/documents/${mention.documentId}?commentId=${mention.referenceId}&annotationId=${mention.annotationId}`
+							: `/documents/${mention.documentId}?commentId=${mention.referenceId}`}
+						class="font-serif text-sm text-ink hover:text-ink-2"
+					>
+						{mention.actorName ?? ''}
+						{#if mention.type === 'MENTION'}<span class="ml-1 font-sans text-xs text-gray-400"
+								>{m.dashboard_notification_mentioned()}</span
+							>{:else}<span class="ml-1 font-sans text-xs text-gray-400"
+								>{m.dashboard_notification_replied()}</span
+							>{/if}
+					</a>
+				{:else}
+					<span class="font-serif text-sm text-ink">{mention.actorName ?? ''}</span>
+				{/if}
+			</div>
+		{/each}
+	</div>
+{/if}

frontend/src/lib/components/DashboardMentions.svelte.spec.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+import DashboardMentions from './DashboardMentions.svelte';
+
+afterEach(cleanup);
+
+type NotificationDTO = {
+	id: string;
+	type: 'REPLY' | 'MENTION';
+	documentId?: string;
+	referenceId?: string;
+	annotationId?: string;
+	read: boolean;
+	createdAt: string;
+	actorName?: string;
+};
+
+function makeMention(overrides: Partial<NotificationDTO> = {}): NotificationDTO {
+	return {
+		id: 'notif-1',
+		type: 'MENTION',
+		documentId: 'doc-abc',
+		referenceId: 'comment-xyz',
+		read: false,
+		createdAt: '2026-01-15T10:00:00Z',
+		actorName: 'Anna Schmidt',
+		...overrides
+	};
+}
+
+describe('DashboardMentions', () => {
+	it('renders nothing when mentions list is empty', async () => {
+		render(DashboardMentions, { mentions: [] });
+		const widget = page.getByTestId('dashboard-mentions');
+		await expect.element(widget).not.toBeInTheDocument();
+	});
+
+	it('shows a heading when mentions are present', async () => {
+		render(DashboardMentions, { mentions: [makeMention()] });
+		const widget = page.getByTestId('dashboard-mentions');
+		await expect.element(widget).toBeInTheDocument();
+	});
+
+	it('builds link with commentId param when no annotationId', async () => {
+		render(DashboardMentions, {
+			mentions: [makeMention({ documentId: 'doc-1', referenceId: 'cmt-1' })]
+		});
+		const link = page.getByRole('link');
+		await expect.element(link).toHaveAttribute('href', '/documents/doc-1?commentId=cmt-1');
+	});
+
+	it('builds link with commentId and annotationId when annotationId is present', async () => {
+		render(DashboardMentions, {
+			mentions: [makeMention({ documentId: 'doc-2', referenceId: 'cmt-2', annotationId: 'ann-9' })]
+		});
+		const link = page.getByRole('link');
+		await expect
+			.element(link)
+			.toHaveAttribute('href', '/documents/doc-2?commentId=cmt-2&annotationId=ann-9');
+	});
+
+	it('shows actor name in each row', async () => {
+		render(DashboardMentions, { mentions: [makeMention({ actorName: 'Maria Müller' })] });
+		await expect.element(page.getByText('Maria Müller')).toBeInTheDocument();
+	});
+});

frontend/src/lib/components/DashboardNeedsMetadata.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+import * as m from '$lib/paraglide/messages.js';
+
+type IncompleteDocumentDTO = {
+	id: string;
+	title: string;
+};
+
+interface Props {
+	incompleteDocs: IncompleteDocumentDTO[];
+}
+
+let { incompleteDocs }: Props = $props();
+</script>
+
+{#if incompleteDocs.length > 0}
+	<div data-testid="dashboard-needs-metadata" class="rounded-sm border border-line bg-surface p-6">
+		<h2 class="mb-4 font-sans text-xs font-bold tracking-widest text-gray-400 uppercase">
+			{m.dashboard_needs_metadata_heading()}
+		</h2>
+		{#each incompleteDocs as doc (doc.id)}
+			<div class="flex items-center border-b border-line py-2 last:border-0">
+				<a
+					href="/enrich/{doc.id}"
+					class="font-serif text-sm text-ink hover:text-ink-2 hover:underline"
+				>
+					{doc.title}
+				</a>
+			</div>
+		{/each}
+		<div class="mt-4">
+			<a href="/enrich" class="font-sans text-xs text-ink-2 hover:text-ink"
+				>{m.dashboard_needs_metadata_show_all()}</a
+			>
+		</div>
+	</div>
+{/if}

frontend/src/lib/components/DashboardNeedsMetadata.svelte.spec.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+import DashboardNeedsMetadata from './DashboardNeedsMetadata.svelte';
+
+afterEach(cleanup);
+
+type IncompleteDocumentDTO = {
+	id: string;
+	title: string;
+};
+
+function makeDoc(id: string, title: string): IncompleteDocumentDTO {
+	return { id, title };
+}
+
+describe('DashboardNeedsMetadata', () => {
+	it('renders nothing when incompleteDocs is empty', async () => {
+		render(DashboardNeedsMetadata, { incompleteDocs: [] });
+		const widget = page.getByTestId('dashboard-needs-metadata');
+		await expect.element(widget).not.toBeInTheDocument();
+	});
+
+	it('shows the widget when incompleteDocs are present', async () => {
+		render(DashboardNeedsMetadata, { incompleteDocs: [makeDoc('d1', 'Taufschein')] });
+		const widget = page.getByTestId('dashboard-needs-metadata');
+		await expect.element(widget).toBeInTheDocument();
+	});
+
+	it('renders a link to /enrich/{id} for each document', async () => {
+		const docs = [makeDoc('d1', 'Taufschein'), makeDoc('d2', 'Heiratsurkunde')];
+		render(DashboardNeedsMetadata, { incompleteDocs: docs });
+		const links = page.getByRole('link');
+		await expect.element(links.nth(0)).toHaveAttribute('href', '/enrich/d1');
+		await expect.element(links.nth(1)).toHaveAttribute('href', '/enrich/d2');
+	});
+
+	it('shows the document title in each row', async () => {
+		render(DashboardNeedsMetadata, { incompleteDocs: [makeDoc('d1', 'Sterbeurkunde 1930')] });
+		await expect.element(page.getByText('Sterbeurkunde 1930')).toBeInTheDocument();
+	});
+
+	it('shows a "Alle anzeigen" link to /enrich', async () => {
+		render(DashboardNeedsMetadata, { incompleteDocs: [makeDoc('d1', 'Dok')] });
+		const allLink = page.getByRole('link', { name: /Alle anzeigen/i });
+		await expect.element(allLink).toHaveAttribute('href', '/enrich');
+	});
+});

frontend/src/lib/components/DashboardRecentDocuments.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+import * as m from '$lib/paraglide/messages.js';
+import { getLocale } from '$lib/paraglide/runtime.js';
+
+type Document = {
+	id: string;
+	title: string;
+	createdAt?: string;
+	sender?: { id: string; firstName: string; lastName: string };
+};
+
+interface Props {
+	recentDocs: Document[];
+}
+
+let { recentDocs }: Props = $props();
+
+function formatDate(dateStr: string): string {
+	return new Intl.DateTimeFormat(getLocale(), {
+		day: 'numeric',
+		month: 'long',
+		year: 'numeric'
+	}).format(new Date(dateStr));
+}
+</script>
+
+{#if recentDocs.length > 0}
+	<div data-testid="dashboard-recent-docs" class="rounded-sm border border-line bg-surface p-6">
+		<h2 class="mb-4 font-sans text-xs font-bold tracking-widest text-gray-400 uppercase">
+			{m.dashboard_recent_heading()}
+		</h2>
+		{#each recentDocs as doc (doc.id)}
+			<div class="flex items-center justify-between border-b border-line py-2 last:border-0">
+				<a
+					href="/documents/{doc.id}"
+					class="font-serif text-sm text-ink hover:text-ink-2 hover:underline"
+				>
+					{doc.title}
+				</a>
+				{#if doc.createdAt}
+					<span
+						data-testid="doc-date-{doc.id}"
+						class="ml-2 shrink-0 font-sans text-xs text-gray-400"
+					>
+						{formatDate(doc.createdAt)}
+					</span>
+				{/if}
+			</div>
+		{/each}
+	</div>
+{/if}

frontend/src/lib/components/DashboardRecentDocuments.svelte.spec.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+import DashboardRecentDocuments from './DashboardRecentDocuments.svelte';
+
+afterEach(cleanup);
+
+type Document = {
+	id: string;
+	title: string;
+	createdAt?: string;
+	sender?: { id: string; firstName: string; lastName: string };
+};
+
+function makeDoc(id: string, title: string, createdAt?: string): Document {
+	return { id, title, createdAt };
+}
+
+describe('DashboardRecentDocuments', () => {
+	it('renders nothing when recentDocs is empty', async () => {
+		render(DashboardRecentDocuments, { recentDocs: [] });
+		const widget = page.getByTestId('dashboard-recent-docs');
+		await expect.element(widget).not.toBeInTheDocument();
+	});
+
+	it('shows the widget when recentDocs are present', async () => {
+		render(DashboardRecentDocuments, { recentDocs: [makeDoc('d1', 'Taufschein')] });
+		const widget = page.getByTestId('dashboard-recent-docs');
+		await expect.element(widget).toBeInTheDocument();
+	});
+
+	it('renders a link to /documents/{id} for each document', async () => {
+		const docs = [makeDoc('d1', 'Taufschein'), makeDoc('d2', 'Heiratsurkunde')];
+		render(DashboardRecentDocuments, { recentDocs: docs });
+		const links = page.getByRole('link');
+		await expect.element(links.nth(0)).toHaveAttribute('href', '/documents/d1');
+		await expect.element(links.nth(1)).toHaveAttribute('href', '/documents/d2');
+	});
+
+	it('shows the document title in each row', async () => {
+		render(DashboardRecentDocuments, {
+			recentDocs: [makeDoc('d1', 'Sterbeurkunde 1930', '1930-05-12')]
+		});
+		await expect.element(page.getByText('Sterbeurkunde 1930')).toBeInTheDocument();
+	});
+
+	it('formats and displays the document date when present', async () => {
+		render(DashboardRecentDocuments, { recentDocs: [makeDoc('d1', 'Dok', '1945-04-20')] });
+		// The date should be visible in some formatted form
+		const widget = page.getByTestId('dashboard-recent-docs');
+		await expect.element(widget).toBeInTheDocument();
+		// Just verify the date element exists (not exact format due to locale)
+		const dateEl = page.getByTestId('doc-date-d1');
+		await expect.element(dateEl).toBeInTheDocument();
+	});
+});

frontend/src/lib/components/DashboardResumeStrip.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+import { onMount } from 'svelte';
+import * as m from '$lib/paraglide/messages.js';
+
+interface LastVisited {
+	id: string;
+	title: string;
+}
+
+let lastVisited = $state<LastVisited | null>(null);
+
+onMount(() => {
+	try {
+		const raw = localStorage.getItem('familienarchiv.lastVisited');
+		if (raw) {
+			const parsed = JSON.parse(raw) as LastVisited;
+			if (parsed?.id) {
+				lastVisited = parsed;
+			}
+		}
+	} catch {
+		// ignore malformed JSON
+	}
+});
+</script>
+
+{#if lastVisited}
+	<div
+		data-testid="resume-strip"
+		class="flex items-center gap-2 rounded-sm border border-line bg-surface px-4 py-3 font-sans text-sm"
+	>
+		<span class="text-ink-2">{m.dashboard_resume_label()}</span>
+		<a href="/documents/{lastVisited.id}" class="font-medium text-ink hover:underline">
+			{lastVisited.title || m.dashboard_resume_fallback()}
+		</a>
+	</div>
+{/if}

frontend/src/lib/components/DashboardResumeStrip.svelte.spec.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+import DashboardResumeStrip from './DashboardResumeStrip.svelte';
+
+afterEach(() => {
+	cleanup();
+	localStorage.clear();
+});
+
+describe('DashboardResumeStrip', () => {
+	it('renders nothing when no last-visited document in localStorage', async () => {
+		render(DashboardResumeStrip, {});
+		const strip = page.getByTestId('resume-strip');
+		await expect.element(strip).not.toBeInTheDocument();
+	});
+
+	it('shows the strip with link when localStorage has a document', async () => {
+		localStorage.setItem(
+			'familienarchiv.lastVisited',
+			JSON.stringify({ id: 'doc-123', title: 'Geburtsurkunde 1920' })
+		);
+		render(DashboardResumeStrip, {});
+		const strip = page.getByTestId('resume-strip');
+		await expect.element(strip).toBeInTheDocument();
+		const link = page.getByRole('link', { name: /Geburtsurkunde 1920/ });
+		await expect.element(link).toBeInTheDocument();
+		await expect.element(link).toHaveAttribute('href', '/documents/doc-123');
+	});
+
+	it('uses title fallback text when title is empty', async () => {
+		localStorage.setItem(
+			'familienarchiv.lastVisited',
+			JSON.stringify({ id: 'doc-456', title: '' })
+		);
+		render(DashboardResumeStrip, {});
+		const strip = page.getByTestId('resume-strip');
+		await expect.element(strip).toBeInTheDocument();
+		const link = page.getByRole('link');
+		await expect.element(link).toHaveAttribute('href', '/documents/doc-456');
+	});
+});

frontend/src/lib/components/DocumentBottomPanel.svelte

@@ -28,6 +28,7 @@ type Props = {
 	open: boolean;
 	height: number;
 	activeTab: DocumentPanelTab;
+	targetCommentId?: string | null;
 };
 
 let {
@@ -38,7 +39,8 @@ let {
 	canAdmin,
 	open = $bindable(),
 	height = $bindable(),
-	activeTab = $bindable()
+	activeTab = $bindable(),
+	targetCommentId = null
 }: Props = $props();
 
 const MIN_HEIGHT = 52; // drag handle (8px) + tab bar (~44px)
@@ -107,7 +109,7 @@ function handleCountChange(count: number) {
 </script>
 
 <div
-	class="fixed right-0 bottom-0 left-0 z-30 flex flex-col border-t border-line bg-surface shadow-[0_-4px_16px_rgba(0,0,0,0.08)]"
+	class="z-30 flex shrink-0 flex-col border-t border-line bg-surface shadow-[0_-4px_16px_rgba(0,0,0,0.08)]"
 	style="height: {panelHeight}px"
 	data-testid="bottom-panel"
 >
@@ -127,35 +129,37 @@ function handleCountChange(count: number) {
 	</div>
 
 	<!-- Tab bar -->
-	<div class="flex shrink-0 items-center border-b border-line bg-surface px-4">
-		{#each tabs as tab (tab.id)}
-			<button
-				onclick={() => openTab(tab.id)}
-				class="mr-1 px-3 py-2.5 font-sans text-xs font-medium transition-colors {activeTab === tab.id && open
-					? 'border-b-2 border-primary text-ink'
-					: 'text-ink-3 hover:text-ink'}"
-				aria-pressed={activeTab === tab.id && open}
-			>
-				{tab.label()}
-				{#if tab.id === 'discussion'}
-					<span
-						data-testid="discussion-count-badge"
-						class="ml-1.5 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-primary px-1 font-sans text-[10px] font-bold text-primary-fg"
-						>{discussionCount}</span
-					>
-				{/if}
-			</button>
-		{/each}
-
-		<!-- spacer -->
-		<div class="flex-1"></div>
+	<div class="flex shrink-0 items-center border-b border-line bg-surface">
+		<!-- Scrollable tabs area — hides scrollbar visually -->
+		<div
+			class="flex flex-1 items-center overflow-x-auto px-2 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+		>
+			{#each tabs as tab (tab.id)}
+				<button
+					onclick={() => openTab(tab.id)}
+					class="mr-1 shrink-0 px-3 py-2.5 font-sans text-xs font-medium transition-colors {activeTab === tab.id && open
+						? 'border-b-2 border-primary text-ink'
+						: 'text-ink-3 hover:text-ink'}"
+					aria-pressed={activeTab === tab.id && open}
+				>
+					{tab.label()}
+					{#if tab.id === 'discussion'}
+						<span
+							data-testid="discussion-count-badge"
+							class="ml-1.5 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-primary px-1 font-sans text-[10px] font-bold text-primary-fg"
+							>{discussionCount}</span
+						>
+					{/if}
+				</button>
+			{/each}
+		</div>
 
 		{#if open}
 			<button
 				onclick={closePanel}
 				data-testid="panel-close-btn"
 				aria-label="Panel schließen"
-				class="rounded p-1.5 text-ink-3 transition-colors hover:bg-muted hover:text-ink"
+				class="mr-2 shrink-0 rounded p-1.5 text-ink-3 transition-colors hover:bg-muted hover:text-ink"
 			>
 				<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
 					<path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
@@ -178,6 +182,7 @@ function handleCountChange(count: number) {
 					canComment={canComment}
 					currentUserId={currentUserId}
 					canAdmin={canAdmin}
+					targetCommentId={targetCommentId}
 					onCountChange={handleCountChange}
 				/>
 			{:else if activeTab === 'history'}

frontend/src/lib/components/DocumentTopBar.svelte

@@ -58,7 +58,7 @@ const compactMeta = $derived.by(() => {
 </script>
 
 <div
-	class="z-20 flex shrink-0 items-center justify-between border-b border-line bg-surface px-6 py-3 shadow-sm"
+	class="z-20 flex shrink-0 items-center justify-between border-b border-line bg-surface px-3 py-3 shadow-sm sm:px-6"
 	data-topbar
 >
 	<!-- Left: back + title -->
@@ -102,8 +102,8 @@ const compactMeta = $derived.by(() => {
 				onclick={() => (annotateMode = !annotateMode)}
 				aria-label={annotateMode ? m.doc_panel_annotate_stop() : m.doc_panel_annotate()}
 				class="flex items-center gap-1.5 rounded px-3 py-1.5 font-sans text-xs font-medium transition {annotateMode
-					? 'bg-primary text-white'
-					: 'border border-primary text-ink hover:bg-primary hover:text-white'}"
+					? 'bg-primary text-primary-fg'
+					: 'border border-primary text-ink hover:bg-primary hover:text-primary-fg'}"
 			>
 				<img
 					src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Note/Note-Add-MD.svg"
@@ -111,14 +111,17 @@ const compactMeta = $derived.by(() => {
 					aria-hidden="true"
 					class="h-4 w-4 {annotateMode ? 'invert' : ''}"
 				/>
-				{annotateMode ? m.doc_panel_annotate_stop() : m.doc_panel_annotate()}
+				<span class="hidden sm:inline"
+					>{annotateMode ? m.doc_panel_annotate_stop() : m.doc_panel_annotate()}</span
+				>
 			</button>
 		{/if}
 
 		{#if canWrite}
 			<a
 				href="/documents/{doc.id}/edit"
-				class="flex items-center gap-2 rounded border border-primary bg-transparent px-3 py-1.5 text-xs font-medium text-ink transition hover:bg-primary hover:text-white"
+				aria-label={m.btn_edit()}
+				class="flex items-center gap-2 rounded border border-primary bg-transparent px-3 py-1.5 text-xs font-medium text-ink transition hover:bg-primary hover:text-primary-fg"
 			>
 				<img
 					src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Edit-Content-MD.svg"
@@ -126,7 +129,7 @@ const compactMeta = $derived.by(() => {
 					aria-hidden="true"
 					class="h-4 w-4"
 				/>
-				{m.btn_edit()}
+				<span class="hidden sm:inline">{m.btn_edit()}</span>
 			</a>
 		{/if}
 

frontend/src/lib/components/LanguageSwitcher.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+import { setLocale, getLocale } from '$lib/paraglide/runtime';
+
+const locales = ['DE', 'EN', 'ES'] as const;
+const localeMap = { DE: 'de', EN: 'en', ES: 'es' } as const;
+const activeLocale = $derived(getLocale().toUpperCase());
+</script>
+
+{#each locales as locale (locale)}
+	<button
+		type="button"
+		onclick={() => setLocale(localeMap[locale])}
+		class="font-sans tracking-widest transition-colors
+               {activeLocale === locale ? 'font-bold text-ink' : 'font-normal text-ink-3 hover:text-ink'}"
+	>
+		{locale}
+	</button>
+{/each}

frontend/src/lib/components/MentionEditor.svelte

@@ -0,0 +1,237 @@
+<script lang="ts">
+import { onDestroy, tick } from 'svelte';
+import { detectMention } from '$lib/utils/mention';
+import type { MentionDTO } from '$lib/types';
+import { m } from '$lib/paraglide/messages.js';
+
+type Props = {
+	value: string;
+	mentionCandidates: MentionDTO[];
+	placeholder?: string;
+	rows?: number;
+	disabled?: boolean;
+	onsubmit?: () => void;
+};
+
+let {
+	value = $bindable(''),
+	mentionCandidates = $bindable([]),
+	placeholder = '',
+	rows = 3,
+	disabled = false,
+	onsubmit
+}: Props = $props();
+
+let query: string | null = $state(null);
+let results: MentionDTO[] = $state([]);
+let highlightedIndex = $state(0);
+let mentionStart = $state(0);
+
+let textarea: HTMLTextAreaElement | null = null;
+let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+
+function attachTextarea(node: HTMLTextAreaElement) {
+	textarea = node;
+	return () => {
+		textarea = null;
+	};
+}
+
+function handleInput() {
+	if (!textarea) return;
+	const cursorPos = textarea.selectionStart;
+	const detected = detectMention(value, cursorPos);
+
+	if (detected === null) {
+		closePopup();
+		return;
+	}
+
+	// Calculate where the @ starts
+	const before = value.slice(0, cursorPos);
+	const atIndex = before.lastIndexOf('@');
+	mentionStart = atIndex;
+
+	if (query !== detected) {
+		query = detected;
+		highlightedIndex = 0;
+		scheduleSearch(detected);
+	}
+}
+
+function scheduleSearch(q: string) {
+	clearTimeout(debounceTimer);
+	if (!q) {
+		results = [];
+		return;
+	}
+	debounceTimer = setTimeout(async () => {
+		try {
+			const res = await fetch(`/api/users/search?q=${encodeURIComponent(q)}`);
+			if (res.ok) {
+				const data: MentionDTO[] = await res.json();
+				results = data.slice(0, 5);
+			} else {
+				results = [];
+			}
+		} catch {
+			results = [];
+		}
+	}, 200);
+}
+
+async function selectUser(user: MentionDTO) {
+	if (!textarea) return;
+
+	const displayName = `${user.firstName} ${user.lastName}`;
+	// Replace @partialQuery with @FirstName LastName (plus trailing space)
+	const replacement = `@${displayName} `;
+	const cursorPos = textarea.selectionStart;
+	const before = value.slice(0, mentionStart);
+	const after = value.slice(cursorPos);
+	value = before + replacement + after;
+
+	// Deduplicate and add to candidates
+	if (!mentionCandidates.some((c) => c.id === user.id)) {
+		mentionCandidates = [...mentionCandidates, user];
+	}
+
+	closePopup();
+
+	// Reposition cursor after the inserted mention
+	await tick();
+	if (!textarea) return;
+	const pos = mentionStart + replacement.length;
+	textarea.selectionStart = pos;
+	textarea.selectionEnd = pos;
+	textarea.focus();
+}
+
+function closePopup() {
+	query = null;
+	results = [];
+	highlightedIndex = 0;
+	clearTimeout(debounceTimer);
+}
+
+function handleKeydown(e: KeyboardEvent) {
+	if (e.ctrlKey && e.key === 'Enter') {
+		e.preventDefault();
+		onsubmit?.();
+		return;
+	}
+
+	if (query === null) return;
+
+	if (e.key === 'Escape') {
+		e.preventDefault();
+		closePopup();
+		return;
+	}
+
+	if (e.key === 'ArrowDown') {
+		e.preventDefault();
+		if (results.length > 0) {
+			highlightedIndex = (highlightedIndex + 1) % results.length;
+		}
+		return;
+	}
+
+	if (e.key === 'ArrowUp') {
+		e.preventDefault();
+		if (results.length > 0) {
+			highlightedIndex = (highlightedIndex - 1 + results.length) % results.length;
+		}
+		return;
+	}
+
+	if (e.key === 'Enter' && results.length > 0) {
+		e.preventDefault();
+		selectUser(results[highlightedIndex]);
+		return;
+	}
+}
+
+async function handleAtButtonClick() {
+	if (!textarea) return;
+	const pos = textarea.selectionStart;
+	const before = value.slice(0, pos);
+	const after = value.slice(pos);
+	// Ensure @ is preceded by whitespace or is at the start
+	const needsSpace = before.length > 0 && !/\s$/.test(before);
+	const insertion = needsSpace ? ' @' : '@';
+	value = before + insertion + after;
+
+	await tick();
+	if (!textarea) return;
+	const newPos = pos + insertion.length;
+	textarea.selectionStart = newPos;
+	textarea.selectionEnd = newPos;
+	textarea.focus();
+
+	// Trigger mention detection after inserting @
+	const detected = detectMention(value, newPos);
+	if (detected !== null) {
+		mentionStart = newPos - 1;
+		query = detected;
+		highlightedIndex = 0;
+		scheduleSearch(detected);
+	}
+}
+
+onDestroy(() => clearTimeout(debounceTimer));
+
+const popupOpen = $derived(query !== null);
+</script>
+
+<div class="relative">
+	<textarea
+		{@attach attachTextarea}
+		class="w-full resize-none rounded border border-line px-3 py-2 font-serif text-sm text-ink focus:ring-1 focus:ring-accent focus:outline-none"
+		rows={rows}
+		placeholder={placeholder}
+		disabled={disabled}
+		bind:value={value}
+		oninput={handleInput}
+		onkeydown={handleKeydown}
+	></textarea>
+
+	{#if popupOpen}
+		<div
+			class="absolute z-20 mt-1 w-64 overflow-hidden rounded-sm border border-line bg-surface shadow-lg"
+			role="listbox"
+			aria-label={m.mention_btn_label()}
+		>
+			{#if results.length === 0}
+				<p class="px-3 py-2 font-sans text-sm text-ink-3">{m.mention_popup_empty()}</p>
+			{:else}
+				{#each results as user, i (user.id)}
+					<div
+						class="w-full px-3 py-2 text-left font-sans text-sm text-ink hover:bg-canvas {i === highlightedIndex ? 'bg-canvas' : ''}"
+						role="option"
+						aria-selected={i === highlightedIndex}
+						tabindex="-1"
+						onmousedown={(e) => {
+							// Use mousedown to fire before textarea blur
+							e.preventDefault();
+							selectUser(user);
+						}}
+					>
+						{user.firstName}
+						{user.lastName}
+					</div>
+				{/each}
+			{/if}
+		</div>
+	{/if}
+
+	<button
+		type="button"
+		aria-label={m.mention_btn_label()}
+		disabled={disabled}
+		class="mt-1 rounded border border-line px-2 py-0.5 font-sans text-xs font-medium text-ink-3 transition-colors hover:border-ink hover:text-ink disabled:opacity-40"
+		onclick={handleAtButtonClick}
+	>
+		@
+	</button>
+</div>

frontend/src/lib/components/NotificationBell.svelte

@@ -0,0 +1,322 @@
+<script lang="ts">
+import { onMount, onDestroy } from 'svelte';
+import { goto } from '$app/navigation';
+import { m } from '$lib/paraglide/messages.js';
+
+type NotificationItem = {
+	id: string;
+	type: 'REPLY' | 'MENTION';
+	documentId: string;
+	referenceId: string;
+	annotationId: string | null;
+	read: boolean;
+	createdAt: string;
+	actorName: string;
+};
+
+let notifications: NotificationItem[] = $state([]);
+let unreadCount: number = $state(0);
+let open = $state(false);
+
+// DOM refs managed via attachments
+let bellButtonEl: HTMLButtonElement | null = null;
+let firstFocusableEl: HTMLButtonElement | null = null;
+
+let eventSource: EventSource | null = null;
+
+async function fetchNotifications() {
+	try {
+		const res = await fetch('/api/notifications?size=10');
+		if (res.ok) {
+			const data = await res.json();
+			notifications = data.content ?? [];
+		}
+	} catch (e) {
+		console.error('Failed to fetch notifications', e);
+	}
+}
+
+async function fetchUnreadCount() {
+	try {
+		const res = await fetch('/api/notifications/unread-count');
+		if (res.ok) {
+			const data = await res.json();
+			unreadCount = data.count;
+		}
+	} catch (e) {
+		console.error('Failed to fetch unread count', e);
+	}
+}
+
+async function toggleDropdown() {
+	open = !open;
+	if (open) {
+		await fetchNotifications();
+		// defer focus until DOM updates
+		setTimeout(() => {
+			firstFocusableEl?.focus();
+		}, 0);
+	}
+}
+
+function closeDropdown() {
+	open = false;
+	bellButtonEl?.focus();
+}
+
+async function markRead(notification: NotificationItem) {
+	if (!notification.read) {
+		try {
+			await fetch(`/api/notifications/${notification.id}/read`, { method: 'PATCH' });
+			notification.read = true;
+			unreadCount = Math.max(0, unreadCount - 1);
+		} catch (e) {
+			console.error('Failed to mark notification as read', e);
+		}
+	}
+	const url = notification.annotationId
+		? `/documents/${notification.documentId}?commentId=${notification.referenceId}&annotationId=${notification.annotationId}`
+		: `/documents/${notification.documentId}?commentId=${notification.referenceId}`;
+	closeDropdown();
+	goto(url);
+}
+
+async function markAllRead() {
+	try {
+		await fetch('/api/notifications/read-all', { method: 'POST' });
+		for (const n of notifications) {
+			n.read = true;
+		}
+		unreadCount = 0;
+	} catch (e) {
+		console.error('Failed to mark all notifications as read', e);
+	}
+}
+
+function handleKeydown(event: KeyboardEvent) {
+	if (event.key === 'Escape' && open) {
+		event.stopPropagation();
+		closeDropdown();
+	}
+}
+
+// Attachment: stores the element reference for the bell button
+function attachBellButton(node: HTMLButtonElement) {
+	bellButtonEl = node;
+	return () => {
+		bellButtonEl = null;
+	};
+}
+
+// Attachment: stores the element reference for the first focusable element in the dropdown
+function attachFirstFocusable(node: HTMLButtonElement) {
+	firstFocusableEl = node;
+	return () => {
+		firstFocusableEl = null;
+	};
+}
+
+// Attachment: closes dropdown when clicking outside the wrapper element
+function attachClickOutside(node: HTMLElement) {
+	const handleClick = (event: MouseEvent) => {
+		if (!node.contains(event.target as Node) && !event.defaultPrevented) {
+			if (open) {
+				open = false;
+			}
+		}
+	};
+	document.addEventListener('click', handleClick, true);
+	return () => {
+		document.removeEventListener('click', handleClick, true);
+	};
+}
+
+function relativeTime(isoString: string): string {
+	const diffMs = Date.now() - new Date(isoString).getTime();
+	const diffMin = Math.floor(diffMs / 60000);
+	const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+	if (diffMin < 1) return rtf.format(0, 'minute');
+	if (diffMin < 60) return rtf.format(-diffMin, 'minute');
+	const diffH = Math.floor(diffMin / 60);
+	if (diffH < 24) return rtf.format(-diffH, 'hour');
+	const diffD = Math.floor(diffH / 24);
+	return rtf.format(-diffD, 'day');
+}
+
+onMount(() => {
+	fetchUnreadCount();
+	eventSource = new EventSource('/api/notifications/stream');
+	eventSource.addEventListener('notification', (e) => {
+		const notification = JSON.parse(e.data) as NotificationItem;
+		notifications = [notification, ...notifications];
+		if (!notification.read) unreadCount += 1;
+	});
+});
+
+onDestroy(() => {
+	eventSource?.close();
+});
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+
+<div class="relative" {@attach attachClickOutside}>
+	<!-- Bell button -->
+	<button
+		{@attach attachBellButton}
+		type="button"
+		onclick={toggleDropdown}
+		aria-label={unreadCount > 0
+			? m.notification_bell_unread_label({ count: unreadCount })
+			: m.notification_bell_label()}
+		aria-expanded={open}
+		aria-haspopup="true"
+		class="relative rounded-sm p-2 text-ink-2 transition-colors hover:text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-accent"
+	>
+		<!-- Bell SVG -->
+		<svg
+			xmlns="http://www.w3.org/2000/svg"
+			class="h-5 w-5"
+			fill="none"
+			viewBox="0 0 24 24"
+			stroke="currentColor"
+			stroke-width="2"
+			aria-hidden="true"
+		>
+			<path
+				stroke-linecap="round"
+				stroke-linejoin="round"
+				d="M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9"
+			/>
+		</svg>
+
+		<!-- Unread badge -->
+		{#if unreadCount > 0}
+			<span
+				aria-live="polite"
+				aria-atomic="true"
+				class="absolute -top-1 -right-1 flex h-5 min-w-5 items-center justify-center rounded-full bg-primary px-1 text-[10px] font-bold text-primary-fg"
+			>
+				{unreadCount}
+			</span>
+		{/if}
+	</button>
+
+	<!-- Dropdown -->
+	{#if open}
+		<div
+			role="dialog"
+			aria-modal="true"
+			aria-label={m.notification_bell_label()}
+			class="absolute right-0 z-50 mt-2 w-80 overflow-hidden rounded-sm border border-line bg-surface shadow-lg"
+		>
+			<!-- Header -->
+			<div class="flex items-center justify-between border-b border-line px-4 py-3">
+				<span class="text-xs font-bold tracking-widest text-ink-2 uppercase">
+					{m.notification_bell_label()}
+				</span>
+				{#if notifications.length > 0}
+					<button
+						{@attach attachFirstFocusable}
+						type="button"
+						onclick={markAllRead}
+						class="text-xs font-medium text-ink-3 transition-colors hover:text-ink"
+					>
+						{m.notification_mark_all_read()}
+					</button>
+				{/if}
+			</div>
+
+			<!-- Notification list -->
+			{#if notifications.length === 0}
+				<!-- Empty state -->
+				<div class="flex flex-col items-center gap-2 px-4 py-8 text-center text-sm text-ink-3">
+					<svg
+						xmlns="http://www.w3.org/2000/svg"
+						class="h-8 w-8 text-ink-3 opacity-40"
+						fill="none"
+						viewBox="0 0 24 24"
+						stroke="currentColor"
+						stroke-width="1.5"
+						aria-hidden="true"
+					>
+						<path
+							stroke-linecap="round"
+							stroke-linejoin="round"
+							d="M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9"
+						/>
+					</svg>
+					<span>{m.notification_empty()}</span>
+				</div>
+			{:else}
+				<ul role="list">
+					{#each notifications as notification (notification.id)}
+						<li>
+							<button
+								type="button"
+								onclick={() => markRead(notification)}
+								class="flex w-full cursor-pointer items-start gap-3 border-b border-line px-4 py-3 text-left last:border-b-0 hover:bg-canvas
+									{!notification.read ? 'bg-accent-bg/20' : ''}"
+							>
+								<!-- Type icon -->
+								<span class="mt-0.5 shrink-0 text-ink-3" aria-hidden="true">
+									{#if notification.type === 'REPLY'}
+										<!-- Reply icon -->
+										<svg
+											xmlns="http://www.w3.org/2000/svg"
+											class="h-4 w-4"
+											fill="none"
+											viewBox="0 0 24 24"
+											stroke="currentColor"
+											stroke-width="2"
+										>
+											<path
+												stroke-linecap="round"
+												stroke-linejoin="round"
+												d="M3 10h10a8 8 0 018 8v2M3 10l6 6m-6-6l6-6"
+											/>
+										</svg>
+									{:else}
+										<!-- Mention icon -->
+										<svg
+											xmlns="http://www.w3.org/2000/svg"
+											class="h-4 w-4"
+											fill="none"
+											viewBox="0 0 24 24"
+											stroke="currentColor"
+											stroke-width="2"
+										>
+											<path
+												stroke-linecap="round"
+												stroke-linejoin="round"
+												d="M16 12a4 4 0 10-8 0 4 4 0 008 0zm0 0v1.5a2.5 2.5 0 005 0V12a9 9 0 10-9 9m4.5-1.206a8.959 8.959 0 01-4.5 1.207"
+											/>
+										</svg>
+									{/if}
+								</span>
+
+								<!-- Text + time -->
+								<div class="min-w-0 flex-1">
+									<p class="text-sm leading-snug text-ink">
+										{notification.type === 'REPLY'
+											? m.notification_type_reply({ actor: notification.actorName })
+											: m.notification_type_mention({ actor: notification.actorName })}
+									</p>
+									<p class="mt-1 text-xs text-ink-3">{relativeTime(notification.createdAt)}</p>
+								</div>
+
+								<!-- Unread dot -->
+								{#if !notification.read}
+									<span
+										class="mt-1.5 h-2 w-2 shrink-0 rounded-full bg-primary"
+										aria-label={m.notification_unread()}
+									></span>
+								{/if}
+							</button>
+						</li>
+					{/each}
+				</ul>
+			{/if}
+		</div>
+	{/if}
+</div>

frontend/src/lib/components/PanelDiscussion.svelte

@@ -8,11 +8,19 @@ type Props = {
 	canComment: boolean;
 	currentUserId: string | null;
 	canAdmin: boolean;
+	targetCommentId?: string | null;
 	onCountChange?: (count: number) => void;
 };
 
-let { documentId, initialComments, canComment, currentUserId, canAdmin, onCountChange }: Props =
-	$props();
+let {
+	documentId,
+	initialComments,
+	canComment,
+	currentUserId,
+	canAdmin,
+	targetCommentId = null,
+	onCountChange
+}: Props = $props();
 </script>
 
 <div class="flex-1 overflow-y-auto p-6">
@@ -22,6 +30,7 @@ let { documentId, initialComments, canComment, currentUserId, canAdmin, onCountC
 		canComment={canComment}
 		currentUserId={currentUserId}
 		canAdmin={canAdmin}
+		targetCommentId={targetCommentId}
 		onCountChange={onCountChange}
 	/>
 </div>

frontend/src/lib/components/PanelHistory.svelte

@@ -328,7 +328,7 @@ $effect(() => {
 				<button
 					onclick={applyCompare}
 					disabled={!compareA || !compareB || compareA === compareB}
-					class="w-full rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-white transition hover:bg-primary/80 disabled:cursor-not-allowed disabled:opacity-40"
+					class="w-full rounded bg-primary px-3 py-1.5 font-sans text-xs font-medium text-primary-fg transition hover:bg-primary/80 disabled:cursor-not-allowed disabled:opacity-40"
 				>
 					{m.history_compare_apply()}
 				</button>
@@ -406,7 +406,7 @@ $effect(() => {
 			{/if}
 		{:else}
 			<!-- Version list with inline diff below each selected item -->
-			<ul class="divide-brand-sand divide-y">
+			<ul class="divide-y divide-line">
 				{#each versions as v, i (v.id)}
 					<li>
 						<button

frontend/src/lib/components/PanelMetadata.svelte

@@ -100,7 +100,7 @@ let { doc }: { doc: Doc } = $props();
 							{#each doc.tags as tag (tag.id)}
 								<a
 									href="/?tag={encodeURIComponent(tag.name)}"
-									class="inline-flex items-center rounded bg-muted px-2 py-0.5 text-xs font-bold tracking-wide text-ink uppercase transition-colors hover:bg-primary hover:text-white"
+									class="inline-flex items-center rounded bg-muted px-2 py-0.5 text-xs font-bold tracking-wide text-ink uppercase transition-colors hover:bg-primary hover:text-primary-fg"
 									title={m.doc_tag_filter_title({ name: tag.name })}
 								>
 									{tag.name}
@@ -131,7 +131,7 @@ let { doc }: { doc: Doc } = $props();
 				>
 					<div class="flex items-center gap-3">
 						<div
-							class="flex h-8 w-8 items-center justify-center rounded-full bg-primary font-serif text-sm text-white"
+							class="flex h-8 w-8 items-center justify-center rounded-full bg-primary font-serif text-sm text-primary-fg"
 						>
 							{doc.sender.firstName[0]}{doc.sender.lastName[0]}
 						</div>

frontend/src/lib/components/PdfViewer.svelte

@@ -297,7 +297,7 @@ function zoomOut() {
 			href={url}
 			target="_blank"
 			rel="noopener noreferrer"
-			class="font-sans text-xs text-accent underline hover:opacity-80"
+			class="font-sans text-xs text-primary underline hover:text-ink-2"
 		>
 			Direkt öffnen
 		</a>

frontend/src/lib/components/document/DescriptionSection.svelte

@@ -9,7 +9,8 @@ let {
 	initialDocumentLocation = '',
 	initialSummary = '',
 	titleRequired = false,
-	suggestedTitle = ''
+	suggestedTitle = '',
+	hideTitle = false
 }: {
 	tags?: string[];
 	initialTitle?: string;
@@ -17,17 +18,12 @@ let {
 	initialSummary?: string;
 	titleRequired?: boolean;
 	suggestedTitle?: string;
+	hideTitle?: boolean;
 } = $props();
 
-let titleValue = $state(untrack(() => initialTitle));
 let titleDirty = $state(false);
-
-$effect(() => {
-	const suggested = suggestedTitle;
-	if (suggested && !untrack(() => titleDirty)) {
-		titleValue = suggested;
-	}
-});
+let titleOverride = $state(untrack(() => initialTitle));
+let titleValue = $derived(titleDirty ? titleOverride : suggestedTitle || titleOverride);
 </script>
 
 <div class="rounded-sm border border-line bg-surface p-6 shadow-sm">
@@ -36,25 +32,27 @@ $effect(() => {
 	</h2>
 
 	<div class="space-y-5">
-		<!-- Titel -->
-		<div>
-			<label for="title" class="mb-1 block text-sm font-medium text-ink-2"
-				>{m.form_label_title()}{#if titleRequired}
-					*{/if}</label
-			>
-			<input
-				id="title"
-				type="text"
-				name="title"
-				value={titleValue}
-				oninput={(e) => {
-					titleValue = (e.target as HTMLInputElement).value;
-					titleDirty = true;
-				}}
-				required={titleRequired}
-				class="block w-full rounded border border-line p-2 text-sm shadow-sm focus:border-ink focus:ring-ink"
-			/>
-		</div>
+		{#if !hideTitle}
+			<!-- Titel -->
+			<div>
+				<label for="title" class="mb-1 block text-sm font-medium text-ink-2"
+					>{m.form_label_title()}{#if titleRequired}
+						*{/if}</label
+				>
+				<input
+					id="title"
+					type="text"
+					name="title"
+					value={titleValue}
+					oninput={(e) => {
+						titleOverride = (e.target as HTMLInputElement).value;
+						titleDirty = true;
+					}}
+					required={titleRequired}
+					class="block w-full rounded border border-line p-2 text-sm shadow-sm focus:border-ink focus:ring-ink"
+				/>
+			</div>
+		{/if}
 
 		<!-- Aufbewahrungsort -->
 		<div>

frontend/src/lib/components/user/UserGroupsSection.svelte

@@ -6,6 +6,8 @@ let {
 	groups: { id: string; name: string }[];
 	selectedGroupIds?: string[];
 } = $props();
+
+let selected = $derived([...selectedGroupIds]);
 </script>
 
 <div class="flex flex-wrap gap-3">
@@ -15,7 +17,7 @@ let {
 				type="checkbox"
 				name="groupIds"
 				value={group.id}
-				checked={selectedGroupIds.includes(group.id)}
+				bind:group={selected}
 				class="rounded border-line text-ink focus:ring-accent"
 			/>
 			{group.name}

frontend/src/lib/generated/api.ts

@@ -36,6 +36,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/users/me/notification-preferences": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getPreferences"];
+        put: operations["updatePreferences"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/tags/{id}": {
         parameters: {
             query?: never;
@@ -78,7 +94,7 @@ export interface paths {
         get: operations["getDocument"];
         put: operations["updateDocument"];
         post?: never;
-        delete?: never;
+        delete: operations["deleteDocument"];
         options?: never;
         head?: never;
         patch?: never;
@@ -148,6 +164,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/notifications/read-all": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["markAllRead"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/groups": {
         parameters: {
             query?: never;
@@ -260,6 +292,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/documents/quick-upload": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["quickUpload"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/auth/reset-password": {
         parameters: {
             query?: never;
@@ -324,6 +372,38 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/admin/backfill-file-hashes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["backfillFileHashes"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/notifications/{id}/read": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch: operations["markOneRead"];
+        trace?: never;
+    };
     "/api/groups/{id}": {
         parameters: {
             query?: never;
@@ -356,6 +436,22 @@ export interface paths {
         patch: operations["editComment"];
         trace?: never;
     };
+    "/api/users/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["search"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/tags": {
         parameters: {
             query?: never;
@@ -420,6 +516,54 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/notifications": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getNotifications"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/notifications/unread-count": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["countUnread"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/notifications/stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["stream"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/documents/{id}/versions": {
         parameters: {
             query?: never;
@@ -468,14 +612,14 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/documents/incomplete-count": {
+    "/api/documents/search": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations["getIncompleteCount"];
+        get: operations["search_1"];
         put?: never;
         post?: never;
         delete?: never;
@@ -516,14 +660,14 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/documents/search": {
+    "/api/documents/incomplete-count": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations["search"];
+        get: operations["getIncompleteCount"];
         put?: never;
         post?: never;
         delete?: never;
@@ -548,6 +692,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/auth/reset-token-for-test": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getResetTokenForTest"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/admin/import-status": {
         parameters: {
             query?: never;
@@ -606,6 +766,8 @@ export interface components {
             email?: string;
             contact?: string;
             enabled: boolean;
+            notifyOnReply: boolean;
+            notifyOnMention: boolean;
             groups: components["schemas"]["UserGroup"][];
             /** Format: date-time */
             createdAt: string;
@@ -624,6 +786,10 @@ export interface components {
             email?: string;
             contact?: string;
         };
+        NotificationPreferenceDTO: {
+            notifyOnReply?: boolean;
+            notifyOnMention?: boolean;
+        };
         Tag: {
             /** Format: uuid */
             id: string;
@@ -663,6 +829,7 @@ export interface components {
             senderId?: string;
             receiverIds?: string[];
             tags?: string;
+            metadataComplete?: boolean;
         };
         Document: {
             /** Format: uuid */
@@ -686,6 +853,7 @@ export interface components {
             createdAt: string;
             /** Format: date-time */
             updatedAt: string;
+            metadataComplete: boolean;
             receivers?: components["schemas"]["Person"][];
             sender?: components["schemas"]["Person"];
             tags?: components["schemas"]["Tag"][];
@@ -711,6 +879,7 @@ export interface components {
         };
         CreateCommentDTO: {
             content?: string;
+            mentionedUserIds?: string[];
         };
         DocumentComment: {
             /** Format: uuid */
@@ -730,6 +899,13 @@ export interface components {
             /** Format: date-time */
             updatedAt: string;
             replies: components["schemas"]["DocumentComment"][];
+            mentionDTOs: components["schemas"]["MentionDTO"][];
+        };
+        MentionDTO: {
+            /** Format: uuid */
+            id: string;
+            firstName: string;
+            lastName: string;
         };
         CreateAnnotationDTO: {
             /** Format: int32 */
@@ -766,6 +942,15 @@ export interface components {
             /** Format: date-time */
             createdAt: string;
         };
+        QuickUploadResult: {
+            created?: components["schemas"]["Document"][];
+            updated?: components["schemas"]["Document"][];
+            errors?: components["schemas"]["UploadError"][];
+        };
+        UploadError: {
+            filename?: string;
+            code?: string;
+        };
         ResetPasswordRequest: {
             token?: string;
             newPassword?: string;
@@ -786,6 +971,60 @@ export interface components {
             /** Format: int32 */
             count: number;
         };
+        NotificationDTO: {
+            /** Format: uuid */
+            id: string;
+            /** @enum {string} */
+            type: "REPLY" | "MENTION";
+            /** Format: uuid */
+            documentId?: string;
+            /** Format: uuid */
+            referenceId?: string;
+            /** Format: uuid */
+            annotationId?: string;
+            read: boolean;
+            /** Format: date-time */
+            createdAt: string;
+            actorName?: string;
+        };
+        PageNotificationDTO: {
+            /** Format: int64 */
+            totalElements?: number;
+            /** Format: int32 */
+            totalPages?: number;
+            pageable?: components["schemas"]["PageableObject"];
+            /** Format: int32 */
+            size?: number;
+            content?: components["schemas"]["NotificationDTO"][];
+            /** Format: int32 */
+            number?: number;
+            sort?: components["schemas"]["SortObject"];
+            /** Format: int32 */
+            numberOfElements?: number;
+            first?: boolean;
+            last?: boolean;
+            empty?: boolean;
+        };
+        PageableObject: {
+            paged?: boolean;
+            /** Format: int32 */
+            pageNumber?: number;
+            /** Format: int32 */
+            pageSize?: number;
+            /** Format: int64 */
+            offset?: number;
+            sort?: components["schemas"]["SortObject"];
+            unpaged?: boolean;
+        };
+        SortObject: {
+            sorted?: boolean;
+            empty?: boolean;
+            unsorted?: boolean;
+        };
+        SseEmitter: {
+            /** Format: int64 */
+            timeout?: number;
+        };
         DocumentVersionSummary: {
             /** Format: uuid */
             id: string;
@@ -807,6 +1046,11 @@ export interface components {
             snapshot: string;
             changedFields: string;
         };
+        IncompleteDocumentDTO: {
+            /** Format: uuid */
+            id: string;
+            title: string;
+        };
     };
     responses: never;
     parameters: never;
@@ -928,6 +1172,50 @@ export interface operations {
             };
         };
     };
+    getPreferences: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["NotificationPreferenceDTO"];
+                };
+            };
+        };
+    };
+    updatePreferences: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["NotificationPreferenceDTO"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["NotificationPreferenceDTO"];
+                };
+            };
+        };
+    };
     updateTag: {
         parameters: {
             query?: never;
@@ -1072,6 +1360,26 @@ export interface operations {
             };
         };
     };
+    deleteDocument: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getAllUsers: {
         parameters: {
             query?: never;
@@ -1212,6 +1520,24 @@ export interface operations {
             };
         };
     };
+    markAllRead: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description No Content */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getAllGroups: {
         parameters: {
             query?: never;
@@ -1479,6 +1805,32 @@ export interface operations {
             };
         };
     };
+    quickUpload: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "multipart/form-data": {
+                    files?: string[];
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["QuickUploadResult"];
+                };
+            };
+        };
+    };
     resetPassword: {
         parameters: {
             query?: never;
@@ -1563,6 +1915,48 @@ export interface operations {
             };
         };
     };
+    backfillFileHashes: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["BackfillResult"];
+                };
+            };
+        };
+    };
+    markOneRead: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["NotificationDTO"];
+                };
+            };
+        };
+    };
     deleteGroup: {
         parameters: {
             query?: never;
@@ -1657,6 +2051,28 @@ export interface operations {
             };
         };
     };
+    search: {
+        parameters: {
+            query?: {
+                q?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["MentionDTO"][];
+                };
+            };
+        };
+    };
     searchTags: {
         parameters: {
             query?: {
@@ -1747,6 +2163,75 @@ export interface operations {
             };
         };
     };
+    getNotifications: {
+        parameters: {
+            query?: {
+                page?: number;
+                size?: number;
+                /** @description Filter by notification type */
+                type?: "REPLY" | "MENTION";
+                /** @description Filter by read status */
+                read?: boolean;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["PageNotificationDTO"];
+                };
+            };
+        };
+    };
+    countUnread: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": {
+                        [key: string]: number;
+                    };
+                };
+            };
+        };
+    };
+    stream: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": components["schemas"]["SseEmitter"];
+                };
+            };
+        };
+    };
     getVersions: {
         parameters: {
             query?: never;
@@ -1814,7 +2299,7 @@ export interface operations {
             };
         };
     };
-    search: {
+    search_1: {
         parameters: {
             query?: {
                 q?: string;
@@ -1823,6 +2308,8 @@ export interface operations {
                 senderId?: string;
                 receiverId?: string;
                 tag?: string[];
+                /** @description Filter by document status */
+                status?: "PLACEHOLDER" | "UPLOADED" | "TRANSCRIBED" | "REVIEWED" | "ARCHIVED";
             };
             header?: never;
             path?: never;
@@ -1841,6 +2328,73 @@ export interface operations {
             };
         };
     };
+    getIncomplete: {
+        parameters: {
+            query?: {
+                /** @description Maximum number of results */
+                size?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["IncompleteDocumentDTO"][];
+                };
+            };
+        };
+    };
+    getNextIncomplete: {
+        parameters: {
+            query: {
+                excludeId: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["Document"];
+                };
+            };
+        };
+    };
+    getIncompleteCount: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": {
+                        [key: string]: number;
+                    };
+                };
+            };
+        };
+    };
     getConversation: {
         parameters: {
             query: {
@@ -1867,52 +2421,10 @@ export interface operations {
             };
         };
     };
-    getIncompleteCount: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "*/*": {
-                        count: number;
-                    };
-                };
-            };
-        };
-    };
-    getIncomplete: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "*/*": components["schemas"]["Document"][];
-                };
-            };
-        };
-    };
-    getNextIncomplete: {
+    getResetTokenForTest: {
         parameters: {
             query: {
-                excludeId: string;
+                email: string;
             };
             header?: never;
             path?: never;
@@ -1926,16 +2438,9 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "*/*": components["schemas"]["Document"];
+                    "*/*": string;
                 };
             };
-            /** @description No Content */
-            204: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
         };
     };
     importStatus: {

frontend/src/lib/types.ts

@@ -1,3 +1,9 @@
+export type MentionDTO = {
+	id: string;
+	firstName: string;
+	lastName: string;
+};
+
 export type CommentReply = {
 	id: string;
 	authorId: string | null;
@@ -5,6 +11,7 @@ export type CommentReply = {
 	content: string;
 	createdAt: string;
 	updatedAt: string;
+	mentionDTOs?: MentionDTO[];
 };
 
 export type Comment = {
@@ -15,6 +22,7 @@ export type Comment = {
 	createdAt: string;
 	updatedAt: string;
 	replies: CommentReply[];
+	mentionDTOs?: MentionDTO[];
 };
 
 export type DocumentPanelTab = 'metadata' | 'transcription' | 'discussion' | 'history';

frontend/src/lib/utils/mention.spec.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest';
+import { detectMention, extractContent, renderBody } from './mention';
+import type { MentionDTO } from '$lib/types';
+
+// ─── detectMention ────────────────────────────────────────────────────────────
+
+describe('detectMention', () => {
+	it('returns null when text has no @', () => {
+		expect(detectMention('hello world', 11)).toBeNull();
+	});
+
+	it('returns null when @ is not the most recent trigger word', () => {
+		// cursor is past a completed mention (next word started)
+		expect(detectMention('hello @Hans Müller more', 22)).toBeNull();
+	});
+
+	it('returns empty string immediately after @', () => {
+		expect(detectMention('hello @', 7)).toBe('');
+	});
+
+	it('returns query text after @', () => {
+		expect(detectMention('hello @Han', 10)).toBe('Han');
+	});
+
+	it('returns null when @ is preceded by a letter (email address pattern)', () => {
+		expect(detectMention('user@example', 12)).toBeNull();
+	});
+
+	it('returns query for @ at the very start of string', () => {
+		expect(detectMention('@Hans', 5)).toBe('Hans');
+	});
+
+	it('returns null when cursor is before the @', () => {
+		expect(detectMention('@Hans', 0)).toBeNull();
+	});
+});
+
+// ─── extractContent ───────────────────────────────────────────────────────────
+
+describe('extractContent', () => {
+	it('returns empty arrays for empty string', () => {
+		const result = extractContent('', []);
+		expect(result.content).toBe('');
+		expect(result.mentionedUserIds).toEqual([]);
+	});
+
+	it('returns plain content unchanged when no candidates', () => {
+		const result = extractContent('Hello world', []);
+		expect(result.content).toBe('Hello world');
+		expect(result.mentionedUserIds).toEqual([]);
+	});
+
+	it('extracts user id when @FirstName LastName is in content', () => {
+		const candidates: MentionDTO[] = [{ id: 'uuid-1', firstName: 'Hans', lastName: 'Müller' }];
+		const result = extractContent('Hey @Hans Müller how are you?', candidates);
+		expect(result.mentionedUserIds).toContain('uuid-1');
+	});
+
+	it('deduplicates user ids when same user mentioned twice', () => {
+		const candidates: MentionDTO[] = [{ id: 'uuid-1', firstName: 'Hans', lastName: 'Müller' }];
+		const result = extractContent('@Hans Müller and @Hans Müller again', candidates);
+		expect(result.mentionedUserIds).toHaveLength(1);
+		expect(result.mentionedUserIds).toContain('uuid-1');
+	});
+
+	it('collects multiple distinct users', () => {
+		const candidates: MentionDTO[] = [
+			{ id: 'uuid-1', firstName: 'Hans', lastName: 'Müller' },
+			{ id: 'uuid-2', firstName: 'Anna', lastName: 'Schmidt' }
+		];
+		const result = extractContent('@Hans Müller and @Anna Schmidt', candidates);
+		expect(result.mentionedUserIds).toContain('uuid-1');
+		expect(result.mentionedUserIds).toContain('uuid-2');
+	});
+});
+
+// ─── renderBody ───────────────────────────────────────────────────────────────
+
+describe('renderBody', () => {
+	it('returns escaped plain text when no mentions', () => {
+		expect(renderBody('Hello world', [])).toBe('Hello world');
+	});
+
+	it('escapes < and > in content', () => {
+		const result = renderBody('<script>alert(1)</script>', []);
+		expect(result).toContain('&lt;script&gt;');
+		expect(result).not.toContain('<script>');
+	});
+
+	it('escapes & in content', () => {
+		const result = renderBody('AT&T', []);
+		expect(result).toContain('AT&amp;T');
+	});
+
+	it('wraps @mention in a mention span', () => {
+		const mentions: MentionDTO[] = [{ id: 'uuid-1', firstName: 'Hans', lastName: 'Müller' }];
+		const result = renderBody('Hey @Hans Müller!', mentions);
+		expect(result).toContain('<span');
+		expect(result).toContain('class="mention"');
+		expect(result).toContain('Hans Müller');
+	});
+
+	it('does not double-encode already escaped text', () => {
+		const mentions: MentionDTO[] = [{ id: 'uuid-1', firstName: 'Hans', lastName: 'Müller' }];
+		const result = renderBody('Check @Hans Müller', mentions);
+		expect(result).not.toContain('&amp;');
+	});
+
+	it('replaces all occurrences of the same mention', () => {
+		const mentions: MentionDTO[] = [{ id: 'uuid-1', firstName: 'Hans', lastName: 'Müller' }];
+		const result = renderBody('@Hans Müller and @Hans Müller', mentions);
+		const spanCount = (result.match(/<span /g) ?? []).length;
+		expect(spanCount).toBe(2);
+	});
+
+	it('escapes HTML special chars in mention display names', () => {
+		const mentions: MentionDTO[] = [{ id: 'u1', firstName: '<script>', lastName: 'alert(1)' }];
+		const result = renderBody('@<script> alert(1)', mentions);
+		expect(result).not.toContain('<script>');
+		expect(result).toContain('&lt;script&gt;');
+	});
+
+	it('converts newlines to <br>', () => {
+		const result = renderBody('line1\nline2', []);
+		expect(result).toContain('<br>');
+		expect(result).not.toContain('\n');
+	});
+});

frontend/src/lib/utils/mention.ts

@@ -0,0 +1,72 @@
+import type { MentionDTO } from '$lib/types';
+
+/**
+ * Given the current textarea value and cursor position, returns the
+ * @-mention query being typed (the text after the last triggering @),
+ * or null if no mention is active.
+ *
+ * Rules:
+ * - @ must be preceded by whitespace or be at the start of the string
+ * - The text between @ and the cursor must not contain a space (a
+ *   completed mention word already has a space)
+ */
+export function detectMention(text: string, cursorPos: number): string | null {
+	const before = text.slice(0, cursorPos);
+	const atIndex = before.lastIndexOf('@');
+	if (atIndex === -1) return null;
+
+	// @ must be at start or preceded by whitespace
+	if (atIndex > 0 && !/\s/.test(before[atIndex - 1])) return null;
+
+	const query = before.slice(atIndex + 1);
+	// If the query contains a space the user has moved past the trigger word
+	if (query.includes(' ')) return null;
+
+	return query;
+}
+
+/**
+ * Given the raw textarea value and a list of candidate users (from the
+ * mention popup selections), returns the plain content string and the
+ * de-duplicated list of mentioned user IDs.
+ */
+export function extractContent(
+	text: string,
+	candidates: MentionDTO[]
+): { content: string; mentionedUserIds: string[] } {
+	const seen = new Set<string>();
+	for (const user of candidates) {
+		const displayName = `${user.firstName} ${user.lastName}`.trim();
+		if (text.includes(`@${displayName}`)) {
+			seen.add(user.id);
+		}
+	}
+	return { content: text, mentionedUserIds: [...seen] };
+}
+
+/**
+ * Renders a comment body as safe HTML:
+ * 1. Escapes all HTML-special characters in the raw content
+ * 2. Replaces every @FirstName LastName occurrence with an anchor link
+ * 3. Converts newlines to <br>
+ */
+export function renderBody(content: string, mentions: MentionDTO[]): string {
+	let escaped = content
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;');
+
+	for (const mention of mentions) {
+		const displayName = `${mention.firstName} ${mention.lastName}`.trim();
+		const escapedDisplayName = displayName
+			.replaceAll('&', '&amp;')
+			.replaceAll('<', '&lt;')
+			.replaceAll('>', '&gt;')
+			.replaceAll('"', '&quot;');
+		const span = `<span class="mention" data-user-id="${mention.id}">@${escapedDisplayName}</span>`;
+		escaped = escaped.replaceAll(`@${escapedDisplayName}`, span);
+	}
+
+	return escaped.replaceAll('\n', '<br>');
+}