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

epic(legibility): documentation — make the codebase self-explaining #394

New Issue
Closed
opened 2026-05-04 16:06:37 +02:00 by marcel · 9 comments
marcel commented 2026-05-04 16:06:37 +02:00
Owner
Copy Link

Epic context

This is Epic 2 of 5 for the Codebase Legibility Refactor (see #387 for the meta-context). The goal of this epic is to replace LLM-targeted CLAUDE.md content with human-targeted documentation that lets Anja, Tobias, or any future Successor-X form a correct mental model from docs/ and code-adjacent READMEs alone, without the original author present.

This epic can run in parallel with Epic 1 (Audit) and before Epic 4 (Refactor) — docs are written against the target domain structure, not the current one.

Scope

Seven focused documentation tasks:

  • DOC-1: Human-targeted root README.md (front door)
  • DOC-2: docs/ARCHITECTURE.md with diagram and domain list
  • DOC-3: docs/GLOSSARY.md for overloaded terms (Person ≠ AppUser, etc.)
  • DOC-4: CONTRIBUTING.md with three concrete walkthroughs (add a domain / endpoint / page)
  • DOC-5: docs/DEPLOYMENT.md (production runtime + env vars + log locations)
  • DOC-6: One short README.md inside each domain package (~14 files across both stacks)
  • DOC-7: Migrate the rules sections from existing CLAUDE.md files into the human docs above; mark migrated content in CLAUDE.md as moved

Inputs

  • Reference bundle in first comment of #387 (Brief, Personas, Canonical Domain Set, Rubric)
  • Audit reports under docs/audits/ (when available — DOC-* tasks should reference findings if Epic 1 has produced them)
  • Existing CLAUDE.md files at repo root, frontend/, backend/, ocr-service/, docs/, scripts/, .devcontainer/ — these contain valuable knowledge that needs migration, not rewriting from scratch

Acceptance criteria

  • All 7 child issues are closed
  • README.md (root) is human-targeted, lists 5 subsystems, links to local-run / contribute / issues (DOC-1)
  • docs/ARCHITECTURE.md contains a diagram and names every canonical domain (DOC-2)
  • docs/GLOSSARY.md disambiguates every overloaded term in the system (DOC-3)
  • CONTRIBUTING.md contains the three walkthroughs (DOC-4)
  • docs/DEPLOYMENT.md covers all production runtime concerns (DOC-5)
  • Each canonical domain package has a short README.md on both stacks (DOC-6)
  • Every CLAUDE.md "rules" section has either been migrated to a human doc or has been justified as LLM-only (DOC-7)
  • Rubric checks C1, C2, C3, C5.1, C5.3, C7.1, C7.4, C9.1, C9.2 all PASS after this epic

Definition of Done

This epic closes when DOC-1 through DOC-7 are all closed AND the rubric checks above are verified PASS in a subsequent audit re-run (CLEANUP-5 in Epic 5 will do this).

## Epic context This is **Epic 2 of 5** for the *Codebase Legibility Refactor* (see #387 for the meta-context). The goal of this epic is to replace LLM-targeted `CLAUDE.md` content with **human-targeted documentation** that lets Anja, Tobias, or any future Successor-X form a correct mental model from `docs/` and code-adjacent READMEs *alone*, without the original author present. This epic can run **in parallel with Epic 1 (Audit)** and **before Epic 4 (Refactor)** — docs are written against the *target* domain structure, not the current one. ## Scope Seven focused documentation tasks: - **DOC-1**: Human-targeted root `README.md` (front door) - **DOC-2**: `docs/ARCHITECTURE.md` with diagram and domain list - **DOC-3**: `docs/GLOSSARY.md` for overloaded terms (Person ≠ AppUser, etc.) - **DOC-4**: `CONTRIBUTING.md` with three concrete walkthroughs (add a domain / endpoint / page) - **DOC-5**: `docs/DEPLOYMENT.md` (production runtime + env vars + log locations) - **DOC-6**: One short `README.md` inside each domain package (~14 files across both stacks) - **DOC-7**: Migrate the rules sections from existing `CLAUDE.md` files into the human docs above; mark migrated content in CLAUDE.md as moved ## Inputs - Reference bundle in **first comment of #387** (Brief, Personas, Canonical Domain Set, Rubric) - Audit reports under `docs/audits/` (when available — DOC-* tasks should reference findings if Epic 1 has produced them) - Existing `CLAUDE.md` files at repo root, `frontend/`, `backend/`, `ocr-service/`, `docs/`, `scripts/`, `.devcontainer/` — these contain valuable knowledge that needs *migration*, not rewriting from scratch ## Acceptance criteria - [ ] All 7 child issues are closed - [ ] `README.md` (root) is human-targeted, lists 5 subsystems, links to local-run / contribute / issues (DOC-1) - [ ] `docs/ARCHITECTURE.md` contains a diagram and names every canonical domain (DOC-2) - [ ] `docs/GLOSSARY.md` disambiguates every overloaded term in the system (DOC-3) - [ ] `CONTRIBUTING.md` contains the three walkthroughs (DOC-4) - [ ] `docs/DEPLOYMENT.md` covers all production runtime concerns (DOC-5) - [ ] Each canonical domain package has a short `README.md` on both stacks (DOC-6) - [ ] Every CLAUDE.md "rules" section has either been migrated to a human doc or has been justified as LLM-only (DOC-7) - [ ] Rubric checks C1, C2, C3, C5.1, C5.3, C7.1, C7.4, C9.1, C9.2 all PASS after this epic ## Definition of Done This epic closes when DOC-1 through DOC-7 are all closed AND the rubric checks above are verified PASS in a subsequent audit re-run (CLEANUP-5 in Epic 5 will do this).
marcel added this to the Codebase Legibility milestone 2026-05-04 16:06:37 +02:00
marcel added the documentationepiclegibility labels 2026-05-04 16:06:56 +02:00
marcel commented 2026-05-04 21:03:35 +02:00
Author
Owner
Copy Link

🏗️ Markus Keller — Senior Application Architect

Observations

  • ADRs already exist (docs/adr/001–006) but the root CLAUDE.md and backend/CLAUDE.md don't link to them. DOC-2 (ARCHITECTURE.md) is the right place to surface them prominently — not just as a file list but with a one-liner on each decision's consequence.
  • The C4 diagrams in docs/architecture/c4-diagrams.md cover Levels 1–3 but the existing diagram pre-dates several subsystems now visible in the codebase: OcrService, GeschichteService, TranscriptionQueueService, SseEmitterRegistry, NotificationService. DOC-2 must refresh these or the diagram is misleading.
  • The "Canonical Domain Set" referenced in #387 is the correct input to DOC-3 (Glossary). The overloaded terms needing disambiguation go beyond Person ≠ AppUser: SenderModel, Geschichte (not a standard German archive term), TranscriptionBlock vs DocumentVersion, OcrJob vs OcrBatchService vs OcrAsyncRunner. Each of these creates a mental-model gap for a newcomer.
  • Package structure drift: The root CLAUDE.md documents controller/, service/, repository/, model/, dto/, exception/, security/, config/ — but the actual codebase also has audit/, dashboard/, relationship/. DOC-2 and the backend domain READMEs (DOC-6) must document actual structure, not the wishlist from CLAUDE.md.
  • DOC-4 (CONTRIBUTING.md walkthroughs) is the highest-leverage document in this epic. The three walkthroughs (add a domain / endpoint / page) are the mental model compression that lets Anja understand the system in an afternoon. Make these walkthrough narratives trace a real, small domain end-to-end — I'd recommend Tag as the example: it has a controller, service, repository, migration, and frontend component all small enough to read in one sitting.

Recommendations

  • DOC-2: Update the C4 Level 2 container diagram to include the OCR service container (Python, port 8000). It's a separate deployable unit with a different tech stack. It belongs in the container diagram.
  • DOC-2: In the component diagram, add GeschichteService and TranscriptionQueueService as they represent significant domain areas not in the original diagram.
  • DOC-3: Lead with the three most dangerous confusions: Person ≠ AppUser, Geschichte (domain-specific meaning), TranscriptionBlock (not a document version). These cause the most incorrect mental models.
  • DOC-6: For the 14 domain-package READMEs, follow a fixed template — three sections only: What this domain owns, What it exposes (public API), What it depends on. Anything longer becomes a maintenance burden.
  • DOC-7: The migration rules from backend/CLAUDE.md — Flyway naming convention, layering rules, @Transactional policy — belong in CONTRIBUTING.md DOC-4, not in a separate doc. Migrate them there rather than creating a fourth location.
  • Write DOC-4's walkthroughs against the actual package structure (audit/, dashboard/, relationship/ exist) so newcomers don't hit the first contradiction on day one.
## 🏗️ Markus Keller — Senior Application Architect ### Observations - **ADRs already exist** (`docs/adr/001–006`) but the root `CLAUDE.md` and `backend/CLAUDE.md` don't link to them. DOC-2 (`ARCHITECTURE.md`) is the right place to surface them prominently — not just as a file list but with a one-liner on each decision's consequence. - **The C4 diagrams** in `docs/architecture/c4-diagrams.md` cover Levels 1–3 but the existing diagram pre-dates several subsystems now visible in the codebase: `OcrService`, `GeschichteService`, `TranscriptionQueueService`, `SseEmitterRegistry`, `NotificationService`. DOC-2 must refresh these or the diagram is misleading. - **The "Canonical Domain Set"** referenced in #387 is the correct input to DOC-3 (Glossary). The overloaded terms needing disambiguation go beyond Person ≠ AppUser: `SenderModel`, `Geschichte` (not a standard German archive term), `TranscriptionBlock` vs `DocumentVersion`, `OcrJob` vs `OcrBatchService` vs `OcrAsyncRunner`. Each of these creates a mental-model gap for a newcomer. - **Package structure drift**: The root CLAUDE.md documents `controller/`, `service/`, `repository/`, `model/`, `dto/`, `exception/`, `security/`, `config/` — but the actual codebase also has `audit/`, `dashboard/`, `relationship/`. DOC-2 and the backend domain READMEs (DOC-6) must document actual structure, not the wishlist from CLAUDE.md. - **DOC-4 (CONTRIBUTING.md walkthroughs)** is the highest-leverage document in this epic. The three walkthroughs (add a domain / endpoint / page) are the mental model compression that lets Anja understand the system in an afternoon. Make these walkthrough narratives trace a real, small domain end-to-end — I'd recommend `Tag` as the example: it has a controller, service, repository, migration, and frontend component all small enough to read in one sitting. ### Recommendations - **DOC-2**: Update the C4 Level 2 container diagram to include the OCR service container (Python, port 8000). It's a separate deployable unit with a different tech stack. It belongs in the container diagram. - **DOC-2**: In the component diagram, add `GeschichteService` and `TranscriptionQueueService` as they represent significant domain areas not in the original diagram. - **DOC-3**: Lead with the three most dangerous confusions: Person ≠ AppUser, Geschichte (domain-specific meaning), TranscriptionBlock (not a document version). These cause the most incorrect mental models. - **DOC-6**: For the 14 domain-package READMEs, follow a fixed template — three sections only: What this domain owns, What it exposes (public API), What it depends on. Anything longer becomes a maintenance burden. - **DOC-7**: The migration rules from `backend/CLAUDE.md` — Flyway naming convention, layering rules, `@Transactional` policy — belong in `CONTRIBUTING.md` DOC-4, not in a separate doc. Migrate them there rather than creating a fourth location. - **Write DOC-4's walkthroughs against the actual package structure** (`audit/`, `dashboard/`, `relationship/` exist) so newcomers don't hit the first contradiction on day one.
marcel commented 2026-05-04 21:03:51 +02:00
Author
Owner
Copy Link

👨‍💻 Felix Brandt — Senior Fullstack Developer

Observations

  • DOC-7 scope is larger than the issue implies. I counted CLAUDE.md files at: repo root, backend/, frontend/, frontend/e2e/, ocr-service/, docs/, scripts/, .devcontainer/, infra/, import/. That's 10 files. Many contain actionable implementation rules (e.g., frontend CLAUDE.md documents the PersonTypeahead, PersonMultiSelect, TagInput component APIs and the $derived/$effect guidance). These rules need to survive migration intact — they are currently the most reliable source of "how to do X in this codebase."
  • The CONTRIBUTING.md walkthroughs (DOC-4) need to cover the SvelteKit side, not just the backend. A frontend-only newcomer tracing "add a page" needs the load function → typed API client → component → form action pattern documented as a concrete walkthrough. The issue only lists "add a domain / endpoint / page" — the third walkthrough should be "add a SvelteKit route with data loading, a form action, and error handling."
  • docs/STYLEGUIDE.md already exists and overlaps with what DOC-4's code-style content would contain. Before writing CONTRIBUTING.md, check what's in STYLEGUIDE.md to avoid a third source of truth for the same rules.
  • Frontend package structure drift: frontend/CLAUDE.md documents briefwechsel/ but calling it /conversations/ in the root CLAUDE.md. The route is actually briefwechsel/ (confirmed via CLAUDE.md frontmatter). DOC-1 and CONTRIBUTING.md must use the actual route names.

Recommendations

  • DOC-4: Write the third walkthrough as "Add a new SvelteKit route with SSR data loading" tracing: +page.server.ts load → typed createApiClient call → !result.response.ok guard → +page.svelte with $props() → error state. This is the pattern every frontend change follows.
  • DOC-7: For each CLAUDE.md file, categorize rules into: (a) LLM workflow instructions (stays in CLAUDE.md), (b) architecture decisions (goes to ARCHITECTURE.md or relevant ADR), (c) implementation conventions (goes to CONTRIBUTING.md or domain README). Never duplicate — pick one home per rule.
  • DOC-6 frontend domain READMEs: These should live inside src/lib/components/ subdirectories (document/, chronik/, user/) not just at the package level, since that's where a newcomer lands when following an import path.
  • Check docs/STYLEGUIDE.md before drafting DOC-4 — migrate its non-duplicated content, then either archive it or replace it with a pointer to CONTRIBUTING.md. Three style-guide sources are worse than one.
## 👨‍💻 Felix Brandt — Senior Fullstack Developer ### Observations - **DOC-7 scope is larger than the issue implies.** I counted CLAUDE.md files at: repo root, `backend/`, `frontend/`, `frontend/e2e/`, `ocr-service/`, `docs/`, `scripts/`, `.devcontainer/`, `infra/`, `import/`. That's 10 files. Many contain actionable implementation rules (e.g., frontend CLAUDE.md documents the `PersonTypeahead`, `PersonMultiSelect`, `TagInput` component APIs and the `$derived`/`$effect` guidance). These rules need to survive migration intact — they are currently the most reliable source of "how to do X in this codebase." - **The CONTRIBUTING.md walkthroughs (DOC-4) need to cover the SvelteKit side**, not just the backend. A frontend-only newcomer tracing "add a page" needs the load function → typed API client → component → form action pattern documented as a concrete walkthrough. The issue only lists "add a domain / endpoint / page" — the third walkthrough should be "add a SvelteKit route with data loading, a form action, and error handling." - **`docs/STYLEGUIDE.md` already exists** and overlaps with what DOC-4's code-style content would contain. Before writing CONTRIBUTING.md, check what's in STYLEGUIDE.md to avoid a third source of truth for the same rules. - **Frontend package structure drift**: `frontend/CLAUDE.md` documents `briefwechsel/` but calling it `/conversations/` in the root CLAUDE.md. The route is actually `briefwechsel/` (confirmed via CLAUDE.md frontmatter). DOC-1 and CONTRIBUTING.md must use the actual route names. ### Recommendations - **DOC-4**: Write the third walkthrough as "Add a new SvelteKit route with SSR data loading" tracing: `+page.server.ts` load → typed `createApiClient` call → `!result.response.ok` guard → `+page.svelte` with `$props()` → error state. This is the pattern every frontend change follows. - **DOC-7**: For each CLAUDE.md file, categorize rules into: (a) LLM workflow instructions (stays in CLAUDE.md), (b) architecture decisions (goes to ARCHITECTURE.md or relevant ADR), (c) implementation conventions (goes to CONTRIBUTING.md or domain README). Never duplicate — pick one home per rule. - **DOC-6 frontend domain READMEs**: These should live inside `src/lib/components/` subdirectories (`document/`, `chronik/`, `user/`) not just at the package level, since that's where a newcomer lands when following an import path. - **Check `docs/STYLEGUIDE.md` before drafting DOC-4** — migrate its non-duplicated content, then either archive it or replace it with a pointer to CONTRIBUTING.md. Three style-guide sources are worse than one.
marcel commented 2026-05-04 21:04:08 +02:00
Author
Owner
Copy Link

🔒 Nora "NullX" Steiner — Application Security Engineer

Observations

  • DOC-5 (DEPLOYMENT.md) must cover secret management explicitly. The existing backend/CLAUDE.md and the root CLAUDE.md give no guidance on which environment variables contain secrets, what their expected formats are, or what happens if they're missing. A newcomer setting up the stack will cargo-cult from .env.example and may accidentally use dev defaults in production. The doc needs a "non-negotiable before going live" checklist.
  • The OCR service security surface is undocumented. ocr-service/CLAUDE.md exists but the root CLAUDE.md doesn't describe the OCR service's auth model (X-Training-Token header for the training endpoint). DOC-5 or a dedicated OCR service README (DOC-6) must document: which OCR endpoints are unauthenticated, which require the training token, and where that token must be set.
  • DOC-3 (Glossary) should define Permission enum values. READ_ALL, WRITE_ALL, ADMIN, ADMIN_USER, ADMIN_TAG, ADMIN_PERMISSION are opaque to someone reading the codebase for the first time. What does ADMIN grant vs ADMIN_USER? The security model's mental map belongs in the glossary or a dedicated security section of ARCHITECTURE.md.
  • docs/security-guide.md already exists at the repo root. DOC-5 or DOC-2 should link to it rather than duplicating production security concerns. But the security guide must itself be reviewed as part of DOC-7 — it may contain stale CLAUDE.md-style guidance that needs migration.

Recommendations

  • DOC-5: Include a dedicated "Secrets checklist" section: list every env var that must be set before production deployment (DB password, MinIO credentials, Spring Session secret, OCR training token, MinIO root user/password), mark which ones fail-fast if missing vs. fall back to dev defaults (the latter are the dangerous ones).
  • DOC-5: Document the MinIO service-account principle — the application should not use root MinIO credentials. If this hasn't been implemented yet, DOC-5 should flag it as "production hardening required."
  • DOC-2 or a dedicated security section: Document the @RequirePermission + PermissionAspect mechanism and the permission hierarchy. Anja needs to know this before she can safely add a new endpoint.
  • DOC-7: Check scripts/CLAUDE.md and infra/CLAUDE.md for any hardcoded test credentials or dev secrets that have drifted into those files. Migrate the legitimate content; delete the sensitive bits from the committed history if any exist.
## 🔒 Nora "NullX" Steiner — Application Security Engineer ### Observations - **DOC-5 (DEPLOYMENT.md) must cover secret management explicitly.** The existing `backend/CLAUDE.md` and the root CLAUDE.md give no guidance on which environment variables contain secrets, what their expected formats are, or what happens if they're missing. A newcomer setting up the stack will cargo-cult from `.env.example` and may accidentally use dev defaults in production. The doc needs a "non-negotiable before going live" checklist. - **The OCR service security surface is undocumented.** `ocr-service/CLAUDE.md` exists but the root CLAUDE.md doesn't describe the OCR service's auth model (`X-Training-Token` header for the training endpoint). DOC-5 or a dedicated OCR service README (DOC-6) must document: which OCR endpoints are unauthenticated, which require the training token, and where that token must be set. - **DOC-3 (Glossary) should define `Permission` enum values.** `READ_ALL`, `WRITE_ALL`, `ADMIN`, `ADMIN_USER`, `ADMIN_TAG`, `ADMIN_PERMISSION` are opaque to someone reading the codebase for the first time. What does `ADMIN` grant vs `ADMIN_USER`? The security model's mental map belongs in the glossary or a dedicated security section of ARCHITECTURE.md. - **`docs/security-guide.md` already exists** at the repo root. DOC-5 or DOC-2 should link to it rather than duplicating production security concerns. But the security guide must itself be reviewed as part of DOC-7 — it may contain stale CLAUDE.md-style guidance that needs migration. ### Recommendations - **DOC-5**: Include a dedicated "Secrets checklist" section: list every env var that must be set before production deployment (DB password, MinIO credentials, Spring Session secret, OCR training token, MinIO root user/password), mark which ones fail-fast if missing vs. fall back to dev defaults (the latter are the dangerous ones). - **DOC-5**: Document the MinIO service-account principle — the application should not use root MinIO credentials. If this hasn't been implemented yet, DOC-5 should flag it as "production hardening required." - **DOC-2 or a dedicated security section**: Document the `@RequirePermission` + `PermissionAspect` mechanism and the permission hierarchy. Anja needs to know this before she can safely add a new endpoint. - **DOC-7**: Check `scripts/CLAUDE.md` and `infra/CLAUDE.md` for any hardcoded test credentials or dev secrets that have drifted into those files. Migrate the legitimate content; delete the sensitive bits from the committed history if any exist.
marcel commented 2026-05-04 21:04:26 +02:00
Author
Owner
Copy Link

🧪 Sara Holt — Senior QA Engineer

Observations

  • No DOC- task covers the test strategy.* A new contributor reading only DOC-1 through DOC-7 will have no idea where the test suite lives, what layers exist, or how to run them. The test pyramid for this project (Vitest unit, @WebMvcTest slices, Testcontainers integration, Playwright E2E) is not documented in any of the seven planned docs. DOC-4 (CONTRIBUTING.md) is the natural home.
  • CI pipeline is documented in docs/infrastructure/ci-gitea.md, but it's unclear whether that document covers test execution order, quality gates, or what blocks a merge. A newcomer won't know to look there for test strategy.
  • 57 Flyway migrations exist (V1–V59, with some gaps). The existence and naming convention are mentioned in CLAUDE.md, but the rationale for the migration-first approach (no DDL outside migrations) needs a permanent human-readable home — CONTRIBUTING.md DOC-4 or the backend domain README.
  • docs/audits/ doesn't exist yet (confirmed by ls). DOC-* tasks reference audit findings as inputs — but Epic 1 (Audit) may not complete before or alongside this epic. The acceptance criteria for DOC-2/DOC-3 that say "reference findings if Epic 1 has produced them" will need a fallback — what does a complete DOC-2 look like if no audit findings are available?

Recommendations

  • DOC-4 (CONTRIBUTING.md): Add a "Testing" section with: the test pyramid for this stack, how to run each layer (./mvnw test, npm run test, npm run test:e2e), what quality gates exist, and the TDD expectation (red/green/refactor). This is the single most important thing a contributor needs after understanding architecture.
  • DOC-4: Document the E2E auth setup — frontend/e2e/.auth/user.json stores authenticated state. A newcomer running Playwright without this setup gets confusing failures. Explain how to regenerate it (npm run test:e2e -- --headed).
  • Acceptance criteria gap: Add an explicit AC: "DOC-4 contains a 'How to run tests' section covering all four layers." Currently no AC requires test documentation.
  • DOC-7 for frontend/e2e/CLAUDE.md: The e2e CLAUDE.md likely contains test-running instructions and seed-data expectations. These should migrate to DOC-4 rather than being marked "LLM-only."
## 🧪 Sara Holt — Senior QA Engineer ### Observations - **No DOC-* task covers the test strategy.** A new contributor reading only DOC-1 through DOC-7 will have no idea where the test suite lives, what layers exist, or how to run them. The test pyramid for this project (Vitest unit, `@WebMvcTest` slices, Testcontainers integration, Playwright E2E) is not documented in any of the seven planned docs. DOC-4 (CONTRIBUTING.md) is the natural home. - **CI pipeline is documented** in `docs/infrastructure/ci-gitea.md`, but it's unclear whether that document covers test execution order, quality gates, or what blocks a merge. A newcomer won't know to look there for test strategy. - **57 Flyway migrations** exist (V1–V59, with some gaps). The existence and naming convention are mentioned in CLAUDE.md, but the rationale for the migration-first approach (no DDL outside migrations) needs a permanent human-readable home — CONTRIBUTING.md DOC-4 or the backend domain README. - **`docs/audits/` doesn't exist yet** (confirmed by `ls`). DOC-* tasks reference audit findings as inputs — but Epic 1 (Audit) may not complete before or alongside this epic. The acceptance criteria for DOC-2/DOC-3 that say "reference findings if Epic 1 has produced them" will need a fallback — what does a complete DOC-2 look like if no audit findings are available? ### Recommendations - **DOC-4 (CONTRIBUTING.md)**: Add a "Testing" section with: the test pyramid for this stack, how to run each layer (`./mvnw test`, `npm run test`, `npm run test:e2e`), what quality gates exist, and the TDD expectation (red/green/refactor). This is the single most important thing a contributor needs after understanding architecture. - **DOC-4**: Document the E2E auth setup — `frontend/e2e/.auth/user.json` stores authenticated state. A newcomer running Playwright without this setup gets confusing failures. Explain how to regenerate it (`npm run test:e2e -- --headed`). - **Acceptance criteria gap**: Add an explicit AC: "DOC-4 contains a 'How to run tests' section covering all four layers." Currently no AC requires test documentation. - **DOC-7 for `frontend/e2e/CLAUDE.md`**: The e2e CLAUDE.md likely contains test-running instructions and seed-data expectations. These should migrate to DOC-4 rather than being marked "LLM-only."
marcel commented 2026-05-04 21:04:47 +02:00
Author
Owner
Copy Link

🎨 Leonie Voss — UX Designer & Accessibility Strategist

Observations

  • This epic produces developer-facing documentation, not user-facing UI. My review focuses on whether the docs themselves will be legible and navigable for their audience (Anja the backend dev, Tobias the PM-with-CS).
  • DOC-1 (root README.md) is the first impression for every contributor. The current repo root has no README.md. That means someone cloning the repo for the first time sees a wall of files: docker-compose.yml, CLAUDE.md, CODESTYLE.md, COLLABORATING.md, CODESTYLE.md (duplicate in git status). The README needs to answer "what is this, how do I run it, and where do I go next" within the first 20 lines.
  • DOC-4 (CONTRIBUTING.md) has three walkthroughs. Three walkthroughs in one document is a navigation challenge. Each walkthrough could be a self-contained section with a clear heading so readers can jump directly to "add an endpoint" without reading "add a domain" first.
  • docs/STYLEGUIDE.md exists but docs/CLAUDE.md also exists. From Tobias's perspective (PM-with-CS), two docs-about-docs create confusion about where to look for design/style decisions. DOC-7 should resolve this by establishing a clear single location.
  • The Seven docs in this epic have no linking strategy. DOC-1 (README) links to what? DOC-2 (ARCHITECTURE) links to which ADRs? Without explicit cross-linking between documents, the "documentation system" is just seven separate files that happen to be in the same repo.

Recommendations

  • DOC-1: Structure the README around three reader journeys: (1) "I want to run it locally" → points to Docker Compose command + CONTRIBUTING.md, (2) "I want to understand the system" → points to docs/ARCHITECTURE.md, (3) "I want to contribute" → points to CONTRIBUTING.md. Three journeys, three paragraphs, done.
  • DOC-1: List the five subsystems (frontend, backend, OCR service, PostgreSQL, MinIO/S3) with one-line descriptions. This is the top-level mental model that every other doc assumes.
  • Cross-linking convention: Each doc should have a "See also" footer with explicit links to related docs. ARCHITECTURE.md → ADR index, CONTRIBUTING.md → ARCHITECTURE.md, DEPLOYMENT.md → security-guide.md.
  • DOC-4 walkthroughs: Use H2 section headings (## Walkthrough: Add a New Domain, ## Walkthrough: Add an API Endpoint, ## Walkthrough: Add a SvelteKit Route) so they appear in the GitHub/Gitea table of contents and can be linked to directly.
  • No concern about accessibility or brand here — this is developer documentation. Plain, well-structured Markdown wins over styled content every time for this audience.
## 🎨 Leonie Voss — UX Designer & Accessibility Strategist ### Observations - This epic produces developer-facing documentation, not user-facing UI. My review focuses on whether the docs themselves will be legible and navigable for their audience (Anja the backend dev, Tobias the PM-with-CS). - **DOC-1 (root README.md) is the first impression for every contributor.** The current repo root has no README.md. That means someone cloning the repo for the first time sees a wall of files: `docker-compose.yml`, `CLAUDE.md`, `CODESTYLE.md`, `COLLABORATING.md`, `CODESTYLE.md` (duplicate in git status). The README needs to answer "what is this, how do I run it, and where do I go next" within the first 20 lines. - **DOC-4 (CONTRIBUTING.md) has three walkthroughs.** Three walkthroughs in one document is a navigation challenge. Each walkthrough could be a self-contained section with a clear heading so readers can jump directly to "add an endpoint" without reading "add a domain" first. - **`docs/STYLEGUIDE.md` exists but `docs/CLAUDE.md` also exists.** From Tobias's perspective (PM-with-CS), two docs-about-docs create confusion about where to look for design/style decisions. DOC-7 should resolve this by establishing a clear single location. - **The Seven docs in this epic have no linking strategy.** DOC-1 (README) links to what? DOC-2 (ARCHITECTURE) links to which ADRs? Without explicit cross-linking between documents, the "documentation system" is just seven separate files that happen to be in the same repo. ### Recommendations - **DOC-1**: Structure the README around three reader journeys: (1) "I want to run it locally" → points to Docker Compose command + `CONTRIBUTING.md`, (2) "I want to understand the system" → points to `docs/ARCHITECTURE.md`, (3) "I want to contribute" → points to `CONTRIBUTING.md`. Three journeys, three paragraphs, done. - **DOC-1**: List the five subsystems (frontend, backend, OCR service, PostgreSQL, MinIO/S3) with one-line descriptions. This is the top-level mental model that every other doc assumes. - **Cross-linking convention**: Each doc should have a "See also" footer with explicit links to related docs. ARCHITECTURE.md → ADR index, CONTRIBUTING.md → ARCHITECTURE.md, DEPLOYMENT.md → security-guide.md. - **DOC-4 walkthroughs**: Use H2 section headings (`## Walkthrough: Add a New Domain`, `## Walkthrough: Add an API Endpoint`, `## Walkthrough: Add a SvelteKit Route`) so they appear in the GitHub/Gitea table of contents and can be linked to directly. - **No concern about accessibility or brand here** — this is developer documentation. Plain, well-structured Markdown wins over styled content every time for this audience.
marcel commented 2026-05-04 21:05:11 +02:00
Author
Owner
Copy Link

🖥️ Tobias Wendt — DevOps & Platform Engineer

Observations

  • docs/infrastructure/ already has all four files (ci-gitea.md, production-compose.md, s3-migration.md, self-hosted-catalogue.md). DOC-5 (DEPLOYMENT.md) risks creating a fifth overlapping source. The better approach is DOC-5 as a single-page entry point that links into the existing infrastructure docs rather than duplicating them.
  • infra/CLAUDE.md exists (untracked in git status). Its content needs to be reviewed as part of DOC-7 — it may contain production-relevant infrastructure rules that belong in docs/infrastructure/production-compose.md rather than a CLAUDE.md.
  • The OCR service's deployment profile is undocumented in the root. ocr-service/Dockerfile and ocr-service/CLAUDE.md exist, but the root CLAUDE.md describes only docker-compose up -d for the three core services (PostgreSQL, MinIO, Spring Boot). The OCR service — which has an 8GB memory limit, a 60-second startup due to model loading, and a training token requirement — is invisible in the current developer-facing documentation.
  • scripts/ directory has clean-e2e-data.sh, download-paperless.sh, flatten-paperless.sh, reset-db.sh, scripts/CLAUDE.md. These operational scripts have no human-readable documentation. DOC-4 or DOC-5 should document what each script does and when to use it.

Recommendations

  • DOC-5: Structure as a "Day 1 production checklist" rather than a reference manual. Operators need sequential steps, not encyclopedic coverage. Sections: Prerequisites, Environment variables (must-set vs optional), docker compose up on the production overlay, Health verification, First-run database seed.
  • DOC-5: Link to docs/infrastructure/production-compose.md for the full Compose file details rather than duplicating it. DOC-5 is the entry point; the infrastructure docs are the reference.
  • DOC-6: The OCR service README is not just a package-level file — it needs a section on startup behavior: "The service takes 30–60 seconds to become healthy on cold start due to model loading. The health endpoint is /health. The training endpoint requires X-Training-Token."
  • DOC-7 for scripts/CLAUDE.md: The reset-db and clean-e2e-data scripts are operationally significant. Their migration target is CONTRIBUTING.md ("Development scripts") or DOC-5 ("Operational scripts"), not deletion. Flag which is which before migrating.
  • Monthly cost: The "~23 EUR/month" figure in my notes should appear somewhere in DOC-5 or DOC-1 so future maintainers understand the infrastructure budget when evaluating changes.
## 🖥️ Tobias Wendt — DevOps & Platform Engineer ### Observations - **`docs/infrastructure/` already has all four files** (`ci-gitea.md`, `production-compose.md`, `s3-migration.md`, `self-hosted-catalogue.md`). DOC-5 (DEPLOYMENT.md) risks creating a fifth overlapping source. The better approach is DOC-5 as a single-page entry point that links into the existing infrastructure docs rather than duplicating them. - **`infra/CLAUDE.md` exists** (untracked in git status). Its content needs to be reviewed as part of DOC-7 — it may contain production-relevant infrastructure rules that belong in `docs/infrastructure/production-compose.md` rather than a CLAUDE.md. - **The OCR service's deployment profile is undocumented in the root.** `ocr-service/Dockerfile` and `ocr-service/CLAUDE.md` exist, but the root CLAUDE.md describes only `docker-compose up -d` for the three core services (PostgreSQL, MinIO, Spring Boot). The OCR service — which has an 8GB memory limit, a 60-second startup due to model loading, and a training token requirement — is invisible in the current developer-facing documentation. - **`scripts/` directory** has `clean-e2e-data.sh`, `download-paperless.sh`, `flatten-paperless.sh`, `reset-db.sh`, `scripts/CLAUDE.md`. These operational scripts have no human-readable documentation. DOC-4 or DOC-5 should document what each script does and when to use it. ### Recommendations - **DOC-5**: Structure as a "Day 1 production checklist" rather than a reference manual. Operators need sequential steps, not encyclopedic coverage. Sections: Prerequisites, Environment variables (must-set vs optional), `docker compose up` on the production overlay, Health verification, First-run database seed. - **DOC-5**: Link to `docs/infrastructure/production-compose.md` for the full Compose file details rather than duplicating it. DOC-5 is the entry point; the infrastructure docs are the reference. - **DOC-6**: The OCR service README is not just a package-level file — it needs a section on startup behavior: "The service takes 30–60 seconds to become healthy on cold start due to model loading. The health endpoint is `/health`. The training endpoint requires `X-Training-Token`." - **DOC-7 for `scripts/CLAUDE.md`**: The reset-db and clean-e2e-data scripts are operationally significant. Their migration target is CONTRIBUTING.md ("Development scripts") or DOC-5 ("Operational scripts"), not deletion. Flag which is which before migrating. - **Monthly cost**: The "~23 EUR/month" figure in my notes should appear somewhere in DOC-5 or DOC-1 so future maintainers understand the infrastructure budget when evaluating changes.
marcel commented 2026-05-04 21:05:37 +02:00
Author
Owner
Copy Link

📋 Elicit — Requirements Engineer

Observations

Scope clarity issues:

  • DOC-5 and the existing docs/infrastructure/ docs have undefined overlap. production-compose.md and s3-migration.md already exist. The acceptance criterion for DOC-5 ("covers all production runtime concerns") is ambiguous: does it duplicate what's in these files, supersede them, or link to them? This is untestable as written.
  • DOC-7 has no definition of "migrated." The AC says "every CLAUDE.md rules section has either been migrated to a human doc or has been justified as LLM-only." But "migrated" is undefined: does it mean the content is verbatim-copied, rewritten for a human audience, or summarized? Does the CLAUDE.md section get deleted, annotated with a pointer, or left as-is? Without this definition, two implementers will produce different results.
  • "~14 files" for DOC-6 is stated but not enumerated. Which 14 domain packages need READMEs on the backend? Which on the frontend? The codebase has controller/, service/, repository/, model/, dto/, exception/, security/, config/, audit/, dashboard/, relationship/ on the backend — that's 11. On the frontend, components/document/, components/chronik/, components/user/, routes subdirectories. The actual list differs from the estimate and affects scope.

Missing acceptance criteria:

  • DOC-4 has no AC for the three walkthroughs being verifiable end-to-end. "Contains the three walkthroughs" is an output check, not a behavior check. Add: "A developer following walkthrough 1 can create a new domain with a passing test in under 2 hours."
  • No AC checks for stale content after DOC-7. After migration, how do we verify no CLAUDE.md still contains rules that should have moved? The rubric checks (C1, C2, C3, etc.) partially address this but the rubric isn't reproduced in this issue.
  • DOC-3 Glossary has no AC for completeness. "Disambiguates every overloaded term" is untestable without a reference list of overloaded terms. The Canonical Domain Set from #387 first comment is that reference list — link it explicitly in this issue.

Recommendations

  • DOC-5: Rewrite the AC as: "A developer who has never run this system can follow DOC-5 alone to bring the production stack to a healthy state on a fresh VPS." This is testable — either you can or you can't.
  • DOC-7: Define "migrated" in the issue body: "Content is moved to the target human doc, the original CLAUDE.md section is replaced with a pointer (e.g., # Layering Rules → See CONTRIBUTING.md#backend-walkthrough), and the CLAUDE.md retains only LLM workflow instructions." This makes the AC auditable.
  • DOC-6: Enumerate the actual 14 target packages before implementation starts. The mismatch between the issue's estimate and the real codebase will surface as scope creep mid-sprint if not resolved now.
  • Add an explicit dependency note: DOC-3 depends on the Canonical Domain Set (in #387 first comment). If that comment is lost or changes, DOC-3 loses its input. Reference the specific rubric and domain set by quoting them in the child issue for DOC-3, not just linking to the parent epic.
## 📋 Elicit — Requirements Engineer ### Observations **Scope clarity issues:** - **DOC-5 and the existing `docs/infrastructure/` docs have undefined overlap.** `production-compose.md` and `s3-migration.md` already exist. The acceptance criterion for DOC-5 ("covers all production runtime concerns") is ambiguous: does it duplicate what's in these files, supersede them, or link to them? This is untestable as written. - **DOC-7 has no definition of "migrated."** The AC says "every CLAUDE.md rules section has either been migrated to a human doc or has been justified as LLM-only." But "migrated" is undefined: does it mean the content is verbatim-copied, rewritten for a human audience, or summarized? Does the CLAUDE.md section get deleted, annotated with a pointer, or left as-is? Without this definition, two implementers will produce different results. - **"~14 files" for DOC-6 is stated but not enumerated.** Which 14 domain packages need READMEs on the backend? Which on the frontend? The codebase has `controller/`, `service/`, `repository/`, `model/`, `dto/`, `exception/`, `security/`, `config/`, `audit/`, `dashboard/`, `relationship/` on the backend — that's 11. On the frontend, `components/document/`, `components/chronik/`, `components/user/`, routes subdirectories. The actual list differs from the estimate and affects scope. **Missing acceptance criteria:** - **DOC-4 has no AC for the three walkthroughs being verifiable end-to-end.** "Contains the three walkthroughs" is an output check, not a behavior check. Add: "A developer following walkthrough 1 can create a new domain with a passing test in under 2 hours." - **No AC checks for stale content after DOC-7.** After migration, how do we verify no CLAUDE.md still contains rules that should have moved? The rubric checks (C1, C2, C3, etc.) partially address this but the rubric isn't reproduced in this issue. - **DOC-3 Glossary has no AC for completeness.** "Disambiguates every overloaded term" is untestable without a reference list of overloaded terms. The Canonical Domain Set from #387 first comment is that reference list — link it explicitly in this issue. ### Recommendations - **DOC-5**: Rewrite the AC as: "A developer who has never run this system can follow DOC-5 alone to bring the production stack to a healthy state on a fresh VPS." This is testable — either you can or you can't. - **DOC-7**: Define "migrated" in the issue body: "Content is moved to the target human doc, the original CLAUDE.md section is replaced with a pointer (e.g., `# Layering Rules → See CONTRIBUTING.md#backend-walkthrough`), and the CLAUDE.md retains only LLM workflow instructions." This makes the AC auditable. - **DOC-6**: Enumerate the actual 14 target packages before implementation starts. The mismatch between the issue's estimate and the real codebase will surface as scope creep mid-sprint if not resolved now. - **Add an explicit dependency note**: DOC-3 depends on the Canonical Domain Set (in #387 first comment). If that comment is lost or changes, DOC-3 loses its input. Reference the specific rubric and domain set by quoting them in the child issue for DOC-3, not just linking to the parent epic.
marcel commented 2026-05-04 21:06:22 +02:00
Author
Owner
Copy Link

🗳️ Decision Queue — Action Required

4 decisions need your input before implementation starts.

Scope

  • DOC-5 vs. existing docs/infrastructure/ docs — production-compose.md, s3-migration.md, ci-gitea.md, and self-hosted-catalogue.md already exist and cover substantial production runtime concerns. Does DOC-5 (a) supersede and consolidate them into one file, (b) become a thin entry-point that links into those files, or (c) duplicate them? Option (a) costs more to write but creates one canonical source; option (b) is cheap but depends on those files being complete and maintained; option (c) creates long-term drift. (Raised by: Tobias, Elicit)

  • DOC-6 package enumeration — what exactly are the "~14 files"? The backend has at least 11 Java packages (controller, service, repository, model, dto, exception, security, config, audit, dashboard, relationship), and the frontend has several component subdirectories. The estimate of 14 is likely off. Enumerate the exact target list before child issues are created, or implementations will have mismatched scope. (Raised by: Elicit)

Process

  • DOC-7 definition of "migrated" — When a CLAUDE.md rule moves to a human doc, does the CLAUDE.md section (a) get deleted entirely, (b) get replaced with a pointer comment (# → CONTRIBUTING.md#backend-layering), or (c) remain as-is with only a note marking it as migrated? Option (b) is recommended because it preserves CLAUDE.md's utility for LLM agents while making the human doc the canonical source. But this needs an explicit decision so all DOC-7 work is consistent. (Raised by: Felix, Elicit)

  • CONTRIBUTING.md walkthrough #3 — backend "add a page" or frontend SvelteKit route? The issue says "add a domain / endpoint / page" but doesn't specify if "page" means a Spring MVC controller endpoint or a SvelteKit route. Anja (backend dev persona) needs a backend walkthrough; Tobias (PM-with-CS) needs the frontend walkthrough. Both audiences are served by different content. Options: (a) two walkthroughs for "page" (one each), (b) one walkthrough that covers a full vertical slice end-to-end (migration → service → controller → SvelteKit load → component). Option (b) is higher effort but closes the mental model gap in one document. (Raised by: Felix, Markus)

## 🗳️ Decision Queue — Action Required _4 decisions need your input before implementation starts._ ### Scope - **DOC-5 vs. existing `docs/infrastructure/` docs** — `production-compose.md`, `s3-migration.md`, `ci-gitea.md`, and `self-hosted-catalogue.md` already exist and cover substantial production runtime concerns. Does DOC-5 (a) supersede and consolidate them into one file, (b) become a thin entry-point that links into those files, or (c) duplicate them? Option (a) costs more to write but creates one canonical source; option (b) is cheap but depends on those files being complete and maintained; option (c) creates long-term drift. _(Raised by: Tobias, Elicit)_ - **DOC-6 package enumeration — what exactly are the "~14 files"?** The backend has at least 11 Java packages (`controller`, `service`, `repository`, `model`, `dto`, `exception`, `security`, `config`, `audit`, `dashboard`, `relationship`), and the frontend has several component subdirectories. The estimate of 14 is likely off. Enumerate the exact target list before child issues are created, or implementations will have mismatched scope. _(Raised by: Elicit)_ ### Process - **DOC-7 definition of "migrated"** — When a CLAUDE.md rule moves to a human doc, does the CLAUDE.md section (a) get deleted entirely, (b) get replaced with a pointer comment (`# → CONTRIBUTING.md#backend-layering`), or (c) remain as-is with only a note marking it as migrated? Option (b) is recommended because it preserves CLAUDE.md's utility for LLM agents while making the human doc the canonical source. But this needs an explicit decision so all DOC-7 work is consistent. _(Raised by: Felix, Elicit)_ - **CONTRIBUTING.md walkthrough #3 — backend "add a page" or frontend SvelteKit route?** The issue says "add a domain / endpoint / page" but doesn't specify if "page" means a Spring MVC controller endpoint or a SvelteKit route. Anja (backend dev persona) needs a backend walkthrough; Tobias (PM-with-CS) needs the frontend walkthrough. Both audiences are served by different content. Options: (a) two walkthroughs for "page" (one each), (b) one walkthrough that covers a full vertical slice end-to-end (migration → service → controller → SvelteKit load → component). Option (b) is higher effort but closes the mental model gap in one document. _(Raised by: Felix, Markus)_
marcel commented 2026-05-05 21:10:58 +02:00
Author
Owner
Copy Link

✅ Decision Queue — Resolved

The four decisions raised earlier in this thread are resolved as follows. The existing child issues (#395–#401, created yesterday with persona reviews) carry these epic-level resolutions; per-child Decision Queues are addressed separately on each issue.

D1 — DOC-5 vs existing docs/infrastructure/ docs → link, don't duplicate

DOC-5 (docs/DEPLOYMENT.md) is a single-page Day-1 production checklist (per Tobias) that links into the four existing infrastructure docs. New content unique to DOC-5: the "Secrets checklist" (per Nora) listing every must-set env var with fail-fast vs dev-default classification.

D2 — DOC-6 enumeration → 18 README.md files (not "~14")

Driven by the Canonical Domain Set (#387 first comment) and current backend/frontend trees on main:

  • Backend (9): document/, person/, tag/, user/, geschichte/, notification/, ocr/, audit/, dashboard/
  • Frontend (8): document/, person/, tag/, user/, geschichte/, notification/, ocr/, shared/
  • OCR service (1): ocr-service/README.md

Skipped (cross-cutting infrastructure, content lives in CONTRIBUTING.md): backend config/, exception/, security/, filestorage/, importing/.

Per Markus: every README uses a fixed 3-section template — What this domain owns / What it exposes / What it depends on.

D3 — DOC-7 definition of "migrated" → pointer-comment policy

Concrete rule, applied uniformly to all 10 CLAUDE.md files:

  • Move rule content into the chosen human doc.
  • Replace the original CLAUDE.md section with a 1-line pointer: → See CONTRIBUTING.md#backend-walkthrough.
  • CLAUDE.md retains only LLM-workflow content.
  • Verification grep: grep -rE "DO NOT|MUST NOT|always|never" CLAUDE.md … returns no rule-shaped sentences outside pointer blocks.

D4 — CONTRIBUTING.md walkthrough #3 → frontend SvelteKit route

Three audience-targeted walkthroughs (per Felix), each H2 so the Gitea TOC links them:

  1. Add a new domain (backend, full vertical slice — worked example: Tag).
  2. Add an API endpoint to an existing domain (smaller scope — worked example: Tag rename).
  3. Add a new SvelteKit route (frontend only — +page.server.ts → typed client → !result.response.ok guard → +page.svelte with $props()).

Plus a Testing section (per Sara) covering all four test layers — closes the test-strategy gap that wasn't covered by any DOC-* in the original epic.

🔗 Child issues

ID Issue Title Priority
DOC-1 #395 docs(legibility): write human-targeted README.md at repo root P0-critical
DOC-2 #396 docs(legibility): write docs/ARCHITECTURE.md with diagram and domain list P0-critical
DOC-3 #397 docs(legibility): write docs/GLOSSARY.md disambiguating overloaded terms P1-high
DOC-4 #398 docs(legibility): write CONTRIBUTING.md with three concrete walkthroughs P1-high
DOC-5 #399 docs(legibility): write docs/DEPLOYMENT.md (production runtime + env vars) P1-high
DOC-6 #400 docs(legibility): add per-domain README.md inside every domain package P1-high
DOC-7 #401 docs(legibility): migrate CLAUDE.md rules into human docs; mark migrated content P2-medium

Suggested implementation order: DOC-3 → DOC-1 → DOC-2 → DOC-4 → DOC-5 → DOC-6 → DOC-7. (DOC-7 is hard-blocked by DOC-2, DOC-4, DOC-5, DOC-6 as migration targets.)

Per-child decisions are being resolved in follow-up comments on each of #395–#401 in this session.

Erratum: an earlier version of this comment referenced a duplicate set of child issues (#432–#438) that I created in error before discovering #395–#401 already existed. Those duplicates have been closed; the existing children carry the persona reviews and are the canonical home for this work.

## ✅ Decision Queue — Resolved The four decisions raised earlier in this thread are resolved as follows. The existing child issues (#395–#401, created yesterday with persona reviews) carry these epic-level resolutions; per-child Decision Queues are addressed separately on each issue. ### D1 — DOC-5 vs existing `docs/infrastructure/` docs → **link, don't duplicate** DOC-5 (`docs/DEPLOYMENT.md`) is a single-page **Day-1 production checklist** (per Tobias) that links into the four existing infrastructure docs. New content unique to DOC-5: the **"Secrets checklist"** (per Nora) listing every must-set env var with **fail-fast vs dev-default** classification. ### D2 — DOC-6 enumeration → **18 README.md files** (not "~14") Driven by the Canonical Domain Set (#387 first comment) and current backend/frontend trees on `main`: - **Backend (9):** `document/`, `person/`, `tag/`, `user/`, `geschichte/`, `notification/`, `ocr/`, `audit/`, `dashboard/` - **Frontend (8):** `document/`, `person/`, `tag/`, `user/`, `geschichte/`, `notification/`, `ocr/`, `shared/` - **OCR service (1):** `ocr-service/README.md` **Skipped** (cross-cutting infrastructure, content lives in CONTRIBUTING.md): backend `config/`, `exception/`, `security/`, `filestorage/`, `importing/`. Per Markus: every README uses a **fixed 3-section template** — _What this domain owns_ / _What it exposes_ / _What it depends on_. ### D3 — DOC-7 definition of "migrated" → **pointer-comment policy** Concrete rule, applied uniformly to all 10 CLAUDE.md files: - **Move** rule content into the chosen human doc. - **Replace** the original CLAUDE.md section with a 1-line pointer: `→ See CONTRIBUTING.md#backend-walkthrough`. - CLAUDE.md retains only LLM-workflow content. - **Verification grep**: `grep -rE "DO NOT|MUST NOT|always|never" CLAUDE.md …` returns no rule-shaped sentences outside pointer blocks. ### D4 — CONTRIBUTING.md walkthrough #3 → **frontend SvelteKit route** Three audience-targeted walkthroughs (per Felix), each H2 so the Gitea TOC links them: 1. **Add a new domain** (backend, full vertical slice — worked example: `Tag`). 2. **Add an API endpoint to an existing domain** (smaller scope — worked example: `Tag` rename). 3. **Add a new SvelteKit route** (frontend only — `+page.server.ts` → typed client → `!result.response.ok` guard → `+page.svelte` with `$props()`). Plus a **Testing** section (per Sara) covering all four test layers — closes the test-strategy gap that wasn't covered by any DOC-* in the original epic. --- ## 🔗 Child issues | ID | Issue | Title | Priority | |---|---|---|---| | DOC-1 | #395 | docs(legibility): write human-targeted README.md at repo root | **P0-critical** | | DOC-2 | #396 | docs(legibility): write docs/ARCHITECTURE.md with diagram and domain list | **P0-critical** | | DOC-3 | #397 | docs(legibility): write docs/GLOSSARY.md disambiguating overloaded terms | P1-high | | DOC-4 | #398 | docs(legibility): write CONTRIBUTING.md with three concrete walkthroughs | P1-high | | DOC-5 | #399 | docs(legibility): write docs/DEPLOYMENT.md (production runtime + env vars) | P1-high | | DOC-6 | #400 | docs(legibility): add per-domain README.md inside every domain package | P1-high | | DOC-7 | #401 | docs(legibility): migrate CLAUDE.md rules into human docs; mark migrated content | P2-medium | **Suggested implementation order:** DOC-3 → DOC-1 → DOC-2 → DOC-4 → DOC-5 → DOC-6 → DOC-7. (DOC-7 is hard-blocked by DOC-2, DOC-4, DOC-5, DOC-6 as migration targets.) **Per-child decisions** are being resolved in follow-up comments on each of #395–#401 in this session. --- > _Erratum: an earlier version of this comment referenced a duplicate set of child issues (#432–#438) that I created in error before discovering #395–#401 already existed. Those duplicates have been closed; the existing children carry the persona reviews and are the canonical home for this work._
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 documentation epic 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#394
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?