From 1e3423934c1d41c3fec01940822b913967c7fbd1 Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 09:55:28 +0200 Subject: [PATCH] =?UTF-8?q?docs(c4):=20update=203b=20document=20domain=20?= =?UTF-8?q?=E2=80=94=20descriptions,=20batch=20ops,=20FTS,=20presigned=20U?= =?UTF-8?q?RLs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture/c4-diagrams.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/architecture/c4-diagrams.md b/docs/architecture/c4-diagrams.md index ef158937..4e32ffaf 100644 --- a/docs/architecture/c4-diagrams.md +++ b/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(adminCtrl, "AdminController", "Spring MVC — /api/admin", "Triggers asynchronous Excel mass import (requires ADMIN permission).") + 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/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(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(massImport, "MassImportService", "Spring Service — @Async", "Reads Excel files from /import mount. Delegates to ExcelService. Runs asynchronously so the HTTP response returns immediately.") - Component(excelSvc, "ExcelService", "Spring Service", "Parses Excel workbooks (Apache POI). Column indices are 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(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, computes SHA-256 hash, downloads with content-type detection, and generates presigned URLs for OCR access.") + 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/ODS workbooks (Apache POI). Column indices configurable via application.properties. Creates/updates document records per row.") + 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(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(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 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(fileSvc, minio, "PUT / GET objects", "S3 API / HTTP") + Rel(minioConf, fileSvc, "Provides S3Client and S3Presigner beans", "") + 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")