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

docs(legibility): write docs/GLOSSARY.md disambiguating overloaded terms (DOC-3) #434

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

Part of #394 (Epic 2 — Documentation). Rubric check: C3.3 (Critical).

Problem

The codebase contains terms whose meanings are non-obvious or domain-specific. Without a glossary, Anja's first wrong assumption is that Person and AppUser are the same entity — a mental-model failure that propagates through every later question (e.g. "can a Person log in?" — no, only AppUsers can). Per Markus and Nora, several other terms (Geschichte, TranscriptionBlock, OcrJob family, Permission enum values) cause similar confusion.

Scope

  1. Create docs/GLOSSARY.md.
  2. Required entries (each: one-paragraph definition + cross-reference to source code as path/file.java:42):
    • Person ≠ AppUser — historical letter actor (no login, possibly deceased) vs. application user account. This is the most-confused distinction.
    • Geschichte — rich-text family story tied to one or more documents/persons; not the generic German word for "history."
    • TranscriptionBlock vs. DocumentVersion — positional OCR output (one block per region) vs. file revision (a different concept entirely).
    • OcrJob vs. OcrBatchService vs. OcrAsyncRunner — the three "OCR" classes serve different roles; documenting them prevents misuse.
    • SenderModel — per-person OCR fine-tune profile.
    • Permission enum values — what each grants vs. excludes:
      • READ_ALL — read all documents (whether the user can read this domain at all).
      • WRITE_ALL — modify all documents.
      • ADMIN — global admin (highest).
      • ADMIN_USER — manage users + groups (subset of ADMIN scope).
      • ADMIN_TAG — manage tags only.
      • ADMIN_PERMISSION — manage roles/permissions only.
    • Conversation — Tier-2 view layer over Document sender/receiver; no entity, no table (per Boundary decisions D-FE-3 / Canonical Domain Set).
    • Activity — Tier-2 view layer over Audit + Notification + Document events; no entity, no table.
    • Tag vs. Label — UI labels in German (Etikett) vs. data-layer entity (Tag).
    • Document lifecycle — PLACEHOLDER → UPLOADED → TRANSCRIBED → REVIEWED → ARCHIVED (each state defined; what triggers the transition).
  3. Linking: GLOSSARY.md is linked from README.md (DOC-1) and docs/ARCHITECTURE.md (DOC-2).

References

  • Parent: epic(legibility): documentation — make the codebase self-explaining (#394)
  • Rubric: C3.3 (Critical)
  • Canonical Domain Set + Boundary decisions D-OQ-1..8, D-FE-1..4 (#387 first comment)
  • Source-code anchors:
    • backend/src/main/java/org/raddatz/familienarchiv/person/Person.java, user/AppUser.java
    • backend/.../document/Document.java, document/DocumentStatus.java
    • backend/.../document/transcription/TranscriptionBlock.java
    • backend/.../security/Permission.java

Acceptance criteria

  • docs/GLOSSARY.md exists.
  • All 10 entries above present, each with definition + source-code reference.
  • Anja-persona test: stranger correctly answers "Can a Person log in?" → No. "What does Conversation map to in the database?" → No table; it's a view layer.
  • GLOSSARY linked from README.md and docs/ARCHITECTURE.md.
  • Rubric C3.3 PASS verified by reviewer.

Definition of Done

GLOSSARY.md is on main with all 10 entries. Rubric C3.3 PASS.

Part of #394 (Epic 2 — Documentation). Rubric check: **C3.3 (Critical)**. ## Problem The codebase contains terms whose meanings are non-obvious or domain-specific. Without a glossary, **Anja's** first wrong assumption is that `Person` and `AppUser` are the same entity — a mental-model failure that propagates through every later question (e.g. "can a Person log in?" — no, only AppUsers can). Per Markus and Nora, several other terms (`Geschichte`, `TranscriptionBlock`, `OcrJob` family, `Permission` enum values) cause similar confusion. ## Scope 1. Create `docs/GLOSSARY.md`. 2. **Required entries** (each: one-paragraph definition + cross-reference to source code as `path/file.java:42`): - **`Person` ≠ `AppUser`** — historical letter actor (no login, possibly deceased) vs. application user account. This is the most-confused distinction. - **`Geschichte`** — rich-text family story tied to one or more documents/persons; not the generic German word for "history." - **`TranscriptionBlock` vs. `DocumentVersion`** — positional OCR output (one block per region) vs. file revision (a different concept entirely). - **`OcrJob` vs. `OcrBatchService` vs. `OcrAsyncRunner`** — the three "OCR" classes serve different roles; documenting them prevents misuse. - **`SenderModel`** — per-person OCR fine-tune profile. - **`Permission` enum values** — what each grants vs. excludes: - `READ_ALL` — read all documents (whether the user can read this domain at all). - `WRITE_ALL` — modify all documents. - `ADMIN` — global admin (highest). - `ADMIN_USER` — manage users + groups (subset of ADMIN scope). - `ADMIN_TAG` — manage tags only. - `ADMIN_PERMISSION` — manage roles/permissions only. - **`Conversation`** — Tier-2 view layer over Document sender/receiver; **no entity, no table** (per Boundary decisions D-FE-3 / Canonical Domain Set). - **`Activity`** — Tier-2 view layer over Audit + Notification + Document events; **no entity, no table**. - **`Tag` vs. `Label`** — UI labels in German (`Etikett`) vs. data-layer entity (`Tag`). - **Document lifecycle** — `PLACEHOLDER → UPLOADED → TRANSCRIBED → REVIEWED → ARCHIVED` (each state defined; what triggers the transition). 3. **Linking**: GLOSSARY.md is linked from `README.md` (DOC-1) and `docs/ARCHITECTURE.md` (DOC-2). ## References - Parent: #394 - Rubric: **C3.3 (Critical)** - Canonical Domain Set + Boundary decisions D-OQ-1..8, D-FE-1..4 (#387 first comment) - Source-code anchors: - `backend/src/main/java/org/raddatz/familienarchiv/person/Person.java`, `user/AppUser.java` - `backend/.../document/Document.java`, `document/DocumentStatus.java` - `backend/.../document/transcription/TranscriptionBlock.java` - `backend/.../security/Permission.java` ## Acceptance criteria - [ ] `docs/GLOSSARY.md` exists. - [ ] All 10 entries above present, each with definition + source-code reference. - [ ] **Anja-persona test**: stranger correctly answers "Can a Person log in?" → No. "What does `Conversation` map to in the database?" → No table; it's a view layer. - [ ] GLOSSARY linked from `README.md` and `docs/ARCHITECTURE.md`. - [ ] Rubric **C3.3 PASS** verified by reviewer. ## Definition of Done GLOSSARY.md is on `main` with all 10 entries. Rubric C3.3 PASS.
marcel added this to the Codebase Legibility milestone 2026-05-05 21:07:03 +02:00
marcel added the P0-criticaldocumentationlegibility labels 2026-05-05 21:07:09 +02:00
marcel commented 2026-05-05 21:14:18 +02:00
Author
Owner
Copy Link

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

**Duplicate of #397.** I created this in error before noticing #397 already existed. #397 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 P0-critical documentation legibility
Milestone
No items
No Milestone Codebase Legibility
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#434
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?