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

docs(c4): accuracy audit — split L3 diagrams, add 6 new sub-diagrams, fix all stale content #448

Merged
marcel merged 27 commits from docs/post-refactor-accuracy-audit into main 2026-05-06 20:00:16 +02:00
Conversation 47 Commits 27 Files Changed 1 +20 -11
1 changed files with 20 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 83c3d85b00 - Show all commits

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