marcel/familienarchiv
1
0
Fork 0
Code Issues 119 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs(c4): fix service layer relationships in diagrams 3b and 3b.2

Browse Source 
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
committed by marcel
parent 9986af7c3d
commit 0582edd840
1 changed files with 20 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/architecture/c4-diagrams.md
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(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