fix: replace remaining hardcoded brand-navy/white tokens with semantic tokens

Fixes dark mode in enrich/done page (bg-white → bg-surface, text-brand-navy → text-ink,
border-brand-sand → border-line), enrich/[id] skip button (text-brand-navy/60 → text-ink-2),
and PanelHistory version list (divide-brand-sand → divide-line).

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/config/DataInitializer.java

@@ -84,6 +84,14 @@ public class DataInitializer {
             TagRepository tagRepo,
             PasswordEncoder passwordEncoder) {
         return args -> {
+            // Always reset the admin password to the configured value so a failed password-reset
+            // test from a previous run can never leave the account locked out.
+            userRepository.findByUsername(adminUsername).ifPresent(admin -> {
+                admin.setPassword(passwordEncoder.encode(adminPassword));
+                userRepository.save(admin);
+                log.info("E2E seed: Admin-Passwort auf konfigurierten Wert zurückgesetzt.");
+            });
+
             // Always ensure the read-only test user exists, even when seed data was already loaded.
             if (userRepository.findByUsername("reader").isEmpty()) {
                 log.info("E2E seed: Erstelle 'reader'-Testbenutzer...");

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

@@ -2,7 +2,11 @@ package org.raddatz.familienarchiv.controller;
 
 import java.io.IOException;
 import java.time.LocalDate;
+import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
 import java.util.UUID;
 
 
@@ -23,6 +27,7 @@ import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.core.io.InputStreamResource;
+import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.ModelAttribute;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -103,6 +108,73 @@ public class DocumentController {
         }
     }
 
+    // --- DELETE ---
+
+    @DeleteMapping("/{id}")
+    @RequirePermission(Permission.WRITE_ALL)
+    public ResponseEntity<Void> deleteDocument(@PathVariable UUID id) {
+        documentService.deleteDocument(id);
+        return ResponseEntity.noContent().build();
+    }
+
+    // --- QUICK UPLOAD ---
+
+    private static final Set<String> ALLOWED_CONTENT_TYPES = Set.of(
+            "application/pdf", "image/jpeg", "image/png", "image/tiff");
+
+    public record UploadError(String filename, String code) {}
+    public record QuickUploadResult(List<Document> created, List<Document> updated, List<UploadError> errors) {}
+
+    @PostMapping(value = "/quick-upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @RequirePermission(Permission.WRITE_ALL)
+    public QuickUploadResult quickUpload(
+            @RequestPart(value = "files", required = false) List<MultipartFile> files) {
+        List<Document> created = new ArrayList<>();
+        List<Document> updated = new ArrayList<>();
+        List<UploadError> errors = new ArrayList<>();
+
+        if (files == null || files.isEmpty()) {
+            return new QuickUploadResult(created, updated, errors);
+        }
+
+        for (MultipartFile file : files) {
+            if (!ALLOWED_CONTENT_TYPES.contains(file.getContentType())) {
+                errors.add(new UploadError(file.getOriginalFilename(), "UNSUPPORTED_FILE_TYPE"));
+                continue;
+            }
+            try {
+                DocumentService.StoreResult result = documentService.storeDocument(file);
+                if (result.isNew()) {
+                    created.add(result.document());
+                } else {
+                    updated.add(result.document());
+                }
+            } catch (Exception e) {
+                errors.add(new UploadError(file.getOriginalFilename(), "FILE_UPLOAD_FAILED"));
+                log.warn("Quick upload failed for file {}: {}", file.getOriginalFilename(), e.getMessage());
+            }
+        }
+
+        return new QuickUploadResult(created, updated, errors);
+    }
+
+    @GetMapping("/incomplete-count")
+    public Map<String, Long> getIncompleteCount() {
+        return Map.of("count", documentService.getIncompleteCount());
+    }
+
+    @GetMapping("/incomplete")
+    public List<Document> getIncomplete() {
+        return documentService.findIncompleteDocuments();
+    }
+
+    @GetMapping("/incomplete/next")
+    public ResponseEntity<Document> getNextIncomplete(@RequestParam UUID excludeId) {
+        return documentService.findNextIncompleteDocument(excludeId)
+                .map(ResponseEntity::ok)
+                .orElse(ResponseEntity.noContent().build());
+    }
+
     @GetMapping("/search")
     public ResponseEntity<List<Document>> search(
             @RequestParam(required = false) String q,

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

@@ -8,6 +8,7 @@ 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.server.ResponseStatusException;
 
 import lombok.extern.slf4j.Slf4j;
 
@@ -30,6 +31,12 @@ public class GlobalExceptionHandler {
         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,97 @@
+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.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,
+            Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        PageRequest pageable = PageRequest.of(page, size, Sort.by("createdAt").descending());
+        return notificationService.getNotifications(user.getId(), 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/DocumentUpdateDTO.java

@@ -17,4 +17,5 @@ public class DocumentUpdateDTO {
     private UUID senderId;
     private List<UUID> receiverIds;
     private String tags;
+    private Boolean metadataComplete;
 }

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

@@ -17,6 +17,8 @@ public enum ErrorCode {
     FILE_NOT_FOUND,
     /** An error occurred while uploading a file to object storage. 500 */
     FILE_UPLOAD_FAILED,
+    /** The uploaded file's content type is not supported (PDF/JPEG/PNG/TIFF only). 400 */
+    UNSUPPORTED_FILE_TYPE,
 
     // --- Users ---
     /** A user with the given ID or username does not exist. 404 */
@@ -48,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/Document.java

@@ -86,6 +86,11 @@ public class Document {
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private LocalDateTime updatedAt;
 
+    @Column(name = "metadata_complete", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    @Builder.Default
+    private boolean metadataComplete = false;
+
     @ManyToMany(fetch = FetchType.EAGER)
     @JoinTable(name = "document_receivers", joinColumns = @JoinColumn(name = "document_id"), inverseJoinColumns = @JoinColumn(name = "person_id"))
     @Builder.Default

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

@@ -21,6 +21,9 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
     // Wichtig für den Abgleich beim Excel-Import & Datei-Upload
     Optional<Document> findByOriginalFilename(String originalFilename);
 
+    // Wie oben, gibt aber nur das erste Ergebnis zurück — sicher wenn doppelte Dateinamen existieren
+    Optional<Document> findFirstByOriginalFilename(String originalFilename);
+
     // Findet alle Dokumente mit einem bestimmten Status
     // z.B. um alle offenen "PLACEHOLDER" zu finden
     List<Document> findByStatus(DocumentStatus status);
@@ -39,6 +42,12 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
 
     List<Document> findByFileHashIsNullAndFilePathIsNotNull();
 
+    long countByMetadataCompleteFalse();
+
+    List<Document> findByMetadataCompleteFalse(Sort sort);
+
+    Optional<Document> findFirstByMetadataCompleteFalseAndIdNot(UUID id, Sort sort);
+
     @Query("SELECT DISTINCT d FROM Document d " +
             "JOIN d.receivers r " +
             "WHERE " +

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

@@ -0,0 +1,22 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.Notification;
+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);
+
+    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/repository/PersonRepository.java

@@ -28,6 +28,9 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
     // Lookup by full alias string, used during ODS mass import
     Optional<Person> findByAliasIgnoreCase(String alias);
 
+    // Exact first+last name match, used for filename-based sender lookup
+    Optional<Person> findByFirstNameIgnoreCaseAndLastNameIgnoreCase(String firstName, String lastName);
+
     // --- Correspondent queries ---
 
     @Query(value = """

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

@@ -42,27 +42,38 @@ public class DocumentService {
     private final DocumentVersionService documentVersionService;
     private final AnnotationService annotationService;
 
+    public record StoreResult(Document document, boolean isNew) {}
+
     /**
      * Lädt eine Datei hoch.
      * - Prüft, ob ein Eintrag (aus Excel) schon existiert.
-     * - Wenn JA: Aktualisiert Status und verknüpft Datei.
-     * - Wenn NEIN: Erstellt neuen Eintrag (wartet auf Metadaten).
+     * - Wenn JA: Aktualisiert Status und verknüpft Datei — isNew = false.
+     * - Wenn NEIN: Erstellt neuen Eintrag — isNew = true.
      */
     @Transactional
-    public Document storeDocument(MultipartFile file) throws IOException {
+    public StoreResult storeDocument(MultipartFile file) throws IOException {
         String originalFilename = file.getOriginalFilename();
 
-        // 1. Check for existing record
-        Optional<Document> existingDoc = documentRepository.findByOriginalFilename(originalFilename);
+        // 1. Check for existing record (findFirst to survive duplicate filenames in the DB)
+        Optional<Document> existingDoc = documentRepository.findFirstByOriginalFilename(originalFilename);
+        boolean isNew = existingDoc.isEmpty();
         Document document;
 
         if (existingDoc.isPresent()) {
             document = existingDoc.get();
         } else {
+            // New uploads from the drop zone always start as incomplete
+            ParsedFilename parsed = parseFilenameData(originalFilename);
+            Person sender = (parsed != null)
+                    ? personService.findByName(parsed.firstName(), parsed.lastName()).orElse(null)
+                    : null;
             document = Document.builder()
                     .originalFilename(originalFilename)
-                    .title(originalFilename)
+                    .title(parsed != null ? parsed.title() : stripExtension(originalFilename))
+                    .documentDate(parsed != null ? parsed.date() : null)
+                    .sender(sender)
                     .status(DocumentStatus.UPLOADED)
+                    .metadataComplete(false)
                     .build();
         }
 
@@ -77,7 +88,7 @@ public class DocumentService {
             document.setStatus(DocumentStatus.UPLOADED);
         }
 
-        return documentRepository.save(document);
+        return new StoreResult(documentRepository.save(document), isNew);
     }
 
     @Transactional
@@ -86,15 +97,31 @@ public class DocumentService {
                 ? file.getOriginalFilename()
                 : (dto.getTitle() != null ? dto.getTitle() : "Unbenanntes Dokument");
 
+        // If the caller explicitly sets metadataComplete, use it.
+        // Otherwise apply heuristic: complete if at least one key field is present.
+        boolean metadataComplete;
+        if (dto.getMetadataComplete() != null) {
+            metadataComplete = dto.getMetadataComplete();
+        } else {
+            metadataComplete = dto.getDocumentDate() != null
+                    || dto.getSenderId() != null
+                    || (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())
                 .transcription(dto.getTranscription())
                 .summary(dto.getSummary())
                 .status(DocumentStatus.PLACEHOLDER)
+                .metadataComplete(metadataComplete)
                 .build();
 
         doc = documentRepository.save(doc);
@@ -173,6 +200,11 @@ public class DocumentService {
             doc.getReceivers().clear(); // Alle entfernen
         }
 
+        // 3b. metadataComplete — only update when explicitly set in the DTO
+        if (dto.getMetadataComplete() != null) {
+            doc.setMetadataComplete(dto.getMetadataComplete());
+        }
+
         // 4. Datei austauschen (nur wenn eine neue ausgewählt wurde)
         if (newFile != null && !newFile.isEmpty()) {
             FileService.UploadResult upload = fileService.uploadFile(newFile, newFile.getOriginalFilename());
@@ -234,8 +266,8 @@ public class DocumentService {
                 .and(hasReceiver(receiver))
                 .and(hasTags(tags));
 
-        // Immer sortiert nach Datum
-        return documentRepository.findAll(spec, Sort.by(Sort.Direction.ASC, "documentDate"));
+        // Neueste zuerst (nach Erstellungsdatum)
+        return documentRepository.findAll(spec, Sort.by(Sort.Direction.DESC, "createdAt"));
     }
 
     // 2. SPEZIALITÄT: Der Schriftwechsel
@@ -277,6 +309,27 @@ public class DocumentService {
         return documentRepository.findConversation(senderId, receiverId, dateFrom, dateTo, sort);
     }
 
+    public long getIncompleteCount() {
+        return documentRepository.countByMetadataCompleteFalse();
+    }
+
+    public List<Document> findIncompleteDocuments() {
+        return documentRepository.findByMetadataCompleteFalse(Sort.by(Sort.Direction.DESC, "createdAt"));
+    }
+
+    public Optional<Document> findNextIncompleteDocument(UUID currentId) {
+        return documentRepository.findFirstByMetadataCompleteFalseAndIdNot(
+                currentId, Sort.by(Sort.Direction.DESC, "createdAt"));
+    }
+
+    @Transactional
+    public void deleteDocument(UUID id) {
+        if (!documentRepository.existsById(id)) {
+            throw DomainException.notFound(ErrorCode.DOCUMENT_NOT_FOUND, "Document not found: " + id);
+        }
+        documentRepository.deleteById(id);
+    }
+
     @Transactional
     public void deleteTagCascading(UUID tagId) {
         documentRepository.findByTags_Id(tagId).forEach(doc -> {
@@ -307,6 +360,87 @@ public class DocumentService {
 
     // ─── private helpers ──────────────────────────────────────────────────────
 
+    private static String stripExtension(String filename) {
+        if (filename == null) return null;
+        int dot = filename.lastIndexOf('.');
+        return dot > 0 ? filename.substring(0, dot) : filename;
+    }
+
+    private record ParsedFilename(LocalDate date, String firstName, String lastName) {
+        String title() {
+            String dateDisplay = String.format("%02d.%02d.%d",
+                    date.getDayOfMonth(), date.getMonthValue(), date.getYear());
+            return firstName + " " + lastName + " (" + dateDisplay + ")";
+        }
+    }
+
+    /**
+     * Parses a structured filename into its date and name components.
+     *
+     * Algorithm: split stem on "_", identify the date token (first or last segment),
+     * treat the outermost remaining segment as firstName, rest as lastName parts.
+     * Compound last names (e.g. "de_Gruyter") are supported naturally.
+     * Returns null for unrecognised filenames.
+     *
+     * Examples:
+     *   18881025_de_Gruyter_Walter.pdf  → date=1888-10-25, firstName=Walter, lastName=de Gruyter
+     *   1965-03-12_Mueller_Hans.pdf     → date=1965-03-12, firstName=Hans,   lastName=Mueller
+     *   Mueller_Hans_19650312.pdf       → date=1965-03-12, firstName=Hans,   lastName=Mueller
+     */
+    private static ParsedFilename parseFilenameData(String filename) {
+        if (filename == null) return null;
+        int dot = filename.lastIndexOf('.');
+        if (dot < 0) return null;
+        String stem = filename.substring(0, dot);
+
+        String[] parts = stem.split("_", -1);
+        if (parts.length < 3) return null;
+
+        String dateIso;
+        String[] nameParts;
+
+        String dateFromFirst = tryParseDate(parts[0]);
+        if (dateFromFirst != null) {
+            dateIso = dateFromFirst;
+            nameParts = Arrays.copyOfRange(parts, 1, parts.length);
+        } else {
+            String dateFromLast = tryParseDate(parts[parts.length - 1]);
+            if (dateFromLast == null) return null;
+            dateIso = dateFromLast;
+            nameParts = Arrays.copyOfRange(parts, 0, parts.length - 1);
+        }
+
+        if (nameParts.length < 2) return null;
+        for (String p : nameParts) {
+            if (!p.matches("\\p{L}+")) return null;
+        }
+
+        String firstName = nameParts[nameParts.length - 1];
+        String lastName = String.join(" ", Arrays.copyOfRange(nameParts, 0, nameParts.length - 1));
+        return new ParsedFilename(LocalDate.parse(dateIso), firstName, lastName);
+    }
+
+    // Used by tests and as a public utility; delegates to parseFilenameData.
+    static String titleFromFilename(String filename) {
+        if (filename == null) return null;
+        ParsedFilename parsed = parseFilenameData(filename);
+        return parsed != null ? parsed.title() : stripExtension(filename);
+    }
+
+    private static String tryParseDate(String s) {
+        if (s.matches("\\d{4}-\\d{2}-\\d{2}")) {
+            int m = Integer.parseInt(s.substring(5, 7));
+            int d = Integer.parseInt(s.substring(8, 10));
+            if (m >= 1 && m <= 12 && d >= 1 && d <= 31) return s;
+        } else if (s.matches("\\d{8}")) {
+            int m = Integer.parseInt(s.substring(4, 6));
+            int d = Integer.parseInt(s.substring(6, 8));
+            if (m >= 1 && m <= 12 && d >= 1 && d <= 31)
+                return s.substring(0, 4) + "-" + s.substring(4, 6) + "-" + s.substring(6, 8);
+        }
+        return null;
+    }
+
     private static String sha256Hex(byte[] bytes) {
         try {
             MessageDigest digest = MessageDigest.getInstance("SHA-256");

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

@@ -312,6 +312,9 @@ public class MassImportService {
                 .originalFilename(originalFilename)
                 .build());
 
+        // Heuristic: mark as complete if at least one key field is present in the spreadsheet row
+        boolean metadataComplete = date != null || !senderRaw.isBlank() || !receiversRaw.isBlank();
+
         doc.setTitle(buildTitle(index, date, location));
         doc.setFilePath(s3Key);
         doc.setContentType(contentType);
@@ -325,6 +328,7 @@ public class MassImportService {
         doc.setSender(sender);
         doc.getReceivers().addAll(receivers);
         if (tag != null) doc.getTags().add(tag);
+        doc.setMetadataComplete(metadataComplete);
 
         documentRepository.save(doc);
         log.info("Importiert{}: {}", file.isEmpty() ? " (nur Metadaten)" : "", originalFilename);

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

@@ -0,0 +1,187 @@
+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, Pageable pageable) {
+        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/PersonService.java

@@ -1,6 +1,7 @@
 package org.raddatz.familienarchiv.service;
 
 import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 
 import org.raddatz.familienarchiv.dto.PersonUpdateDTO;
@@ -42,6 +43,10 @@ public class PersonService {
         return personRepository.findAllById(ids);
     }
 
+    public Optional<Person> findByName(String firstName, String lastName) {
+        return personRepository.findByFirstNameIgnoreCaseAndLastNameIgnoreCase(firstName, lastName);
+    }
+
     @Transactional
     public Person findOrCreateByAlias(String rawName) {
         String alias = rawName.trim();

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/V14__add_cascade_delete_to_document_join_tables.sql

@@ -0,0 +1,12 @@
+-- Add ON DELETE CASCADE to document_tags and document_receivers so that
+-- deleting a document automatically removes its tag and receiver associations.
+
+ALTER TABLE public.document_tags
+    DROP CONSTRAINT fkc99c5qjulwx9gru07yrhicgd2,
+    ADD CONSTRAINT fkc99c5qjulwx9gru07yrhicgd2
+        FOREIGN KEY (document_id) REFERENCES public.documents(id) ON DELETE CASCADE;
+
+ALTER TABLE public.document_receivers
+    DROP CONSTRAINT fks7t60twjgfmpeqcuc3g0fvjpm,
+    ADD CONSTRAINT fks7t60twjgfmpeqcuc3g0fvjpm
+        FOREIGN KEY (document_id) REFERENCES public.documents(id) ON DELETE CASCADE;

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

@@ -0,0 +1,6 @@
+-- Add metadata_complete flag to documents.
+-- Existing rows default to true (already reviewed before this feature existed).
+-- New documents created via Java will receive false from the entity default.
+
+ALTER TABLE documents
+    ADD COLUMN metadata_complete BOOLEAN NOT NULL DEFAULT TRUE;

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

@@ -21,6 +21,7 @@ import org.springframework.test.web.servlet.MockMvc;
 import java.time.LocalDateTime;
 import java.util.Collections;
 import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 
 import static org.mockito.ArgumentMatchers.any;
@@ -121,6 +122,243 @@ class DocumentControllerTest {
                 .andExpect(status().isOk());
     }
 
+    // ─── DELETE /api/documents/{id} ──────────────────────────────────────────
+
+    @Test
+    void deleteDocument_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders
+                        .delete("/api/documents/" + UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void deleteDocument_returns403_whenMissingWritePermission() throws Exception {
+        mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders
+                        .delete("/api/documents/" + UUID.randomUUID()))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void deleteDocument_returns204_whenHasWritePermission() throws Exception {
+        UUID id = UUID.randomUUID();
+        mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders
+                        .delete("/api/documents/" + id))
+                .andExpect(status().isNoContent());
+    }
+
+    // ─── POST /api/documents/quick-upload ────────────────────────────────────
+
+    @Test
+    void quickUpload_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(multipart("/api/documents/quick-upload"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void quickUpload_returns403_whenMissingWritePermission() throws Exception {
+        mockMvc.perform(multipart("/api/documents/quick-upload"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_returns200_withValidPdfFile() throws Exception {
+        Document doc = Document.builder()
+                .id(UUID.randomUUID()).title("scan001").originalFilename("scan001.pdf").build();
+        when(documentService.storeDocument(any()))
+                .thenReturn(new DocumentService.StoreResult(doc, true));
+
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("files", "scan001.pdf", "application/pdf", new byte[]{1});
+
+        mockMvc.perform(multipart("/api/documents/quick-upload").file(file))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created[0].title").value("scan001"))
+                .andExpect(jsonPath("$.updated").isEmpty())
+                .andExpect(jsonPath("$.errors").isEmpty());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_placesDocumentInUpdated_whenFilenameAlreadyExists() throws Exception {
+        Document existing = Document.builder()
+                .id(UUID.randomUUID()).title("Alter Brief").originalFilename("scan001.pdf").build();
+        when(documentService.storeDocument(any()))
+                .thenReturn(new DocumentService.StoreResult(existing, false));
+
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("files", "scan001.pdf", "application/pdf", new byte[]{1});
+
+        mockMvc.perform(multipart("/api/documents/quick-upload").file(file))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created").isEmpty())
+                .andExpect(jsonPath("$.updated[0].title").value("Alter Brief"))
+                .andExpect(jsonPath("$.errors").isEmpty());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_skipsUnsupportedFileType_andReturnsError() throws Exception {
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("files", "report.docx",
+                        "application/vnd.openxmlformats-officedocument.wordprocessingml.document", new byte[]{1});
+
+        mockMvc.perform(multipart("/api/documents/quick-upload").file(file))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created").isEmpty())
+                .andExpect(jsonPath("$.errors[0].filename").value("report.docx"))
+                .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
+    void getIncompleteCount_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/incomplete-count"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getIncompleteCount_returns200_withCount() throws Exception {
+        when(documentService.getIncompleteCount()).thenReturn(3L);
+
+        mockMvc.perform(get("/api/documents/incomplete-count"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.count").value(3));
+    }
+
+    // ─── GET /api/documents/incomplete ───────────────────────────────────────
+
+    @Test
+    void getIncomplete_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/incomplete"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @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));
+
+        mockMvc.perform(get("/api/documents/incomplete"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].title").value("Unvollständig"));
+    }
+
+    // ─── GET /api/documents/incomplete/next ──────────────────────────────────
+
+    @Test
+    void getNextIncomplete_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/incomplete/next")
+                        .param("excludeId", UUID.randomUUID().toString()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getNextIncomplete_returns200_whenNextExists() throws Exception {
+        UUID excludeId = UUID.randomUUID();
+        Document next = Document.builder()
+                .id(UUID.randomUUID()).title("Nächster").originalFilename("next.pdf").build();
+        when(documentService.findNextIncompleteDocument(excludeId)).thenReturn(Optional.of(next));
+
+        mockMvc.perform(get("/api/documents/incomplete/next")
+                        .param("excludeId", excludeId.toString()))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.title").value("Nächster"));
+    }
+
+    @Test
+    @WithMockUser
+    void getNextIncomplete_returns204_whenNoneRemain() throws Exception {
+        UUID excludeId = UUID.randomUUID();
+        when(documentService.findNextIncompleteDocument(excludeId)).thenReturn(Optional.empty());
+
+        mockMvc.perform(get("/api/documents/incomplete/next")
+                        .param("excludeId", excludeId.toString()))
+                .andExpect(status().isNoContent());
+    }
+
     // ─── GET /api/documents/{id}/versions ────────────────────────────────────
 
     @Test

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

@@ -0,0 +1,306 @@
+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()))
+                .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()))
+                .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()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk());
+
+        verify(notificationService).getNotifications(eq(USER_ID), any());
+    }
+
+    // ─── 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()))
+                .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,150 @@
+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 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);
+    }
+}

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

@@ -0,0 +1,252 @@
+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();
+    }
+}

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

@@ -2,6 +2,7 @@ package org.raddatz.familienarchiv.service;
 
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
@@ -9,9 +10,13 @@ import org.raddatz.familienarchiv.dto.DocumentUpdateDTO;
 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.Sort;
+import org.springframework.mock.web.MockMultipartFile;
 
+import java.time.LocalDate;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Optional;
@@ -35,6 +40,29 @@ class DocumentServiceTest {
     @Mock AnnotationService annotationService;
     @InjectMocks DocumentService documentService;
 
+    // ─── deleteDocument ───────────────────────────────────────────────────────
+
+    @Test
+    void deleteDocument_deletesById_whenExists() {
+        UUID id = UUID.randomUUID();
+        when(documentRepository.existsById(id)).thenReturn(true);
+
+        documentService.deleteDocument(id);
+
+        verify(documentRepository).deleteById(id);
+    }
+
+    @Test
+    void deleteDocument_throwsNotFound_whenMissing() {
+        UUID id = UUID.randomUUID();
+        when(documentRepository.existsById(id)).thenReturn(false);
+
+        assertThatThrownBy(() -> documentService.deleteDocument(id))
+                .isInstanceOf(DomainException.class)
+                .hasMessageContaining(id.toString());
+        verify(documentRepository, never()).deleteById(any());
+    }
+
     // ─── getDocumentById ──────────────────────────────────────────────────────
 
     @Test
@@ -212,6 +240,75 @@ class DocumentServiceTest {
         verify(documentVersionService).recordVersion(any(Document.class));
     }
 
+    // ─── storeDocument ───────────────────────────────────────────────────────
+
+    @Test
+    void storeDocument_setsTitle_withoutFileExtension_forNewDocument() throws Exception {
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("file", "scan001.pdf", "application/pdf", new byte[]{1});
+        FileService.UploadResult uploadResult = new FileService.UploadResult("documents/uuid_scan001.pdf", "abc123");
+        Document saved = Document.builder().id(UUID.randomUUID()).title("scan001").originalFilename("scan001.pdf").build();
+
+        when(documentRepository.findFirstByOriginalFilename("scan001.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(fileService.uploadFile(any(), any())).thenReturn(uploadResult);
+
+        org.mockito.ArgumentCaptor<Document> captor = org.mockito.ArgumentCaptor.forClass(Document.class);
+        documentService.storeDocument(file);
+
+        verify(documentRepository).save(captor.capture());
+        assertThat(captor.getValue().getTitle()).isEqualTo("scan001");
+    }
+
+    @Test
+    void storeDocument_preservesExistingTitle_whenPlaceholderAlreadyExists() throws Exception {
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("file", "scan001.pdf", "application/pdf", new byte[]{1});
+        FileService.UploadResult uploadResult = new FileService.UploadResult("documents/uuid_scan001.pdf", "abc123");
+        Document placeholder = Document.builder()
+                .id(UUID.randomUUID()).title("Brief an Oma").originalFilename("scan001.pdf")
+                .status(DocumentStatus.PLACEHOLDER).build();
+
+        when(documentRepository.findFirstByOriginalFilename("scan001.pdf")).thenReturn(Optional.of(placeholder));
+        when(documentRepository.save(any())).thenReturn(placeholder);
+        when(fileService.uploadFile(any(), any())).thenReturn(uploadResult);
+
+        documentService.storeDocument(file);
+
+        assertThat(placeholder.getTitle()).isEqualTo("Brief an Oma");
+    }
+
+    @Test
+    void storeDocument_marksResultAsNew_whenNoExistingDocument() throws Exception {
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("file", "new.pdf", "application/pdf", new byte[]{1});
+        Document saved = Document.builder().id(UUID.randomUUID()).originalFilename("new.pdf").build();
+
+        when(documentRepository.findFirstByOriginalFilename("new.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("documents/new.pdf", "hash"));
+
+        DocumentService.StoreResult result = documentService.storeDocument(file);
+
+        assertThat(result.isNew()).isTrue();
+    }
+
+    @Test
+    void storeDocument_marksResultAsNotNew_whenDocumentWithSameFilenameExists() throws Exception {
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("file", "existing.pdf", "application/pdf", new byte[]{1});
+        Document existing = Document.builder().id(UUID.randomUUID()).originalFilename("existing.pdf")
+                .status(DocumentStatus.UPLOADED).build();
+
+        when(documentRepository.findFirstByOriginalFilename("existing.pdf")).thenReturn(Optional.of(existing));
+        when(documentRepository.save(any())).thenReturn(existing);
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("documents/existing.pdf", "hash"));
+
+        DocumentService.StoreResult result = documentService.storeDocument(file);
+
+        assertThat(result.isNew()).isFalse();
+    }
+
     // ─── backfillFileHashes ───────────────────────────────────────────────────
 
     @Test
@@ -252,6 +349,265 @@ class DocumentServiceTest {
         verify(annotationService).backfillAnnotationFileHashForDocument(eq(docId), any());
     }
 
+    // ─── getIncompleteCount ───────────────────────────────────────────────────
+
+    @Test
+    void getIncompleteCount_delegatesToRepository() {
+        when(documentRepository.countByMetadataCompleteFalse()).thenReturn(5L);
+        assertThat(documentService.getIncompleteCount()).isEqualTo(5L);
+    }
+
+    // ─── 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));
+
+        assertThat(documentService.findIncompleteDocuments()).containsExactly(doc);
+        verify(documentRepository).findByMetadataCompleteFalse(Sort.by(Sort.Direction.DESC, "createdAt"));
+    }
+
+    // ─── findNextIncompleteDocument ───────────────────────────────────────────
+
+    @Test
+    void findNextIncompleteDocument_returnsNext_whenAnotherIncompleteExists() {
+        UUID currentId = UUID.randomUUID();
+        Document next = Document.builder().id(UUID.randomUUID()).title("Next").build();
+        when(documentRepository.findFirstByMetadataCompleteFalseAndIdNot(eq(currentId), any(Sort.class)))
+                .thenReturn(Optional.of(next));
+
+        assertThat(documentService.findNextIncompleteDocument(currentId)).contains(next);
+    }
+
+    @Test
+    void findNextIncompleteDocument_returnsEmpty_whenNoMoreIncomplete() {
+        UUID currentId = UUID.randomUUID();
+        when(documentRepository.findFirstByMetadataCompleteFalseAndIdNot(eq(currentId), any(Sort.class)))
+                .thenReturn(Optional.empty());
+
+        assertThat(documentService.findNextIncompleteDocument(currentId)).isEmpty();
+    }
+
+    // ─── storeDocument metadataComplete ──────────────────────────────────────
+
+    @Test
+    void storeDocument_setsMetadataCompleteFalse_forNewDocument() throws Exception {
+        MockMultipartFile file = new MockMultipartFile("file", "scan.pdf", "application/pdf", new byte[]{1});
+        Document saved = Document.builder().id(UUID.randomUUID()).originalFilename("scan.pdf").build();
+        when(documentRepository.findFirstByOriginalFilename("scan.pdf")).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenReturn(saved);
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.storeDocument(file);
+
+        verify(documentRepository).save(captor.capture());
+        assertThat(captor.getValue().isMetadataComplete()).isFalse();
+    }
+
+    @Test
+    void storeDocument_doesNotChangeMetadataComplete_forExistingDocument() throws Exception {
+        MockMultipartFile file = new MockMultipartFile("file", "scan.pdf", "application/pdf", new byte[]{1});
+        Document existing = Document.builder().id(UUID.randomUUID()).originalFilename("scan.pdf")
+                .status(DocumentStatus.PLACEHOLDER).metadataComplete(true).build();
+        when(documentRepository.findFirstByOriginalFilename("scan.pdf")).thenReturn(Optional.of(existing));
+        when(documentRepository.save(any())).thenReturn(existing);
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+
+        documentService.storeDocument(file);
+
+        assertThat(existing.isMetadataComplete()).isTrue();
+    }
+
+    @Test
+    void storeDocument_parsesDateFromFilename_forNewDocument() throws Exception {
+        MockMultipartFile file = new MockMultipartFile("file", "19650312_Mueller_Hans.pdf", "application/pdf", new byte[]{1});
+        when(documentRepository.findFirstByOriginalFilename(any())).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+        when(personService.findByName(any(), any())).thenReturn(Optional.empty());
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.storeDocument(file);
+
+        verify(documentRepository).save(captor.capture());
+        assertThat(captor.getValue().getDocumentDate()).isEqualTo(java.time.LocalDate.of(1965, 3, 12));
+        assertThat(captor.getValue().getTitle()).isEqualTo("Hans Mueller (12.03.1965)");
+    }
+
+    @Test
+    void storeDocument_setsSender_whenPersonExistsForParsedName() throws Exception {
+        MockMultipartFile file = new MockMultipartFile("file", "18881025_de_Gruyter_Walter.pdf", "application/pdf", new byte[]{1});
+        Person walter = Person.builder().id(UUID.randomUUID()).firstName("Walter").lastName("de Gruyter").build();
+        when(documentRepository.findFirstByOriginalFilename(any())).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+        when(personService.findByName("Walter", "de Gruyter")).thenReturn(Optional.of(walter));
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.storeDocument(file);
+
+        verify(documentRepository).save(captor.capture());
+        assertThat(captor.getValue().getSender()).isEqualTo(walter);
+    }
+
+    @Test
+    void storeDocument_leavesSenderNull_whenPersonNotFound() throws Exception {
+        MockMultipartFile file = new MockMultipartFile("file", "19650312_Mueller_Hans.pdf", "application/pdf", new byte[]{1});
+        when(documentRepository.findFirstByOriginalFilename(any())).thenReturn(Optional.empty());
+        when(documentRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        when(fileService.uploadFile(any(), any())).thenReturn(new FileService.UploadResult("path", "hash"));
+        when(personService.findByName(any(), any())).thenReturn(Optional.empty());
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        documentService.storeDocument(file);
+
+        verify(documentRepository).save(captor.capture());
+        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
+    void createDocument_setsMetadataCompleteFromDto_whenExplicitlyProvided() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Doc");
+        dto.setMetadataComplete(true);
+        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()).isTrue();
+    }
+
+    @Test
+    void createDocument_setsMetadataCompleteFalse_whenAllKeyFieldsMissingAndNoExplicitFlag() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Doc");
+        // no documentDate, no senderId, no receiverIds, no metadataComplete flag
+        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();
+    }
+
+    @Test
+    void createDocument_setsMetadataCompleteTrue_whenDatePresentAndNoExplicitFlag() throws Exception {
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setTitle("Doc");
+        dto.setDocumentDate(LocalDate.of(2020, 1, 1));
+        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()).isTrue();
+    }
+
+    // ─── updateDocument metadataComplete ─────────────────────────────────────
+
+    @Test
+    void updateDocument_setsMetadataComplete_whenDtoHasValue() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document existing = Document.builder().id(id).title("Doc").originalFilename("doc.pdf")
+                .status(DocumentStatus.PLACEHOLDER).metadataComplete(false).build();
+        when(documentRepository.findById(id)).thenReturn(Optional.of(existing));
+        when(documentRepository.save(any())).thenReturn(existing);
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        dto.setMetadataComplete(true);
+        documentService.updateDocument(id, dto, null);
+
+        assertThat(existing.isMetadataComplete()).isTrue();
+    }
+
+    @Test
+    void updateDocument_doesNotChangeMetadataComplete_whenDtoHasNull() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document existing = Document.builder().id(id).title("Doc").originalFilename("doc.pdf")
+                .status(DocumentStatus.PLACEHOLDER).metadataComplete(false).build();
+        when(documentRepository.findById(id)).thenReturn(Optional.of(existing));
+        when(documentRepository.save(any())).thenReturn(existing);
+
+        DocumentUpdateDTO dto = new DocumentUpdateDTO();
+        // metadataComplete not set → null
+        documentService.updateDocument(id, dto, null);
+
+        assertThat(existing.isMetadataComplete()).isFalse();
+    }
+
     @Test
     void backfillFileHashes_returnsCountOfUpdatedDocuments() throws Exception {
         UUID id1 = UUID.randomUUID();
@@ -266,4 +622,551 @@ class DocumentServiceTest {
 
         assertThat(count).isEqualTo(2);
     }
+
+    // ─── titleFromFilename ────────────────────────────────────────────────────
+
+    @Test
+    void titleFromFilename_dateIso_name() {
+        assertThat(DocumentService.titleFromFilename("1965-03-12_Mueller_Hans.pdf"))
+                .isEqualTo("Hans Mueller (12.03.1965)");
+    }
+
+    @Test
+    void titleFromFilename_dateCompact_name() {
+        assertThat(DocumentService.titleFromFilename("19650312_Mueller_Hans.pdf"))
+                .isEqualTo("Hans Mueller (12.03.1965)");
+    }
+
+    @Test
+    void titleFromFilename_name_dateIso() {
+        assertThat(DocumentService.titleFromFilename("Mueller_Hans_1965-03-12.pdf"))
+                .isEqualTo("Hans Mueller (12.03.1965)");
+    }
+
+    @Test
+    void titleFromFilename_name_dateCompact() {
+        assertThat(DocumentService.titleFromFilename("Mueller_Hans_19650312.pdf"))
+                .isEqualTo("Hans Mueller (12.03.1965)");
+    }
+
+    @Test
+    void titleFromFilename_compound_lastName_dateFirst() {
+        assertThat(DocumentService.titleFromFilename("18881025_de_Gruyter_Walter.pdf"))
+                .isEqualTo("Walter de Gruyter (25.10.1888)");
+    }
+
+    @Test
+    void titleFromFilename_compound_lastName_dateLast() {
+        assertThat(DocumentService.titleFromFilename("de_Gruyter_Walter_18881025.pdf"))
+                .isEqualTo("Walter de Gruyter (25.10.1888)");
+    }
+
+    @Test
+    void titleFromFilename_fallsBackToStripExtension() {
+        assertThat(DocumentService.titleFromFilename("scan_001.pdf")).isEqualTo("scan_001");
+    }
+
+    @Test
+    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();
+    }
 }

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,371 @@
+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 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);
+    }
+
+    // ─── 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/bottom-panel.spec.ts

@@ -0,0 +1,180 @@
+import { test, expect } from '@playwright/test';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PDF_FIXTURE = path.resolve(__dirname, 'fixtures/minimal.pdf');
+
+/**
+ * Bottom panel E2E tests — issue #62.
+ * Verifies the new document detail layout: full-viewport viewer + floating bottom panel.
+ */
+
+let pdfDocHref: string;
+let noFileDocHref: string;
+
+test.describe('Document bottom panel', () => {
+	test.beforeAll(async ({ request }) => {
+		const baseURL = process.env.E2E_BASE_URL ?? 'http://localhost:3000';
+
+		// Create a document with a PDF and a date for metadata tests.
+		const createRes = await request.post('/api/documents', {
+			multipart: { title: 'E2E Bottom Panel Test', documentDate: '1945-05-08' }
+		});
+		if (!createRes.ok()) throw new Error(`Create document failed: ${createRes.status()}`);
+		const doc = await createRes.json();
+
+		const uploadRes = await request.put(`/api/documents/${doc.id}`, {
+			multipart: {
+				title: doc.title,
+				documentDate: '1945-05-08',
+				transcription: 'Dies ist eine vollständige Transkription des Dokuments für den E2E-Test.',
+				file: {
+					name: 'minimal.pdf',
+					mimeType: 'application/pdf',
+					buffer: fs.readFileSync(PDF_FIXTURE)
+				}
+			}
+		});
+		if (!uploadRes.ok()) throw new Error(`Upload PDF failed: ${uploadRes.status()}`);
+		pdfDocHref = `${baseURL}/documents/${doc.id}`;
+
+		// Create a document WITHOUT a file — panel should open to Metadaten by default.
+		const noFileRes = await request.post('/api/documents', {
+			multipart: { title: 'E2E Bottom Panel No-File Test' }
+		});
+		if (!noFileRes.ok()) throw new Error(`Create no-file document failed: ${noFileRes.status()}`);
+		noFileDocHref = `${baseURL}/documents/${noFileRes.json().then ? (await noFileRes.json()).id : ''}`;
+		const noFileDoc = await noFileRes.json();
+		noFileDocHref = `${baseURL}/documents/${noFileDoc.id}`;
+	});
+
+	test('bottom panel tab bar is visible and panel content is closed by default on a PDF document', async ({
+		page
+	}) => {
+		test.setTimeout(30_000);
+		// Clear localStorage to ensure no previous panel state.
+		await page.goto(pdfDocHref);
+		await page.evaluate(() => localStorage.clear());
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		// Tab bar must always be visible.
+		await expect(page.getByRole('button', { name: 'Metadaten' })).toBeVisible();
+		await expect(page.getByRole('button', { name: 'Transkription' })).toBeVisible();
+		await expect(page.getByRole('button', { name: 'Diskussion' })).toBeVisible();
+		await expect(page.getByRole('button', { name: 'Verlauf' })).toBeVisible();
+
+		// Panel content must NOT be visible when closed.
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).not.toBeVisible();
+
+		await page.screenshot({ path: 'test-results/e2e/bottom-panel-closed-default.png' });
+	});
+
+	test('clicking Metadaten tab opens the panel and shows metadata content', async ({ page }) => {
+		test.setTimeout(30_000);
+		await page.goto(pdfDocHref);
+		await page.evaluate(() => localStorage.clear());
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		await page.getByRole('button', { name: 'Metadaten' }).click();
+
+		// Panel content becomes visible.
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).toBeVisible();
+
+		// Metadata section heading should be present.
+		await expect(page.getByText('Details', { exact: false })).toBeVisible();
+
+		await page.screenshot({ path: 'test-results/e2e/bottom-panel-metadata.png' });
+	});
+
+	test('clicking Transkription tab shows transcription text', async ({ page }) => {
+		test.setTimeout(30_000);
+		await page.goto(pdfDocHref);
+		await page.evaluate(() => localStorage.clear());
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		await page.getByRole('button', { name: 'Transkription' }).click();
+
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).toBeVisible();
+		await expect(
+			page.getByText('Dies ist eine vollständige Transkription', { exact: false })
+		).toBeVisible();
+
+		await page.screenshot({ path: 'test-results/e2e/bottom-panel-transcription.png' });
+	});
+
+	test('clicking Diskussion tab shows the comment input', async ({ page }) => {
+		test.setTimeout(30_000);
+		await page.goto(pdfDocHref);
+		await page.evaluate(() => localStorage.clear());
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		await page.getByRole('button', { name: 'Diskussion' }).click();
+
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).toBeVisible();
+		await expect(page.getByPlaceholder('Kommentar schreiben…')).toBeVisible();
+
+		await page.screenshot({ path: 'test-results/e2e/bottom-panel-discussion.png' });
+	});
+
+	test('clicking × close button collapses the panel content', async ({ page }) => {
+		test.setTimeout(30_000);
+		await page.goto(pdfDocHref);
+		await page.evaluate(() => localStorage.clear());
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		// Open the panel first.
+		await page.getByRole('button', { name: 'Metadaten' }).click();
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).toBeVisible();
+
+		// Close it.
+		await page.locator('[data-testid="panel-close-btn"]').click();
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).not.toBeVisible();
+
+		// Tab bar still visible after closing.
+		await expect(page.getByRole('button', { name: 'Metadaten' })).toBeVisible();
+
+		await page.screenshot({ path: 'test-results/e2e/bottom-panel-closed-after-x.png' });
+	});
+
+	test('panel open state persists after page reload', async ({ page }) => {
+		test.setTimeout(30_000);
+		await page.goto(pdfDocHref);
+		await page.evaluate(() => localStorage.clear());
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		// Open the panel to Diskussion.
+		await page.getByRole('button', { name: 'Diskussion' }).click();
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).toBeVisible();
+
+		// Reload — panel should re-open on the same tab.
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).toBeVisible();
+		await expect(page.getByPlaceholder('Kommentar schreiben…')).toBeVisible();
+
+		await page.screenshot({ path: 'test-results/e2e/bottom-panel-persisted.png' });
+	});
+
+	test('document without a file opens panel to Metadaten by default', async ({ page }) => {
+		test.setTimeout(30_000);
+		await page.goto(noFileDocHref);
+		await page.evaluate(() => localStorage.clear());
+		await page.reload();
+		await page.waitForSelector('[data-hydrated]');
+
+		// Panel should be open to Metadaten by default when there is no file.
+		await expect(page.locator('[data-testid="bottom-panel-content"]')).toBeVisible();
+		await expect(page.getByText('Details', { exact: false })).toBeVisible();
+
+		await page.screenshot({ path: 'test-results/e2e/bottom-panel-no-file-default.png' });
+	});
+});

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/theme.spec.ts

@@ -0,0 +1,73 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Theme toggle', () => {
+	test.beforeEach(async ({ page }) => {
+		// Clear any saved theme preference before each test
+		await page.goto('/');
+		await page.evaluate(() => localStorage.removeItem('theme'));
+	});
+
+	test('toggle button is visible in the header', async ({ page }) => {
+		await page.goto('/');
+		await expect(
+			page.getByRole('banner').getByRole('button', { name: /dark mode|light mode/i })
+		).toBeVisible();
+	});
+
+	test('clicking the toggle switches to dark mode', async ({ page }) => {
+		await page.goto('/');
+		await page.waitForSelector('[data-hydrated]');
+
+		const html = page.locator('html');
+		await expect(html).not.toHaveAttribute('data-theme', 'dark');
+
+		await page
+			.getByRole('banner')
+			.getByRole('button', { name: /dark mode/i })
+			.click();
+
+		await expect(html).toHaveAttribute('data-theme', 'dark');
+	});
+
+	test('clicking the toggle again switches back to light mode', async ({ page }) => {
+		await page.goto('/');
+		await page.waitForSelector('[data-hydrated]');
+
+		await page
+			.getByRole('banner')
+			.getByRole('button', { name: /dark mode/i })
+			.click();
+		await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');
+
+		await page
+			.getByRole('banner')
+			.getByRole('button', { name: /light mode/i })
+			.click();
+		await expect(page.locator('html')).toHaveAttribute('data-theme', 'light');
+	});
+
+	test('theme persists after page reload', async ({ page }) => {
+		await page.goto('/');
+		await page.waitForSelector('[data-hydrated]');
+
+		await page
+			.getByRole('banner')
+			.getByRole('button', { name: /dark mode/i })
+			.click();
+		await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');
+
+		await page.reload();
+		await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');
+	});
+
+	test('saved theme is applied before first paint (no flash)', async ({ page }) => {
+		// Set dark theme in localStorage before navigating
+		await page.goto('/');
+		await page.evaluate(() => localStorage.setItem('theme', 'dark'));
+
+		// Intercept the initial HTML to verify data-theme is set immediately
+		await page.goto('/');
+		const theme = await page.evaluate(() => document.documentElement.getAttribute('data-theme'));
+		expect(theme).toBe('dark');
+	});
+});

frontend/messages/de.json

@@ -7,6 +7,7 @@
 	"error_document_no_file": "Diesem Dokument ist noch keine Datei zugeordnet.",
 	"error_file_not_found": "Die Datei konnte im Speicher nicht gefunden werden.",
 	"error_file_upload_failed": "Die Datei konnte nicht hochgeladen werden.",
+	"error_unsupported_file_type": "Dieses Dateiformat wird nicht unterstützt.",
 	"error_user_not_found": "Der Benutzer wurde nicht gefunden.",
 	"error_import_already_running": "Ein Import läuft bereits. Bitte warten Sie, bis dieser abgeschlossen ist.",
 	"error_unauthorized": "Sie sind nicht angemeldet.",
@@ -23,6 +24,7 @@
 	"btn_edit": "Bearbeiten",
 	"btn_create": "Erstellen",
 	"btn_delete": "Löschen",
+	"doc_delete_confirm": "Dokument wirklich löschen? Diese Aktion kann nicht rückgängig gemacht werden.",
 	"btn_back_to_overview": "Zurück zur Übersicht",
 	"btn_back": "Zurück",
 	"btn_back_to_document": "Zurück zum Dokument",
@@ -37,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…",
@@ -73,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",
@@ -255,5 +258,59 @@
 	"comment_btn_reply": "Antworten",
 	"comment_edited_label": "· bearbeitet",
 	"comment_panel_title": "Kommentare",
-	"comment_panel_close": "Schließen"
+	"comment_panel_close": "Schließen",
+	"doc_panel_tab_metadata": "Metadaten",
+	"doc_panel_tab_transcription": "Transkription",
+	"doc_panel_tab_discussion": "Diskussion",
+	"doc_panel_tab_history": "Verlauf",
+	"doc_panel_annotate": "Annotieren",
+	"doc_panel_annotate_stop": "Fertig",
+	"doc_panel_annotation_thread_title": "Annotation",
+	"doc_panel_discussion_annotation_tab": "Annotation · Seite {page}",
+	"pdf_annotations_show": "Annotierungen anzeigen",
+	"pdf_annotations_hide": "Annotierungen verbergen",
+	"upload_drop_hint": "Einzeln oder mehrere Dateien auf einmal hochladen",
+	"upload_accepted_types": "PDF, JPEG, PNG, TIFF",
+	"upload_filename_hint": "Tipp: 2024-03-15_Mueller_Hans.pdf → Datum und Absender werden vorausgefüllt",
+	"upload_success": "{count} Dokument(e) erstellt",
+	"upload_duplicate": "{filename} existiert bereits —",
+	"upload_duplicate_link": "Zum Dokument",
+	"upload_invalid_type": "{filename}: Dateiformat nicht unterstützt",
+	"upload_error": "Fehler beim Hochladen von {filename}",
+	"enrich_list_back": "Zurück zur Übersicht",
+	"enrich_list_count": "Dokumente",
+	"btn_save_and_mark_reviewed": "Speichern & abschließen",
+	"btn_mark_for_review": "Zur Überprüfung markieren",
+	"enrich_needs_metadata_title": "Dokumente ohne Metadaten",
+	"enrich_needs_metadata_count": "{count} Dokument(e) warten auf Metadaten",
+	"enrich_needs_metadata_cta": "Jetzt vervollständigen",
+	"enrich_list_heading": "Dokumente ohne Metadaten",
+	"enrich_list_empty_heading": "Alle Dokumente vollständig",
+	"enrich_list_empty_body": "Es gibt keine Dokumente, die noch Metadaten benötigen.",
+	"enrich_list_start": "Überprüfung starten",
+	"enrich_progress": "{count} verbleibend",
+	"enrich_skip": "Überspringen",
+	"enrich_done_heading": "Alles erledigt!",
+	"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 →",
+	"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"
 }

frontend/messages/en.json

@@ -7,6 +7,7 @@
 	"error_document_no_file": "No file is associated with this document.",
 	"error_file_not_found": "The file could not be found in storage.",
 	"error_file_upload_failed": "The file could not be uploaded.",
+	"error_unsupported_file_type": "This file format is not supported.",
 	"error_user_not_found": "User not found.",
 	"error_import_already_running": "An import is already running. Please wait for it to finish.",
 	"error_unauthorized": "You are not logged in.",
@@ -23,6 +24,7 @@
 	"btn_edit": "Edit",
 	"btn_create": "Create",
 	"btn_delete": "Delete",
+	"doc_delete_confirm": "Really delete this document? This action cannot be undone.",
 	"btn_back_to_overview": "Back to overview",
 	"btn_back": "Back",
 	"btn_back_to_document": "Back to document",
@@ -37,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…",
@@ -73,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",
@@ -255,5 +258,59 @@
 	"comment_btn_reply": "Reply",
 	"comment_edited_label": "· edited",
 	"comment_panel_title": "Comments",
-	"comment_panel_close": "Close"
+	"comment_panel_close": "Close",
+	"doc_panel_tab_metadata": "Metadata",
+	"doc_panel_tab_transcription": "Transcription",
+	"doc_panel_tab_discussion": "Discussion",
+	"doc_panel_tab_history": "History",
+	"doc_panel_annotate": "Annotate",
+	"doc_panel_annotate_stop": "Done",
+	"doc_panel_annotation_thread_title": "Annotation",
+	"doc_panel_discussion_annotation_tab": "Annotation · Page {page}",
+	"pdf_annotations_show": "Show annotations",
+	"pdf_annotations_hide": "Hide annotations",
+	"upload_drop_hint": "Drop one or multiple files at once",
+	"upload_accepted_types": "PDF, JPEG, PNG, TIFF",
+	"upload_filename_hint": "Tip: 2024-03-15_Mueller_Hans.pdf → date and sender pre-filled",
+	"upload_success": "{count} document(s) created",
+	"upload_duplicate": "{filename} already exists —",
+	"upload_duplicate_link": "View document",
+	"upload_invalid_type": "{filename}: unsupported file format",
+	"upload_error": "Error uploading {filename}",
+	"enrich_list_back": "Back to overview",
+	"enrich_list_count": "documents",
+	"btn_save_and_mark_reviewed": "Save & mark as reviewed",
+	"btn_mark_for_review": "Mark for review",
+	"enrich_needs_metadata_title": "Documents without metadata",
+	"enrich_needs_metadata_count": "{count} document(s) waiting for metadata",
+	"enrich_needs_metadata_cta": "Complete now",
+	"enrich_list_heading": "Documents without metadata",
+	"enrich_list_empty_heading": "All documents complete",
+	"enrich_list_empty_body": "There are no documents that still need metadata.",
+	"enrich_list_start": "Start reviewing",
+	"enrich_progress": "{count} remaining",
+	"enrich_skip": "Skip",
+	"enrich_done_heading": "All done!",
+	"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 →",
+	"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"
 }

frontend/messages/es.json

@@ -7,6 +7,7 @@
 	"error_document_no_file": "No hay ningún archivo asociado a este documento.",
 	"error_file_not_found": "El archivo no pudo encontrarse en el almacenamiento.",
 	"error_file_upload_failed": "No se pudo subir el archivo.",
+	"error_unsupported_file_type": "Este formato de archivo no está admitido.",
 	"error_user_not_found": "Usuario no encontrado.",
 	"error_import_already_running": "Ya hay una importación en curso. Por favor, espere a que finalice.",
 	"error_unauthorized": "No ha iniciado sesión.",
@@ -23,6 +24,7 @@
 	"btn_edit": "Editar",
 	"btn_create": "Crear",
 	"btn_delete": "Eliminar",
+	"doc_delete_confirm": "¿Realmente eliminar este documento? Esta acción no se puede deshacer.",
 	"btn_back_to_overview": "Volver al resumen",
 	"btn_back": "Volver",
 	"btn_back_to_document": "Volver al documento",
@@ -37,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…",
@@ -73,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",
@@ -255,5 +258,59 @@
 	"comment_btn_reply": "Responder",
 	"comment_edited_label": "· editado",
 	"comment_panel_title": "Comentarios",
-	"comment_panel_close": "Cerrar"
+	"comment_panel_close": "Cerrar",
+	"doc_panel_tab_metadata": "Metadatos",
+	"doc_panel_tab_transcription": "Transcripción",
+	"doc_panel_tab_discussion": "Discusión",
+	"doc_panel_tab_history": "Historial",
+	"doc_panel_annotate": "Anotar",
+	"doc_panel_annotate_stop": "Listo",
+	"doc_panel_annotation_thread_title": "Anotación",
+	"doc_panel_discussion_annotation_tab": "Anotación · Página {page}",
+	"pdf_annotations_show": "Mostrar anotaciones",
+	"pdf_annotations_hide": "Ocultar anotaciones",
+	"upload_drop_hint": "Uno o varios archivos a la vez",
+	"upload_accepted_types": "PDF, JPEG, PNG, TIFF",
+	"upload_filename_hint": "Consejo: 2024-03-15_Mueller_Hans.pdf → fecha y remitente prellenados",
+	"upload_success": "{count} documento(s) creado(s)",
+	"upload_duplicate": "{filename} ya existe —",
+	"upload_duplicate_link": "Ver documento",
+	"upload_invalid_type": "{filename}: formato de archivo no admitido",
+	"upload_error": "Error al subir {filename}",
+	"enrich_list_back": "Volver a la vista general",
+	"enrich_list_count": "documentos",
+	"btn_save_and_mark_reviewed": "Guardar y marcar como revisado",
+	"btn_mark_for_review": "Marcar para revisión",
+	"enrich_needs_metadata_title": "Documentos sin metadatos",
+	"enrich_needs_metadata_count": "{count} documento(s) esperando metadatos",
+	"enrich_needs_metadata_cta": "Completar ahora",
+	"enrich_list_heading": "Documentos sin metadatos",
+	"enrich_list_empty_heading": "Todos los documentos completos",
+	"enrich_list_empty_body": "No hay documentos que necesiten metadatos.",
+	"enrich_list_start": "Comenzar revisión",
+	"enrich_progress": "{count} restante(s)",
+	"enrich_skip": "Omitir",
+	"enrich_done_heading": "¡Todo listo!",
+	"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 →",
+	"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"
 }

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/app.html

@@ -3,6 +3,12 @@
 	<head>
 		<meta charset="utf-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<script>
+			(function () {
+				var t = localStorage.getItem('theme');
+				if (t === 'dark' || t === 'light') document.documentElement.setAttribute('data-theme', t);
+			})();
+		</script>
 		%sveltekit.head%
 	</head>
 	<body data-sveltekit-preload-data="hover">

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/AnnotationCommentPanel.svelte

@@ -25,16 +25,16 @@ let {
 
 <!-- Desktop / tablet panel (≥ sm): absolute overlay on the right side -->
 <div
-	class="absolute top-0 right-0 z-50 hidden h-full w-80 flex-col border-l border-brand-sand bg-white shadow-2xl sm:flex"
+	class="absolute top-0 right-0 z-50 hidden h-full w-80 flex-col border-l border-line bg-surface shadow-2xl sm:flex"
 >
-	<div class="flex shrink-0 items-center justify-between border-b border-brand-sand px-4 py-3">
-		<h3 class="font-sans text-xs font-bold tracking-widest text-brand-navy uppercase">
+	<div class="flex shrink-0 items-center justify-between border-b border-line px-4 py-3">
+		<h3 class="font-sans text-xs font-bold tracking-widest text-ink uppercase">
 			{m.comment_panel_title()}
 		</h3>
 		<button
 			onclick={onClose}
 			aria-label={m.comment_panel_close()}
-			class="rounded p-1 text-gray-400 transition-colors hover:bg-brand-sand/50 hover:text-brand-navy"
+			class="rounded p-1 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" />
@@ -60,15 +60,15 @@ let {
 	<div class="flex-1 bg-black/40" onclick={onClose} role="presentation"></div>
 
 	<!-- Slide-up panel -->
-	<div class="flex max-h-[80vh] flex-col rounded-t-2xl bg-white shadow-2xl">
-		<div class="flex shrink-0 items-center justify-between border-b border-brand-sand px-4 py-3">
-			<h3 class="font-sans text-xs font-bold tracking-widest text-brand-navy uppercase">
+	<div class="flex max-h-[80vh] flex-col rounded-t-2xl bg-surface shadow-2xl">
+		<div class="flex shrink-0 items-center justify-between border-b border-line px-4 py-3">
+			<h3 class="font-sans text-xs font-bold tracking-widest text-ink uppercase">
 				{m.comment_panel_title()}
 			</h3>
 			<button
 				onclick={onClose}
 				aria-label={m.comment_panel_close()}
-				class="rounded p-1 text-gray-400 transition-colors hover:bg-brand-sand/50 hover:text-brand-navy"
+				class="rounded p-1 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" />

frontend/src/lib/components/AnnotationLayer.svelte

@@ -1,15 +1,5 @@
 <script lang="ts">
-type Annotation = {
-	id: string;
-	documentId: string;
-	pageNumber: number;
-	x: number;
-	y: number;
-	width: number;
-	height: number;
-	color: string;
-	createdAt: string;
-};
+import type { Annotation } from '$lib/types';
 
 type DrawRect = {
 	x: number;
@@ -103,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>
 
@@ -123,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

@@ -0,0 +1,68 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import CommentThread from './CommentThread.svelte';
+
+type Props = {
+	documentId: string;
+	activeAnnotationId: string | null;
+	activeAnnotationPage: number | null;
+	canComment: boolean;
+	currentUserId: string | null;
+	canAdmin: boolean;
+	targetCommentId?: string | null;
+	onClose: () => void;
+};
+
+let {
+	documentId,
+	activeAnnotationId,
+	activeAnnotationPage,
+	canComment,
+	currentUserId,
+	canAdmin,
+	targetCommentId = null,
+	onClose
+}: Props = $props();
+
+const visible = $derived(activeAnnotationId !== null);
+</script>
+
+<div
+	class="absolute inset-y-0 right-0 z-10 flex w-80 flex-col border-l border-line bg-surface shadow-[-4px_0_16px_rgba(0,0,0,0.08)] transition-transform duration-200 {visible
+		? 'translate-x-0'
+		: 'pointer-events-none translate-x-full'}"
+	data-testid="annotation-side-panel"
+>
+	<!-- Header -->
+	<div class="flex shrink-0 items-center justify-between border-b border-line px-4 py-3">
+		<span class="font-sans text-xs font-medium text-ink">
+			{m.doc_panel_discussion_annotation_tab({ page: String(activeAnnotationPage ?? '?') })}
+		</span>
+		<button
+			onclick={onClose}
+			aria-label={m.comment_panel_close()}
+			class="rounded p-1 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" />
+			</svg>
+		</button>
+	</div>
+
+	<!-- Comment thread -->
+	<div class="flex-1 overflow-y-auto p-4">
+		{#if activeAnnotationId}
+			{#key activeAnnotationId}
+				<CommentThread
+					documentId={documentId}
+					annotationId={activeAnnotationId}
+					canComment={canComment}
+					currentUserId={currentUserId}
+					canAdmin={canAdmin}
+					targetCommentId={targetCommentId}
+					loadOnMount={true}
+				/>
+			{/key}
+		{/if}
+	</div>
+</div>

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,25 +1,10 @@
 <script lang="ts">
-import { onMount, untrack } from 'svelte';
+import { onMount, tick, untrack } from 'svelte';
 import { m } from '$lib/paraglide/messages.js';
-
-type CommentReply = {
-	id: string;
-	authorId: string | null;
-	authorName: string;
-	content: string;
-	createdAt: string;
-	updatedAt: string;
-};
-
-type Comment = {
-	id: string;
-	authorId: string | null;
-	authorName: string;
-	content: string;
-	createdAt: string;
-	updatedAt: string;
-	replies: CommentReply[];
-};
+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;
@@ -29,6 +14,7 @@ type Props = {
 	canComment: boolean;
 	currentUserId: string | null;
 	canAdmin: boolean;
+	targetCommentId?: string | null;
 	onCountChange?: (count: number) => void;
 };
 
@@ -40,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
@@ -94,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 {
@@ -113,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();
 		}
@@ -133,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 {
@@ -165,6 +162,7 @@ async function deleteComment(commentId: string) {
 function startEdit(comment: Comment | CommentReply) {
 	editingId = comment.id;
 	editText = comment.content;
+	editMentionCandidates = [];
 }
 
 function cancelEdit() {
@@ -182,183 +180,177 @@ 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>
 
-<div class="space-y-4">
-	{#each comments as thread, ti (thread.id)}
-		<div class={ti > 0 ? 'border-t border-brand-sand pt-4' : ''}>
-			<!-- Root comment -->
-			<div>
-				{#if editingId === thread.id}
-					<div class="flex flex-col gap-2">
-						<textarea
-							class="w-full resize-none rounded border border-brand-sand px-3 py-2 font-serif text-sm text-brand-navy focus:ring-1 focus:ring-brand-mint focus:outline-none"
-							rows={3}
-							bind:value={editText}
-						></textarea>
-						<div class="flex items-center gap-3">
-							<button
-								class="rounded bg-brand-navy px-3 py-1.5 font-sans text-xs font-medium text-white hover:bg-brand-navy/80 disabled:opacity-40"
-								disabled={posting}
-								onclick={() => saveEdit(thread.id)}
-							>
-								{m.btn_save()}
-							</button>
-							<button
-								class="font-sans text-xs text-gray-400 transition-colors hover:text-brand-navy"
-								onclick={cancelEdit}
-							>
-								{m.btn_cancel()}
-							</button>
-						</div>
-					</div>
-				{:else}
-					<div class="flex items-start justify-between gap-2">
-						<div class="min-w-0 flex-1">
-							<div class="flex flex-wrap items-center gap-2">
-								<span class="font-sans text-xs font-semibold text-brand-navy"
-									>{thread.authorName}</span
-								>
-								<span class="font-sans text-xs text-gray-400">{timeAgo(thread.createdAt)}</span>
-								{#if wasEdited(thread)}
-									<span class="font-sans text-xs text-gray-400">
-										{m.comment_edited_label()}
-										{timeAgo(thread.updatedAt)}
-									</span>
-								{/if}
-							</div>
-							<p class="mt-1 font-serif text-sm leading-relaxed text-gray-700">{thread.content}</p>
-						</div>
-						{#if canModify(thread)}
-							<div class="flex shrink-0 items-center gap-2">
-								<button
-									class="font-sans text-xs text-gray-400 transition-colors hover:text-brand-navy"
-									onclick={() => startEdit(thread)}
-								>
-									{m.btn_edit()}
-								</button>
-								<button
-									class="font-sans text-xs text-gray-400 transition-colors hover:text-brand-navy"
-									onclick={() => deleteComment(thread.id)}
-								>
-									{m.btn_delete()}
-								</button>
-							</div>
-						{/if}
-					</div>
-					<!-- Reply button on root comment only if there are no replies -->
-					{#if thread.replies.length === 0 && canComment}
-						<div class="mt-1">
-							<button
-								class="font-sans text-xs font-medium text-brand-mint transition-colors hover:text-brand-navy"
-								onclick={() => startReply(thread.id)}
-							>
-								{m.comment_btn_reply()}
-							</button>
-						</div>
+<!--
+  Renders a single comment or reply entry.
+  showReplyButton: whether the "Reply" button appears (only on last item in a thread).
+-->
+{#snippet commentEntry(comment: Comment | CommentReply, threadId: string, showReplyButton: boolean)}
+	{#if editingId === comment.id}
+		<div class="flex flex-col gap-2">
+			<MentionEditor
+				bind:value={editText}
+				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-primary-fg hover:bg-primary/80 disabled:opacity-40"
+					disabled={posting}
+					onclick={() => saveEdit(comment.id)}
+				>
+					{m.btn_save()}
+				</button>
+				<button
+					class="font-sans text-xs text-ink-3 transition-colors hover:text-ink"
+					onclick={cancelEdit}
+				>
+					{m.btn_cancel()}
+				</button>
+			</div>
+		</div>
+	{:else}
+		<div class="flex items-start justify-between gap-2">
+			<div class="min-w-0 flex-1">
+				<div class="flex flex-wrap items-center gap-2">
+					<span class="font-sans text-xs font-semibold text-ink">{comment.authorName}</span>
+					<span class="font-sans text-xs text-ink-3">{timeAgo(comment.createdAt)}</span>
+					{#if wasEdited(comment)}
+						<span class="font-sans text-xs text-ink-3">
+							{m.comment_edited_label()}
+							{timeAgo(comment.updatedAt)}
+						</span>
 					{/if}
-				{/if}
+				</div>
+				<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">
+					<button
+						class="font-sans text-xs text-ink-3 transition-colors hover:text-ink"
+						onclick={() => startEdit(comment)}
+					>
+						{m.btn_edit()}
+					</button>
+					<button
+						class="font-sans text-xs text-ink-3 transition-colors hover:text-ink"
+						onclick={() => deleteComment(comment.id)}
+					>
+						{m.btn_delete()}
+					</button>
+				</div>
+			{/if}
+		</div>
+		{#if showReplyButton && canComment}
+			<div class="mt-1">
+				<button
+					class="font-sans text-xs font-medium text-primary transition-colors hover:text-ink-2"
+					onclick={() => startReply(threadId)}
+				>
+					{m.comment_btn_reply()}
+				</button>
+			</div>
+		{/if}
+	{/if}
+{/snippet}
+
+<div class="space-y-4">
+	{#if comments.length === 0}
+		<div class="flex flex-col items-center gap-3 py-8 text-center">
+			<svg
+				class="h-10 w-10 text-ink-3"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="1.5"
+			>
+				<path
+					stroke-linecap="round"
+					stroke-linejoin="round"
+					d="M2.25 12.76c0 1.6 1.123 2.994 2.707 3.227 1.087.16 2.185.283 3.293.369V21l4.076-4.076a1.526 1.526 0 0 1 1.037-.443 48.282 48.282 0 0 0 5.68-.494c1.584-.233 2.707-1.626 2.707-3.228V6.741c0-1.602-1.123-2.995-2.707-3.228A48.394 48.394 0 0 0 12 3c-2.392 0-4.744.175-7.043.513C3.373 3.746 2.25 5.14 2.25 6.741v6.018Z"
+				/>
+			</svg>
+			<p class="font-sans text-sm text-ink-3">{m.comment_empty_hint()}</p>
+		</div>
+	{/if}
+	{#each comments as thread, ti (thread.id)}
+		<div class={ti > 0 ? 'border-t border-line pt-4' : ''}>
+			<!-- Root comment -->
+			<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-brand-sand pl-4">
-					{#if editingId === reply.id}
-						<div class="flex flex-col gap-2">
-							<textarea
-								class="w-full resize-none rounded border border-brand-sand px-3 py-2 font-serif text-sm text-brand-navy focus:ring-1 focus:ring-brand-mint focus:outline-none"
-								rows={3}
-								bind:value={editText}
-							></textarea>
-							<div class="flex items-center gap-3">
-								<button
-									class="rounded bg-brand-navy px-3 py-1.5 font-sans text-xs font-medium text-white hover:bg-brand-navy/80 disabled:opacity-40"
-									disabled={posting}
-									onclick={() => saveEdit(reply.id)}
-								>
-									{m.btn_save()}
-								</button>
-								<button
-									class="font-sans text-xs text-gray-400 transition-colors hover:text-brand-navy"
-									onclick={cancelEdit}
-								>
-									{m.btn_cancel()}
-								</button>
-							</div>
-						</div>
-					{:else}
-						<div class="flex items-start justify-between gap-2">
-							<div class="min-w-0 flex-1">
-								<div class="flex flex-wrap items-center gap-2">
-									<span class="font-sans text-xs font-semibold text-brand-navy"
-										>{reply.authorName}</span
-									>
-									<span class="font-sans text-xs text-gray-400">{timeAgo(reply.createdAt)}</span>
-									{#if wasEdited(reply)}
-										<span class="font-sans text-xs text-gray-400">
-											{m.comment_edited_label()}
-											{timeAgo(reply.updatedAt)}
-										</span>
-									{/if}
-								</div>
-								<p class="mt-1 font-serif text-sm leading-relaxed text-gray-700">{reply.content}</p>
-							</div>
-							{#if canModify(reply)}
-								<div class="flex shrink-0 items-center gap-2">
-									<button
-										class="font-sans text-xs text-gray-400 transition-colors hover:text-brand-navy"
-										onclick={() => startEdit(reply)}
-									>
-										{m.btn_edit()}
-									</button>
-									<button
-										class="font-sans text-xs text-gray-400 transition-colors hover:text-brand-navy"
-										onclick={() => deleteComment(reply.id)}
-									>
-										{m.btn_delete()}
-									</button>
-								</div>
-							{/if}
-						</div>
-						<!-- Reply button only on the last reply -->
-						{#if ri === thread.replies.length - 1 && canComment}
-							<div class="mt-1">
-								<button
-									class="font-sans text-xs font-medium text-brand-mint transition-colors hover:text-brand-navy"
-									onclick={() => startReply(thread.id)}
-								>
-									{m.comment_btn_reply()}
-								</button>
-							</div>
-						{/if}
-					{/if}
+				<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}
 
-			<!-- Reply textarea (shown when replyingTo === thread.id) -->
+			<!-- 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-brand-sand px-3 py-2 font-serif text-sm text-brand-navy focus:ring-1 focus:ring-brand-mint 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-brand-navy px-3 py-1.5 font-sans text-xs font-medium text-white hover:bg-brand-navy/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)}
 						>
 							{m.comment_btn_post()}
 						</button>
 						<button
-							class="font-sans text-xs text-gray-400 transition-colors hover:text-brand-navy"
+							class="font-sans text-xs text-ink-3 transition-colors hover:text-ink"
 							onclick={cancelReply}
 						>
 							{m.btn_cancel()}
@@ -369,19 +361,21 @@ onMount(() => {
 		</div>
 	{/each}
 
-	<!-- New top-level comment textarea -->
+	<!-- New top-level comment -->
 	{#if canComment}
-		<div class={comments.length > 0 ? 'border-t border-brand-sand pt-4' : ''}>
+		<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-brand-sand px-3 py-2 font-serif text-sm text-brand-navy focus:ring-1 focus:ring-brand-mint 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-brand-navy px-3 py-1.5 font-sans text-xs font-medium text-white hover:bg-brand-navy/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/CommentThread.svelte.spec.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+import CommentThread from './CommentThread.svelte';
+import type { Comment } from '$lib/types';
+
+afterEach(() => {
+	cleanup();
+	vi.unstubAllGlobals();
+});
+
+function makeComment(id: string, content = 'Hello'): Comment {
+	return {
+		id,
+		authorId: 'user-1',
+		authorName: 'Alice',
+		content,
+		createdAt: new Date().toISOString(),
+		updatedAt: new Date().toISOString(),
+		replies: []
+	};
+}
+
+const baseProps = {
+	documentId: 'doc-1',
+	canComment: true,
+	currentUserId: 'user-1',
+	canAdmin: false
+};
+
+describe('CommentThread – empty state', () => {
+	it('shows empty state hint when there are no comments', async () => {
+		render(CommentThread, { ...baseProps, initialComments: [] });
+		await expect
+			.element(page.getByText('Noch keine Kommentare – starte die Diskussion!'))
+			.toBeInTheDocument();
+	});
+
+	it('does not show empty state hint when comments exist', async () => {
+		render(CommentThread, { ...baseProps, initialComments: [makeComment('c-1')] });
+		await expect
+			.element(page.getByText('Noch keine Kommentare – starte die Diskussion!'))
+			.not.toBeInTheDocument();
+	});
+});
+
+describe('CommentThread – onCountChange', () => {
+	it('calls onCountChange with initial SSR count on mount', async () => {
+		const onCountChange = vi.fn();
+		render(CommentThread, {
+			...baseProps,
+			initialComments: [makeComment('c-1'), makeComment('c-2')],
+			onCountChange
+		});
+		expect(onCountChange).toHaveBeenCalledWith(2);
+	});
+
+	it('calls onCountChange with 0 when no initial comments', async () => {
+		const onCountChange = vi.fn();
+		render(CommentThread, { ...baseProps, initialComments: [], onCountChange });
+		expect(onCountChange).toHaveBeenCalledWith(0);
+	});
+
+	it('counts replies in the total', async () => {
+		const onCountChange = vi.fn();
+		const comment = { ...makeComment('c-1'), replies: [makeComment('r-1') as never] };
+		render(CommentThread, { ...baseProps, initialComments: [comment], onCountChange });
+		expect(onCountChange).toHaveBeenCalledWith(2);
+	});
+});

frontend/src/lib/components/DocumentBottomPanel.svelte

@@ -0,0 +1,193 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import PanelMetadata from './PanelMetadata.svelte';
+import PanelTranscription from './PanelTranscription.svelte';
+import PanelDiscussion from './PanelDiscussion.svelte';
+import PanelHistory from './PanelHistory.svelte';
+import type { Comment, DocumentPanelTab } from '$lib/types';
+
+type Doc = {
+	id: string;
+	title?: string | null;
+	documentDate?: string | null;
+	location?: string | null;
+	documentLocation?: string | null;
+	tags?: { id: string; name: string }[] | null;
+	sender?: { id: string; firstName: string; lastName: string; alias?: string | null } | null;
+	receivers?: { id: string; firstName: string; lastName: string }[] | null;
+	summary?: string | null;
+	transcription?: string | null;
+};
+
+type Props = {
+	doc: Doc;
+	comments: Comment[];
+	canComment: boolean;
+	currentUserId: string | null;
+	canAdmin: boolean;
+	open: boolean;
+	height: number;
+	activeTab: DocumentPanelTab;
+	targetCommentId?: string | null;
+};
+
+let {
+	doc,
+	comments,
+	canComment,
+	currentUserId,
+	canAdmin,
+	open = $bindable(),
+	height = $bindable(),
+	activeTab = $bindable(),
+	targetCommentId = null
+}: Props = $props();
+
+const MIN_HEIGHT = 52; // drag handle (8px) + tab bar (~44px)
+
+let isDragging = $state(false);
+let dragStartY = 0;
+let dragStartHeight = 0;
+
+function fullHeight() {
+	const topbar = document.querySelector('[data-topbar]');
+	return window.innerHeight - (topbar?.getBoundingClientRect().bottom ?? 0);
+}
+
+function openTab(tab: DocumentPanelTab) {
+	activeTab = tab;
+	if (!open) {
+		open = true;
+		if (height <= MIN_HEIGHT) height = fullHeight();
+	}
+}
+
+function closePanel() {
+	open = false;
+}
+
+function onDragStart(e: PointerEvent) {
+	isDragging = true;
+	dragStartY = e.clientY;
+	dragStartHeight = open ? height : MIN_HEIGHT;
+	(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+}
+
+function onDragMove(e: PointerEvent) {
+	if (!isDragging) return;
+	const delta = dragStartY - e.clientY; // positive = dragging up = bigger panel
+	const newHeight = dragStartHeight + delta;
+	const maxHeight = fullHeight();
+
+	if (newHeight <= MIN_HEIGHT + 20) {
+		// collapsed past threshold → close
+		open = false;
+	} else {
+		open = true;
+		height = Math.max(80, Math.min(newHeight, maxHeight));
+	}
+}
+
+function onDragEnd() {
+	isDragging = false;
+}
+
+const tabs: { id: DocumentPanelTab; label: () => string }[] = [
+	{ id: 'metadata', label: m.doc_panel_tab_metadata },
+	{ id: 'transcription', label: m.doc_panel_tab_transcription },
+	{ id: 'discussion', label: m.doc_panel_tab_discussion },
+	{ id: 'history', label: m.doc_panel_tab_history }
+];
+
+const panelHeight = $derived(open ? height : MIN_HEIGHT);
+
+let discussionCount = $state((() => comments.reduce((s, c) => s + 1 + c.replies.length, 0))());
+
+function handleCountChange(count: number) {
+	discussionCount = count;
+}
+</script>
+
+<div
+	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"
+>
+	<!-- Drag handle -->
+	<div
+		class="flex h-2 shrink-0 cursor-ns-resize items-center justify-center bg-surface"
+		style="touch-action: none"
+		role="separator"
+		aria-orientation="horizontal"
+		aria-label="Panel resize"
+		onpointerdown={onDragStart}
+		onpointermove={onDragMove}
+		onpointerup={onDragEnd}
+		onpointercancel={onDragEnd}
+	>
+		<div class="h-1 w-12 rounded-full bg-line"></div>
+	</div>
+
+	<!-- Tab bar -->
+	<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="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" />
+				</svg>
+			</button>
+		{/if}
+	</div>
+
+	<!-- Tab content -->
+	{#if open}
+		<div class="flex-1 overflow-y-auto" data-testid="bottom-panel-content">
+			{#if activeTab === 'metadata'}
+				<PanelMetadata doc={doc} />
+			{:else if activeTab === 'transcription'}
+				<PanelTranscription doc={doc} />
+			{:else if activeTab === 'discussion'}
+				<PanelDiscussion
+					documentId={doc.id}
+					initialComments={comments}
+					canComment={canComment}
+					currentUserId={currentUserId}
+					canAdmin={canAdmin}
+					targetCommentId={targetCommentId}
+					onCountChange={handleCountChange}
+				/>
+			{:else if activeTab === 'history'}
+				<PanelHistory documentId={doc.id} />
+			{/if}
+		</div>
+	{/if}
+</div>

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

@@ -0,0 +1,47 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+import DocumentBottomPanel from './DocumentBottomPanel.svelte';
+import type { Comment } from '$lib/types';
+
+afterEach(cleanup);
+
+function makeComment(id: string): Comment {
+	return {
+		id,
+		authorId: 'user-1',
+		authorName: 'Alice',
+		content: 'Hello',
+		createdAt: new Date().toISOString(),
+		updatedAt: new Date().toISOString(),
+		replies: []
+	};
+}
+
+const doc = { id: 'doc-1', title: 'Test' };
+
+const baseProps = {
+	doc,
+	canComment: true,
+	currentUserId: 'user-1',
+	canAdmin: false,
+	height: 300,
+	activeTab: 'discussion' as const
+};
+
+describe('DocumentBottomPanel – discussion badge', () => {
+	it('always shows a badge on the Discussion tab', async () => {
+		render(DocumentBottomPanel, { ...baseProps, comments: [], open: true });
+		await expect.element(page.getByTestId('discussion-count-badge')).toBeInTheDocument();
+		await expect.element(page.getByTestId('discussion-count-badge')).toHaveTextContent('0');
+	});
+
+	it('shows the correct count when comments exist', async () => {
+		render(DocumentBottomPanel, {
+			...baseProps,
+			comments: [makeComment('c-1'), makeComment('c-2')],
+			open: true
+		});
+		await expect.element(page.getByTestId('discussion-count-badge')).toHaveTextContent('2');
+	});
+});

frontend/src/lib/components/DocumentTopBar.svelte

@@ -0,0 +1,152 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+
+type Person = { id: string; firstName: string; lastName: string };
+
+type Doc = {
+	id: string;
+	title?: string | null;
+	originalFilename?: string | null;
+	documentDate?: string | null;
+	sender?: Person | null;
+	receivers?: Person[] | null;
+	filePath?: string | null;
+	contentType?: string | null;
+};
+
+type Props = {
+	doc: Doc;
+	canWrite: boolean;
+	canAnnotate: boolean;
+	fileUrl: string;
+	annotateMode: boolean;
+};
+
+let { doc, canWrite, canAnnotate, fileUrl, annotateMode = $bindable() }: Props = $props();
+
+const isPdf = $derived(!!doc.filePath && doc.contentType?.startsWith('application/pdf'));
+
+const receiverDisplay = $derived.by(() => {
+	const receivers = doc.receivers ?? [];
+	if (receivers.length === 0) return null;
+	const shown = receivers.slice(0, 2);
+	const extra = receivers.length - shown.length;
+	const names = shown.map((r) => `${r.firstName} ${r.lastName}`).join(', ');
+	return extra > 0 ? `${names} +${extra}` : names;
+});
+
+const compactMeta = $derived.by(() => {
+	const parts: string[] = [];
+	if (doc.documentDate) {
+		parts.push(
+			new Intl.DateTimeFormat('de-DE', {
+				day: 'numeric',
+				month: 'numeric',
+				year: 'numeric'
+			}).format(new Date(doc.documentDate + 'T12:00:00'))
+		);
+	}
+	if (doc.sender) {
+		const senderName = `${doc.sender.firstName} ${doc.sender.lastName}`;
+		const receiver = receiverDisplay;
+		parts.push(receiver ? `${senderName} → ${receiver}` : senderName);
+	} else if (receiverDisplay) {
+		parts.push(`→ ${receiverDisplay}`);
+	}
+	return parts.join(' · ');
+});
+</script>
+
+<div
+	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 -->
+	<div class="flex min-w-0 items-center gap-4 overflow-hidden">
+		<a
+			href="/"
+			class="group flex shrink-0 items-center gap-2 font-sans text-sm font-medium text-ink-2 transition-colors hover:text-ink"
+		>
+			<div
+				class="flex h-8 w-8 items-center justify-center rounded-full bg-canvas transition-colors group-hover:bg-accent"
+			>
+				<img
+					src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Arrow/Arrow-Left-MD.svg"
+					alt=""
+					aria-hidden="true"
+					class="h-4 w-4"
+				/>
+			</div>
+			<span class="hidden sm:inline">{m.btn_back()}</span>
+		</a>
+
+		<div class="min-w-0 border-l border-line pl-4">
+			<h1
+				class="truncate font-serif text-base leading-tight text-ink"
+				title={doc.title ?? doc.originalFilename ?? ''}
+			>
+				{doc.title || doc.originalFilename}
+			</h1>
+			{#if compactMeta}
+				<p class="truncate font-sans text-xs text-ink-2" title={compactMeta}>
+					{compactMeta}
+				</p>
+			{/if}
+		</div>
+	</div>
+
+	<!-- Right: actions -->
+	<div class="ml-4 flex shrink-0 items-center gap-2 font-sans">
+		{#if canAnnotate && isPdf}
+			<button
+				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-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"
+					alt=""
+					aria-hidden="true"
+					class="h-4 w-4 {annotateMode ? 'invert' : ''}"
+				/>
+				<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"
+				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"
+					alt=""
+					aria-hidden="true"
+					class="h-4 w-4"
+				/>
+				<span class="hidden sm:inline">{m.btn_edit()}</span>
+			</a>
+		{/if}
+
+		{#if doc.filePath}
+			<a
+				href={fileUrl}
+				download={doc.originalFilename}
+				class="rounded border border-transparent bg-muted p-1.5 text-ink transition hover:bg-accent"
+				title={m.doc_download_title()}
+			>
+				<img
+					src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Download-MD.svg"
+					alt=""
+					aria-hidden="true"
+					class="h-5 w-5"
+				/>
+			</a>
+		{/if}
+	</div>
+</div>

frontend/src/lib/components/DocumentViewer.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import PdfViewer from './PdfViewer.svelte';
+
+type Doc = {
+	id: string;
+	filePath?: string | null;
+	contentType?: string | null;
+	fileHash?: string | null;
+};
+
+type Props = {
+	doc: Doc;
+	fileUrl: string;
+	isLoading: boolean;
+	error: string;
+	annotateMode: boolean;
+	activeAnnotationId: string | null;
+	activeAnnotationPage: number | null;
+	onAnnotationClick: (id: string) => void;
+};
+
+let {
+	doc,
+	fileUrl,
+	isLoading,
+	error,
+	annotateMode = $bindable(),
+	activeAnnotationId = $bindable(),
+	activeAnnotationPage = $bindable(),
+	onAnnotationClick
+}: Props = $props();
+</script>
+
+<div class="absolute inset-0 bg-pdf-bg">
+	{#if isLoading}
+		<div class="flex h-full flex-col items-center justify-center text-accent">
+			<svg
+				class="mb-4 h-8 w-8 animate-spin"
+				xmlns="http://www.w3.org/2000/svg"
+				fill="none"
+				viewBox="0 0 24 24"
+			>
+				<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"
+				></circle>
+				<path
+					class="opacity-75"
+					fill="currentColor"
+					d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+				></path>
+			</svg>
+			<span class="font-sans text-sm tracking-wide">{m.doc_loading()}</span>
+		</div>
+	{:else if error}
+		<div class="flex h-full flex-col items-center justify-center px-4 text-center text-ink-3">
+			<p class="mb-2 font-serif">{error}</p>
+			{#if doc.filePath}
+				<a
+					href="/api/documents/{doc.id}/file"
+					target="_blank"
+					class="text-sm underline hover:text-white"
+				>
+					{m.doc_download_link()}
+				</a>
+			{/if}
+		</div>
+	{:else if !doc.filePath}
+		<div class="flex h-full flex-col items-center justify-center text-ink-3">
+			<div class="mb-6 rounded-full bg-surface/5 p-8">
+				<img
+					src="/degruyter-icons/Simple/Medium-24px/SVG/Action/PDF-Document-MD.svg"
+					alt=""
+					aria-hidden="true"
+					class="h-12 w-12 opacity-50 invert"
+				/>
+			</div>
+			<p class="font-sans text-sm tracking-wide uppercase">{m.doc_no_scan()}</p>
+		</div>
+	{:else if fileUrl && doc.contentType?.startsWith('application/pdf')}
+		<PdfViewer
+			url={fileUrl}
+			documentId={doc.id}
+			bind:annotateMode={annotateMode}
+			bind:activeAnnotationId={activeAnnotationId}
+			bind:activeAnnotationPage={activeAnnotationPage}
+			onAnnotationClick={onAnnotationClick}
+			documentFileHash={doc.fileHash ?? null}
+		/>
+	{:else if fileUrl}
+		<div class="flex h-full w-full items-center justify-center overflow-auto p-8">
+			<img
+				src={fileUrl}
+				alt={m.doc_image_alt()}
+				class="max-h-full max-w-full object-contain shadow-2xl"
+			/>
+		</div>
+	{/if}
+</div>

frontend/src/lib/components/ExpandableText.svelte

@@ -18,14 +18,14 @@ $effect(() => {
 	<div
 		bind:this={el}
 		style={!expanded ? `overflow: hidden; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: ${maxLines}` : ''}
-		class="rounded border border-brand-sand bg-brand-sand/30 p-5 font-serif text-sm leading-relaxed whitespace-pre-wrap text-brand-navy"
+		class="rounded border border-line bg-muted p-5 font-serif text-sm leading-relaxed whitespace-pre-wrap text-ink"
 	>
 		{text}
 	</div>
 	{#if isClamped || expanded}
 		<button
 			onclick={() => (expanded = !expanded)}
-			class="mt-2 font-sans text-xs text-gray-400 transition hover:text-brand-navy"
+			class="mt-2 font-sans text-xs text-ink-3 transition hover:text-ink"
 		>
 			{expanded ? m.comp_expandable_show_less() : m.comp_expandable_show_more()}
 		</button>

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

@@ -0,0 +1,36 @@
+<script lang="ts">
+import CommentThread from './CommentThread.svelte';
+import type { Comment } from '$lib/types';
+
+type Props = {
+	documentId: string;
+	initialComments: Comment[];
+	canComment: boolean;
+	currentUserId: string | null;
+	canAdmin: boolean;
+	targetCommentId?: string | null;
+	onCountChange?: (count: number) => void;
+};
+
+let {
+	documentId,
+	initialComments,
+	canComment,
+	currentUserId,
+	canAdmin,
+	targetCommentId = null,
+	onCountChange
+}: Props = $props();
+</script>
+
+<div class="flex-1 overflow-y-auto p-6">
+	<CommentThread
+		documentId={documentId}
+		initialComments={initialComments}
+		canComment={canComment}
+		currentUserId={currentUserId}
+		canAdmin={canAdmin}
+		targetCommentId={targetCommentId}
+		onCountChange={onCountChange}
+	/>
+</div>

frontend/src/lib/components/PanelHistory.svelte

@@ -0,0 +1,519 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import { diffWords } from 'diff';
+
+let { documentId }: { documentId: string } = $props();
+
+type VersionSummary = {
+	id: string;
+	savedAt: string;
+	editorName: string;
+	changedFields: string[];
+};
+
+type SnapshotDoc = {
+	title?: string;
+	documentDate?: string;
+	location?: string;
+	documentLocation?: string;
+	transcription?: string;
+	summary?: string;
+	sender?: { id: string; firstName: string; lastName: string } | null;
+	receivers?: { id: string; firstName: string; lastName: string }[];
+	tags?: { id: string; name: string }[];
+};
+
+type DiffEntry =
+	| {
+			kind: 'text';
+			field: string;
+			label: string;
+			parts: { value: string; added?: boolean; removed?: boolean }[];
+	  }
+	| { kind: 'scalar'; field: string; label: string; oldVal: string; newVal: string }
+	| { kind: 'relation'; field: string; label: string; removed: string[]; added: string[] };
+
+let historyLoaded = $state(false);
+let historyLoading = $state(false);
+let versions = $state<VersionSummary[]>([]);
+
+let compareMode = $state(false);
+let compareA = $state('');
+let compareB = $state('');
+
+let selectedVersionId = $state<string | null>(null);
+let diffEntries = $state<DiffEntry[]>([]);
+let diffLoading = $state(false);
+let noDiff = $state(false);
+
+const fieldLabels: Record<string, () => string> = {
+	title: m.history_field_title,
+	documentDate: m.history_field_document_date,
+	location: m.history_field_location,
+	documentLocation: m.history_field_document_location,
+	transcription: m.history_field_transcription,
+	summary: m.history_field_summary,
+	sender: m.history_field_sender,
+	receivers: m.history_field_receivers,
+	tags: m.history_field_tags
+};
+
+const TEXT_FIELDS = ['title', 'summary', 'transcription'] as const;
+const SCALAR_FIELDS = ['documentDate', 'location', 'documentLocation'] as const;
+
+function parseSnapshot(raw: string): SnapshotDoc {
+	try {
+		return JSON.parse(raw) as SnapshotDoc;
+	} catch {
+		return {};
+	}
+}
+
+function personLabel(p: { firstName: string; lastName: string }): string {
+	return `${p.firstName} ${p.lastName}`.trim();
+}
+
+const DIFF_CONTEXT_WORDS = 4;
+
+type DiffPart = { value: string; added?: boolean; removed?: boolean };
+
+function trimContextParts(parts: DiffPart[]): DiffPart[] {
+	return parts.flatMap((part, i) => {
+		if (part.added || part.removed) return [part];
+		const tokens = part.value.split(/(\s+)/).filter(Boolean);
+		const wordCount = tokens.filter((t) => /\S/.test(t)).length;
+		if (wordCount <= DIFF_CONTEXT_WORDS * 2) return [part];
+
+		function keepFirst(n: number): string {
+			let count = 0;
+			const out: string[] = [];
+			for (const t of tokens) {
+				out.push(t);
+				if (/\S/.test(t) && ++count >= n) break;
+			}
+			return out.join('');
+		}
+		function keepLast(n: number): string {
+			let count = 0;
+			const out: string[] = [];
+			for (const t of [...tokens].reverse()) {
+				out.unshift(t);
+				if (/\S/.test(t) && ++count >= n) break;
+			}
+			return out.join('');
+		}
+
+		const isFirst = i === 0;
+		const isLast = i === parts.length - 1;
+		if (isFirst) return [{ value: '… ' + keepLast(DIFF_CONTEXT_WORDS) }];
+		if (isLast) return [{ value: keepFirst(DIFF_CONTEXT_WORDS) + ' …' }];
+		return [{ value: keepFirst(DIFF_CONTEXT_WORDS) + ' … ' + keepLast(DIFF_CONTEXT_WORDS) }];
+	});
+}
+
+function buildDiff(older: SnapshotDoc | null, newer: SnapshotDoc): DiffEntry[] {
+	const entries: DiffEntry[] = [];
+
+	for (const field of TEXT_FIELDS) {
+		const a = older?.[field] ?? '';
+		const b = newer[field] ?? '';
+		if (a === b) continue;
+		const parts = trimContextParts(diffWords(a, b));
+		entries.push({ kind: 'text', field, label: fieldLabels[field](), parts });
+	}
+
+	for (const field of SCALAR_FIELDS) {
+		const a = older?.[field] ?? '';
+		const b = newer[field] ?? '';
+		if (a === b) continue;
+		entries.push({ kind: 'scalar', field, label: fieldLabels[field](), oldVal: a, newVal: b });
+	}
+
+	const senderA = older?.sender ? personLabel(older.sender) : '';
+	const senderB = newer.sender ? personLabel(newer.sender) : '';
+	if (senderA !== senderB) {
+		entries.push({
+			kind: 'relation',
+			field: 'sender',
+			label: fieldLabels['sender'](),
+			removed: senderA ? [senderA] : [],
+			added: senderB ? [senderB] : []
+		});
+	}
+
+	const receiversA = new Set((older?.receivers ?? []).map(personLabel));
+	const receiversB = new Set((newer.receivers ?? []).map(personLabel));
+	const removedReceivers = [...receiversA].filter((r) => !receiversB.has(r));
+	const addedReceivers = [...receiversB].filter((r) => !receiversA.has(r));
+	if (removedReceivers.length > 0 || addedReceivers.length > 0) {
+		entries.push({
+			kind: 'relation',
+			field: 'receivers',
+			label: fieldLabels['receivers'](),
+			removed: removedReceivers,
+			added: addedReceivers
+		});
+	}
+
+	const tagsA = new Set((older?.tags ?? []).map((t) => t.name));
+	const tagsB = new Set((newer.tags ?? []).map((t) => t.name));
+	const removedTags = [...tagsA].filter((t) => !tagsB.has(t));
+	const addedTags = [...tagsB].filter((t) => !tagsA.has(t));
+	if (removedTags.length > 0 || addedTags.length > 0) {
+		entries.push({
+			kind: 'relation',
+			field: 'tags',
+			label: fieldLabels['tags'](),
+			removed: removedTags,
+			added: addedTags
+		});
+	}
+
+	return entries;
+}
+
+async function fetchSnapshot(versionId: string): Promise<SnapshotDoc> {
+	const res = await fetch(`/api/documents/${documentId}/versions/${versionId}`);
+	if (!res.ok) throw new Error('Failed to fetch version');
+	const v = await res.json();
+	return parseSnapshot(v.snapshot);
+}
+
+async function loadHistory() {
+	if (historyLoaded) return;
+	historyLoading = true;
+	try {
+		const res = await fetch(`/api/documents/${documentId}/versions`);
+		if (res.ok) {
+			versions = await res.json();
+		}
+		historyLoaded = true;
+	} catch {
+		// ignore
+	} finally {
+		historyLoading = false;
+	}
+}
+
+async function selectVersion(versionId: string) {
+	if (selectedVersionId === versionId) {
+		selectedVersionId = null;
+		diffEntries = [];
+		noDiff = false;
+		return;
+	}
+	selectedVersionId = versionId;
+	diffEntries = [];
+	noDiff = false;
+	diffLoading = true;
+	try {
+		const idx = versions.findIndex((v) => v.id === versionId);
+		const newerSnap = await fetchSnapshot(versionId);
+		const olderSnap = idx > 0 ? await fetchSnapshot(versions[idx - 1].id) : null;
+		const entries = buildDiff(olderSnap, newerSnap);
+		if (entries.length === 0) {
+			noDiff = true;
+		} else {
+			diffEntries = entries;
+		}
+	} catch {
+		// ignore
+	} finally {
+		diffLoading = false;
+	}
+}
+
+async function applyCompare() {
+	if (!compareA || !compareB || compareA === compareB) return;
+	selectedVersionId = null;
+	diffEntries = [];
+	noDiff = false;
+	diffLoading = true;
+	try {
+		const [snapA, snapB] = await Promise.all([fetchSnapshot(compareA), fetchSnapshot(compareB)]);
+		const entries = buildDiff(snapA, snapB);
+		if (entries.length === 0) {
+			noDiff = true;
+		} else {
+			diffEntries = entries;
+		}
+	} catch {
+		// ignore
+	} finally {
+		diffLoading = false;
+	}
+}
+
+function formatDateTime(iso: string): string {
+	try {
+		return new Intl.DateTimeFormat('de-DE', {
+			day: 'numeric',
+			month: 'short',
+			year: 'numeric',
+			hour: '2-digit',
+			minute: '2-digit'
+		}).format(new Date(iso));
+	} catch {
+		return iso;
+	}
+}
+
+function versionLabel(v: VersionSummary, index: number): string {
+	return `Version ${index + 1} — ${v.editorName} — ${formatDateTime(v.savedAt)}`;
+}
+
+// Load history when this panel mounts.
+$effect(() => {
+	loadHistory();
+});
+</script>
+
+<div class="space-y-4 p-6">
+	{#if historyLoading}
+		<p class="font-sans text-xs text-ink-3">{m.history_loading()}</p>
+	{:else if !historyLoaded}
+		<!-- initial state before effect runs — show nothing -->
+	{:else if versions.length === 0}
+		<p class="font-serif text-sm text-ink-3 italic">{m.history_empty()}</p>
+	{:else}
+		<!-- Compare mode toggle -->
+		<div class="flex justify-end">
+			<button
+				onclick={() => {
+					compareMode = !compareMode;
+					diffEntries = [];
+					noDiff = false;
+					selectedVersionId = null;
+				}}
+				class="font-sans text-xs font-medium transition {compareMode
+					? 'text-ink underline'
+					: 'text-ink-3 hover:text-ink'}"
+			>
+				{m.history_compare_mode()}
+			</button>
+		</div>
+
+		{#if compareMode}
+			<div class="space-y-2">
+				<div>
+					<label for="compare-a" class="mb-1 block font-sans text-[10px] text-ink-3 uppercase"
+						>{m.history_compare_select_a()}</label
+					>
+					<select
+						id="compare-a"
+						bind:value={compareA}
+						class="w-full rounded border border-line bg-surface px-2 py-1 font-sans text-xs text-ink focus:ring-1 focus:ring-accent focus:outline-none"
+					>
+						<option value="">—</option>
+						{#each versions as v, i (v.id)}
+							<option value={v.id}>{versionLabel(v, i)}</option>
+						{/each}
+					</select>
+				</div>
+				<div>
+					<label for="compare-b" class="mb-1 block font-sans text-[10px] text-ink-3 uppercase"
+						>{m.history_compare_select_b()}</label
+					>
+					<select
+						id="compare-b"
+						bind:value={compareB}
+						class="w-full rounded border border-line bg-surface px-2 py-1 font-sans text-xs text-ink focus:ring-1 focus:ring-accent focus:outline-none"
+					>
+						<option value="">—</option>
+						{#each versions as v, i (v.id)}
+							<option value={v.id}>{versionLabel(v, i)}</option>
+						{/each}
+					</select>
+				</div>
+				<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-primary-fg transition hover:bg-primary/80 disabled:cursor-not-allowed disabled:opacity-40"
+				>
+					{m.history_compare_apply()}
+				</button>
+			</div>
+
+			<!-- Diff panel for compare mode -->
+			{#if diffLoading}
+				<p class="font-sans text-xs text-ink-3">{m.history_loading()}</p>
+			{:else if noDiff}
+				<div
+					data-testid="history-diff"
+					class="rounded-sm border border-line bg-surface p-4 font-serif text-sm text-ink-3 italic"
+				>
+					{m.history_diff_no_changes()}
+				</div>
+			{:else if diffEntries.length > 0}
+				<div
+					data-testid="history-diff"
+					class="space-y-4 rounded-sm border border-line bg-surface p-4"
+				>
+					{#each diffEntries as entry (entry.field)}
+						<div>
+							<span
+								class="mb-1.5 block font-sans text-[10px] font-bold tracking-wide text-ink-3 uppercase"
+								>{entry.label}</span
+							>
+							{#if entry.kind === 'text'}
+								<p class="font-serif text-sm leading-relaxed">
+									{#each entry.parts as part, partIdx (partIdx)}
+										{#if part.added}
+											<span class="bg-green-50 text-green-700">{part.value}</span>
+										{:else if part.removed}
+											<span class="bg-red-50 text-red-600 line-through">{part.value}</span>
+										{:else}
+											<span>{part.value}</span>
+										{/if}
+									{/each}
+								</p>
+							{:else if entry.kind === 'scalar'}
+								<div class="flex items-center gap-2 font-serif text-sm">
+									<span class="text-red-600 line-through">{entry.oldVal || '—'}</span>
+									<svg
+										class="h-3 w-3 flex-shrink-0 text-ink-3"
+										viewBox="0 0 20 20"
+										fill="currentColor"
+										aria-hidden="true"
+									>
+										<path
+											fill-rule="evenodd"
+											d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
+											clip-rule="evenodd"
+										/>
+									</svg>
+									<span class="text-green-700">{entry.newVal || '—'}</span>
+								</div>
+							{:else if entry.kind === 'relation'}
+								<div class="flex flex-wrap gap-1.5">
+									{#each entry.removed as item (item)}
+										<span
+											class="rounded bg-red-50 px-1.5 py-0.5 font-sans text-[11px] text-red-600 line-through"
+											>{item}</span
+										>
+									{/each}
+									{#each entry.added as item (item)}
+										<span
+											class="rounded bg-green-50 px-1.5 py-0.5 font-sans text-[11px] text-green-700"
+											>{item}</span
+										>
+									{/each}
+								</div>
+							{/if}
+						</div>
+					{/each}
+				</div>
+			{/if}
+		{:else}
+			<!-- Version list with inline diff below each selected item -->
+			<ul class="divide-y divide-line">
+				{#each versions as v, i (v.id)}
+					<li>
+						<button
+							onclick={() => selectVersion(v.id)}
+							data-testid="history-version"
+							class="w-full py-2 text-left transition hover:bg-muted {selectedVersionId ===
+							v.id
+								? 'border-l-2 border-accent pl-2'
+								: 'pl-0'}"
+						>
+							<div class="flex items-baseline justify-between gap-2">
+								<span class="font-sans text-xs font-medium text-ink">
+									Version {i + 1}
+								</span>
+								<span class="font-sans text-[10px] text-ink-3">
+									{formatDateTime(v.savedAt)}
+								</span>
+							</div>
+							<span class="font-sans text-[11px] text-ink-2">{v.editorName}</span>
+							{#if v.changedFields && v.changedFields.length > 0}
+								<div class="mt-1 flex flex-wrap gap-1">
+									{#each v.changedFields as field (field)}
+										<span
+											class="rounded bg-muted px-1.5 py-0.5 font-sans text-[10px] tracking-wide text-ink-2 uppercase"
+										>
+											{fieldLabels[field] ? fieldLabels[field]() : field}
+										</span>
+									{/each}
+								</div>
+							{/if}
+						</button>
+
+						<!-- Diff shown inline below the selected version -->
+						{#if selectedVersionId === v.id}
+							{#if diffLoading}
+								<p class="pb-3 pl-2 font-sans text-xs text-ink-3">{m.history_loading()}</p>
+							{:else if noDiff}
+								<div
+									data-testid="history-diff"
+									class="mb-2 rounded-sm border border-line bg-surface p-4 font-serif text-sm text-ink-3 italic"
+								>
+									{m.history_diff_no_changes()}
+								</div>
+							{:else if diffEntries.length > 0}
+								<div
+									data-testid="history-diff"
+									class="mb-2 space-y-4 rounded-sm border border-line bg-surface p-4"
+								>
+									{#each diffEntries as entry (entry.field)}
+										<div>
+											<span
+												class="mb-1.5 block font-sans text-[10px] font-bold tracking-wide text-ink-3 uppercase"
+												>{entry.label}</span
+											>
+											{#if entry.kind === 'text'}
+												<p class="font-serif text-sm leading-relaxed">
+													{#each entry.parts as part, partIdx (partIdx)}
+														{#if part.added}
+															<span class="bg-green-50 text-green-700">{part.value}</span>
+														{:else if part.removed}
+															<span class="bg-red-50 text-red-600 line-through">{part.value}</span>
+														{:else}
+															<span>{part.value}</span>
+														{/if}
+													{/each}
+												</p>
+											{:else if entry.kind === 'scalar'}
+												<div class="flex items-center gap-2 font-serif text-sm">
+													<span class="text-red-600 line-through">{entry.oldVal || '—'}</span>
+													<svg
+														class="h-3 w-3 flex-shrink-0 text-ink-3"
+														viewBox="0 0 20 20"
+														fill="currentColor"
+														aria-hidden="true"
+													>
+														<path
+															fill-rule="evenodd"
+															d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
+															clip-rule="evenodd"
+														/>
+													</svg>
+													<span class="text-green-700">{entry.newVal || '—'}</span>
+												</div>
+											{:else if entry.kind === 'relation'}
+												<div class="flex flex-wrap gap-1.5">
+													{#each entry.removed as item (item)}
+														<span
+															class="rounded bg-red-50 px-1.5 py-0.5 font-sans text-[11px] text-red-600 line-through"
+															>{item}</span
+														>
+													{/each}
+													{#each entry.added as item (item)}
+														<span
+															class="rounded bg-green-50 px-1.5 py-0.5 font-sans text-[11px] text-green-700"
+															>{item}</span
+														>
+													{/each}
+												</div>
+											{/if}
+										</div>
+									{/each}
+								</div>
+							{/if}
+						{/if}
+					</li>
+				{/each}
+			</ul>
+		{/if}
+	{/if}
+</div>

frontend/src/lib/components/PanelMetadata.svelte

@@ -0,0 +1,200 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import { formatDate } from '$lib/utils/date';
+
+type Person = { id: string; firstName: string; lastName: string; alias?: string | null };
+type Tag = { id: string; name: string };
+
+type Doc = {
+	documentDate?: string | null;
+	location?: string | null;
+	documentLocation?: string | null;
+	tags?: Tag[] | null;
+	sender?: Person | null;
+	receivers?: Person[] | null;
+};
+
+let { doc }: { doc: Doc } = $props();
+</script>
+
+<div class="space-y-10 p-6">
+	<!-- DETAILS GROUP -->
+	<div>
+		<h3
+			class="mb-4 border-b border-line pb-2 font-sans text-xs font-bold tracking-widest text-ink uppercase"
+		>
+			{m.doc_section_details()}
+		</h3>
+		<div class="space-y-5">
+			<!-- Date -->
+			<div class="flex items-start">
+				<span class="mt-0.5 w-8 text-accent">
+					<img
+						src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Calendar/Calendar-Add-MD.svg"
+						alt=""
+						aria-hidden="true"
+						class="h-5 w-5"
+					/>
+				</span>
+				<div>
+					<span class="block font-serif text-lg text-ink">
+						{doc.documentDate ? formatDate(doc.documentDate) : '—'}
+					</span>
+					<span class="font-sans text-xs text-ink-2">{m.doc_label_document_date()}</span>
+				</div>
+			</div>
+
+			<!-- Creation Location -->
+			<div class="flex items-start">
+				<span class="mt-0.5 w-8 text-accent">
+					<img
+						src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Location-MD.svg"
+						alt=""
+						aria-hidden="true"
+						class="h-5 w-5"
+					/>
+				</span>
+				<div>
+					<span class="block font-serif text-lg text-ink">
+						{doc.location ? doc.location : '—'}
+					</span>
+					<span class="font-sans text-xs text-ink-2">{m.doc_label_creation_location()}</span>
+				</div>
+			</div>
+
+			<!-- Physical Archive Location -->
+			{#if doc.documentLocation}
+				<div class="flex items-start">
+					<span class="mt-0.5 w-8 text-accent">
+						<img
+							src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Folder-MD.svg"
+							alt=""
+							aria-hidden="true"
+							class="h-5 w-5"
+						/>
+					</span>
+					<div>
+						<span class="block font-serif text-lg text-ink">
+							{doc.documentLocation}
+						</span>
+						<span class="font-sans text-xs text-ink-2"
+							>{m.doc_label_archive_location_original()}</span
+						>
+					</div>
+				</div>
+			{/if}
+
+			<!-- Tags -->
+			{#if doc.tags && doc.tags.length > 0}
+				<div class="flex items-start">
+					<span class="mt-0.5 w-8 text-accent">
+						<img
+							src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Bookmark/Bookmark-Outline-MD.svg"
+							alt=""
+							aria-hidden="true"
+							class="h-5 w-5"
+						/>
+					</span>
+					<div class="flex-1">
+						<div class="mb-1 flex flex-wrap gap-2">
+							{#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-primary-fg"
+									title={m.doc_tag_filter_title({ name: tag.name })}
+								>
+									{tag.name}
+								</a>
+							{/each}
+						</div>
+						<span class="font-sans text-xs text-ink-2">{m.form_label_tags()}</span>
+					</div>
+				</div>
+			{/if}
+		</div>
+	</div>
+
+	<!-- PERSONEN GROUP -->
+	<div>
+		<h3
+			class="mb-4 border-b border-line pb-2 font-sans text-xs font-bold tracking-widest text-ink uppercase"
+		>
+			{m.doc_section_persons()}
+		</h3>
+
+		<div class="mb-6">
+			<span class="mb-2 block font-sans text-xs text-ink-3 uppercase">{m.form_label_sender()}</span>
+			{#if doc.sender}
+				<a
+					href="/persons/{doc.sender.id}"
+					class="group block rounded border border-line bg-muted p-3 transition hover:border-accent hover:bg-accent/10"
+				>
+					<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-primary-fg"
+						>
+							{doc.sender.firstName[0]}{doc.sender.lastName[0]}
+						</div>
+						<div>
+							<p
+								class="font-serif text-ink decoration-brand-mint underline-offset-2 group-hover:underline"
+							>
+								{doc.sender.firstName}
+								{doc.sender.lastName}
+							</p>
+							{#if doc.sender.alias}
+								<p class="font-sans text-xs text-ink-2">{doc.sender.alias}</p>
+							{/if}
+						</div>
+					</div>
+				</a>
+			{:else}
+				<span class="font-serif text-sm text-ink-3 italic">{m.doc_sender_not_specified()}</span>
+			{/if}
+		</div>
+
+		<div>
+			<span class="mb-2 block font-sans text-xs text-ink-3 uppercase"
+				>{m.form_label_receivers()}</span
+			>
+			{#if doc.receivers && doc.receivers.length > 0}
+				<div class="space-y-2">
+					{#each doc.receivers as receiver (receiver.id)}
+						<div
+							class="group flex items-center justify-between rounded border border-line bg-surface p-3 transition hover:border-primary"
+						>
+							<a href="/persons/{receiver.id}" class="flex min-w-0 flex-1 items-center gap-3">
+								<div
+									class="flex h-6 w-6 items-center justify-center rounded-full bg-muted font-serif text-xs text-ink-2"
+								>
+									{receiver.firstName[0]}{receiver.lastName[0]}
+								</div>
+								<span class="truncate font-serif text-sm text-ink">
+									{receiver.firstName}
+									{receiver.lastName}
+								</span>
+							</a>
+
+							{#if doc.sender}
+								<a
+									href="/conversations?senderId={doc.sender.id}&receiverId={receiver.id}"
+									class="text-ink-3 transition hover:text-accent"
+									title={m.doc_conversation_title()}
+								>
+									<img
+										src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Chat-MD.svg"
+										alt=""
+										aria-hidden="true"
+										class="h-5 w-5"
+									/>
+								</a>
+							{/if}
+						</div>
+					{/each}
+				</div>
+			{:else}
+				<span class="font-serif text-sm text-ink-3 italic">{m.doc_no_receivers()}</span>
+			{/if}
+		</div>
+	</div>
+</div>

frontend/src/lib/components/PanelTranscription.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+
+type Doc = {
+	summary?: string | null;
+	transcription?: string | null;
+};
+
+let { doc }: { doc: Doc } = $props();
+</script>
+
+<div class="flex justify-center px-6 py-8">
+	<div class="w-full max-w-prose space-y-8">
+		{#if !doc.summary && !doc.transcription}
+			<p class="font-serif text-sm text-ink-3 italic">—</p>
+		{/if}
+
+		{#if doc.summary}
+			<div>
+				<span class="mb-3 block font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+					{m.doc_label_summary()}
+				</span>
+				<p class="font-serif text-base leading-relaxed text-ink">{doc.summary}</p>
+			</div>
+		{/if}
+
+		{#if doc.transcription}
+			<div>
+				<span class="mb-3 block font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+					{m.form_label_transcription()}
+				</span>
+				<p class="font-serif text-base leading-relaxed whitespace-pre-wrap text-ink">
+					{doc.transcription}
+				</p>
+			</div>
+		{/if}
+	</div>
+</div>

frontend/src/lib/components/PdfViewer.svelte

@@ -3,24 +3,24 @@ import { onMount } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
 import type { PDFDocumentProxy, PDFPageProxy, RenderTask } from 'pdfjs-dist';
 import AnnotationLayer from './AnnotationLayer.svelte';
-import AnnotationCommentPanel from './AnnotationCommentPanel.svelte';
+import type { Annotation } from '$lib/types';
 import { m } from '$lib/paraglide/messages.js';
 
 let {
 	url,
 	documentId = '',
-	canAnnotate = false,
-	canComment,
-	currentUserId,
-	canAdmin,
+	annotateMode = $bindable(false),
+	activeAnnotationId = $bindable<string | null>(null),
+	activeAnnotationPage = $bindable<number | null>(null),
+	onAnnotationClick,
 	documentFileHash
 }: {
 	url: string;
 	documentId?: string;
-	canAnnotate?: boolean;
-	canComment?: boolean;
-	currentUserId?: string | null;
-	canAdmin?: boolean;
+	annotateMode?: boolean;
+	activeAnnotationId?: string | null;
+	activeAnnotationPage?: number | null;
+	onAnnotationClick?: (id: string) => void;
 	documentFileHash?: string | null;
 } = $props();
 
@@ -44,24 +44,10 @@ let textLayerInstance: { cancel: () => void } | null = null;
 let pdfjsLib: typeof import('pdfjs-dist') | null = null;
 let pdfjsReady = $state(false);
 
-type Annotation = {
-	id: string;
-	documentId: string;
-	pageNumber: number;
-	x: number;
-	y: number;
-	width: number;
-	height: number;
-	color: string;
-	createdAt: string;
-	fileHash?: string | null;
-};
-
 let annotations = $state<Annotation[]>([]);
-let annotateMode = $state(false);
 let annotateColor = $state('#ffff00');
 let commentCounts = new SvelteMap<string, number>();
-let activeAnnotationId = $state<string | null>(null);
+let showAnnotations = $state(true);
 
 const visibleAnnotations = $derived(
 	annotations.filter((a) => !a.fileHash || !documentFileHash || a.fileHash === documentFileHash)
@@ -227,6 +213,8 @@ async function handleAnnotationDraw(rect: { x: number; y: number; width: number;
 			const created: Annotation = await res.json();
 			annotations = [...annotations, created];
 			activeAnnotationId = created.id;
+			activeAnnotationPage = created.pageNumber;
+			onAnnotationClick?.(created.id);
 		}
 	} catch {
 		// ignore
@@ -247,6 +235,13 @@ async function handleAnnotationDelete(annotationId: string) {
 	}
 }
 
+function handleAnnotationClick(id: string) {
+	activeAnnotationId = id;
+	const ann = annotations.find((a) => a.id === id);
+	activeAnnotationPage = ann?.pageNumber ?? null;
+	onAnnotationClick?.(id);
+}
+
 $effect(() => {
 	if (pdfjsReady && url) {
 		loadDocument(url);
@@ -270,6 +265,10 @@ $effect(() => {
 	}
 });
 
+$effect(() => {
+	if (annotateMode) showAnnotations = true;
+});
+
 function prevPage() {
 	if (currentPage > 1) currentPage -= 1;
 }
@@ -288,25 +287,23 @@ function zoomOut() {
 </script>
 
 {#if !url}
-	<div class="flex h-full w-full items-center justify-center bg-[#2A2A2A] text-gray-400">
+	<div class="flex h-full w-full items-center justify-center bg-pdf-bg text-ink-3">
 		<p class="font-sans text-sm">Keine Datei vorhanden</p>
 	</div>
 {:else if error}
-	<div
-		class="flex h-full w-full flex-col items-center justify-center gap-3 bg-[#2A2A2A] text-gray-300"
-	>
+	<div class="flex h-full w-full flex-col items-center justify-center gap-3 bg-pdf-bg text-ink-3">
 		<p class="font-sans text-sm text-red-400">Fehler beim Laden der PDF</p>
 		<a
 			href={url}
 			target="_blank"
 			rel="noopener noreferrer"
-			class="font-sans text-xs text-brand-mint underline hover:opacity-80"
+			class="font-sans text-xs text-primary underline hover:text-ink-2"
 		>
 			Direkt öffnen
 		</a>
 	</div>
 {:else}
-	<div class="flex h-full w-full flex-col bg-[#2A2A2A]">
+	<div class="flex h-full w-full flex-col bg-pdf-bg">
 		{#if outdatedCount > 0}
 			<div
 				class="flex shrink-0 items-center gap-2 border-b border-amber-500/30 bg-amber-500/10 px-4 py-2"
@@ -330,7 +327,7 @@ function zoomOut() {
 		{/if}
 		<!-- Controls -->
 		<div
-			class="flex shrink-0 items-center justify-between gap-2 border-b border-white/10 px-4 py-2"
+			class="flex shrink-0 items-center justify-between gap-2 border-b border-pdf-ctrl px-4 py-2"
 		>
 			<!-- Page navigation -->
 			<div class="flex items-center gap-2">
@@ -338,7 +335,7 @@ function zoomOut() {
 					onclick={prevPage}
 					disabled={currentPage <= 1}
 					aria-label="Zurück"
-					class="rounded p-1 text-gray-300 transition hover:bg-white/10 disabled:opacity-40"
+					class="rounded p-1 text-ink-3 transition hover:bg-surface/10 disabled:opacity-40"
 				>
 					<svg
 						class="h-4 w-4"
@@ -352,7 +349,7 @@ function zoomOut() {
 				</button>
 
 				{#if totalPages > 0}
-					<span class="font-sans text-xs text-gray-300 tabular-nums">
+					<span class="font-sans text-xs text-ink-3 tabular-nums">
 						{currentPage} / {totalPages}
 					</span>
 				{/if}
@@ -361,7 +358,7 @@ function zoomOut() {
 					onclick={nextPage}
 					disabled={!pdfDoc || currentPage >= totalPages}
 					aria-label="Weiter"
-					class="rounded p-1 text-gray-300 transition hover:bg-white/10 disabled:opacity-40"
+					class="rounded p-1 text-ink-3 transition hover:bg-surface/10 disabled:opacity-40"
 				>
 					<svg
 						class="h-4 w-4"
@@ -380,7 +377,7 @@ function zoomOut() {
 				<button
 					onclick={zoomOut}
 					aria-label="Verkleinern"
-					class="rounded p-1 text-gray-300 transition hover:bg-white/10"
+					class="rounded p-1 text-ink-3 transition hover:bg-surface/10"
 				>
 					<svg
 						class="h-4 w-4"
@@ -398,7 +395,7 @@ function zoomOut() {
 				<button
 					onclick={zoomIn}
 					aria-label="Vergrößern"
-					class="rounded p-1 text-gray-300 transition hover:bg-white/10"
+					class="rounded p-1 text-ink-3 transition hover:bg-surface/10"
 				>
 					<svg
 						class="h-4 w-4"
@@ -415,34 +412,52 @@ function zoomOut() {
 				</button>
 			</div>
 
-			<!-- Annotate controls -->
-			{#if canAnnotate}
-				<div class="flex items-center gap-1">
-					<button
-						onclick={() => (annotateMode = !annotateMode)}
-						aria-label={annotateMode ? 'Annotieren beenden' : 'Annotieren'}
-						class="rounded px-2 py-1 font-sans text-xs text-gray-300 transition hover:bg-white/10 {annotateMode ? 'bg-white/20' : ''}"
-					>
-						{annotateMode ? 'Fertig' : 'Annotieren'}
-					</button>
-					{#if annotateMode}
-						<input
-							type="color"
-							bind:value={annotateColor}
-							aria-label="Farbe wählen"
-							class="h-6 w-6 cursor-pointer rounded border-0 bg-transparent p-0"
-							title="Farbe wählen"
-						/>
-					{/if}
-				</div>
-			{:else}
+			<!-- Color picker (shown in annotate mode) -->
+			{#if annotateMode}
+				<input
+					type="color"
+					bind:value={annotateColor}
+					aria-label="Farbe wählen"
+					class="h-6 w-6 cursor-pointer rounded border-0 bg-transparent p-0"
+					title="Farbe wählen"
+				/>
+			{/if}
+			<!-- Annotation visibility toggle (shown when annotations exist) -->
+			{#if annotations.length > 0}
 				<button
-					disabled
-					title="Sie benötigen die Berechtigung ANNOTATE_ALL zum Annotieren"
-					class="cursor-not-allowed rounded px-2 py-1 font-sans text-xs text-gray-500"
-					aria-label="Annotieren (keine Berechtigung)"
+					onclick={() => (showAnnotations = !showAnnotations)}
+					aria-label={showAnnotations ? m.pdf_annotations_hide() : m.pdf_annotations_show()}
+					class="flex items-center gap-1.5 rounded px-2 py-1 font-sans text-xs transition {showAnnotations
+						? 'text-ink-3 hover:bg-surface/10'
+						: 'bg-surface/10 text-accent'}"
 				>
-					Annotieren
+					<svg
+						class="h-3.5 w-3.5 shrink-0"
+						viewBox="0 0 24 24"
+						fill="none"
+						stroke="currentColor"
+						stroke-width="2"
+					>
+						{#if showAnnotations}
+							<path
+								stroke-linecap="round"
+								stroke-linejoin="round"
+								d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+							/>
+							<path
+								stroke-linecap="round"
+								stroke-linejoin="round"
+								d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z"
+							/>
+						{:else}
+							<path
+								stroke-linecap="round"
+								stroke-linejoin="round"
+								d="M13.875 18.825A10.05 10.05 0 0112 19c-4.478 0-8.268-2.943-9.543-7a9.97 9.97 0 011.563-3.029m5.858.908a3 3 0 114.243 4.243M9.878 9.878l4.242 4.242M9.88 9.88l-3.29-3.29m7.532 7.532l3.29 3.29M3 3l3.59 3.59m0 0A9.953 9.953 0 0112 5c4.478 0 8.268 2.943 9.543 7a10.025 10.025 0 01-4.132 5.411m0 0L21 21"
+							/>
+						{/if}
+					</svg>
+					{showAnnotations ? m.pdf_annotations_hide() : m.pdf_annotations_show()}
 				</button>
 			{/if}
 		</div>
@@ -468,34 +483,20 @@ function zoomOut() {
 							class="textLayer"
 							style="position: absolute; top: 0; left: 0; overflow: hidden; pointer-events: none; line-height: 1;"
 						></div>
-						<AnnotationLayer
-							annotations={visibleAnnotations.filter((a) => a.pageNumber === currentPage)}
-							canAnnotate={annotateMode}
-							color={annotateColor}
-							onDraw={handleAnnotationDraw}
-							onDelete={handleAnnotationDelete}
-							commentCounts={Object.fromEntries(commentCounts)}
-							onAnnotationClick={(id) => (activeAnnotationId = id)}
-						/>
+						{#if showAnnotations}
+							<AnnotationLayer
+								annotations={visibleAnnotations.filter((a) => a.pageNumber === currentPage)}
+								canAnnotate={annotateMode}
+								color={annotateColor}
+								onDraw={handleAnnotationDraw}
+								onDelete={handleAnnotationDelete}
+								commentCounts={Object.fromEntries(commentCounts)}
+								onAnnotationClick={handleAnnotationClick}
+							/>
+						{/if}
 					</div>
 				</div>
 			{/if}
 		</div>
-
-		{#key activeAnnotationId}
-			{#if activeAnnotationId}
-				<AnnotationCommentPanel
-					documentId={documentId}
-					annotationId={activeAnnotationId}
-					canComment={canComment ?? false}
-					currentUserId={currentUserId ?? null}
-					canAdmin={canAdmin ?? false}
-					onClose={() => (activeAnnotationId = null)}
-					onCountChange={(count) => {
-						if (activeAnnotationId) commentCounts.set(activeAnnotationId, count);
-					}}
-				/>
-			{/if}
-		{/key}
 	</div>
 {/if}

frontend/src/lib/components/PersonMultiSelect.svelte

@@ -80,18 +80,18 @@ function clickOutside(node: HTMLElement) {
 
 <div class="relative" use:clickOutside>
 	<div
-		class="flex min-h-[42px] flex-wrap gap-2 rounded border border-gray-300 bg-white p-2 focus-within:border-brand-navy focus-within:ring-1 focus-within:ring-brand-navy"
+		class="flex min-h-[42px] flex-wrap gap-2 rounded border border-line bg-surface p-2 focus-within:border-ink focus-within:ring-1 focus-within:ring-ink"
 	>
 		{#each selectedPersons as person (person.id)}
 			<span
-				class="inline-flex items-center gap-1 rounded bg-brand-sand/40 px-2 py-1 text-sm font-medium text-brand-navy"
+				class="inline-flex items-center gap-1 rounded bg-muted px-2 py-1 text-sm font-medium text-ink"
 			>
 				{person.firstName}
 				{person.lastName}
 				<button
 					type="button"
 					onclick={() => removePerson(person.id)}
-					class="ml-0.5 text-brand-navy/50 hover:text-red-500 focus:outline-none"
+					class="ml-0.5 text-ink/50 hover:text-red-500 focus:outline-none"
 					aria-label={m.comp_multiselect_remove()}
 				>
 					<svg class="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -121,14 +121,14 @@ function clickOutside(node: HTMLElement) {
 	{#if showDropdown && (results.length > 0 || loading)}
 		<div
 			style={dropdownStyle}
-			class="ring-opacity-5 z-50 max-h-60 overflow-auto rounded-md bg-white py-1 text-base shadow-lg ring-1 ring-black sm:text-sm"
+			class="ring-opacity-5 z-50 max-h-60 overflow-auto rounded-md bg-surface py-1 text-base shadow-lg ring-1 ring-black sm:text-sm"
 		>
 			{#if loading}
-				<div class="p-2 text-sm text-gray-500">{m.comp_multiselect_loading()}</div>
+				<div class="p-2 text-sm text-ink-2">{m.comp_multiselect_loading()}</div>
 			{:else}
 				{#each results as person (person.id)}
 					<div
-						class="cursor-pointer py-2 pr-9 pl-3 text-gray-900 select-none hover:bg-brand-sand/30"
+						class="cursor-pointer py-2 pr-9 pl-3 text-ink select-none hover:bg-muted"
 						onclick={() => selectPerson(person)}
 						onkeydown={(e) => e.key === 'Enter' && selectPerson(person)}
 						role="button"

frontend/src/lib/components/PersonTypeahead.svelte

@@ -9,6 +9,7 @@ interface Props {
 	label: string;
 	value?: string;
 	initialName?: string;
+	suggestedName?: string;
 	restrictToCorrespondentsOf?: string;
 	onchange?: (value: string) => void;
 }
@@ -18,12 +19,20 @@ let {
 	label,
 	value = $bindable(''),
 	initialName = '',
+	suggestedName = '',
 	restrictToCorrespondentsOf,
 	onchange
 }: Props = $props();
 
 let searchTerm = $state(initialName);
 
+$effect(() => {
+	const suggested = suggestedName;
+	if (suggested && !untrack(() => value)) {
+		searchTerm = suggested;
+	}
+});
+
 let results: Person[] = $state([]);
 let showDropdown = $state(false);
 let loading = $state(false);
@@ -111,7 +120,7 @@ function clickOutside(node: HTMLElement) {
 </script>
 
 <div class="relative" use:clickOutside>
-	<label for={name} class="block text-sm font-medium text-gray-700">{label}</label>
+	<label for={name} class="block text-sm font-medium text-ink-2">{label}</label>
 
 	<input type="hidden" name={name} bind:value={value} />
 
@@ -123,19 +132,19 @@ function clickOutside(node: HTMLElement) {
 		oninput={handleInput}
 		onfocus={handleFocus}
 		placeholder={m.comp_typeahead_placeholder()}
-		class="mt-1 block w-full rounded-md border border-gray-300 p-2 shadow-sm focus:border-blue-500 focus:ring-blue-500"
+		class="mt-1 block w-full rounded-md border border-line p-2 shadow-sm focus:border-accent focus:ring-accent"
 	/>
 
 	{#if showDropdown && (results.length > 0 || loading)}
 		<div
-			class="ring-opacity-5 absolute top-full left-0 z-50 mt-1 max-h-60 w-full overflow-auto rounded-md bg-white py-1 text-base shadow-lg ring-1 ring-black focus:outline-none sm:text-sm"
+			class="ring-opacity-5 absolute top-full left-0 z-50 mt-1 max-h-60 w-full overflow-auto rounded-md bg-surface py-1 text-base shadow-lg ring-1 ring-black focus:outline-none sm:text-sm"
 		>
 			{#if loading}
-				<div class="p-2 text-sm text-gray-500">{m.comp_typeahead_loading()}</div>
+				<div class="p-2 text-sm text-ink-2">{m.comp_typeahead_loading()}</div>
 			{:else}
 				{#each results as person (person.id)}
 					<div
-						class="relative cursor-pointer py-2 pr-9 pl-3 text-gray-900 select-none hover:bg-blue-100"
+						class="relative cursor-pointer py-2 pr-9 pl-3 text-ink select-none hover:bg-accent-bg"
 						onclick={() => selectPerson(person)}
 						onkeydown={(e) => e.key === 'Enter' && selectPerson(person)}
 						role="button"