From 83c3d85b0086dbd418bac618a63af6fe29aec954 Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 11:03:23 +0200 Subject: [PATCH] docs(c4): fix service layer relationships in diagrams 3b and 3b.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Diagram 3b: DocumentService calls PersonService and TagService, not their repositories directly. Replace personRepo/tagRepo cross-ref stubs with personSvc/tagSvc to accurately reflect the layering rule. Diagram 3b.2: TranscriptionService, AnnotationService, and CommentService each use a JPA repository, not JDBC directly. Add TranscriptionBlockRepository, AnnotationRepository, and CommentRepository components and route the service→repo→db chain. TranscriptionQueueService delegates to DocumentService and AuditLogQueryService (no repo of its own); replace the incorrect →db arrow with cross-diagram stubs. Co-Authored-By: Claude Sonnet 4.6 --- docs/architecture/c4-diagrams.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/architecture/c4-diagrams.md b/docs/architecture/c4-diagrams.md index 995994c8..1980b6e6 100644 --- a/docs/architecture/c4-diagrams.md +++ b/docs/architecture/c4-diagrams.md @@ -111,8 +111,8 @@ C4Component 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.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.") + Component(personSvc, "PersonService", "Spring Service", "See diagram 3c.2. Called by DocumentService to resolve sender / receiver persons by ID.") + Component(tagSvc, "TagService", "Spring Service", "See diagram 3c. Called by DocumentService to find or create tags by name.") Rel(frontend, docCtrl, "Document requests", "HTTP / JSON") Rel(frontend, adminCtrl, "Trigger import", "HTTP / JSON") @@ -121,15 +121,13 @@ C4Component Rel(docSvc, fileSvc, "Upload / download files", "") Rel(docSvc, docRepo, "Reads / writes documents", "") Rel(docSvc, docSpec, "Builds search predicates", "") - Rel(docSvc, personRepo, "Resolves sender / receivers", "") - Rel(docSvc, tagRepo, "Finds or creates tags", "") + Rel(docSvc, personSvc, "Resolves sender / receivers", "") + Rel(docSvc, tagSvc, "Finds or creates tags", "") Rel(massImport, excelSvc, "Parses Excel/ODS file", "") Rel(excelSvc, docSvc, "Creates / updates documents", "") 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") ``` ### 3b.2 — Document Transcription Pipeline @@ -149,11 +147,18 @@ C4Component Component(commentCtrl, "CommentController", "Spring MVC — /api/documents/{id}/comments", "Threaded comment CRUD on transcription blocks with @mention support and notification triggers.") Component(transcriptionSvc, "TranscriptionService", "Spring Service", "Creates and updates transcription blocks from annotation regions. Tracks block versions, sanitizes text with an HTML allow-list, and triggers mentions.") - Component(transcriptionQueueSvc, "TranscriptionQueueService", "Spring Service", "Exposes segmentation, transcription, and review queue projections for the mission-control enrichment workflow.") + Component(transcriptionQueueSvc, "TranscriptionQueueService", "Spring Service", "Assembles segmentation, transcription, and review queue projections by delegating to DocumentService and AuditLogQueryService.") Component(annotationSvc, "AnnotationService", "Spring Service", "Manages document page annotations with polygon coordinates. Called by OcrAsyncRunner to persist OCR-generated block boundaries.") Component(commentSvc, "CommentService", "Spring Service", "Creates and manages threaded comments with @mention parsing. Triggers NotificationService for REPLY and MENTION events.") + + Component(blockRepo, "TranscriptionBlockRepository", "Spring Data JPA", "Reads and writes TranscriptionBlock and TranscriptionBlockVersion records.") + Component(annotationRepo, "AnnotationRepository", "Spring Data JPA", "Reads and writes DocumentAnnotation records.") + Component(commentRepo, "CommentRepository", "Spring Data JPA", "Reads and writes DocumentComment records.") } + Component(documentSvc, "DocumentService", "Spring Service", "See diagram 3b. Called by TranscriptionQueueService to assemble pipeline queue projections.") + Component(auditQuerySvc, "AuditLogQueryService", "Spring Service", "See diagram 3e. Called by TranscriptionQueueService for pipeline activity data.") + Rel(frontend, transcriptionCtrl, "Transcription block requests", "HTTP / JSON") Rel(frontend, annotationCtrl, "Annotation requests", "HTTP / JSON") Rel(frontend, commentCtrl, "Comment requests", "HTTP / JSON") @@ -161,10 +166,14 @@ C4Component Rel(transcriptionCtrl, transcriptionQueueSvc, "Queries pipeline queues", "") Rel(annotationCtrl, annotationSvc, "Delegates to", "") Rel(commentCtrl, commentSvc, "Delegates to", "") - Rel(transcriptionSvc, db, "Reads / writes blocks and versions", "JDBC") - Rel(annotationSvc, db, "Reads / writes annotations", "JDBC") - Rel(commentSvc, db, "Reads / writes comments", "JDBC") - Rel(transcriptionQueueSvc, db, "Queue projection queries", "JDBC") + Rel(transcriptionSvc, blockRepo, "Reads / writes blocks and versions", "") + Rel(annotationSvc, annotationRepo, "Reads / writes annotations", "") + Rel(commentSvc, commentRepo, "Reads / writes comments", "") + Rel(transcriptionQueueSvc, documentSvc, "Queries pipeline document state", "") + Rel(transcriptionQueueSvc, auditQuerySvc, "Queries pipeline activity data", "") + Rel(blockRepo, db, "SQL queries", "JDBC") + Rel(annotationRepo, db, "SQL queries", "JDBC") + Rel(commentRepo, db, "SQL queries", "JDBC") ``` ### 3c — Users, Groups & Administration