From 63d8065cd889881177e2c75fe80cbaef37d4fc64 Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 21:28:02 +0200 Subject: [PATCH] docs(c4): add L3 backend 3c transcription and 3d users/groups --- .../c4/l3-backend-3c-transcription.puml | 41 +++++++++++++++++++ .../c4/l3-backend-3d-users-groups.puml | 41 +++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/architecture/c4/l3-backend-3c-transcription.puml create mode 100644 docs/architecture/c4/l3-backend-3d-users-groups.puml diff --git a/docs/architecture/c4/l3-backend-3c-transcription.puml b/docs/architecture/c4/l3-backend-3c-transcription.puml new file mode 100644 index 00000000..cee54e97 --- /dev/null +++ b/docs/architecture/c4/l3-backend-3c-transcription.puml @@ -0,0 +1,41 @@ +@startuml +!include + +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 diff --git a/docs/architecture/c4/l3-backend-3d-users-groups.puml b/docs/architecture/c4/l3-backend-3d-users-groups.puml new file mode 100644 index 00000000..d90711c8 --- /dev/null +++ b/docs/architecture/c4/l3-backend-3d-users-groups.puml @@ -0,0 +1,41 @@ +@startuml +!include + +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