From b60ad668160360571f5a7b00121091094505e390 Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 19:58:26 +0200 Subject: [PATCH] fix(c4): flatten decimal sub-diagram numbering; note invite gate at L1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename 3b.2→3c, 3c→3d, 3c.2→3e, 3d→3f, 3e→3g to eliminate decimal notation that read as version numbers rather than sub-levels - Update all seven "See diagram X" cross-references to match - Correct backend intro: "three focused views" → "seven focused sub-diagrams" - Add "Access by administrator invite." to L1 Family Member description to surface the invite-only registration constraint at the context level Co-Authored-By: Claude Sonnet 4.6 --- docs/architecture/c4-diagrams.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/architecture/c4-diagrams.md b/docs/architecture/c4-diagrams.md index 67e8c53c..9585f735 100644 --- a/docs/architecture/c4-diagrams.md +++ b/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")