docs(c4): update 3b document domain — descriptions, batch ops, FTS, presigned URLs

docs/architecture/c4-diagrams.md

@@ -85,33 +85,33 @@ C4Component
     Rel(userDetails, db, "Loads user by email", "JDBC")
 ```
 
-### 3b — Document, File & Import Domain
+### 3b — Document Management & Import
 
-Document management, file storage, and bulk Excel import.
+Document management, file storage, and bulk Excel/ODS import.
 
 ```mermaid
 C4Component
-    title Component Diagram: API Backend — Document, File & Import Domain
+    title Component Diagram: API Backend — Document Management & Import
 
     Container(frontend, "Web Frontend", "SvelteKit")
     ContainerDb(db, "PostgreSQL")
     ContainerDb(minio, "MinIO")
 
     System_Boundary(backend, "API Backend (Spring Boot)") {
-        Component(docCtrl, "DocumentController", "Spring MVC — /api/documents", "CRUD for documents. Endpoints: search, get by ID, update metadata, upload file, download file, get conversation thread.")
+        Component(docCtrl, "DocumentController", "Spring MVC — /api/documents", "CRUD for documents: search, get by ID, update metadata, upload/download file, conversation thread, and batch metadata updates.")
-        Component(adminCtrl, "AdminController", "Spring MVC — /api/admin", "Triggers asynchronous Excel mass import (requires ADMIN permission).")
+        Component(adminCtrl, "AdminController", "Spring MVC — /api/admin", "Triggers asynchronous Excel/ODS mass import (requires ADMIN permission). Reports import state (IDLE/RUNNING/DONE/FAILED).")
 
-        Component(docSvc, "DocumentService", "Spring Service", "Core business logic: store, update, search documents. Resolves persons and tags. Delegates file I/O to FileService. Builds JPA Specifications for dynamic search queries.")
+        Component(docSvc, "DocumentService", "Spring Service", "Core document business logic: store, update, search. Resolves persons and tags, delegates file I/O to FileService, builds dynamic JPA Specifications, and integrates with audit logging.")
-        Component(fileSvc, "FileService", "Spring Service", "Wraps AWS SDK v2 S3Client. Uploads files with UUID-keyed paths. Downloads with content-type detection (PDF, JPEG, PNG, octet-stream).")
+        Component(fileSvc, "FileService", "Spring Service", "Wraps AWS SDK v2 S3Client. Uploads files with UUID-keyed paths, computes SHA-256 hash, downloads with content-type detection, and generates presigned URLs for OCR access.")
-        Component(massImport, "MassImportService", "Spring Service — @Async", "Reads Excel files from /import mount. Delegates to ExcelService. Runs asynchronously so the HTTP response returns immediately.")
+        Component(massImport, "MassImportService", "Spring Service — @Async", "Reads Excel/ODS files from /import mount. Tracks import state (IDLE/RUNNING/DONE/FAILED) and delegates to ExcelService. Returns immediately; processing runs asynchronously.")
-        Component(excelSvc, "ExcelService", "Spring Service", "Parses Excel workbooks (Apache POI). Column indices are configurable via application.properties. Creates/updates document records per row.")
+        Component(excelSvc, "ExcelService", "Spring Service", "Parses Excel/ODS workbooks (Apache POI). Column indices configurable via application.properties. Creates/updates document records per row.")
-        Component(minioConf, "MinioConfig", "Spring @Configuration", "Creates the S3Client bean with path-style access for MinIO. Validates MinIO connectivity on startup.")
+        Component(minioConf, "MinioConfig", "Spring @Configuration", "Creates the S3Client and S3Presigner beans with path-style access for MinIO. Validates MinIO connectivity on startup.")
 
-        Component(docRepo, "DocumentRepository", "Spring Data JPA", "Queries documents. Supports Specification-based dynamic search, conversation thread queries (bidirectional sender/receiver), and filename lookups.")
+        Component(docRepo, "DocumentRepository", "Spring Data JPA", "Queries documents with Specification-based dynamic search, bidirectional conversation thread queries, full-text search with ranking and match highlighting, and transcription pipeline queue projections.")
-        Component(docSpec, "DocumentSpecifications", "JPA Criteria API", "Factory for composable query predicates: hasText (full-text across title/filename/transcription/location), hasSender, hasReceiver (join), isBetween (date range), hasTags (subquery AND logic).")
+        Component(docSpec, "DocumentSpecifications", "JPA Criteria API", "Factory for composable predicates: hasText (full-text), hasSender, hasReceiver, isBetween (date range), hasTags (subquery AND/OR logic).")
     }
 
-    Component(personRepo, "PersonRepository", "Spring Data JPA", "See diagram 3c. Used here by DocumentService to resolve sender / receiver persons.")
+    Component(personRepo, "PersonRepository", "Spring Data JPA", "See diagram 3c.2. Used here by DocumentService to resolve sender / receiver persons.")
     Component(tagRepo, "TagRepository", "Spring Data JPA", "See diagram 3c. Used here by DocumentService to find or create tags.")
 
     Rel(frontend, docCtrl, "Document requests", "HTTP / JSON")
@@ -123,10 +123,10 @@ C4Component
     Rel(docSvc, docSpec, "Builds search predicates", "")
     Rel(docSvc, personRepo, "Resolves sender / receivers", "")
     Rel(docSvc, tagRepo, "Finds or creates tags", "")
-    Rel(massImport, excelSvc, "Parses Excel file", "")
+    Rel(massImport, excelSvc, "Parses Excel/ODS file", "")
     Rel(excelSvc, docSvc, "Creates / updates documents", "")
-    Rel(minioConf, fileSvc, "Provides S3Client bean", "")
+    Rel(minioConf, fileSvc, "Provides S3Client and S3Presigner beans", "")
-    Rel(fileSvc, minio, "PUT / GET objects", "S3 API / HTTP")
+    Rel(fileSvc, minio, "PUT / GET / presigned URL objects", "S3 API / HTTP")
     Rel(docRepo, db, "SQL queries", "JDBC")
     Rel(personRepo, db, "SQL queries", "JDBC")
     Rel(tagRepo, db, "SQL queries", "JDBC")