docs(c4): add C4-PlantUML diagram files for all architecture views #450
Reference in New Issue
Block a user
Delete Branch "docs/post-refactor-accuracy-audit"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
.pumlfiles indocs/architecture/c4/— one per C4 diagram (L1 context, L2 containers, 7 L3 backend sub-diagrams, 4 L3 frontend sub-diagrams, 2 sequence diagrams)!include <C4/C4_*>from the stdlib bundled in the self-hosted PlantUML server (http://heim-nas:8500) — no external fetchesdocs/architecture/c4/README.mdwith a file index and VS Code rendering instructions.vscode/settings.jsonto point the PlantUML extension at the shared server (Alt+Dto preview any.pumlfile)docs/architecture/c4-diagrams.mdis left unchanged — Mermaid blocks stay for native Gitea inline rendering; the.pumlfiles exist for layout-accurate C4-PlantUML rendering in VS Code and when browsed directly in GiteaWhy both formats
Gitea's external renderer handles whole files but not code fences inside Markdown. Mermaid renders natively inline; PlantUML does not. The
.pumlfiles solve the arrow-layout problem via C4-PlantUML's directional hints while keeping Gitea inline rendering working via Mermaid.Test plan
.pumlfile in VS Code with the PlantUML extension installed →Alt+Drenders diagram viahttp://heim-nas:8500.pumlfile in Gitea → renders as a diagram (Gitea already configured)docs/architecture/c4-diagrams.mdstill renders Mermaid diagrams inline in Gitea🤖 Generated with Claude Code
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>🏛️ Markus Keller — Senior Application Architect
Verdict: ✅ Approved
This is a documentation-only PR. I reviewed it from an architectural documentation hygiene perspective.
What's Good
Dual-format strategy is well-justified. The PR description explains the tradeoff clearly: Mermaid for inline Gitea rendering, PlantUML for layout-accurate C4-PlantUML in VS Code. This is the right call — Gitea's external renderer limitation is real, and keeping both formats rather than fighting the tooling is pragmatic.
Cross-diagram stub pattern is sound. Components placed outside a
System_Boundarywith "See diagram X" annotations correctly model cross-domain dependencies without duplicating definitions. Thec4-diagrams.mdeven documents this pattern explicitly in the updated header. This is the right architectural convention for split L3 diagrams.The sub-diagram decomposition maps to the actual module structure. 3a security, 3b documents, 3c transcription, 3d users/groups, 3e persons, 3f OCR, 3g supporting — these align with the package-by-feature structure in the codebase. A new developer can navigate from diagram to package directory without a gap.
The Mermaid updates fix real accuracy issues. The old monolithic L3 backend diagram mixed
PersonRepositoryandTagRepositorycalls insideDocumentService— that violated the service boundary rules. The new diagrams correctly modelDocumentService → PersonServiceandDocumentService → TagServicecross-domain calls. Good catch.Suggestions (non-blocking)
The PlantUML server URL is environment-specific and committed.
.vscode/settings.jsonnow containshttp://heim-nas:8500. This works for this team but is a friction point if anyone works from a machine whereheim-nasis not resolvable. Consider documenting the local PlantUML server alternative (e.g.,docker run -d -p 8500:8080 plantuml/plantuml-server) indocs/architecture/c4/README.md. Not a blocker — the current setup is appropriate for a solo/small-team project.Missing ADR for the dual-format decision. The PR description is a good explanation, but it lives in git history, not in
docs/adr/. If someone later asks "why are there two sets of diagrams?", an ADR would surface the answer without archaeology. Low priority for a solo project — the PR description is sufficient documentation for now.👨💻 Felix Brandt — Senior Fullstack Developer
Verdict: ✅ Approved
Pure documentation PR — no production code changed. My review focuses on documentation quality, naming conventions, and accuracy of the architectural descriptions.
What's Good
Naming is precise and intent-revealing throughout. File names follow a clear convention (
l1-context.puml,l2-containers.puml,l3-backend-3a-security.puml) that maps directly to C4 levels and sub-diagram index. No abbreviations, no ambiguity. A new developer can find the diagram they need from the filename alone.The
c4-diagrams.mdaccuracy fixes are meaningful. Key corrections I noticed:username→emailin the login sequence andCustomUserDetailsServicedescription — correctly reflects the actual auth implementationDocumentService → PersonServiceandDocumentService → TagServicereplacing direct repository calls — correct layeringExcelServicenow handles ODS files too — accurateMassImportServicestate machine (IDLE/RUNNING/DONE/FAILED) added to description — good detailRegisterPage,ForgotPassword,ResetPasswordfrontend routes added — these were missing from the old diagramThe cross-diagram stub pattern with "See diagram X" comments avoids both duplication and mystery references. Readable, follows the same intent-revealing convention as the code.
Minor Observations (non-blocking)
ContainerDb(db, "PostgreSQL", "PostgreSQL 16")vsContainerDb(db, "PostgreSQL")inconsistency between the.pumlfiles and the Mermaid versions inc4-diagrams.md. The.pumlfiles add the version as a third argument — that's correct C4-PlantUML syntax and adds useful detail. The Mermaid versions don't have this level of detail which is fine for Mermaid's DSL.docs/architecture/c4/README.mdlast row of the file table is truncated in my diff view (thel3-frontend-3brow). Looked fine in the full file read — confirming it renders correctly in Gitea is part of the test plan, so this should be caught.Nothing here requires changes.
🔒 Nora "NullX" Steiner — Application Security Engineer
Verdict: ⚠️ Approved with concerns
Documentation-only PR. My review focuses on what the architecture diagrams reveal about the security model and whether the committed configuration introduces any exposure.
Concern (worth addressing, not blocking)
Hardcoded internal hostname in committed VS Code settings.
docs/architecture/c4/README.mdand.vscode/settings.jsonboth referencehttp://heim-nas:8500as the PlantUML render server. The concern here is information disclosure, not a direct vulnerability: the hostnameheim-nasand port8500are now part of the public (or semi-public) git history. For a private family project on a self-hosted Gitea this is low risk, but it's worth noting:http://(nothttps://) means the VS Code extension sends PlantUML source over unencrypted HTTP to the render server. The diagrams contain internal component names, API routes, and authentication flow details. On a trusted home LAN this is acceptable; it would not be acceptable over a corporate network or VPN.Recommendation: Add a note in
docs/architecture/c4/README.mdthat the render server uses HTTP on the internal LAN only, and that contributors should not use this setup over untrusted networks. No code change required — one sentence in the README is sufficient.What's Correct in the Architecture Descriptions
Reviewing the security-relevant content of the diagrams themselves:
PermissionAspectas AOP-enforced and separate from the filter chain — this is the right representation of how@RequirePermissionworks in this codebase.CustomUserDetailsServiceloads by email (updated from username) — the diagram now matches the actual authentication field.permitAllinSecurityConfig).SecurityConfigcomponent description — this is appropriate for a Basic Auth + httpOnly cookie setup where CSRF is structurally mitigated.Rel(backend, user, "SSE notifications"...)) — this is correct and confirms no sensitive data routing through an intermediary.No security regressions in this PR.
🧪 Sara Holt — Senior QA Engineer
Verdict: ✅ Approved
Documentation-only PR — no test coverage impact. My review covers testability of the test plan items in the PR description.
Test Plan Assessment
The PR's test plan has three items:
These are all manual, environment-dependent checks — which is appropriate for tooling configuration PRs. There's nothing to automate here in the standard test pyramid. Confirmed these are the right acceptance criteria for this type of change.
One Observation
The test plan doesn't specify which
.pumlfile to use as a smoke test. Given there are 15 new files spanning C4 levels and diagram types, a more complete test plan would verify:!include—C4_Sequence)l3-backend-3b-document-management.pumlfile specifically, which has the mostComponent()andRel()declarations and is most likely to reveal syntax errorsThis is a suggestion for the author's manual verification, not a blocker. The existing test plan is sufficient for a documentation PR.
No Test Coverage Impact
No production code changed. No test files added or modified. The existing test suite is unaffected. ✅
⚙️ Tobias Wendt — DevOps & Platform Engineer
Verdict: ✅ Approved
Documentation and VS Code configuration PR. Nothing touches the Docker Compose file, CI pipeline, or production infrastructure.
What I Checked
.vscode/settings.jsonchange: Addsplantuml.renderandplantuml.serverkeys pointing athttp://heim-nas:8500. This is a developer tooling config — it affects VS Code only, not the build pipeline or deployed services.heim-nas:8500is presumably the self-hostedplantuml/plantuml-servercontainer. It's not wired into CI, which is correct — diagram rendering is a dev convenience, not a build step.New
docs/architecture/c4/directory: Pure documentation — 15.pumlfiles and aREADME.md. No impact on build, test, or deployment.No CI impact. The Gitea Actions pipeline doesn't build or lint
.pumlfiles, and there's nothing here that would break any existing CI job.Suggestion (non-blocking)
Consider adding a
plantuml/plantuml-serverservice todocker-compose.override.ymlfor contributors who don't haveheim-nason their network. Something like:With a matching note in the README: "If
heim-nasis not reachable, rundocker compose up plantumland point your VS Code setting athttp://localhost:8500." This makes the diagrams renderable for any future contributor. Not required for the current solo setup.📋 Elicit — Requirements Engineer
Verdict: ✅ Approved
Reviewing from a requirements documentation perspective: does the architecture documentation accurately reflect what the system does, and is it useful as a communication artifact?
Accuracy Assessment
The diagram updates in
c4-diagrams.mdfix several requirements-level inaccuracies in the previous version:User persona descriptions improved:
"Family Member"persona now correctly includes "transcribes archived documents" — the original omitted transcription as a member capability"Access by administrator invite") is now explicit at L1 — this is an important access control requirement that was previously invisible in the diagramsEmail service now modelled at L1 and L2:
System_Ext(mail, "Email Service")addition surfaces a dependency that was missing. Password reset and mention notifications via SMTP are real functional requirements — they should be visible at the context level.Auth field corrected (
username→email):email:passwordin the Basic Auth encoding andSELECT user WHERE email=?in the DB query. Matches actual behavior.MassImportServicenow handles ODS in addition to Excel:"Excel/ODS workbooks (Apache POI)"— the original said Excel only. Apache POI supports both; the description now matches the actual capability.Observation
The
c4-diagrams.mdheader now includes a definition of the "cross-diagram stub" pattern. This is good requirements hygiene — defining conventions at the point of use prevents ambiguity for future readers who need to understand why a component appears without a full definition.No Requirements Gaps Introduced
This PR adds no new system behaviors — it only documents existing ones more accurately. All changes are additive corrections to existing descriptions. LGTM from a requirements perspective.
🎨 Leonie Voss — UI/UX Design Lead
Verdict: ✅ Approved
This PR contains no frontend component changes, Svelte files, Tailwind classes, or UI-layer modifications. My review is therefore brief.
What I Checked
No
.sveltefiles changed. Zero UI impact — no brand compliance concerns, no accessibility regressions, no touch target or typography changes.No frontend route changes. The diagram descriptions document existing routes (including the new
/enrich,/briefwechsel,/aktivitaeten,/stammbaum, etc.) but don't add or modify them.The
c4-diagrams.mdfrontend diagrams now correctly show the dual-audience design in the route structure — the split between transcription paths (desktop/tablet-first) and reading paths (mobile-first) is implicitly captured in the component descriptions.One Positive Note
The new Frontend 3c diagram (
/persons,/briefwechsel,/aktivitaeten,/geschichten,/stammbaum) documents routes that exist but weren't in the previous architecture diagram. The family tree (/stammbaum) and stories (/geschichten) are notable for mobile UX — these are reading-path features used by the younger audience on phones. Good that they're now visible at the architecture level.No UI concerns. LGTM.