marcel/familienarchiv
1
0
Fork 0
Code Issues 117 Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

docs(legibility): write docs/ARCHITECTURE.md with diagram, domains, security model (DOC-2) #433

New Issue
Closed
opened 2026-05-05 21:06:32 +02:00 by marcel · 1 comment
marcel commented 2026-05-05 21:06:32 +02:00
Owner
Copy Link

Part of #394 (Epic 2 — Documentation). Rubric checks: C1.3 (Major), C3.1 (Critical), C3.2 (Major).

Problem

Tobias (PM-with-CS) needs a single architecture document that names every domain, shows component data flow, and links to the existing ADRs (docs/adr/001..006). The existing C4 diagrams in docs/architecture/c4-diagrams.md predate OcrService, GeschichteService, TranscriptionQueueService, SseEmitterRegistry, NotificationService (per Markus's audit). Without ARCHITECTURE.md, the diagram is inaccurate and the canonical domain set is invisible.

Scope

  1. Create docs/ARCHITECTURE.md.
  2. Required sections:
    • System context — one-paragraph elevator pitch + the 5 deployable components (frontend, backend, OCR Python service, PostgreSQL, MinIO). Per Markus: OCR service must appear as a separate container in the diagram (different tech stack, port 8000).
    • C4 Level 2 diagram — refresh docs/architecture/c4-diagrams.md (or supersede it) so it includes OcrService, GeschichteService, TranscriptionQueueService, SseEmitterRegistry, NotificationService. Embed or link from ARCHITECTURE.md.
    • Domains — list every Tier 1 and Tier 2 domain from the Canonical Domain Set (#387 first comment): document, person, tag, user, geschichte, notification, ocr, conversation (derived), activity (derived). Each gets a one-paragraph definition (what it owns / what it does NOT own).
    • Vertical slice — trace one full data-flow end to end (recommended: document upload → S3 → PLACEHOLDER → OCR transcription → notification). This is what makes the architecture operational in the reader's head.
    • Security model (per Nora) — @RequirePermission + PermissionAspect AOP mechanism, the permission hierarchy (READ_ALL, WRITE_ALL, ADMIN, ADMIN_USER, ADMIN_TAG, ADMIN_PERMISSION), and a link to docs/security-guide.md for production hardening.
    • Decision records — table linking to docs/adr/001..006 with a one-line consequence per ADR (per Markus: not just a list of files).
    • See also — links to CONTRIBUTING.md (DOC-4) and docs/DEPLOYMENT.md (DOC-5).

References

Acceptance criteria

  • docs/ARCHITECTURE.md exists.
  • Diagram shows OCR service as a separate container.
  • Diagram includes the five subsystems Markus flagged as missing.
  • Every Tier 1 domain (document, person, tag, user, geschichte, notification, ocr) has a one-paragraph definition (rubric C3.2).
  • ADR table lists 001..006 with one-line consequences.
  • Security model section documents @RequirePermission + permission hierarchy.
  • Tobias-persona test: stranger reproduces the diagram from memory after one read.
  • Rubric C1.3, C3.1, C3.2 PASS verified by reviewer.

Definition of Done

docs/ARCHITECTURE.md is on main. C4 diagram is refreshed (either inline or in docs/architecture/c4-diagrams.md). Rubric C1.3, C3.1, C3.2 PASS.

Part of #394 (Epic 2 — Documentation). Rubric checks: C1.3 (Major), **C3.1 (Critical)**, C3.2 (Major). ## Problem **Tobias** (PM-with-CS) needs a single architecture document that names every domain, shows component data flow, and links to the existing ADRs (`docs/adr/001..006`). The existing C4 diagrams in `docs/architecture/c4-diagrams.md` predate `OcrService`, `GeschichteService`, `TranscriptionQueueService`, `SseEmitterRegistry`, `NotificationService` (per Markus's audit). Without ARCHITECTURE.md, the diagram is inaccurate and the canonical domain set is invisible. ## Scope 1. Create `docs/ARCHITECTURE.md`. 2. Required sections: - **System context** — one-paragraph elevator pitch + the 5 deployable components (frontend, backend, OCR Python service, PostgreSQL, MinIO). Per Markus: OCR service must appear as a separate container in the diagram (different tech stack, port 8000). - **C4 Level 2 diagram** — refresh `docs/architecture/c4-diagrams.md` (or supersede it) so it includes `OcrService`, `GeschichteService`, `TranscriptionQueueService`, `SseEmitterRegistry`, `NotificationService`. Embed or link from ARCHITECTURE.md. - **Domains** — list every Tier 1 and Tier 2 domain from the Canonical Domain Set (#387 first comment): `document`, `person`, `tag`, `user`, `geschichte`, `notification`, `ocr`, `conversation` (derived), `activity` (derived). Each gets a one-paragraph definition (what it owns / what it does NOT own). - **Vertical slice** — trace one full data-flow end to end (recommended: document upload → S3 → PLACEHOLDER → OCR transcription → notification). This is what makes the architecture *operational* in the reader's head. - **Security model** (per Nora) — `@RequirePermission` + `PermissionAspect` AOP mechanism, the permission hierarchy (`READ_ALL`, `WRITE_ALL`, `ADMIN`, `ADMIN_USER`, `ADMIN_TAG`, `ADMIN_PERMISSION`), and a link to `docs/security-guide.md` for production hardening. - **Decision records** — table linking to `docs/adr/001..006` with a one-line *consequence* per ADR (per Markus: not just a list of files). - **See also** — links to `CONTRIBUTING.md` (DOC-4) and `docs/DEPLOYMENT.md` (DOC-5). ## References - Parent: #394 - Rubric: C1.3, C3.1, C3.2 - Inputs: #387 first comment (Canonical Domain Set + Boundary decisions D-OQ-1..8, D-FE-1..4) - Existing docs to refresh or link: `docs/architecture/c4-diagrams.md`, `docs/adr/001..006.md`, `docs/security-guide.md` ## Acceptance criteria - [ ] `docs/ARCHITECTURE.md` exists. - [ ] Diagram shows OCR service as a separate container. - [ ] Diagram includes the five subsystems Markus flagged as missing. - [ ] Every Tier 1 domain (`document`, `person`, `tag`, `user`, `geschichte`, `notification`, `ocr`) has a one-paragraph definition (rubric C3.2). - [ ] ADR table lists 001..006 with one-line consequences. - [ ] Security model section documents `@RequirePermission` + permission hierarchy. - [ ] **Tobias-persona test**: stranger reproduces the diagram from memory after one read. - [ ] Rubric C1.3, **C3.1**, C3.2 PASS verified by reviewer. ## Definition of Done `docs/ARCHITECTURE.md` is on `main`. C4 diagram is refreshed (either inline or in `docs/architecture/c4-diagrams.md`). Rubric C1.3, C3.1, C3.2 PASS.
marcel added this to the (deleted) milestone 2026-05-05 21:06:32 +02:00
marcel added the P1-highdocumentationlegibility labels 2026-05-05 21:06:37 +02:00
marcel commented 2026-05-05 21:14:16 +02:00
Author
Owner
Copy Link

Duplicate of #396. I created this in error before noticing #396 already existed. #396 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.

**Duplicate of #396.** I created this in error before noticing #396 already existed. #396 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
P0-critical
Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.
 P1-high
Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.
 P2-medium
Noticeable improvement; doesn't block anything; schedule opportunistically.
 P3-later
Cosmetic or parking-lot work; fine to stay open indefinitely.
 audit
Read-only audit / assessment work; produces a report rather than changing code
 bug
Something isn't working
 cleanup
Removal of dead code, vague comments, naming violations, and scratch artifacts
 collaboration
We want to extend the family archive to have more collaboration tools
 conversation
descoped
We will do that later
 devops
documentation
README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs
 epic
Marker for epic-level issues that group multiple child issues
 feature
file-upload
legibility
Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction
 notification
person
phase-1: security
Security hygiene — must be done first
 phase-2: container-images
Production-ready multi-stage Docker images
 phase-3: prod-compose
Production compose overlay + Caddy reverse proxy
 phase-4: spring-prod-profile
Spring Boot production configuration profile
 phase-5: backups
Database and object storage backup strategy
 phase-6: deployment-docs
.env.example, DEPLOYMENT.md, runbook
 phase-7: monitoring
Prometheus, Loki, Grafana, Alertmanager
 refactor
Code restructuring without behaviour change
 security
test
ui
UI/UX and accessibility issues
 user
No Label P1-high documentation legibility
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Jens marcel
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: marcel/familienarchiv#433
Delete Branch "%!s()"

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?