docs/architecture/c4-diagrams.md

@@ -13,7 +13,7 @@ C4Context
     title System Context: Familienarchiv
 
     Person(admin, "Administrator", "Manages users, triggers bulk imports, reviews and transcribes documents")
-    Person(member, "Family Member", "Searches, browses, reads, and transcribes archived documents")
+    Person(member, "Family Member", "Access by administrator invite. Searches, browses, reads, and transcribes archived documents.")
 
     System(familienarchiv, "Familienarchiv", "Web application for digitising, organising, and searching family documents")
     System_Ext(mail, "Email Service", "SMTP server. Delivers notification emails (mentions, replies) and password-reset links.")
@@ -65,7 +65,7 @@ C4Container
 
 ## Level 3 — Components: API Backend
 
-The internal structure of the Spring Boot backend, split into three focused views.
+The internal structure of the Spring Boot backend, split into seven focused sub-diagrams.
 
 ### 3a — Security & Authentication
 
@@ -117,8 +117,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(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.")
+    Component(personSvc, "PersonService", "Spring Service", "See diagram 3e. Called by DocumentService to resolve sender / receiver persons by ID.")
+    Component(tagSvc, "TagService", "Spring Service", "See diagram 3d. Called by DocumentService to find or create tags by name.")
 
     Rel(frontend, docCtrl, "Document requests", "HTTP / JSON")
     Rel(frontend, adminCtrl, "Trigger import", "HTTP / JSON")
@@ -136,7 +136,7 @@ C4Component
     Rel(docRepo, db, "SQL queries", "JDBC")
 ```
 
-### 3b.2 — Document Transcription Pipeline
+### 3c — Document Transcription Pipeline
 
 Annotation-driven transcription: page markup, text blocks, versioning, and comment threads.
 
@@ -163,7 +163,7 @@ C4Component
     }
 
     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.")
+    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")
@@ -182,7 +182,7 @@ C4Component
     Rel(commentRepo, db, "SQL queries", "JDBC")
 ```
 
-### 3c — Users, Groups & Administration
+### 3d — Users, Groups & Administration
 
 User lifecycle, permission groups, tag management, and authentication endpoints.
 
@@ -228,7 +228,7 @@ C4Component
     Rel(tagRepo, db, "SQL queries", "JDBC")
 ```
 
-### 3c.2 — Persons & Family Graph
+### 3e — Persons & Family Graph
 
 Person management including family relationship modelling and transitive inference.
 
@@ -263,7 +263,7 @@ C4Component
     Rel(relRepo, db, "SQL queries", "JDBC")
 ```
 
-### 3d — OCR Orchestration
+### 3f — OCR Orchestration
 
 How the Spring Boot backend manages OCR jobs, streams results, and trains recognition models.
 
@@ -286,8 +286,8 @@ C4Component
         Component(ocrJobRepo, "OcrJobRepository, OcrJobDocumentRepository", "Spring Data JPA", "Reads and writes OcrJob and OcrJobDocument records. Tracks job status (RUNNING/DONE/FAILED), per-document progress, page counts, and error messages.")
     }
 
-    Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3b.2. Called by OcrAsyncRunner to persist transcription blocks per page.")
-    Component(annotationSvc, "AnnotationService", "Spring Service", "See diagram 3b.2. Called by OcrAsyncRunner to persist OCR-generated annotation regions per page.")
+    Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3c. Called by OcrAsyncRunner to persist transcription blocks per page.")
+    Component(annotationSvc, "AnnotationService", "Spring Service", "See diagram 3c. Called by OcrAsyncRunner to persist OCR-generated annotation regions per page.")
 
     Rel(frontend, ocrCtrl, "OCR trigger, status, and progress requests", "HTTP / JSON / SSE")
     Rel(ocrCtrl, ocrSvc, "Single-document jobs", "")
@@ -307,7 +307,7 @@ C4Component
     Rel(ocrTraining, db, "Persists training run metrics", "JDBC")
 ```
 
-### 3e — Supporting Domains
+### 3g — Supporting Domains
 
 Audit logging, dashboard stats, SSE notifications, stories (Geschichten), and cross-cutting exception handling.
 
@@ -338,7 +338,7 @@ C4Component
     }
 
     Component(documentSvc, "DocumentService", "Spring Service", "See diagram 3b. Called by DashboardService to fetch document titles and resume data.")
-    Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3b.2. Called by DashboardService to fetch transcription block progress for resume.")
+    Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3c. Called by DashboardService to fetch transcription block progress for resume.")
 
     Rel(frontend, dashCtrl, "Dashboard requests", "HTTP / JSON")
     Rel(frontend, statsCtrl, "GET /api/stats", "HTTP / JSON")