docs(db): add ER and ORM diagrams (PlantUML) #452

Merged

marcel merged 3 commits from docs/db-diagrams into main 2026-05-07 07:12:31 +02:00

Conversation 7 Commits 3 Files Changed 3 +575

marcel commented 2026-05-06 23:45:32 +02:00

Owner

Copy Link

Closes #451.

Summary

• Adds docs/architecture/db/db-relationships.puml — crow's-foot ER diagram showing all 30 tables and their FK connections, grouped into 7 domain packages (Auth, Documents, Persons, Tags, Transcription, OCR, Supporting). Left-to-right layout for readability.
• Adds docs/architecture/db/db-orm.puml — full schema reference with every column, PostgreSQL type, and <<PK>>/<<FK>> markers for all 30 tables. Use this when mapping Java entities to database columns.
• Updates docs/architecture/c4-diagrams.md with a new Database section linking both diagrams and describing their intended use.

Schema snapshot

Both diagrams are derived from Flyway migrations V1–V60 (excluding V37 and V43, which were intentionally removed). Snapshot date: 2026-05-06.

Open in VS Code with the PlantUML extension pointed at http://heim-nas:8500.

Test plan

• Open db-relationships.puml in VS Code with PlantUML extension — diagram renders without errors
• Open db-orm.puml in VS Code with PlantUML extension — diagram renders without errors
• Check c4-diagrams.md Database section links resolve correctly to the .puml files

Closes #451. ## Summary - Adds `docs/architecture/db/db-relationships.puml` — crow's-foot ER diagram showing all 30 tables and their FK connections, grouped into 7 domain packages (Auth, Documents, Persons, Tags, Transcription, OCR, Supporting). Left-to-right layout for readability. - Adds `docs/architecture/db/db-orm.puml` — full schema reference with every column, PostgreSQL type, and `<<PK>>`/`<<FK>>` markers for all 30 tables. Use this when mapping Java entities to database columns. - Updates `docs/architecture/c4-diagrams.md` with a new **Database** section linking both diagrams and describing their intended use. ## Schema snapshot Both diagrams are derived from Flyway migrations V1–V60 (excluding V37 and V43, which were intentionally removed). Snapshot date: 2026-05-06. Open in VS Code with the PlantUML extension pointed at `http://heim-nas:8500`. ## Test plan - [ ] Open `db-relationships.puml` in VS Code with PlantUML extension — diagram renders without errors - [ ] Open `db-orm.puml` in VS Code with PlantUML extension — diagram renders without errors - [ ] Check `c4-diagrams.md` Database section links resolve correctly to the `.puml` files

marcel added 3 commits 2026-05-06 23:45:33 +02:00

docs(db): add relationship diagram (db-relationships.puml) ... e209d4877d

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(db): add full ORM diagram (db-orm.puml) ... d4b5c14a26

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(db): add Database section to c4-diagrams.md ... ba0bfc6a7e

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

marcel commented 2026-05-06 23:48:27 +02:00

Author

Owner

Copy Link

🏗️ Markus Keller (@mkeller) — Senior Application Architect

Verdict: ✅ Approved

Solid documentation work. I checked the diagrams against the actual Flyway migration trail (V1–V60) and the structural choices are correct. A few observations.

What I Checked

• Domain groupings match the backend package structure: Auth, Documents, Persons, Tags, Transcription, OCR, Supporting. The grouping is consistent with how we organize code.
• The intentional non-FK on transcription_block_mentioned_persons.person_id is correctly modelled — no FK arrow in the relationship diagram, no <<FK>> in the ORM. The migration comment explains exactly why (lazy degradation on person delete). The diagram correctly reflects the deliberate design choice.
• ocr_jobs.created_by — also correctly shown as a plain UUID with no FK (matches V25 which uses no REFERENCES).
• The sender_models ||--|| persons relationship uses ||--|| (one-to-one mandatory), which is correct given the UNIQUE NOT NULL REFERENCES in V40.
• The tag }o--o| tag self-reference correctly shows the nullable parent hierarchy (V39).
• Schema snapshot date and Flyway version range are declared in the file headers — good.

Advisory

• The geschichten table references author_id as nullable (}o--o|). This is correct per V58 (REFERENCES users(id) ON DELETE SET NULL). No change needed.
• The relationship diagram says left to right direction — good for overview readability given 30 tables.
• Consider adding a brief comment in the db-relationships.puml header explaining that transcription_block_mentioned_persons.person_id intentionally has no FK (the ORM comment block is there, but the relationships file is silent on this). This is advisory — not a blocker.
• The c4-diagrams.md "Schema as of Flyway V60" notation is the right way to communicate this is a snapshot. The warning comment in both files (⚠ This is a versioned snapshot) is appropriate.

No structural accuracy issues found. Architecture LGTM.

## 🏗️ Markus Keller (@mkeller) — Senior Application Architect **Verdict: ✅ Approved** Solid documentation work. I checked the diagrams against the actual Flyway migration trail (V1–V60) and the structural choices are correct. A few observations. ### What I Checked - **Domain groupings** match the backend package structure: Auth, Documents, Persons, Tags, Transcription, OCR, Supporting. The grouping is consistent with how we organize code. - **The intentional non-FK on `transcription_block_mentioned_persons.person_id`** is correctly modelled — no FK arrow in the relationship diagram, no `<<FK>>` in the ORM. The migration comment explains exactly why (lazy degradation on person delete). The diagram correctly reflects the deliberate design choice. - **`ocr_jobs.created_by`** — also correctly shown as a plain UUID with no FK (matches V25 which uses no `REFERENCES`). - **The `sender_models ||--|| persons` relationship** uses `||--||` (one-to-one mandatory), which is correct given the `UNIQUE NOT NULL REFERENCES` in V40. - **The `tag }o--o| tag` self-reference** correctly shows the nullable parent hierarchy (V39). - **Schema snapshot date and Flyway version range** are declared in the file headers — good. ### Advisory - The `geschichten` table references `author_id` as nullable (`}o--o|`). This is correct per V58 (`REFERENCES users(id) ON DELETE SET NULL`). No change needed. - The relationship diagram says `left to right direction` — good for overview readability given 30 tables. - Consider adding a brief comment in the `db-relationships.puml` header explaining that `transcription_block_mentioned_persons.person_id` intentionally has no FK (the ORM comment block is there, but the relationships file is silent on this). This is advisory — not a blocker. - The `c4-diagrams.md` "Schema as of Flyway V60" notation is the right way to communicate this is a snapshot. The warning comment in both files (`⚠ This is a versioned snapshot`) is appropriate. No structural accuracy issues found. Architecture LGTM.

marcel commented 2026-05-06 23:48:36 +02:00

Author

Owner

Copy Link

👨‍💻 Felix Brandt (@felixbrandt) — Senior Fullstack Developer

Verdict: ✅ Approved

This is a documentation-only PR. I reviewed it from a code accuracy perspective — whether the diagram content reflects what the actual Java entities and Flyway migrations say.

What I Verified Against Migrations

I traced through V1–V60 (minus V37 and V43) and the schema in the diagrams is accurate:

• app_users: username correctly absent (dropped in V44). email NOT NULL UNIQUE correct. color NOT NULL correct (V47). notify_on_reply, notify_on_mention correct (V16). first_name, last_name VARCHAR(100) correct (V7).
• persons.first_name: shown without NOT NULL — correct, V22 dropped the NOT NULL constraint.
• transcription_blocks: source, reviewed correctly present (V26). text shown as plain TEXT (V31 made it nullable). The ORM diagram shows text : TEXT without NOT NULL, which is correct after V31.
• document_comments.block_id: correctly present (V20 added it).
• ocr_training_runs: person_id, cer, loss, accuracy, epochs all correctly present (V41, V32).
• document_annotations.polygon: correctly present (V23).
• document_annotations.file_hash VARCHAR(64): correctly present (V13 adds it to both documents and document_annotations).

Suggestions (not blockers)

• The db-orm.puml comment header says text : TEXT for transcription_blocks but doesn't call out it's nullable post-V31. A -- nullable since V31 inline comment would help the next developer who wonders why there's no NOT NULL. Advisory only.
• The PlantUML files have good header comments explaining the snapshot concept. Keep that pattern when updating.

Schema content is accurate. LGTM.

## 👨‍💻 Felix Brandt (@felixbrandt) — Senior Fullstack Developer **Verdict: ✅ Approved** This is a documentation-only PR. I reviewed it from a code accuracy perspective — whether the diagram content reflects what the actual Java entities and Flyway migrations say. ### What I Verified Against Migrations I traced through V1–V60 (minus V37 and V43) and the schema in the diagrams is accurate: - **`app_users`**: `username` correctly absent (dropped in V44). `email NOT NULL UNIQUE` correct. `color NOT NULL` correct (V47). `notify_on_reply`, `notify_on_mention` correct (V16). `first_name`, `last_name VARCHAR(100)` correct (V7). - **`persons.first_name`**: shown without NOT NULL — correct, V22 dropped the NOT NULL constraint. - **`transcription_blocks`**: `source`, `reviewed` correctly present (V26). `text` shown as plain `TEXT` (V31 made it nullable). The ORM diagram shows `text : TEXT` without NOT NULL, which is correct after V31. - **`document_comments.block_id`**: correctly present (V20 added it). - **`ocr_training_runs`**: `person_id`, `cer`, `loss`, `accuracy`, `epochs` all correctly present (V41, V32). - **`document_annotations.polygon`**: correctly present (V23). - **`document_annotations.file_hash VARCHAR(64)`**: correctly present (V13 adds it to both `documents` and `document_annotations`). ### Suggestions (not blockers) - The `db-orm.puml` comment header says `text : TEXT` for `transcription_blocks` but doesn't call out it's nullable post-V31. A `-- nullable since V31` inline comment would help the next developer who wonders why there's no `NOT NULL`. Advisory only. - The PlantUML files have good header comments explaining the snapshot concept. Keep that pattern when updating. Schema content is accurate. LGTM.

marcel commented 2026-05-06 23:49:23 +02:00

Author

Owner

Copy Link

🔒 Nora "NullX" Steiner — Application Security Engineer

Verdict: ✅ Approved

Documentation-only PR — no production code changes. My focus here is whether the diagrams expose any sensitive structure that could be useful to an attacker, and whether any security-relevant schema details are misrepresented.

What I Checked

Sensitive column visibility: The app_users entity in db-orm.puml lists password : VARCHAR(255) NOT NULL. This is documenting a schema fact, not exposing anything that isn't already in the codebase. For an internal family archive with private repository hosting (Gitea self-hosted), this is appropriate. The value is that new developers understand BCrypt is stored here, not plaintext.

Auth-relevant tables accurately represented:

• invite_tokens.created_by — correctly shown as UUID <<FK>> with NOT NULL (per V45: NOT NULL REFERENCES users(id)). Important: revoked invites are blocked at the application layer but the diagram shows the revoked : BOOLEAN NOT NULL field, which is correct.
• password_reset_tokens — token, expires_at, used all correctly present.
• audit_log — actor_id shown as nullable (}o--o|), correct per V46 (ON DELETE SET NULL for GDPR right-to-erasure). This is a security-relevant design choice that the diagram models accurately.

No misleading FK arrows on security-sensitive soft references: ocr_jobs.created_by is shown as a plain UUID without FK — correct, this field has no referential constraint in V25.

Advisory

• The diagram documents app_users.password as VARCHAR(255) NOT NULL. If this repo were ever made public, consider whether including column names of sensitive fields in documentation is desirable. For a private self-hosted family archive, this is not a concern today.
• The audit_log append-only enforcement (REVOKE UPDATE/DELETE per V46/V47) is a schema-layer security control not visible in the diagram. This is advisory — diagrams don't need to document REVOKE grants, but the control exists and works.

No security concerns with the diagrams themselves. LGTM.

## 🔒 Nora "NullX" Steiner — Application Security Engineer **Verdict: ✅ Approved** Documentation-only PR — no production code changes. My focus here is whether the diagrams expose any sensitive structure that could be useful to an attacker, and whether any security-relevant schema details are misrepresented. ### What I Checked **Sensitive column visibility**: The `app_users` entity in `db-orm.puml` lists `password : VARCHAR(255) NOT NULL`. This is documenting a schema fact, not exposing anything that isn't already in the codebase. For an internal family archive with private repository hosting (Gitea self-hosted), this is appropriate. The value is that new developers understand BCrypt is stored here, not plaintext. **Auth-relevant tables accurately represented**: - `invite_tokens.created_by` — correctly shown as `UUID <<FK>>` with `NOT NULL` (per V45: `NOT NULL REFERENCES users(id)`). Important: revoked invites are blocked at the application layer but the diagram shows the `revoked : BOOLEAN NOT NULL` field, which is correct. - `password_reset_tokens` — `token`, `expires_at`, `used` all correctly present. - `audit_log` — `actor_id` shown as nullable (`}o--o|`), correct per V46 (`ON DELETE SET NULL` for GDPR right-to-erasure). This is a security-relevant design choice that the diagram models accurately. **No misleading FK arrows on security-sensitive soft references**: `ocr_jobs.created_by` is shown as a plain UUID without FK — correct, this field has no referential constraint in V25. ### Advisory - The diagram documents `app_users.password` as `VARCHAR(255) NOT NULL`. If this repo were ever made public, consider whether including column names of sensitive fields in documentation is desirable. For a private self-hosted family archive, this is not a concern today. - The `audit_log` append-only enforcement (REVOKE UPDATE/DELETE per V46/V47) is a schema-layer security control not visible in the diagram. This is advisory — diagrams don't need to document REVOKE grants, but the control exists and works. No security concerns with the diagrams themselves. LGTM.

marcel commented 2026-05-06 23:49:32 +02:00

Author

Owner

Copy Link

🧪 Sara Holt (@saraholt) — Senior QA Engineer

Verdict: ✅ Approved

Documentation-only PR — no test coverage required for PlantUML files. My review focuses on whether the diagrams can be used to drive test coverage decisions and whether the schema is accurate enough to trust for test data setup.

What I Checked

Schema accuracy for test fixtures: The ORM diagram is detailed enough to write accurate test factories. Key facts verified:

• documents.status — the CHECK constraint limits values to PLACEHOLDER | UPLOADED | TRANSCRIBED | REVIEWED | ARCHIVED. The ORM just shows status : VARCHAR(255) NOT NULL, which is sufficient for documentation purposes.
• Nullable vs NOT NULL is represented correctly in column lists (absence of NOT NULL means nullable), matching V31's nullable transcription_blocks.text.
• FK relationships with ON DELETE SET NULL are correctly shown as optional (}o--o|) rather than mandatory (}o--||).

Test plan in PR body: The test plan is minimal but appropriate for a docs-only PR:

• "Open in VS Code PlantUML extension — renders without errors" is a valid manual smoke test for PlantUML syntax.

Advisory

• The test plan doesn't include verifying the diagram against a live database query (e.g., \d table_name in psql). This would be the gold standard for accuracy validation. Not a blocker for a snapshot diagram, but worth considering for future updates.
• The PR mentions "30 tables" — I counted 30 entities in both PUML files. Count checks out.

LGTM for documentation purposes.

## 🧪 Sara Holt (@saraholt) — Senior QA Engineer **Verdict: ✅ Approved** Documentation-only PR — no test coverage required for PlantUML files. My review focuses on whether the diagrams can be used to drive test coverage decisions and whether the schema is accurate enough to trust for test data setup. ### What I Checked **Schema accuracy for test fixtures**: The ORM diagram is detailed enough to write accurate test factories. Key facts verified: - `documents.status` — the CHECK constraint limits values to `PLACEHOLDER | UPLOADED | TRANSCRIBED | REVIEWED | ARCHIVED`. The ORM just shows `status : VARCHAR(255) NOT NULL`, which is sufficient for documentation purposes. - Nullable vs NOT NULL is represented correctly in column lists (absence of `NOT NULL` means nullable), matching V31's nullable `transcription_blocks.text`. - FK relationships with `ON DELETE SET NULL` are correctly shown as optional (`}o--o|`) rather than mandatory (`}o--||`). **Test plan in PR body**: The test plan is minimal but appropriate for a docs-only PR: - "Open in VS Code PlantUML extension — renders without errors" is a valid manual smoke test for PlantUML syntax. ### Advisory - The test plan doesn't include verifying the diagram against a live database query (e.g., `\d table_name` in psql). This would be the gold standard for accuracy validation. Not a blocker for a snapshot diagram, but worth considering for future updates. - The PR mentions "30 tables" — I counted 30 entities in both PUML files. Count checks out. LGTM for documentation purposes.

marcel commented 2026-05-06 23:49:43 +02:00

Author

Owner

Copy Link

🚀 Tobias Wendt (@tobiwendt) — DevOps & Platform Engineer

Verdict: ✅ Approved

Documentation-only PR. No infrastructure changes. My check here is whether the docs are maintainable and whether the tooling assumptions are valid for our setup.

What I Checked

PlantUML server reference: Both files and the c4-diagrams.md entry point to http://heim-nas:8500 as the PlantUML rendering server. This matches the existing VS Code config already in the repo from PR #448 (the C4 diagram series). Consistent. Good.

No new services, volumes, or CI changes: Pure doc addition. Zero operational impact.

Snapshot model: The ⚠ This is a versioned snapshot. Update when the schema changes significantly. comment is pragmatic. Better than a stale auto-generated diagram that claims to be live. The snapshot date in the header (2026-05-06) gives readers a reference point.

Advisory

• There's no CI step that validates PlantUML syntax. If someone edits these files and introduces a syntax error, it won't be caught until a developer opens VS Code. This is acceptable for a small team — adding a PlantUML linter to CI would be the improvement, but it's not worth the complexity right now.
• The docs/architecture/db/ directory is a new path. Confirm the VS Code workspace settings (.vscode/settings.json) PlantUML root paths cover this directory. Based on the C4 diagram PR, they should — the server config is global, not path-specific. No action needed.

Infrastructure is unaffected. LGTM.

## 🚀 Tobias Wendt (@tobiwendt) — DevOps & Platform Engineer **Verdict: ✅ Approved** Documentation-only PR. No infrastructure changes. My check here is whether the docs are maintainable and whether the tooling assumptions are valid for our setup. ### What I Checked **PlantUML server reference**: Both files and the `c4-diagrams.md` entry point to `http://heim-nas:8500` as the PlantUML rendering server. This matches the existing VS Code config already in the repo from PR #448 (the C4 diagram series). Consistent. Good. **No new services, volumes, or CI changes**: Pure doc addition. Zero operational impact. **Snapshot model**: The `⚠ This is a versioned snapshot. Update when the schema changes significantly.` comment is pragmatic. Better than a stale auto-generated diagram that claims to be live. The snapshot date in the header (2026-05-06) gives readers a reference point. ### Advisory - There's no CI step that validates PlantUML syntax. If someone edits these files and introduces a syntax error, it won't be caught until a developer opens VS Code. This is acceptable for a small team — adding a PlantUML linter to CI would be the improvement, but it's not worth the complexity right now. - The `docs/architecture/db/` directory is a new path. Confirm the VS Code workspace settings (`.vscode/settings.json`) PlantUML root paths cover this directory. Based on the C4 diagram PR, they should — the server config is global, not path-specific. No action needed. Infrastructure is unaffected. LGTM.

marcel commented 2026-05-06 23:49:53 +02:00

Author

Owner

Copy Link

📋 Elicit — Requirements Engineer

Verdict: ✅ Approved

Documentation PR. My review checks whether the diagrams serve the information needs of future developers and whether the scope matches what was promised in issue #451.

Traceability to Issue #451

The PR closes #451. Both deliverables promised in the PR description are present:

• db-relationships.puml — ER overview diagram ✓
• db-orm.puml — Full schema reference diagram ✓
• c4-diagrams.md updated with a Database section linking both ✓

Fitness for Purpose

Two-diagram strategy is well-chosen: Separating "overview for navigation" (db-relationships.puml) from "column-level reference" (db-orm.puml) matches two distinct use cases:

1. A new developer wanting to understand how domains relate — uses the relationships diagram.
2. A developer mapping Java entity fields to DB columns — uses the ORM diagram.

These are genuinely different jobs-to-be-done and warrant separate artifacts.

Intended use is documented: The c4-diagrams.md section clearly distinguishes the two diagrams' purposes with "Start here for an overview" vs "Use this when mapping Java entities to database columns." Good discoverability.

Snapshot framing is honest: Calling out "Schema as of Flyway V60 (2026-05-06)" sets appropriate expectations. The ⚠ versioned snapshot warning in the PUML headers is correct.

Advisory

• The PR description notes "excluding V37 and V43 — intentionally removed." New developers won't know what these migrations contained. A one-line comment in the PUML header explaining why they were removed (e.g., "V37, V43 were rollback/fix scripts with no net schema change") would prevent confusion. Advisory — not a blocker.
• The c4-diagrams.md now has a Database section at the bottom. If the document grows, a table of contents would help. Not needed now.

Requirements fulfilled. LGTM.

## 📋 Elicit — Requirements Engineer **Verdict: ✅ Approved** Documentation PR. My review checks whether the diagrams serve the information needs of future developers and whether the scope matches what was promised in issue #451. ### Traceability to Issue #451 The PR closes #451. Both deliverables promised in the PR description are present: - `db-relationships.puml` — ER overview diagram ✓ - `db-orm.puml` — Full schema reference diagram ✓ - `c4-diagrams.md` updated with a Database section linking both ✓ ### Fitness for Purpose **Two-diagram strategy is well-chosen**: Separating "overview for navigation" (`db-relationships.puml`) from "column-level reference" (`db-orm.puml`) matches two distinct use cases: 1. A new developer wanting to understand how domains relate — uses the relationships diagram. 2. A developer mapping Java entity fields to DB columns — uses the ORM diagram. These are genuinely different jobs-to-be-done and warrant separate artifacts. **Intended use is documented**: The `c4-diagrams.md` section clearly distinguishes the two diagrams' purposes with "Start here for an overview" vs "Use this when mapping Java entities to database columns." Good discoverability. **Snapshot framing is honest**: Calling out "Schema as of Flyway V60 (2026-05-06)" sets appropriate expectations. The `⚠ versioned snapshot` warning in the PUML headers is correct. ### Advisory - The PR description notes "excluding V37 and V43 — intentionally removed." New developers won't know what these migrations contained. A one-line comment in the PUML header explaining *why* they were removed (e.g., "V37, V43 were rollback/fix scripts with no net schema change") would prevent confusion. Advisory — not a blocker. - The `c4-diagrams.md` now has a Database section at the bottom. If the document grows, a table of contents would help. Not needed now. Requirements fulfilled. LGTM.

marcel commented 2026-05-06 23:50:04 +02:00

Author

Owner

Copy Link

🎨 Leonie Voss (@leonievoss) — UI/UX Design Lead

Verdict: ✅ Approved

Documentation-only PR — PlantUML diagrams, no UI changes. My review is scoped to whether the documentation is usable by developers as a reference for UI/UX work.

What I Checked

Relevance to frontend development: The ORM diagram's column types and nullability information directly supports frontend work — knowing which fields are nullable helps developers decide when to show placeholder states vs. guaranteed content. For example:

• persons.first_name — nullable (correct, V22). The person display component needs a fallback when first_name is absent.
• documents.file_path — nullable (shown without NOT NULL). UI must handle "no file yet" state (PLACEHOLDER status).
• documents.thumbnail_key, thumbnail_generated_at, thumbnail_aspect — all nullable. The document grid needs a fallback thumbnail state.

These are correctly represented and useful for frontend development decisions.

The search_vector : tsvector <<computed>> field in the documents ORM is correctly tagged as <<computed>>. Frontend developers should know this is not a field they set.

Advisory

• The diagrams are optimized for developer navigation, not for UX workflow mapping. If the team ever wants a diagram that shows "what data does the document detail page need," that would be a different artifact (a C4 level 4 or a sequence diagram). Not needed now, and not in scope for this PR.
• No UI impact from this PR. Purely internal tooling for developer reference.

LGTM.

## 🎨 Leonie Voss (@leonievoss) — UI/UX Design Lead **Verdict: ✅ Approved** Documentation-only PR — PlantUML diagrams, no UI changes. My review is scoped to whether the documentation is usable by developers as a reference for UI/UX work. ### What I Checked **Relevance to frontend development**: The ORM diagram's column types and nullability information directly supports frontend work — knowing which fields are nullable helps developers decide when to show placeholder states vs. guaranteed content. For example: - `persons.first_name` — nullable (correct, V22). The person display component needs a fallback when first_name is absent. - `documents.file_path` — nullable (shown without NOT NULL). UI must handle "no file yet" state (PLACEHOLDER status). - `documents.thumbnail_key`, `thumbnail_generated_at`, `thumbnail_aspect` — all nullable. The document grid needs a fallback thumbnail state. These are correctly represented and useful for frontend development decisions. **The `search_vector : tsvector <<computed>>` field** in the documents ORM is correctly tagged as `<<computed>>`. Frontend developers should know this is not a field they set. ### Advisory - The diagrams are optimized for developer navigation, not for UX workflow mapping. If the team ever wants a diagram that shows "what data does the document detail page need," that would be a different artifact (a C4 level 4 or a sequence diagram). Not needed now, and not in scope for this PR. - No UI impact from this PR. Purely internal tooling for developer reference. LGTM.

marcel merged commit ba0bfc6a7e into main 2026-05-07 07:12:31 +02:00

marcel deleted branch docs/db-diagrams 2026-05-07 07:12:33 +02:00

Sign in to join this conversation.

Reviewers

No Reviewers

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

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

Jens marcel

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#452