docs(c4): accuracy audit — split L3 diagrams, add 6 new sub-diagrams, fix all stale content #448

Merged
marcel merged 27 commits from docs/post-refactor-accuracy-audit into main 2026-05-06 20:00:16 +02:00

27 Commits

Author SHA1 Message Date
Marcel
b60ad66816 fix(c4): flatten decimal sub-diagram numbering; note invite gate at L1
Some checks failed
CI / Unit & Component Tests (push) Failing after 3m42s
CI / OCR Service Tests (push) Successful in 40s
CI / Backend Unit Tests (push) Failing after 3m33s
CI / Unit & Component Tests (pull_request) Failing after 3m38s
CI / OCR Service Tests (pull_request) Successful in 1m8s
CI / Backend Unit Tests (pull_request) Failing after 3m32s
- 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 <noreply@anthropic.com>
2026-05-06 19:58:26 +02:00
Marcel
7ac39541ef docs(c4): add cross-diagram stub convention note to header
Some checks failed
CI / Unit & Component Tests (push) Failing after 3m32s
CI / OCR Service Tests (push) Successful in 40s
CI / Backend Unit Tests (push) Failing after 3m29s
CI / Unit & Component Tests (pull_request) Failing after 3m35s
CI / OCR Service Tests (pull_request) Successful in 43s
CI / Backend Unit Tests (pull_request) Failing after 3m21s
The C4 standard doesn't define this pattern. Adding a one-sentence
explanation so readers unfamiliar with the project's rendering convention
understand what stub components outside System_Boundary blocks mean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:54:43 +02:00
Marcel
9878810a2a fix(c4): stammbaum — remove D3 library detail from component description
C4 L3 describes responsibility, not library choice. Removing the D3
reference keeps the description implementation-agnostic.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:54:07 +02:00
Marcel
caf86b3225 fix(c4): sequence diagram — username → email in auth flow
Three stale references: "Enter username + password", Base64 encode
"user:password", and SELECT WHERE username — all updated to email to
match AppUserRepository.findByEmail() and CustomUserDetailsService.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:53:32 +02:00
Marcel
af24d63176 fix(c4): loginPage — username → email in component description
CustomUserDetailsService loads by email, not username. The component
description had a stale "encodes username:password" label.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:52:55 +02:00
Marcel
318d83d2fd fix(c4): correct docBulkEdit endpoint /batch → /bulk
DocumentController has @PatchMapping("/bulk"); the component description
had the wrong path. The Rel in the same diagram was already correct.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:52:09 +02:00
Marcel
818246a26d docs(c4): add Email Service to L1 and L2 — NotificationService and PasswordResetService send SMTP
Some checks failed
CI / Unit & Component Tests (push) Failing after 3m29s
CI / OCR Service Tests (push) Successful in 35s
CI / Backend Unit Tests (push) Failing after 3m17s
CI / Unit & Component Tests (pull_request) Failing after 3m7s
CI / OCR Service Tests (pull_request) Successful in 29s
CI / Backend Unit Tests (pull_request) Failing after 3m17s
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:18:42 +02:00
Marcel
3fafaf29fc docs(c4): fix 3e DashboardService — add documentSvc and transcriptionSvc cross-domain stubs
DashboardService.getResume() calls DocumentService.getDocumentById() and
TranscriptionService.listBlocks() — both missing from the diagram.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:17:50 +02:00
Marcel
83f4f8352c docs(c4): add OcrJobRepository intermediary in 3d — route ocrAsync through repo, not bare db
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:16:54 +02:00
Marcel
61ca5aacf7 docs(c4): fix 3a secFilter description — BCrypt validation is in DaoAuthenticationProvider
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 12:16:07 +02:00
Marcel
bbded5b921 docs(c4): fix 3d frontend — add User actor for /hilfe/transkription
Some checks failed
CI / Unit & Component Tests (push) Failing after 3m14s
CI / OCR Service Tests (push) Successful in 36s
CI / Backend Unit Tests (push) Failing after 3m20s
CI / Unit & Component Tests (pull_request) Failing after 3m29s
CI / OCR Service Tests (pull_request) Successful in 35s
CI / Backend Unit Tests (pull_request) Failing after 3m22s
The help guide is used by all transcribers, not just administrators. Only
showing admin as the actor was misleading about who accesses this route.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 11:28:03 +02:00
Marcel
e3bfbde8e9 docs(c4): fix 3a — remove AOP @Around from secFilter→permAspect rel label
The filter chain doesn't invoke the AOP aspect directly — Spring Security
hands off to the servlet and AOP intercepts at the method level. The label
implied a direct invocation chain that doesn't exist.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 11:27:13 +02:00
Marcel
632fb9ef7b docs(c4): fix 3b frontend — correct docBulkEdit endpoint to /bulk
DocumentController maps the batch update to PATCH /api/documents/bulk,
not /api/documents/batch.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 11:26:33 +02:00
Marcel
a20a46b262 docs(c4): fix 3c.2 — add PersonRelationshipRepository, route through repo
Both RelationshipService and RelationshipInferenceService inject
PersonRelationshipRepository. The previous direct db arrows were inaccurate.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 11:25:57 +02:00
Marcel
35d82814a6 docs(c4): fix 3d OCR — route transcription/annotation through domain services
OcrAsyncRunner injects TranscriptionService and AnnotationService; it only
accesses the DB directly for OcrJob state (OcrJobRepository). The previous
Rel arrow incorrectly showed direct JDBC access for transcription blocks and
annotations, contradicting the component description.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 11:25:14 +02:00
Marcel
83c3d85b00 docs(c4): fix service layer relationships in diagrams 3b and 3b.2
Some checks failed
CI / Unit & Component Tests (push) Failing after 3m33s
CI / OCR Service Tests (push) Successful in 35s
CI / Backend Unit Tests (push) Failing after 3m22s
CI / Unit & Component Tests (pull_request) Failing after 3m28s
CI / OCR Service Tests (pull_request) Successful in 31s
CI / Backend Unit Tests (pull_request) Failing after 3m16s
Diagram 3b: DocumentService calls PersonService and TagService, not
their repositories directly. Replace personRepo/tagRepo cross-ref
stubs with personSvc/tagSvc to accurately reflect the layering rule.

Diagram 3b.2: TranscriptionService, AnnotationService, and
CommentService each use a JPA repository, not JDBC directly. Add
TranscriptionBlockRepository, AnnotationRepository, and
CommentRepository components and route the service→repo→db chain.
TranscriptionQueueService delegates to DocumentService and
AuditLogQueryService (no repo of its own); replace the incorrect
→db arrow with cross-diagram stubs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 11:03:23 +02:00
Marcel
18a7ee1fa5 docs: remove accidentally committed spec file
Spec file was pre-staged from a prior session and bundled into the previous commit. Specs belong in Gitea issues, not committed to the repo.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 10:29:30 +02:00
Marcel
42c6e58d36 docs(c4): fix diagram 3c service layer and add missing 3e components
- diagram 3c: GroupController delegates to UserService (not groupRepo directly)
- diagram 3c: add TagService; TagController delegates to TagService (not tagRepo)
- diagram 3e: add DashboardController serving /api/dashboard/resume|pulse|activity
- diagram 3e: add StatsService; StatsController delegates to StatsService

Addresses blocker feedback from Markus, Felix, and Elicit in PR #448 review.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 10:28:16 +02:00
Marcel
e1f66e2e65 docs(c4): rewrite frontend 3b, add 3c people/stories/discovery, add 3d admin/help
Some checks failed
CI / Unit & Component Tests (push) Failing after 3m26s
CI / OCR Service Tests (push) Successful in 32s
CI / Backend Unit Tests (push) Failing after 3m24s
CI / Unit & Component Tests (pull_request) Failing after 3m30s
CI / OCR Service Tests (pull_request) Successful in 40s
CI / Backend Unit Tests (pull_request) Failing after 3m21s
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 10:02:38 +02:00
Marcel
be40cc0f38 docs(c4): update frontend 3a — hooks layers, add register/forgot/reset routes 2026-05-06 09:59:46 +02:00
Marcel
f744e8c59d docs(c4): add 3d OCR orchestration and 3e supporting domains 2026-05-06 09:58:55 +02:00
Marcel
dbbb989aa6 docs(c4): restructure 3c users/groups, add 3c.2 persons and family graph 2026-05-06 09:57:39 +02:00
Marcel
04b2b33d7f docs(c4): add 3b.2 transcription pipeline — annotations, blocks, comments 2026-05-06 09:56:19 +02:00
Marcel
1e3423934c docs(c4): update 3b document domain — descriptions, batch ops, FTS, presigned URLs 2026-05-06 09:55:28 +02:00
Marcel
d51c5e9b80 docs(c4): fix 3a security — email field, permitted endpoints 2026-05-06 09:54:31 +02:00
Marcel
d4eb0edfe1 docs(c4): update L1 personas and L2 frontend container description 2026-05-06 09:53:38 +02:00
Marcel
aff15fd208 docs(c4): split L3 monolith diagrams into five focused sub-diagrams
Backend L3 split into 3a (Security & Auth), 3b (Document/File/Import),
3c (People/Users/Groups). Frontend L3 split into 3a (Middleware/Auth/Layout)
and 3b (Pages & Shared Components). Each sub-diagram stays within dagre's
clean-layout range (5–10 components, 6–12 relationships).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 09:51:46 +02:00