From 04b2b33d7fa78df8b10b5ee90b4843677ad59d73 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Wed, 6 May 2026 09:56:19 +0200
Subject: [PATCH] =?UTF-8?q?docs(c4):=20add=203b.2=20transcription=20pipeli?=
 =?UTF-8?q?ne=20=E2=80=94=20annotations,=20blocks,=20comments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/architecture/c4-diagrams.md | 35 ++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/architecture/c4-diagrams.md b/docs/architecture/c4-diagrams.md
index 4e32ffaf..cfe88f68 100644
--- a/docs/architecture/c4-diagrams.md
+++ b/docs/architecture/c4-diagrams.md
@@ -132,6 +132,41 @@ C4Component
     Rel(tagRepo, db, "SQL queries", "JDBC")
 ```
 
+### 3b.2 — Document Transcription Pipeline
+
+Annotation-driven transcription: page markup, text blocks, versioning, and comment threads.
+
+```mermaid
+C4Component
+    title Component Diagram: API Backend — Document Transcription Pipeline
+
+    Container(frontend, "Web Frontend", "SvelteKit")
+    ContainerDb(db, "PostgreSQL")
+
+    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", "Exposes segmentation, transcription, and review queue projections for the mission-control enrichment workflow.")
+        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.")
+    }
+
+    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, 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")
+```
+
 ### 3c — People, Users & Group Administration
 
 Person, user, and group management, including startup seed data.