docs(legibility): write human-targeted README.md at repo root — DOC-1 #440
Reference in New Issue
Block a user
Delete Branch "feat/issue-395-readme"
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?
Summary
Implements DOC-1 from Epic #394 — the front-door README for new contributors (Anja, Tobias).
README.mdat repo root (93 lines, well under the 150-line cap)CLAUDE.mdpointing humans to README (no other CLAUDE.md changes — full migration is DOC-7).env.example— it already existed and is comprehensiveFive sections
ocr-service/is not part of the default dev stackdocs/architecture/c4-diagrams.mdanddocs/adr/(both exist now); TODO markers with issue refs for DOC-2 (#396), DOC-4 (#398), DOC-5 (#399);docs/GLOSSARY.md(lands with DOC-3 PR #439); Gitea tracker with LAN qualifierDecisions applied (from resolved Decision Queue on #395)
.env.examplealready existed — not recreated; quick-start references it directly(internal — home network only)qualifierOne correction vs issue body
The issue specified
http://localhost:3000for the frontend. The actual Vite port is 5173 (confirmed invite.config.tsand.env.example). README uses 5173.PR checklist
_(coming: [DOC-N, #NNN])_##heading level onlyCloses #395
👨💻 Felix Brandt — Senior Fullstack Developer
Verdict: ✅ Approved
What I checked
This PR touches no production code — no Svelte components, no Java services, no Python endpoints, no TypeScript types. My clean-code and TDD lenses don't have much surface to work with here, but I read the README carefully from a developer-experience angle.
Findings
No blockers.
Suggestions (nice to have):
The Quick Start says
cd backend/./mvnw spring-boot:runand separatelycd frontend/npm run dev. New contributors who follow literally may wonder: "Do I need tocdback to root between steps?" A small note like "Open a new terminal for the frontend" would eliminate any ambiguity, especially for less experienced contributors (Anja, Tobias mentioned in the PR body).npm installis listed as a step inside Quick Start (step 4). That's correct, but for contributors who later pull changes, they'll need to remember to rerun it afterpackage.jsonchanges. This is a very minor onboarding friction; worth a one-liner in a future CONTRIBUTING.md (DOC-4 already tracks this).The port correction (5173 instead of 3000) is explicitly documented in the PR description — good catch. No action needed.
Summary
A clean, purposeful README. The scope is correctly bounded to the issue. No code quality concerns. LGTM from me.
🔒 Nora "NullX" Steiner — Application Security Engineer
Verdict: ⚠️ Approved with concerns
What I checked
Documentation PRs can introduce security issues: hardcoded credentials, internal URLs exposed to public repositories, insecure quick-start instructions that ship insecure defaults, and missing security caveats on deployment instructions.
Findings
Blocker — none confirmed.
Concern (should fix before wider audience sees this):
The README publicly documents the default development credentials:
The PR wraps this in a "local dev only" warning block, which is the right instinct. However, the warning says "change before any network-exposed deployment" — this is necessary but insufficient for a private family project where contributors may not have strong security intuitions.
Recommendation: Add a concrete, actionable call-to-action instead of just a warning. For example:
If no such script exists, the warning is good enough for now — but it should tell the reader how to change it, not just that they should.
Security smell (informational):
The Gitea tracker URL
http://heim-nas:3005/...is documented with(internal — home network only). This is fine for a private project, but if this repo ever becomes public, that URL leaks an internal hostname and service topology. Worth noting for later.The quick-start instructs
docker compose up -d db minio mailpit(exposing only three services). The note about the fulldocker compose up -dexposing the database port is correctly placed in the warning block. Good.Summary
The credential disclosure is a known trade-off for developer experience in local setups. The warning is present and correct. A more actionable remediation instruction would be the improvement. No hard blockers from a security standpoint — this is a documentation file for a private family project.
🏛️ Markus Keller — Senior Application Architect
Verdict: ✅ Approved
What I checked
README content for architectural accuracy, consistency with the actual system design, forward-link validity, and whether the subsystem descriptions reflect the real module structure.
Findings
No blockers.
Observations worth noting:
Subsystem map is accurate. The five entries (
frontend/,backend/,ocr-service/,infra/,scripts/) match the actual package-by-domain structure documented in CLAUDE.md. The note thatocr-service/is "not part of the default dev stack" is architecturally correct — it has different resource requirements (the justification for its extraction as a separate service is exactly what an ADR should capture, and ADR-001 is already linked).The C4 diagram link (
docs/architecture/c4-diagrams.md) is listed as the first "Where to go next" resource. I'd flag that if this file exists, it should be verified to accurately reflect the current container view. If it's stale, a new contributor following it will get a wrong mental model before they've even opened a code file. This isn't a blocker for this PR but is worth a follow-up validation before DOC-2 lands.The
docs/GLOSSARY.mdlink is included without a_(coming: ...)_marker, implying it already exists. PR #439 (DOC-3) is mentioned in the PR body as the landing vehicle. If that PR isn't merged before this one, the link will be a 404. Recommend verifying merge order or adding a_(coming: [DOC-3, #439])_marker.The monolith-first principle is implicit but not stated. The README describes the stack correctly without overpromising distributed architecture. This is the right framing for a family project on a single VPS.
Summary
Architecturally sound and accurate. One potential 404 on
docs/GLOSSARY.mdif merge order isn't controlled — worth a quick check.🧪 Sara Holt — Senior QA Engineer
Verdict: ✅ Approved
What I checked
Documentation PRs don't introduce test cases, but they can introduce false statements about the application's behaviour that will mislead testers, or they can create gaps in contributor onboarding that lead to broken test runs. I reviewed the Quick Start for accuracy against what I know about the test suite and CI setup.
Findings
No blockers.
Observations:
The Quick Start documents the happy path: start infra → start backend → start frontend → open browser. It does not mention running tests. For new contributors (Anja, Tobias), there's no guidance on
./mvnw testornpm run test. This is intentional scope for DOC-4 (CONTRIBUTING.md), but it means contributors may start submitting PRs without knowing a test suite exists. Worth noting as a gap for DOC-4 to close explicitly.The README says the API docs are available at
http://localhost:8080/v3/api-docs(dev profile, auto-enabled). The CLAUDE.md docs say the dev profile must be manually activated with--spring.profiles.active=dev. The README says "auto-enabled" in a comment on themvnw spring-boot:runline. If the dev profile is not auto-activated by default (i.e., it requires the explicit flag), this comment is misleading. A new contributor trying to access the API docs will hit a 404 and not know why.Recommendation: Clarify with:
# API docs available only with dev profile: ./mvnw spring-boot:run -Dspring-boot.run.arguments=--spring.profiles.active=devThe PR checklist item "Quick-start steps verified against actual repo state" is checked — I'll take this at face value for the infrastructure steps, but the API docs caveat above may have slipped through.
Summary
One potentially misleading statement about the API docs auto-enabling. No test coverage concerns for a documentation-only PR. LGTM with the one clarification suggestion.
⚙️ Tobias Wendt — DevOps & Platform Engineer
Verdict: ✅ Approved
What I checked
Infrastructure accuracy in the Quick Start, Docker Compose command correctness, port documentation, and whether the documented setup matches the actual
docker-compose.ymlstructure.Findings
No blockers.
What looks correct:
docker compose up -d db minio mailpit— uses the V2 plugin syntax (no hyphen), matches the prerequisite statement "Docker with thedocker composeplugin (V2)". Correct.docker compose up -dfor everything) is the right default for local dev — it avoids starting the backend and frontend containers when running those locally. Good call.--scale ocr-service=0flag is a practical tip.Minor observations:
The README does not document the MinIO console port (typically 9001 in dev setups). Not needed for the Quick Start, but a contributor who wants to inspect the object store will have to dig for it. A follow-up in DOC-4 or a future infra doc would handle this well.
cp .env.example .env— the README says "The defaults in .env.example work for local development without changes." If this is true (and I believe it is for the standard MinIO/Postgres credentials), it's correct. If any value requires machine-specific configuration (e.g. a path or IP), this statement would mislead. Worth a one-time verification against the actual.env.example.The note about Mailpit is implicit (it's in the compose command but not introduced in the text). New contributors may wonder what Mailpit is. One parenthetical — "(Mailpit captures outgoing emails so you can inspect them at http://localhost:8025)" — would close that gap. Not a blocker.
Summary
Infrastructure documentation is accurate and uses the right tooling conventions. Minor gaps are all appropriate targets for DOC-4 or DOC-5. LGTM.
🎨 Leonie Voss — UX Designer & Accessibility Strategist
Verdict: ✅ Approved
What I checked
As UX lead, my surface area on a Markdown README is narrow — but documentation is a user experience too, and the "user" here is Anja and Tobias (new contributors). I reviewed information architecture, progressive disclosure, and whether the document would successfully onboard someone with limited familiarity with this stack.
Findings
No blockers.
What works well:
Suggestion:
The
docs/GLOSSARY.mdrow in "Where to go next" describes the glossary as covering "Overloaded terms: Person vs AppUser, Chronik vs Aktivität, etc." These German terms (Chronik, Aktivität) will be opaque to an English-speaking contributor who opens the README first. A small parenthetical — "(German domain terms used in the UI and issue tracker)" — would prevent confusion without adding noise.This is cosmetic. No action required before merge.
Summary
The README achieves its stated goal: a human-readable front door for Anja and Tobias. Information architecture is sound, progressive disclosure is well-applied, and the tone is appropriate for the audience. LGTM.
📋 Elicit — Requirements Engineer
Verdict: ⚠️ Approved with concerns
What I checked
Whether the README satisfies the acceptance criteria for DOC-1 (issue #395), whether forward-links introduce unresolved requirements debt, and whether the stated scope is complete relative to the epic (#394) intent.
Findings
No blockers.
DOC-1 acceptance criteria — compliance check:
Based on the PR body and the diff, the README delivers:
Concern — forward-links as implicit requirements debt:
The README contains five forward-links to documents that do not yet exist:
docs/ARCHITECTURE.md→ DOC-2, docs(legibility): write docs/ARCHITECTURE.md with diagram and domain list (#396)CONTRIBUTING.md→ DOC-4, docs(legibility): write CONTRIBUTING.md with three concrete walkthroughs (#398)docs/DEPLOYMENT.md→ DOC-5, docs(legibility): write docs/DEPLOYMENT.md (production runtime + env vars) (#399)docs/GLOSSARY.md→ DOC-3, PR #439 (imminent)docs/architecture/c4-diagrams.md→ listed as existing nowThe
_(coming: [DOC-N, #NNN])_convention is clean and honest. My concern is: if any of those linked issues are deprioritized or dropped from the epic, the README will contain dead forward-references with no resolution. This is requirements debt.Recommendation: Confirm that issues #396, #398, #399 are all actively tracked and in-scope for Epic #394. If any are "maybe later," add them to the PR backlog or flag them as parked in the issue. This is a process concern, not a content concern.
Gap — audience is implied, not stated:
The README's intended audience (new contributors "Anja" and "Tobias") is documented in the PR body but not in the README itself. This is a minor gap: the document does not say "intended for contributors setting up a local development environment for the first time." Without that framing, the scope of Quick Start is ambiguous — is it for production setup too? The deployment warning block partially covers this, but an explicit audience statement in the opening paragraph would make the scope unambiguous.
Suggestion (low priority): Add one sentence after the product description: "This guide is for contributors setting up a local development environment." This removes all ambiguity about scope.
Summary
DOC-1 is delivered within scope. Two process-level concerns: forward-link resolution tracking (medium priority), and audience ambiguity (low priority). No functional gaps in the content itself. Approved with concerns noted for backlog awareness.