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

docs(c4): add L3 backend 3c transcription and 3d users/groups

Browse Source
This commit is contained in:
Marcel
2026-05-06 21:28:02 +02:00
parent f2bb0ca442
commit 63d8065cd8
2 changed files with 82 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/architecture/c4/l3-backend-3c-transcription.puml Normal file
View File

@@ -0,0 +1,41 @@
@startuml
!include <C4/C4_Component>
title Component Diagram: API Backend — Document Transcription Pipeline
Container(frontend, "Web Frontend", "SvelteKit")
ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
System_Boundary(backend, "API Backend (Spring Boot)") {
Component(transcriptionCtrl, "TranscriptionBlockController", "Spring MVC — /api/transcription", "CRUD for transcription text blocks per document page. Manages sort order, review status, and block version history.")
Component(annotationCtrl, "AnnotationController", "Spring MVC — /api/documents/{id}/annotations", "CRUD for free-form page annotations with polygon coordinates, colour coding, and file-hash tracking.")
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", "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 3g. 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")
Rel(transcriptionCtrl, transcriptionSvc, "Delegates to")
Rel(transcriptionCtrl, transcriptionQueueSvc, "Queries pipeline queues")
Rel(annotationCtrl, annotationSvc, "Delegates to")
Rel(commentCtrl, commentSvc, "Delegates to")
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")
@enduml

41
docs/architecture/c4/l3-backend-3d-users-groups.puml Normal file
View File

@@ -0,0 +1,41 @@
@startuml
!include <C4/C4_Component>
title Component Diagram: API Backend — Users, Groups & Administration
Container(frontend, "Web Frontend", "SvelteKit")
ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
System_Boundary(backend, "API Backend (Spring Boot)") {
Component(userCtrl, "UserController", "Spring MVC — /api/users", "Returns current user (/me), creates and deletes users (requires ADMIN_USER), supports user search and profile updates.")
Component(groupCtrl, "GroupController", "Spring MVC — /api/groups", "Lists and manages permission groups.")
Component(tagCtrl, "TagController", "Spring MVC — /api/tags", "Lists tags for typeahead, supports tag merge, tree structure, and subtree deletion.")
Component(inviteCtrl, "InviteController", "Spring MVC — /api/auth/invite", "Creates invite codes and validates them at registration time. Rate-limited via WebConfig interceptor.")
Component(authCtrl, "AuthController", "Spring MVC — /api/auth", "Handles user registration (POST /register) and password reset token endpoints (/forgot-password, /reset-password).")
Component(userSvc, "UserService", "Spring Service", "User CRUD with BCrypt password encoding, group assignment, and audit logging. Orchestrates invite-based registration and password reset tokens.")
Component(tagSvc, "TagService", "Spring Service", "Tag CRUD with name search, hierarchical tree structure, merge/reparent operations, and recursive subtree deletion.")
Component(dataInit, "DataInitializer", "CommandLineRunner", "On startup: creates default admin user and groups if none exist. Seeds test data if DB is empty.")
Component(userRepo, "AppUserRepository", "Spring Data JPA", "Finds users by email. Supports search by email or display name.")
Component(groupRepo, "UserGroupRepository", "Spring Data JPA", "Manages permission groups.")
Component(tagRepo, "TagRepository", "Spring Data JPA", "Finds or creates tags by name (case-insensitive). Supports recursive ancestor/descendant CTE queries and merge/reparent helpers.")
}
Rel(frontend, userCtrl, "User requests", "HTTP / JSON")
Rel(frontend, groupCtrl, "Group requests", "HTTP / JSON")
Rel(frontend, tagCtrl, "Tag requests", "HTTP / JSON")
Rel(frontend, inviteCtrl, "Invite validation", "HTTP / JSON")
Rel(frontend, authCtrl, "Registration and password reset", "HTTP / JSON")
Rel(userCtrl, userSvc, "Delegates to")
Rel(groupCtrl, userSvc, "Delegates to")
Rel(tagCtrl, tagSvc, "Delegates to")
Rel(tagSvc, tagRepo, "Reads / writes tags")
Rel(inviteCtrl, userSvc, "Creates and validates invites")
Rel(authCtrl, userSvc, "Registers users, resets passwords")
Rel(userSvc, userRepo, "Reads / writes users")
Rel(userSvc, groupRepo, "Assigns groups")
Rel(dataInit, db, "Seeds initial data", "JDBC")
Rel(userRepo, db, "SQL queries", "JDBC")
Rel(groupRepo, db, "SQL queries", "JDBC")
Rel(tagRepo, db, "SQL queries", "JDBC")
@enduml