docs(c4): fix service layer relationships in diagrams 3b and 3b.2
Some checks failed
CI / Unit & Component Tests (push) Failing after 3m33s
CI / OCR Service Tests (push) Successful in 35s
CI / Backend Unit Tests (push) Failing after 3m22s
CI / Unit & Component Tests (pull_request) Failing after 3m28s
CI / OCR Service Tests (pull_request) Successful in 31s
CI / Backend Unit Tests (pull_request) Failing after 3m16s

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 <noreply@anthropic.com>
This commit is contained in:
Marcel
2026-05-06 11:03:23 +02:00
parent 18a7ee1fa5
commit 83c3d85b00

View File

@@ -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(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(personSvc, "PersonService", "Spring Service", "See diagram 3c.2. Called by DocumentService to resolve sender / receiver persons by ID.")
Component(tagRepo, "TagRepository", "Spring Data JPA", "See diagram 3c. Used here by DocumentService to find or create tags.") 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, docCtrl, "Document requests", "HTTP / JSON")
Rel(frontend, adminCtrl, "Trigger import", "HTTP / JSON") Rel(frontend, adminCtrl, "Trigger import", "HTTP / JSON")
@@ -121,15 +121,13 @@ C4Component
Rel(docSvc, fileSvc, "Upload / download files", "") Rel(docSvc, fileSvc, "Upload / download files", "")
Rel(docSvc, docRepo, "Reads / writes documents", "") Rel(docSvc, docRepo, "Reads / writes documents", "")
Rel(docSvc, docSpec, "Builds search predicates", "") Rel(docSvc, docSpec, "Builds search predicates", "")
Rel(docSvc, personRepo, "Resolves sender / receivers", "") Rel(docSvc, personSvc, "Resolves sender / receivers", "")
Rel(docSvc, tagRepo, "Finds or creates tags", "") Rel(docSvc, tagSvc, "Finds or creates tags", "")
Rel(massImport, excelSvc, "Parses Excel/ODS file", "") Rel(massImport, excelSvc, "Parses Excel/ODS file", "")
Rel(excelSvc, docSvc, "Creates / updates documents", "") Rel(excelSvc, docSvc, "Creates / updates documents", "")
Rel(minioConf, fileSvc, "Provides S3Client and S3Presigner beans", "") Rel(minioConf, fileSvc, "Provides S3Client and S3Presigner beans", "")
Rel(fileSvc, minio, "PUT / GET / presigned URL objects", "S3 API / HTTP") Rel(fileSvc, minio, "PUT / GET / presigned URL objects", "S3 API / HTTP")
Rel(docRepo, db, "SQL queries", "JDBC") Rel(docRepo, db, "SQL queries", "JDBC")
Rel(personRepo, db, "SQL queries", "JDBC")
Rel(tagRepo, db, "SQL queries", "JDBC")
``` ```
### 3b.2 — Document Transcription Pipeline ### 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(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(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(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(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, transcriptionCtrl, "Transcription block requests", "HTTP / JSON")
Rel(frontend, annotationCtrl, "Annotation requests", "HTTP / JSON") Rel(frontend, annotationCtrl, "Annotation requests", "HTTP / JSON")
Rel(frontend, commentCtrl, "Comment requests", "HTTP / JSON") Rel(frontend, commentCtrl, "Comment requests", "HTTP / JSON")
@@ -161,10 +166,14 @@ C4Component
Rel(transcriptionCtrl, transcriptionQueueSvc, "Queries pipeline queues", "") Rel(transcriptionCtrl, transcriptionQueueSvc, "Queries pipeline queues", "")
Rel(annotationCtrl, annotationSvc, "Delegates to", "") Rel(annotationCtrl, annotationSvc, "Delegates to", "")
Rel(commentCtrl, commentSvc, "Delegates to", "") Rel(commentCtrl, commentSvc, "Delegates to", "")
Rel(transcriptionSvc, db, "Reads / writes blocks and versions", "JDBC") Rel(transcriptionSvc, blockRepo, "Reads / writes blocks and versions", "")
Rel(annotationSvc, db, "Reads / writes annotations", "JDBC") Rel(annotationSvc, annotationRepo, "Reads / writes annotations", "")
Rel(commentSvc, db, "Reads / writes comments", "JDBC") Rel(commentSvc, commentRepo, "Reads / writes comments", "")
Rel(transcriptionQueueSvc, db, "Queue projection queries", "JDBC") 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 ### 3c — Users, Groups & Administration