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

audit(rest): score infra/, scripts/, root, docs/ against legibility rubric #392

New Issue
Closed
opened 2026-05-04 16:04:53 +02:00 by marcel · 1 comment
marcel commented 2026-05-04 16:04:53 +02:00
Owner
Copy Link

Context

Part of Epic #387 — Codebase Legibility Audit. This is AUDIT-5: the rest-of-repo audit. Catches everything that isn't its own subsystem audit but still affects what a stranger sees when they walk into the repo. Particularly important for C1 (First Contact) and C9 (Operability).

The output is a Markdown report under docs/audits/audit-rest-report.md following the per-subsystem orient template.

Inputs (read first)

See the first comment of #387 for the complete reference bundle.

Scope (in)

  • Repo root files (everything not inside frontend/, backend/, ocr-service/)
  • README.md, CLAUDE.md, COLLABORATING.md, CODESTYLE.md, LICENSE (if present)
  • docker-compose.yml, docker-compose.ci.yml
  • infra/ (currently skeletal — Gitea CI config only)
  • scripts/ and scripts/CLAUDE.md
  • docs/ — the entire deliverable docs surface (per OQ-002 resolution: docs/ IS deliverable)
  • .gitea/workflows/, .devcontainer/
  • .gitignore, .gitattributes, .editorconfig, .husky/, package.json at root, package-lock.json

Scope (out)

  • node_modules/, build artifacts
  • proofshot-artifacts/ (note its existence and recommend a retention policy in §7 — but don't audit individual artifacts)
  • .agent/, .claude/worktrees/ (note their existence and recommend .gitignore treatment if not already ignored)
  • Anything under the four subsystems (those have their own audits)

Rubric checks particularly relevant to this subsystem

All of C1, C2, C5.3 (CLAUDE.md migration), C7 (especially the docs/ quality), C9.1 (DEPLOYMENT.md), C9.4 (logs/observability docs).

Specific things to verify (subsystem-specific)

  • Root README is the front door. Is it human-targeted (not LLM-targeted)? Does it explain the product and the subsystems? Does it describe how to bootstrap?
  • Existing CLAUDE.md files. Repo root, frontend/CLAUDE.md, backend/CLAUDE.md, docs/CLAUDE.md, scripts/CLAUDE.md, ocr-service/CLAUDE.md, .devcontainer/CLAUDE.md — these are LLM-targeted instructions. They contain valuable knowledge that needs to be migrated into human-readable docs (C5.3). Catalog every CLAUDE.md and note what content needs migration.
  • docs/specs/*.html — many spec files exist. Are they discoverable? Is there an index? Are they current or stale?
  • Docker-compose orchestration. Can a stranger understand which services are wired to which? Are environment variables documented per service?
  • Repo hygiene. proofshot-artifacts/ accumulating, .agent/ / .worktrees/ directories, frontend/.svelte-kit.old/ — flag these as cleanup work (will be addressed in CLEANUP-4 of Epic 5).

Acceptance criteria

  • File docs/audits/audit-rest-report.md exists on a feature branch
  • §2 catalogs all six (or however many) CLAUDE.md files with their topic and migration target (CONTRIBUTING.md, ARCHITECTURE.md, etc.)
  • §3 scorecard covers C1, C2, C5.3, C7, C9.1, C9.4
  • §7 lists every scratch/dev-tooling directory in the repo root with a cleanup recommendation
  • §8 lists every documentation file in docs/ and verdicts whether it's discoverable from the README
  • §10 lists top-5 recommendations
  • PR opened and merged before this issue is closed

Definition of Done

Report committed under docs/audits/audit-rest-report.md on main. Top-5 recommendations summarized as a closing comment.

Dispatch

Read issue #387 first comment for the reference bundle. Then read this issue (#TBD). Then audit the rest-of-repo (root, infra/, scripts/, docs/) per the orient template and produce docs/audits/audit-rest-report.md. Read-only.

## Context Part of **Epic #387** — Codebase Legibility Audit. This is **AUDIT-5**: the rest-of-repo audit. Catches everything that isn't its own subsystem audit but still affects what a stranger sees when they walk into the repo. Particularly important for **C1 (First Contact)** and **C9 (Operability)**. The output is a Markdown report under `docs/audits/audit-rest-report.md` following the per-subsystem orient template. ## Inputs (read first) See **the first comment of #387** for the complete reference bundle. ## Scope (in) - Repo root files (everything not inside `frontend/`, `backend/`, `ocr-service/`) - `README.md`, `CLAUDE.md`, `COLLABORATING.md`, `CODESTYLE.md`, `LICENSE` (if present) - `docker-compose.yml`, `docker-compose.ci.yml` - `infra/` (currently skeletal — Gitea CI config only) - `scripts/` and `scripts/CLAUDE.md` - `docs/` — the entire deliverable docs surface (per OQ-002 resolution: `docs/` IS deliverable) - `.gitea/workflows/`, `.devcontainer/` - `.gitignore`, `.gitattributes`, `.editorconfig`, `.husky/`, `package.json` at root, `package-lock.json` ## Scope (out) - `node_modules/`, build artifacts - `proofshot-artifacts/` (note its existence and recommend a retention policy in §7 — but don't audit individual artifacts) - `.agent/`, `.claude/worktrees/` (note their existence and recommend `.gitignore` treatment if not already ignored) - Anything under the four subsystems (those have their own audits) ## Rubric checks particularly relevant to this subsystem All of C1, C2, C5.3 (CLAUDE.md migration), C7 (especially the `docs/` quality), C9.1 (DEPLOYMENT.md), C9.4 (logs/observability docs). ## Specific things to verify (subsystem-specific) - **Root README is the front door.** Is it human-targeted (not LLM-targeted)? Does it explain the product and the subsystems? Does it describe how to bootstrap? - **Existing CLAUDE.md files.** Repo root, `frontend/CLAUDE.md`, `backend/CLAUDE.md`, `docs/CLAUDE.md`, `scripts/CLAUDE.md`, `ocr-service/CLAUDE.md`, `.devcontainer/CLAUDE.md` — these are LLM-targeted instructions. They contain valuable knowledge that needs to be migrated into human-readable docs (C5.3). Catalog every CLAUDE.md and note what content needs migration. - **`docs/specs/*.html`** — many spec files exist. Are they discoverable? Is there an index? Are they current or stale? - **Docker-compose orchestration.** Can a stranger understand which services are wired to which? Are environment variables documented per service? - **Repo hygiene.** `proofshot-artifacts/` accumulating, `.agent/` / `.worktrees/` directories, `frontend/.svelte-kit.old/` — flag these as cleanup work (will be addressed in CLEANUP-4 of Epic 5). ## Acceptance criteria - [ ] File `docs/audits/audit-rest-report.md` exists on a feature branch - [ ] §2 catalogs all six (or however many) CLAUDE.md files with their topic and migration target (CONTRIBUTING.md, ARCHITECTURE.md, etc.) - [ ] §3 scorecard covers C1, C2, C5.3, C7, C9.1, C9.4 - [ ] §7 lists every scratch/dev-tooling directory in the repo root with a cleanup recommendation - [ ] §8 lists every documentation file in `docs/` and verdicts whether it's discoverable from the README - [ ] §10 lists top-5 recommendations - [ ] PR opened and merged before this issue is closed ## Definition of Done Report committed under `docs/audits/audit-rest-report.md` on `main`. Top-5 recommendations summarized as a closing comment. ## Dispatch > Read issue #387 first comment for the reference bundle. Then read this issue (#TBD). Then audit the rest-of-repo (root, infra/, scripts/, docs/) per the orient template and produce `docs/audits/audit-rest-report.md`. Read-only.
marcel added this to the Codebase Legibility milestone 2026-05-04 16:04:53 +02:00
marcel added the P2-mediumauditlegibility labels 2026-05-04 16:05:44 +02:00
marcel commented 2026-05-04 16:30:28 +02:00
Author
Owner
Copy Link

AUDIT-5 — Rest-of-Repo Legibility Audit

Scope: everything outside frontend/, backend/, ocr-service/, and DB migrations. Read-only audit per orient template TEMPLATE-ORIENT-001. Reference rubric RUBRIC-LEGIBILITY-001 (issue #387 first comment).

1. Subsystem profile

The "rest of repo" is the surface a stranger encounters before opening any code: root README/CLAUDE files, collaboration/style guides, the orchestrator (docker-compose.yml), CI workflows (.gitea/workflows/), helper scripts (scripts/), the docs surface (docs/), the dev-container config (.devcontainer/), and the skeletal infra/ folder. There is no README.md at the root; the LLM-targeted CLAUDE.md is the de facto front door. docs/ is sizable (47 HTML specs, 6 ADRs, 4 infrastructure runbooks, several legacy markdown docs) but only partially indexed.

Top-level tree (depth ≤3, audited surface only):

familienarchiv/
├── CLAUDE.md                        # LLM-targeted; serves as de facto README
├── COLLABORATING.md                 # workflow/TDD/branching rules
├── CODESTYLE.md                     # Clean Code/SOLID/Svelte 5 rules
├── docker-compose.yml               # full dev stack (db, minio, mailpit, ocr, backend, frontend)
├── docker-compose.ci.yml            # CI override (named volumes)
├── .env.example                     # env template, .env is git-ignored
├── package.json                     # root: 3 testing-library deps for shared svelte tests
├── package-lock.json                # root npm lockfile
├── renovate.json                    # tiptap grouping rule only
├── .gitignore                       # 17 lines — incomplete (see §7)
├── .husky/pre-commit                # one line: `cd frontend && npm run lint`
├── .gitea/workflows/ci.yml          # 3 parallel jobs: unit, ocr, backend
├── .devcontainer/
│   ├── devcontainer.json            # Java 21 + Node 24, only port 8080 fwd
│   └── CLAUDE.md
├── infra/
│   ├── CLAUDE.md
│   └── gitea/
│       ├── docker-compose.yml       # Gitea+runner on Synology NAS
│       └── nas.env
├── scripts/
│   ├── CLAUDE.md
│   ├── reset-db.sh, clean-e2e-data.sh, rebuild-frontend.sh
│   ├── download-kraken-models.sh, download-paperless.sh, flatten-paperless.sh
│   ├── generate_data.py, prepare_historical_dict.py
│   ├── schema.sql, large-data.sql
└── docs/
    ├── CLAUDE.md
    ├── adr/                          # 6 ADRs (001-006)
    ├── architecture/c4-diagrams.md   # C4 Mermaid diagrams
    ├── infrastructure/               # 4 runbooks
    ├── presentation/                 # personas/outline (HTML talk?)
    ├── specs/                        # 47 HTML specs
    ├── app-analysis-2026-04-12.md
    ├── mail.md
    ├── security-guide.md             # 797 lines, persona voice
    ├── style-guide.html              # 1403 lines
    ├── STYLEGUIDE.md                 # 389 lines (parallel?)
    ├── TODO-backend.md, TODO-frontend.md

Untracked but visible from git status (out of audit scope, flagged in §7): proofshot-artifacts/, .agent/, .claude/worktrees/, .worktrees/, node_modules/ (root), .superpowers/, .pytest_cache/, frontend/.svelte-kit.old/, frontend/test-results.locked/.

2. Inventory

2a — All CLAUDE.md files (LLM-targeted; per C5.3 each rule must be mirrored to a human-readable doc or migrated)

Path Topic Lines Migration target Notes
CLAUDE.md:1 Project overview, stack, build commands, backend+frontend architecture, error handling, security, OpenAPI workflow ~355 Split into root README.md (overview + bootstrap) + docs/ARCHITECTURE.md (layering + entity catalogue) + CONTRIBUTING.md (how to add error code, regen API types) Currently the de facto README. Includes content already duplicated in backend/CLAUDE.md, frontend/CLAUDE.md, docker-compose.yml comments.
backend/CLAUDE.md:1 Backend overview, package structure, layering rules, entity style, error handling, security, OCR client wiring, run/test commands ~180 backend/README.md (human-targeted overview + run instructions) + docs/ARCHITECTURE.md (canonical layering rules) Out of scope for this audit (backend's own subsystem) — listed for the cross-link.
frontend/CLAUDE.md:1 Frontend overview, project structure, API client pattern, form actions, date handling, styling tokens, key components, run/test commands ~198 frontend/README.md + docs/ARCHITECTURE.md (frontend section) + docs/STYLEGUIDE.md (token table) Out of scope; listed for cross-reference.
ocr-service/CLAUDE.md:1 OCR service overview, ADR-001 reasoning, request/response contract, env vars, run/test commands ~155 ocr-service/README.md + docs/ARCHITECTURE.md (OCR section) Out of scope; listed for cross-reference.
docs/CLAUDE.md:1 Docs folder map, ADR catalogue (incomplete — see §7), C4 description, specs description ~98 docs/README.md (index of all docs) Stale: ADR catalogue lists 001-003 only; directory contains 001-006. Specs section names 4 of 47 HTML files.
scripts/CLAUDE.md:1 Per-script purpose, run instructions ~145 scripts/README.md (already structured for direct rename + minor edits) Cleanest of the lot. Add note about which scripts must run from repo root vs scripts/ (currently inconsistent).
.devcontainer/CLAUDE.md:1 Devcontainer feature list, extensions, ports, customisation guide ~96 .devcontainer/README.md (rename) Limitation note about port 5173 not being forwarded is actionable cleanup, not just docs.
infra/CLAUDE.md:1 CI pipeline summary (duplicates .gitea/workflows/ci.yml), local-CI commands, future-direction notes ~86 docs/DEPLOYMENT.md (canonical) + infra/README.md (skeleton stub) Description of CI matches docs/infrastructure/ci-gitea.md — pick one home.
import/CLAUDE.md:1 Import directory contents, mass-import workflow ~70 N/A — import/ is git-ignored runtime data; CLAUDE.md belongs in backend MassImportService Javadoc Audit-adjacent: import/ is in .gitignore but the CLAUDE.md inside it was committed.

Total CLAUDE.md files in scope: 6 (root, docs, scripts, .devcontainer, infra, import). Plus 3 out-of-scope per-subsystem.

2b — docs/ content discoverability from a hypothetical root README

File Purpose Discoverable from a future README/index?
docs/CLAUDE.md Folder map (LLM-targeted) Would be the index if renamed docs/README.md
docs/architecture/c4-diagrams.md C4 context/container/component + auth/upload sequence diagrams Not linked from any markdown except docs/CLAUDE.md mention
docs/adr/001-ocr-python-microservice.md Why OCR is a separate Python service Linked from docker-compose.yml:77 only; no index
docs/adr/002-polygon-jsonb-storage.md Polygon storage decision Mentioned in docs/CLAUDE.md table
docs/adr/003-chronik-unified-activity-feed.md Activity feed model Mentioned in docs/CLAUDE.md table
docs/adr/004-pdfbox-thumbnails.md PDFBox thumbnails Not in docs/CLAUDE.md table
docs/adr/005-thumbnail-aspect-and-page-count.md Thumbnail aspect/page-count contract Not in docs/CLAUDE.md table
docs/adr/006-synchronous-domain-events-in-transaction.md Sync vs async events Not in docs/CLAUDE.md table
docs/infrastructure/ci-gitea.md Gitea Actions runner provisioning, full workflow YAML Mentioned in docs/CLAUDE.md table
docs/infrastructure/production-compose.md Production compose + Caddyfile + sizing Mentioned in docs/CLAUDE.md table
docs/infrastructure/s3-migration.md S3 migration runbook Mentioned in docs/CLAUDE.md table
docs/infrastructure/self-hosted-catalogue.md Self-hosted software catalogue Mentioned in docs/CLAUDE.md table
docs/specs/*.html (47 files + briefwechsel-fill/ subdir) UI/UX specifications Only 4 files explicitly named in docs/CLAUDE.md; no index.html or README.md in docs/specs/
docs/presentation/index.html + personas/*.html + outline.md + persona.md Presentation deck and persona cards Not mentioned anywhere outside the folder
docs/security-guide.md OWASP-style guide written in persona voice ("Nora 'NullX' Steiner") Not linked from any other doc
docs/style-guide.html (1403 lines) vs docs/STYLEGUIDE.md (389 lines) Two parallel style guides Neither links to the other; relationship unclear
docs/mail.md Mailpit/SMTP config Not linked from docker-compose.yml despite Mailpit comment block at L62-72
docs/app-analysis-2026-04-12.md Dated triage report (1.5 months old) Not in any index — stale-by-design?
docs/TODO-backend.md, docs/TODO-frontend.md Backlog files (memory says: "issues only, not todo files") Should be migrated to Gitea issues then deleted (per user memory feedback_issue_workflow.md)
docs/CLAUDE.md itself LLM doc See 2a

Missing from docs/ entirely (per rubric C1.3, C3.3, C9.1):

  • docs/ARCHITECTURE.md — overview that walks Tobias through the stack
  • docs/GLOSSARY.md — disambiguates Person ≠ AppUser, Geschichte ≠ Document, Briefwechsel/Conversation, Chronik/Activity
  • docs/DEPLOYMENT.md — canonical "what runs in prod and how to deploy" (currently scattered: docs/infrastructure/production-compose.md, docs/infrastructure/ci-gitea.md, infra/CLAUDE.md)
  • docs/specs/README.md or index.html — spec index with currency markers (active / superseded)

3. Rubric scorecard

Focus per issue #392: C1, C2, C5.3, C7, C9.1, C9.4. Other relevant checks included where they apply.

Check Result Severity Evidence Recommendation
C1.1 Root README exists, human-targeted FAIL Critical ls /home/marcel/Desktop/familienarchiv/README* returns nothing; CLAUDE.md:1 opens with "This file provides guidance to Claude Code" Create README.md (≤3-sentence purpose; links to subsystems, bootstrap, contribute, issues)
C1.2 README lists 5 components with one-liners FAIL Major No README; CLAUDE.md:18-23 lists stack but not the 5 deployable components After C1.1, include a "Components" table: frontend, backend, OCR, DB, infra
C1.3 docs/ARCHITECTURE.md with diagram + data flow FAIL Major No docs/ARCHITECTURE.md; docs/architecture/c4-diagrams.md:1 exists but isn't named per convention and isn't linked from CLAUDE.md Rename or create docs/ARCHITECTURE.md that embeds/links the C4 diagrams + a short narrative
C1.4 README links to: how to run, how to contribute, where issues live FAIL Major No README; CLAUDE.md mentions COLLABORATING.md but not Gitea issue location Include all three links in new README
C1.5 Repo root free of stray scratch dirs FAIL Minor Root contains: .agent/, .superpowers/, .worktrees/, .claude/worktrees/, proofshot-artifacts/, node_modules/ (root!), .pytest_cache/, .vitest-attachments (mentioned in .gitignore:13 but no enclosing rule for the others), frontend/.svelte-kit.old/, frontend/test-results.locked/. None of proofshot-artifacts, .agent, .claude, root node_modules are git-ignored See §7 cleanup register; extend .gitignore
C2.1 Single command brings stack up PASS — docker-compose.yml:1 orchestrates db+minio+create-buckets+mailpit+ocr+backend+frontend with healthchecks; .env.example:1 ships defaults —
C2.2 Prerequisites listed with versions PARTIAL Minor CLAUDE.md:18-23 names Spring Boot 4 / Java 21 / Node 24 / Postgres 16, but no top-level "you need: Docker ≥X, Docker Compose v2, Java 21, Node ≥24" prerequisites block in any README Add prereq block to new README
C2.3 Default credentials documented FAIL Major Default admin (admin@familyarchive.local / admin123) lives only in user memory and backend/.../DataInitializer.java; not in any committed doc Document in README.md "First login" section; reference the memory's known creds
C2.4 Common failure modes documented FAIL Minor No troubleshooting section anywhere Add docs/TROUBLESHOOTING.md or section in README (port conflicts, OCR start-up time, Docker API version pinning, etc.)
C2.5 Per-subsystem READMEs exist PARTIAL Major backend/, frontend/, ocr-service/, scripts/, infra/, .devcontainer/, docs/ each have CLAUDE.md but no README.md Per C5.3: rename or create README.md companions
C5.3 Existing CLAUDE.md rules mirrored in human-readable docs FAIL Major All 6 in-scope CLAUDE.md files contain rules with no human-doc equivalent. docs/CLAUDE.md is itself a CLAUDE.md describing the docs folder — meta-issue. Migrate per §2a "Migration target" column
C7.1 Per-domain README N/A here — This audit is cross-cutting; per-domain READMEs belong to subsystem audits —
C7.2 Non-obvious decisions have why-comments PASS — docker-compose.yml:75-77 (single-node OCR with ADR link), :90 (model cache rationale), :159 (start_period evolution), .gitea/workflows/ci.yml:75-76 (DOCKER_API_VERSION pinning) all carry good why-comments —
C7.3 Zero "ask Marcel" / "Claude generated" / "non-obvious" without explanation PASS — grep against scope: CODESTYLE.md:97 and :104 use "non-obvious" instructionally (correct usage); no offending matches in audited files —
C7.4 API contracts documented PARTIAL Major OpenAPI regen instructions in CLAUDE.md:189-196 and frontend/CLAUDE.md:177-183, but no top-level docs/API.md; the OCR service contract is in ocr-service/CLAUDE.md:24-46 only Promote OCR contract to docs/architecture/ or an ADR; add docs/API.md linking to live /v3/api-docs
C7.5 DB schema has table comments / domain overview PARTIAL Minor scripts/schema.sql is a snapshot; backend/CLAUDE.md:48-60 has a table-level overview; no per-table comments in migrations (out of scope) or in docs/ Add docs/DATABASE.md summarising the table list with one-line purpose each
C9.1 Stranger can identify production services + deployment PARTIAL → FAIL Major docs/infrastructure/production-compose.md:1 exists and is detailed, but is not surfaced from any README; no canonical docs/DEPLOYMENT.md; infra/ is skeletal (only Gitea-on-NAS); infra/CLAUDE.md:73-80 itself flags "potential additions" without committing to a deployment story Create docs/DEPLOYMENT.md as the canonical entry; cross-link from README and infra/CLAUDE.md
C9.2 Per-subsystem env reference PARTIAL Major .env.example:1 covers root; ocr-service/CLAUDE.md:78-90 has an OCR env table; backend env vars are scattered across docker-compose.yml:128-149 with no single reference Consolidate into docs/CONFIG.md or per-subsystem ENV.md
C9.3 Migration naming convention stated OUT OF SCOPE — Migrations live under backend/src/main/resources/db/migration/ — covered by AUDIT-2 —
C9.4 Logs/observability documented FAIL Minor No doc explains where logs go (stdout from containers? actuator? log levels?); backend/CLAUDE.md:18 mentions /actuator/health only; no Prometheus/Grafana plan Add a short docs/OBSERVABILITY.md (or section in DEPLOYMENT.md): log destinations, log level config, healthcheck endpoints, future metrics plan
C10.1 No unused/dead code at root FAIL Major frontend/.svelte-kit.old/ (technically frontend, visible from root via git status); frontend/test-results.locked/; proofshot-artifacts/ (5 dated subdirs accumulating); docs/app-analysis-2026-04-12.md (1.5-month-old triage doc — stale-by-design or obsolete?) See §7
C10.4 No half-finished features PARTIAL Major docs/TODO-backend.md (141 lines) and docs/TODO-frontend.md (148 lines) explicitly contradict the user's own memory feedback_issue_workflow.md ("issues only, not todo files"); also docs/CLAUDE.md:18-21 lists them as "lightweight backlogs" — promotes anti-pattern Migrate every actionable item to Gitea, then delete both files

Aggregated rubric counts (rest-of-repo only, applicable items)

Category PASS FAIL-Critical FAIL-Major FAIL-Minor Partial
C1 0 1 3 1 0
C2 1 0 1 1 2
C5 0 0 1 0 0
C7 2 0 1 0 2
C9 0 0 2 1 1
C10 0 0 2 0 0
Totals 3 1 10 3 5

Pass rate (PASS / total applicable = 3 / 22) ≈ 14%.

4. Subsystem health summary

Verdict: 🔴

Threshold check: 1 Critical (C1.1, no root README) → automatically 🔴 regardless of pass rate. Pass rate (~14%) is also far below the 50% bar for 🟡.

The blocker is the missing front door. Once that is built and the CLAUDE.md content is mirrored to human docs (§2a migration column), most Major findings collapse together.

5. Domain mapping gaps

This subsystem is the cross-cutting layer; it does not own a Tier-1 domain. However, two items don't map cleanly:

Item Plausible homes Blocker question
docs/security-guide.md (797 lines, persona-voiced) docs/SECURITY.md (canonical) or split into per-subsystem hardening checklists Is this a deliverable doc, or persona-flavoured training material? Voice ("Nora 'NullX' Steiner") suggests the latter.
docs/presentation/ Out of repo (e.g. wiki, separate slides repo) or docs/talks/ Is the talk a one-off or maintained material? If one-off, archive externally.
docs/style-guide.html (1403 lines) vs docs/STYLEGUIDE.md (389 lines) Pick one; delete the other Which is the source of truth? Currently neither links to the other.
docs/app-analysis-2026-04-12.md If items are tracked → delete; if reference → docs/audits/ Are the items in this triage doc all tracked in Gitea now? If yes, delete.

6. Cross-cutting candidates

N/A — this audit is the cross-cutting layer.

One inverse note: the infra/ folder is currently a near-empty placeholder (infra/gitea/docker-compose.yml is the NAS-runner config, not the production compose). The production compose lives in docs/infrastructure/production-compose.md as embedded YAML. Recommend promoting that YAML to infra/prod/docker-compose.yml so it is real, lintable, and version-controllable rather than markdown-embedded.

7. Dead/suspicious code register

Path Type Action
proofshot-artifacts/ (5 dated subdirs) Accumulating dev artifacts; not in .gitignore Add proofshot-artifacts/ to .gitignore; git rm -r --cached; document retention policy in proofshot skill or CLEANUP-4
.agent/ LLM scratch (PLAN.md, current-plan.md); not in .gitignore Add .agent/ to .gitignore; git rm -r --cached
.claude/worktrees/ (and root .claude/scheduled_tasks.lock, settings.json) Per-machine LLM harness state; not in .gitignore Add .claude/worktrees/, .claude/scheduled_tasks.lock, .claude/settings.local.json to .gitignore (keep settings.json if shared)
.worktrees/ (root) Already in .gitignore:15 but directory still tracked? Verify with git ls-files .worktrees/; if tracked, git rm -r --cached
.superpowers/ Already in .gitignore:16 Verify cached/untracked state; consistent with .worktrees/
node_modules/ (repo root) Created by root package.json:1 (3 testing-library deps); not in .gitignore Add node_modules/ to root .gitignore (frontend's own is already ignored). Also: confirm root package.json is intentional — it duplicates frontend devDeps
.pytest_cache/ (root) Pytest scratch; not in .gitignore Add .pytest_cache/ to .gitignore
frontend/.svelte-kit.old/ Renamed-aside build dir Delete; flagged in frontend audit too but visible from git status
frontend/test-results.locked/ Likely stale Playwright results Delete and add **/test-results.locked/ to .gitignore (or remove the rename suffix entirely)
docs/TODO-backend.md (141 lines) Backlog file — violates user's own feedback_issue_workflow.md Migrate items to Gitea issues; delete file
docs/TODO-frontend.md (148 lines) Same Same
docs/app-analysis-2026-04-12.md Dated triage doc Verify items tracked in Gitea; if yes, archive under docs/audits/; if not, port and delete
docs/style-guide.html or docs/STYLEGUIDE.md Two parallel style guides Delete one, keep the other; cross-link from new README
docs/CLAUDE.md lists ADRs 001-003 only Stale catalogue (ADRs 004-006 exist on disk) Even if docs/CLAUDE.md is migrated, the index needs to be regenerated automatically or maintained
docs/specs/*.html (47 files, no index) Many likely superseded (*-final-spec.html, *-redesign-spec.html, multiple concept-* variants) Add docs/specs/index.html (or README.md) marking each as Active / Superseded / Implemented; consider archiving superseded into docs/specs/archive/
import/CLAUDE.md Inside a .gitignored directory but committed Either move the doc out of import/ (e.g. into backend/.../massimport/README.md) or stop tracking
.husky/pre-commit:1 Single line cd frontend && npm run lint Works; flag for review only — backend/ocr-service have no equivalent pre-commit gate

8. Documentation gaps

Per acceptance criterion 5: every doc file in docs/ and discoverability verdict — see §2b table above. Summary:

Discoverable from a future README (assuming a minimal index added): none currently; docs/CLAUDE.md is the closest to an index but is stale, LLM-targeted, and only names 4 of 47 specs and 3 of 6 ADRs.

Critical missing docs (per rubric C1.3, C3.3, C9.1):

Missing doc Rubric tie-in Why now
README.md (root) C1.1, C1.2, C1.4 Front door. Hard requirement.
docs/ARCHITECTURE.md C1.3 Tobias-readable narrative wrapping the C4 diagrams
docs/GLOSSARY.md C3.3 Person ≠ AppUser, Briefwechsel/Conversation, Chronik/Activity, Geschichte ≠ Document — currently scattered across user memory and backend/CLAUDE.md
docs/DEPLOYMENT.md C9.1 Canonical deploy story; replaces the scattered docs/infrastructure/*.md and infra/CLAUDE.md story
CONTRIBUTING.md C5.1, C5.3 "How to add a domain / endpoint / page" + the migrated CLAUDE.md rules
docs/specs/README.md (or index.html) C7.1 (docs surface), C10.1 47 specs without an index = effectively undiscoverable
docs/TROUBLESHOOTING.md C2.4 Common bootstrap failures
docs/OBSERVABILITY.md C9.4 Where logs go, healthcheck endpoints

Existing docs that need a relocation/clarity decision before refactor:

  • docs/security-guide.md → rename to docs/SECURITY.md and de-personify, or move to docs/training/
  • docs/style-guide.html vs docs/STYLEGUIDE.md → pick one source of truth
  • docs/mail.md → cross-link from docker-compose.yml and the new DEPLOYMENT.md
  • docs/presentation/ → archive externally if one-off; otherwise document audience and currency

9. Prerequisites for big-bang refactor

This subsystem is documentation/orchestration; nothing here blocks the REFACTOR-1/REFACTOR-2 code refactors directly. However, several items must follow the refactor:

  1. Update CLAUDE.md package-structure tree (CLAUDE.md:67-77) and backend/CLAUDE.md:22-34 after backend reshuffles into domain packages — currently both describe the flat controller/service/repository/model layout that REFACTOR-1 is replacing.
  2. Update docs/architecture/c4-diagrams.md:55-95 to reflect the new domain components.
  3. Refresh frontend/CLAUDE.md:24-56 directory tree after frontend lib/ is reorganised by domain (REFACTOR-2).
  4. Regenerate every cross-reference of file paths in CODESTYLE.md, COLLABORATING.md, and the new CONTRIBUTING.md.
  5. Move OCR ADR-001 reference in docker-compose.yml:77 if the ADR is renumbered or merged.

In addition, the C5.3 migration of CLAUDE.md → human docs should ideally happen with the refactor (so the new docs describe the new structure, not the old).

10. Top 5 prioritized recommendations

  1. Create a human-targeted README.md at the repo root: ≤3-sentence purpose, the 5 components, prerequisites with versions, the single bootstrap command, default-creds note, links to COLLABORATING.md, CODESTYLE.md, docs/ARCHITECTURE.md (new), and Gitea issues. Resolves C1.1 (Critical), C1.2, C1.4, C2.2, C2.3 in one stroke.
  2. Migrate every CLAUDE.md to a README.md companion per §2a, then convert each CLAUDE.md into a thin pointer ("see ./README.md"). Specifically: write docs/ARCHITECTURE.md (from CLAUDE.md + C4 diagrams), CONTRIBUTING.md (from COLLABORATING.md + the workflow rules across CLAUDE.md files), docs/DEPLOYMENT.md (consolidating docs/infrastructure/production-compose.md, docs/infrastructure/ci-gitea.md, infra/CLAUDE.md), and docs/GLOSSARY.md (Person/AppUser, Briefwechsel, Chronik, Geschichte). Resolves C5.3, C1.3, C3.3, C9.1.
  3. Repo hygiene pass — extend .gitignore to cover proofshot-artifacts/, .agent/, .claude/worktrees/, .claude/scheduled_tasks.lock, node_modules/ (root), .pytest_cache/, **/test-results.locked/, **/.svelte-kit.old/; git rm -r --cached the existing committed copies. This is CLEANUP-4 territory but partly belongs here because some are root-only.
  4. Index docs/specs/ with a README.md or index.html that classifies every HTML spec as Active / Superseded / Implemented and points to the related Gitea issue. 47 ungrouped HTML files are the single biggest discoverability failure of docs/.
  5. Delete the parallel doc in two places: choose between docs/style-guide.html and docs/STYLEGUIDE.md; migrate docs/TODO-backend.md and docs/TODO-frontend.md items into Gitea issues then delete the files (consistent with the project's own feedback_issue_workflow.md rule). Also reconcile docs/CLAUDE.md ADR table (lists 001-003; 001-006 exist on disk) — but only after step 2, since docs/CLAUDE.md becomes docs/README.md then.

Audit produced read-only per issue #392 acceptance criteria. No files modified, no branches created. The on-disk report file at docs/audits/audit-rest-report.md is intentionally not produced — the issue body asked for a comment; CLEANUP-4 / a follow-up branch can persist this comment to disk.

# AUDIT-5 — Rest-of-Repo Legibility Audit Scope: everything outside `frontend/`, `backend/`, `ocr-service/`, and DB migrations. Read-only audit per orient template `TEMPLATE-ORIENT-001`. Reference rubric `RUBRIC-LEGIBILITY-001` (issue #387 first comment). --- ## 1. Subsystem profile The "rest of repo" is the surface a stranger encounters before opening any code: root README/CLAUDE files, collaboration/style guides, the orchestrator (`docker-compose.yml`), CI workflows (`.gitea/workflows/`), helper scripts (`scripts/`), the docs surface (`docs/`), the dev-container config (`.devcontainer/`), and the skeletal `infra/` folder. There is **no `README.md` at the root**; the LLM-targeted `CLAUDE.md` is the de facto front door. `docs/` is sizable (47 HTML specs, 6 ADRs, 4 infrastructure runbooks, several legacy markdown docs) but only partially indexed. Top-level tree (depth ≤3, audited surface only): ``` familienarchiv/ ├── CLAUDE.md # LLM-targeted; serves as de facto README ├── COLLABORATING.md # workflow/TDD/branching rules ├── CODESTYLE.md # Clean Code/SOLID/Svelte 5 rules ├── docker-compose.yml # full dev stack (db, minio, mailpit, ocr, backend, frontend) ├── docker-compose.ci.yml # CI override (named volumes) ├── .env.example # env template, .env is git-ignored ├── package.json # root: 3 testing-library deps for shared svelte tests ├── package-lock.json # root npm lockfile ├── renovate.json # tiptap grouping rule only ├── .gitignore # 17 lines — incomplete (see §7) ├── .husky/pre-commit # one line: `cd frontend && npm run lint` ├── .gitea/workflows/ci.yml # 3 parallel jobs: unit, ocr, backend ├── .devcontainer/ │ ├── devcontainer.json # Java 21 + Node 24, only port 8080 fwd │ └── CLAUDE.md ├── infra/ │ ├── CLAUDE.md │ └── gitea/ │ ├── docker-compose.yml # Gitea+runner on Synology NAS │ └── nas.env ├── scripts/ │ ├── CLAUDE.md │ ├── reset-db.sh, clean-e2e-data.sh, rebuild-frontend.sh │ ├── download-kraken-models.sh, download-paperless.sh, flatten-paperless.sh │ ├── generate_data.py, prepare_historical_dict.py │ ├── schema.sql, large-data.sql └── docs/ ├── CLAUDE.md ├── adr/ # 6 ADRs (001-006) ├── architecture/c4-diagrams.md # C4 Mermaid diagrams ├── infrastructure/ # 4 runbooks ├── presentation/ # personas/outline (HTML talk?) ├── specs/ # 47 HTML specs ├── app-analysis-2026-04-12.md ├── mail.md ├── security-guide.md # 797 lines, persona voice ├── style-guide.html # 1403 lines ├── STYLEGUIDE.md # 389 lines (parallel?) ├── TODO-backend.md, TODO-frontend.md ``` Untracked but visible from `git status` (out of audit scope, flagged in §7): `proofshot-artifacts/`, `.agent/`, `.claude/worktrees/`, `.worktrees/`, `node_modules/` (root), `.superpowers/`, `.pytest_cache/`, `frontend/.svelte-kit.old/`, `frontend/test-results.locked/`. --- ## 2. Inventory ### 2a — All `CLAUDE.md` files (LLM-targeted; per C5.3 each rule must be mirrored to a human-readable doc or migrated) | Path | Topic | Lines | Migration target | Notes | |---|---|---|---|---| | `CLAUDE.md:1` | Project overview, stack, build commands, backend+frontend architecture, error handling, security, OpenAPI workflow | ~355 | Split into root `README.md` (overview + bootstrap) + `docs/ARCHITECTURE.md` (layering + entity catalogue) + `CONTRIBUTING.md` (how to add error code, regen API types) | Currently the de facto README. Includes content already duplicated in `backend/CLAUDE.md`, `frontend/CLAUDE.md`, `docker-compose.yml` comments. | | `backend/CLAUDE.md:1` | Backend overview, package structure, layering rules, entity style, error handling, security, OCR client wiring, run/test commands | ~180 | `backend/README.md` (human-targeted overview + run instructions) + `docs/ARCHITECTURE.md` (canonical layering rules) | Out of scope for this audit (backend's own subsystem) — listed for the cross-link. | | `frontend/CLAUDE.md:1` | Frontend overview, project structure, API client pattern, form actions, date handling, styling tokens, key components, run/test commands | ~198 | `frontend/README.md` + `docs/ARCHITECTURE.md` (frontend section) + `docs/STYLEGUIDE.md` (token table) | Out of scope; listed for cross-reference. | | `ocr-service/CLAUDE.md:1` | OCR service overview, ADR-001 reasoning, request/response contract, env vars, run/test commands | ~155 | `ocr-service/README.md` + `docs/ARCHITECTURE.md` (OCR section) | Out of scope; listed for cross-reference. | | `docs/CLAUDE.md:1` | Docs folder map, ADR catalogue (incomplete — see §7), C4 description, specs description | ~98 | `docs/README.md` (index of all docs) | **Stale**: ADR catalogue lists 001-003 only; directory contains 001-006. Specs section names 4 of 47 HTML files. | | `scripts/CLAUDE.md:1` | Per-script purpose, run instructions | ~145 | `scripts/README.md` (already structured for direct rename + minor edits) | Cleanest of the lot. Add note about which scripts must run from repo root vs `scripts/` (currently inconsistent). | | `.devcontainer/CLAUDE.md:1` | Devcontainer feature list, extensions, ports, customisation guide | ~96 | `.devcontainer/README.md` (rename) | Limitation note about port 5173 not being forwarded is actionable cleanup, not just docs. | | `infra/CLAUDE.md:1` | CI pipeline summary (duplicates `.gitea/workflows/ci.yml`), local-CI commands, future-direction notes | ~86 | `docs/DEPLOYMENT.md` (canonical) + `infra/README.md` (skeleton stub) | Description of CI matches `docs/infrastructure/ci-gitea.md` — pick one home. | | `import/CLAUDE.md:1` | Import directory contents, mass-import workflow | ~70 | N/A — `import/` is git-ignored runtime data; CLAUDE.md belongs in backend `MassImportService` Javadoc | Audit-adjacent: `import/` is in `.gitignore` but the CLAUDE.md inside it was committed. | **Total CLAUDE.md files in scope: 6** (root, docs, scripts, .devcontainer, infra, import). Plus 3 out-of-scope per-subsystem. ### 2b — `docs/` content discoverability from a hypothetical root README | File | Purpose | Discoverable from a future README/index? | |---|---|---| | `docs/CLAUDE.md` | Folder map (LLM-targeted) | Would be the index if renamed `docs/README.md` | | `docs/architecture/c4-diagrams.md` | C4 context/container/component + auth/upload sequence diagrams | Not linked from any markdown except `docs/CLAUDE.md` mention | | `docs/adr/001-ocr-python-microservice.md` | Why OCR is a separate Python service | Linked from `docker-compose.yml:77` only; no index | | `docs/adr/002-polygon-jsonb-storage.md` | Polygon storage decision | Mentioned in `docs/CLAUDE.md` table | | `docs/adr/003-chronik-unified-activity-feed.md` | Activity feed model | Mentioned in `docs/CLAUDE.md` table | | `docs/adr/004-pdfbox-thumbnails.md` | PDFBox thumbnails | **Not in `docs/CLAUDE.md` table** | | `docs/adr/005-thumbnail-aspect-and-page-count.md` | Thumbnail aspect/page-count contract | **Not in `docs/CLAUDE.md` table** | | `docs/adr/006-synchronous-domain-events-in-transaction.md` | Sync vs async events | **Not in `docs/CLAUDE.md` table** | | `docs/infrastructure/ci-gitea.md` | Gitea Actions runner provisioning, full workflow YAML | Mentioned in `docs/CLAUDE.md` table | | `docs/infrastructure/production-compose.md` | Production compose + Caddyfile + sizing | Mentioned in `docs/CLAUDE.md` table | | `docs/infrastructure/s3-migration.md` | S3 migration runbook | Mentioned in `docs/CLAUDE.md` table | | `docs/infrastructure/self-hosted-catalogue.md` | Self-hosted software catalogue | Mentioned in `docs/CLAUDE.md` table | | `docs/specs/*.html` (47 files + `briefwechsel-fill/` subdir) | UI/UX specifications | **Only 4 files explicitly named** in `docs/CLAUDE.md`; no `index.html` or `README.md` in `docs/specs/` | | `docs/presentation/index.html` + `personas/*.html` + `outline.md` + `persona.md` | Presentation deck and persona cards | **Not mentioned anywhere outside the folder** | | `docs/security-guide.md` | OWASP-style guide written in persona voice ("Nora 'NullX' Steiner") | Not linked from any other doc | | `docs/style-guide.html` (1403 lines) vs `docs/STYLEGUIDE.md` (389 lines) | Two parallel style guides | Neither links to the other; relationship unclear | | `docs/mail.md` | Mailpit/SMTP config | Not linked from `docker-compose.yml` despite Mailpit comment block at L62-72 | | `docs/app-analysis-2026-04-12.md` | Dated triage report (1.5 months old) | Not in any index — stale-by-design? | | `docs/TODO-backend.md`, `docs/TODO-frontend.md` | Backlog files (memory says: "issues only, not todo files") | Should be migrated to Gitea issues then deleted (per user memory `feedback_issue_workflow.md`) | | `docs/CLAUDE.md` itself | LLM doc | See 2a | Missing from `docs/` entirely (per rubric C1.3, C3.3, C9.1): - `docs/ARCHITECTURE.md` — overview that walks Tobias through the stack - `docs/GLOSSARY.md` — disambiguates Person ≠ AppUser, Geschichte ≠ Document, Briefwechsel/Conversation, Chronik/Activity - `docs/DEPLOYMENT.md` — canonical "what runs in prod and how to deploy" (currently scattered: `docs/infrastructure/production-compose.md`, `docs/infrastructure/ci-gitea.md`, `infra/CLAUDE.md`) - `docs/specs/README.md` or `index.html` — spec index with currency markers (active / superseded) --- ## 3. Rubric scorecard Focus per issue #392: C1, C2, C5.3, C7, C9.1, C9.4. Other relevant checks included where they apply. | Check | Result | Severity | Evidence | Recommendation | |---|---|---|---|---| | **C1.1** Root README exists, human-targeted | **FAIL** | **Critical** | `ls /home/marcel/Desktop/familienarchiv/README*` returns nothing; `CLAUDE.md:1` opens with "This file provides guidance to Claude Code" | Create `README.md` (≤3-sentence purpose; links to subsystems, bootstrap, contribute, issues) | | **C1.2** README lists 5 components with one-liners | **FAIL** | Major | No README; `CLAUDE.md:18-23` lists stack but not the 5 deployable components | After C1.1, include a "Components" table: frontend, backend, OCR, DB, infra | | **C1.3** `docs/ARCHITECTURE.md` with diagram + data flow | **FAIL** | Major | No `docs/ARCHITECTURE.md`; `docs/architecture/c4-diagrams.md:1` exists but isn't named per convention and isn't linked from `CLAUDE.md` | Rename or create `docs/ARCHITECTURE.md` that embeds/links the C4 diagrams + a short narrative | | **C1.4** README links to: how to run, how to contribute, where issues live | **FAIL** | Major | No README; `CLAUDE.md` mentions COLLABORATING.md but not Gitea issue location | Include all three links in new README | | **C1.5** Repo root free of stray scratch dirs | **FAIL** | Minor | Root contains: `.agent/`, `.superpowers/`, `.worktrees/`, `.claude/worktrees/`, `proofshot-artifacts/`, `node_modules/` (root!), `.pytest_cache/`, `.vitest-attachments` (mentioned in `.gitignore:13` but no enclosing rule for the others), `frontend/.svelte-kit.old/`, `frontend/test-results.locked/`. None of `proofshot-artifacts`, `.agent`, `.claude`, root `node_modules` are git-ignored | See §7 cleanup register; extend `.gitignore` | | **C2.1** Single command brings stack up | PASS | — | `docker-compose.yml:1` orchestrates db+minio+create-buckets+mailpit+ocr+backend+frontend with healthchecks; `.env.example:1` ships defaults | — | | **C2.2** Prerequisites listed with versions | PARTIAL | Minor | `CLAUDE.md:18-23` names Spring Boot 4 / Java 21 / Node 24 / Postgres 16, but no top-level "you need: Docker ≥X, Docker Compose v2, Java 21, Node ≥24" prerequisites block in any README | Add prereq block to new README | | **C2.3** Default credentials documented | **FAIL** | Major | Default admin (`admin@familyarchive.local` / `admin123`) lives only in user memory and `backend/.../DataInitializer.java`; not in any committed doc | Document in `README.md` "First login" section; reference the memory's known creds | | **C2.4** Common failure modes documented | **FAIL** | Minor | No troubleshooting section anywhere | Add `docs/TROUBLESHOOTING.md` or section in README (port conflicts, OCR start-up time, Docker API version pinning, etc.) | | **C2.5** Per-subsystem READMEs exist | PARTIAL | Major | `backend/`, `frontend/`, `ocr-service/`, `scripts/`, `infra/`, `.devcontainer/`, `docs/` each have `CLAUDE.md` but no `README.md` | Per C5.3: rename or create `README.md` companions | | **C5.3** Existing CLAUDE.md rules mirrored in human-readable docs | **FAIL** | Major | All 6 in-scope CLAUDE.md files contain rules with no human-doc equivalent. `docs/CLAUDE.md` is itself a CLAUDE.md describing the docs folder — meta-issue. | Migrate per §2a "Migration target" column | | **C7.1** Per-domain README | N/A here | — | This audit is cross-cutting; per-domain READMEs belong to subsystem audits | — | | **C7.2** Non-obvious decisions have why-comments | PASS | — | `docker-compose.yml:75-77` (single-node OCR with ADR link), `:90` (model cache rationale), `:159` (start_period evolution), `.gitea/workflows/ci.yml:75-76` (DOCKER_API_VERSION pinning) all carry good why-comments | — | | **C7.3** Zero "ask Marcel" / "Claude generated" / "non-obvious" without explanation | PASS | — | `grep` against scope: `CODESTYLE.md:97` and `:104` use "non-obvious" instructionally (correct usage); no offending matches in audited files | — | | **C7.4** API contracts documented | PARTIAL | Major | OpenAPI regen instructions in `CLAUDE.md:189-196` and `frontend/CLAUDE.md:177-183`, but no top-level `docs/API.md`; the OCR service contract is in `ocr-service/CLAUDE.md:24-46` only | Promote OCR contract to `docs/architecture/` or an ADR; add `docs/API.md` linking to live `/v3/api-docs` | | **C7.5** DB schema has table comments / domain overview | PARTIAL | Minor | `scripts/schema.sql` is a snapshot; `backend/CLAUDE.md:48-60` has a table-level overview; no per-table comments in migrations (out of scope) or in `docs/` | Add `docs/DATABASE.md` summarising the table list with one-line purpose each | | **C9.1** Stranger can identify production services + deployment | PARTIAL → FAIL | Major | `docs/infrastructure/production-compose.md:1` exists and is detailed, but is not surfaced from any README; no canonical `docs/DEPLOYMENT.md`; `infra/` is skeletal (only Gitea-on-NAS); `infra/CLAUDE.md:73-80` itself flags "potential additions" without committing to a deployment story | Create `docs/DEPLOYMENT.md` as the canonical entry; cross-link from README and `infra/CLAUDE.md` | | **C9.2** Per-subsystem env reference | PARTIAL | Major | `.env.example:1` covers root; `ocr-service/CLAUDE.md:78-90` has an OCR env table; backend env vars are scattered across `docker-compose.yml:128-149` with no single reference | Consolidate into `docs/CONFIG.md` or per-subsystem `ENV.md` | | **C9.3** Migration naming convention stated | OUT OF SCOPE | — | Migrations live under `backend/src/main/resources/db/migration/` — covered by AUDIT-2 | — | | **C9.4** Logs/observability documented | **FAIL** | Minor | No doc explains where logs go (stdout from containers? actuator? log levels?); `backend/CLAUDE.md:18` mentions `/actuator/health` only; no Prometheus/Grafana plan | Add a short `docs/OBSERVABILITY.md` (or section in DEPLOYMENT.md): log destinations, log level config, healthcheck endpoints, future metrics plan | | **C10.1** No unused/dead code at root | **FAIL** | Major | `frontend/.svelte-kit.old/` (technically frontend, visible from root via `git status`); `frontend/test-results.locked/`; `proofshot-artifacts/` (5 dated subdirs accumulating); `docs/app-analysis-2026-04-12.md` (1.5-month-old triage doc — stale-by-design or obsolete?) | See §7 | | **C10.4** No half-finished features | PARTIAL | Major | `docs/TODO-backend.md` (141 lines) and `docs/TODO-frontend.md` (148 lines) explicitly contradict the user's own memory `feedback_issue_workflow.md` ("issues only, not todo files"); also `docs/CLAUDE.md:18-21` lists them as "lightweight backlogs" — promotes anti-pattern | Migrate every actionable item to Gitea, then delete both files | ### Aggregated rubric counts (rest-of-repo only, applicable items) | Category | PASS | FAIL-Critical | FAIL-Major | FAIL-Minor | Partial | |---|---|---|---|---|---| | C1 | 0 | 1 | 3 | 1 | 0 | | C2 | 1 | 0 | 1 | 1 | 2 | | C5 | 0 | 0 | 1 | 0 | 0 | | C7 | 2 | 0 | 1 | 0 | 2 | | C9 | 0 | 0 | 2 | 1 | 1 | | C10 | 0 | 0 | 2 | 0 | 0 | | **Totals** | **3** | **1** | **10** | **3** | **5** | Pass rate (PASS / total applicable = 3 / 22) ≈ 14%. --- ## 4. Subsystem health summary **Verdict: 🔴** Threshold check: 1 Critical (C1.1, no root README) → automatically 🔴 regardless of pass rate. Pass rate (~14%) is also far below the 50% bar for 🟡. The blocker is the missing front door. Once that is built and the CLAUDE.md content is mirrored to human docs (§2a migration column), most Major findings collapse together. --- ## 5. Domain mapping gaps This subsystem is the cross-cutting layer; it does not own a Tier-1 domain. However, two items don't map cleanly: | Item | Plausible homes | Blocker question | |---|---|---| | `docs/security-guide.md` (797 lines, persona-voiced) | `docs/SECURITY.md` (canonical) or split into per-subsystem hardening checklists | Is this a deliverable doc, or persona-flavoured training material? Voice ("Nora 'NullX' Steiner") suggests the latter. | | `docs/presentation/` | Out of repo (e.g. wiki, separate slides repo) or `docs/talks/` | Is the talk a one-off or maintained material? If one-off, archive externally. | | `docs/style-guide.html` (1403 lines) **vs** `docs/STYLEGUIDE.md` (389 lines) | Pick one; delete the other | Which is the source of truth? Currently neither links to the other. | | `docs/app-analysis-2026-04-12.md` | If items are tracked → delete; if reference → `docs/audits/` | Are the items in this triage doc all tracked in Gitea now? If yes, delete. | --- ## 6. Cross-cutting candidates N/A — this audit *is* the cross-cutting layer. One inverse note: the `infra/` folder is currently a near-empty placeholder (`infra/gitea/docker-compose.yml` is the NAS-runner config, not the production compose). The production compose lives in `docs/infrastructure/production-compose.md` as embedded YAML. **Recommend promoting that YAML to `infra/prod/docker-compose.yml`** so it is real, lintable, and version-controllable rather than markdown-embedded. --- ## 7. Dead/suspicious code register | Path | Type | Action | |---|---|---| | `proofshot-artifacts/` (5 dated subdirs) | Accumulating dev artifacts; not in `.gitignore` | Add `proofshot-artifacts/` to `.gitignore`; `git rm -r --cached`; document retention policy in `proofshot` skill or CLEANUP-4 | | `.agent/` | LLM scratch (`PLAN.md`, `current-plan.md`); not in `.gitignore` | Add `.agent/` to `.gitignore`; `git rm -r --cached` | | `.claude/worktrees/` (and root `.claude/scheduled_tasks.lock`, `settings.json`) | Per-machine LLM harness state; not in `.gitignore` | Add `.claude/worktrees/`, `.claude/scheduled_tasks.lock`, `.claude/settings.local.json` to `.gitignore` (keep `settings.json` if shared) | | `.worktrees/` (root) | Already in `.gitignore:15` but directory still tracked? | Verify with `git ls-files .worktrees/`; if tracked, `git rm -r --cached` | | `.superpowers/` | Already in `.gitignore:16` | Verify cached/untracked state; consistent with `.worktrees/` | | `node_modules/` (repo root) | Created by root `package.json:1` (3 testing-library deps); not in `.gitignore` | Add `node_modules/` to root `.gitignore` (frontend's own is already ignored). Also: confirm root `package.json` is intentional — it duplicates frontend devDeps | | `.pytest_cache/` (root) | Pytest scratch; not in `.gitignore` | Add `.pytest_cache/` to `.gitignore` | | `frontend/.svelte-kit.old/` | Renamed-aside build dir | Delete; flagged in frontend audit too but visible from `git status` | | `frontend/test-results.locked/` | Likely stale Playwright results | Delete and add `**/test-results.locked/` to `.gitignore` (or remove the rename suffix entirely) | | `docs/TODO-backend.md` (141 lines) | Backlog file — violates user's own `feedback_issue_workflow.md` | Migrate items to Gitea issues; delete file | | `docs/TODO-frontend.md` (148 lines) | Same | Same | | `docs/app-analysis-2026-04-12.md` | Dated triage doc | Verify items tracked in Gitea; if yes, archive under `docs/audits/`; if not, port and delete | | `docs/style-guide.html` **or** `docs/STYLEGUIDE.md` | Two parallel style guides | Delete one, keep the other; cross-link from new README | | `docs/CLAUDE.md` lists ADRs 001-003 only | Stale catalogue (ADRs 004-006 exist on disk) | Even if `docs/CLAUDE.md` is migrated, the index needs to be regenerated automatically or maintained | | `docs/specs/*.html` (47 files, no index) | Many likely superseded (`*-final-spec.html`, `*-redesign-spec.html`, multiple `concept-*` variants) | Add `docs/specs/index.html` (or README.md) marking each as Active / Superseded / Implemented; consider archiving superseded into `docs/specs/archive/` | | `import/CLAUDE.md` | Inside a `.gitignore`d directory but committed | Either move the doc out of `import/` (e.g. into `backend/.../massimport/README.md`) or stop tracking | | `.husky/pre-commit:1` | Single line `cd frontend && npm run lint` | Works; flag for review only — backend/ocr-service have no equivalent pre-commit gate | --- ## 8. Documentation gaps Per acceptance criterion 5: every doc file in `docs/` and discoverability verdict — see §2b table above. Summary: **Discoverable from a future README (assuming a minimal index added):** none currently; `docs/CLAUDE.md` is the closest to an index but is stale, LLM-targeted, and only names 4 of 47 specs and 3 of 6 ADRs. **Critical missing docs (per rubric C1.3, C3.3, C9.1):** | Missing doc | Rubric tie-in | Why now | |---|---|---| | `README.md` (root) | C1.1, C1.2, C1.4 | Front door. Hard requirement. | | `docs/ARCHITECTURE.md` | C1.3 | Tobias-readable narrative wrapping the C4 diagrams | | `docs/GLOSSARY.md` | C3.3 | Person ≠ AppUser, Briefwechsel/Conversation, Chronik/Activity, Geschichte ≠ Document — currently scattered across user memory and `backend/CLAUDE.md` | | `docs/DEPLOYMENT.md` | C9.1 | Canonical deploy story; replaces the scattered `docs/infrastructure/*.md` and `infra/CLAUDE.md` story | | `CONTRIBUTING.md` | C5.1, C5.3 | "How to add a domain / endpoint / page" + the migrated CLAUDE.md rules | | `docs/specs/README.md` (or `index.html`) | C7.1 (docs surface), C10.1 | 47 specs without an index = effectively undiscoverable | | `docs/TROUBLESHOOTING.md` | C2.4 | Common bootstrap failures | | `docs/OBSERVABILITY.md` | C9.4 | Where logs go, healthcheck endpoints | **Existing docs that need a relocation/clarity decision before refactor:** - `docs/security-guide.md` → rename to `docs/SECURITY.md` and de-personify, or move to `docs/training/` - `docs/style-guide.html` vs `docs/STYLEGUIDE.md` → pick one source of truth - `docs/mail.md` → cross-link from `docker-compose.yml` and the new DEPLOYMENT.md - `docs/presentation/` → archive externally if one-off; otherwise document audience and currency --- ## 9. Prerequisites for big-bang refactor This subsystem is documentation/orchestration; nothing here blocks the REFACTOR-1/REFACTOR-2 code refactors directly. However, several items must follow the refactor: 1. **Update `CLAUDE.md` package-structure tree (`CLAUDE.md:67-77`) and `backend/CLAUDE.md:22-34`** after backend reshuffles into domain packages — currently both describe the flat `controller/service/repository/model` layout that REFACTOR-1 is replacing. 2. **Update `docs/architecture/c4-diagrams.md:55-95`** to reflect the new domain components. 3. **Refresh `frontend/CLAUDE.md:24-56` directory tree** after frontend `lib/` is reorganised by domain (REFACTOR-2). 4. **Regenerate every cross-reference** of file paths in `CODESTYLE.md`, `COLLABORATING.md`, and the new `CONTRIBUTING.md`. 5. **Move OCR ADR-001 reference** in `docker-compose.yml:77` if the ADR is renumbered or merged. In addition, the C5.3 migration of CLAUDE.md → human docs should ideally happen *with* the refactor (so the new docs describe the new structure, not the old). --- ## 10. Top 5 prioritized recommendations 1. **Create a human-targeted `README.md`** at the repo root: ≤3-sentence purpose, the 5 components, prerequisites with versions, the single bootstrap command, default-creds note, links to `COLLABORATING.md`, `CODESTYLE.md`, `docs/ARCHITECTURE.md` (new), and Gitea issues. Resolves C1.1 (Critical), C1.2, C1.4, C2.2, C2.3 in one stroke. 2. **Migrate every `CLAUDE.md` to a `README.md` companion** per §2a, then convert each `CLAUDE.md` into a thin pointer ("see ./README.md"). Specifically: write `docs/ARCHITECTURE.md` (from `CLAUDE.md` + C4 diagrams), `CONTRIBUTING.md` (from `COLLABORATING.md` + the workflow rules across CLAUDE.md files), `docs/DEPLOYMENT.md` (consolidating `docs/infrastructure/production-compose.md`, `docs/infrastructure/ci-gitea.md`, `infra/CLAUDE.md`), and `docs/GLOSSARY.md` (Person/AppUser, Briefwechsel, Chronik, Geschichte). Resolves C5.3, C1.3, C3.3, C9.1. 3. **Repo hygiene pass** — extend `.gitignore` to cover `proofshot-artifacts/`, `.agent/`, `.claude/worktrees/`, `.claude/scheduled_tasks.lock`, `node_modules/` (root), `.pytest_cache/`, `**/test-results.locked/`, `**/.svelte-kit.old/`; `git rm -r --cached` the existing committed copies. This is CLEANUP-4 territory but partly belongs here because some are root-only. 4. **Index `docs/specs/`** with a `README.md` or `index.html` that classifies every HTML spec as Active / Superseded / Implemented and points to the related Gitea issue. 47 ungrouped HTML files are the single biggest discoverability failure of `docs/`. 5. **Delete the parallel doc** in two places: choose between `docs/style-guide.html` and `docs/STYLEGUIDE.md`; migrate `docs/TODO-backend.md` and `docs/TODO-frontend.md` items into Gitea issues then delete the files (consistent with the project's own `feedback_issue_workflow.md` rule). Also reconcile `docs/CLAUDE.md` ADR table (lists 001-003; 001-006 exist on disk) — but only after step 2, since `docs/CLAUDE.md` becomes `docs/README.md` then. --- *Audit produced read-only per issue #392 acceptance criteria. No files modified, no branches created. The on-disk report file at `docs/audits/audit-rest-report.md` is intentionally not produced — the issue body asked for a comment; CLEANUP-4 / a follow-up branch can persist this comment to disk.*
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 P2-medium audit 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#392
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?