- docs/README.md: remove duplicate infrastructure/ entry at end of folder tree
- ocr-service/CLAUDE.md: add **LLM reminder:** prefix to ALLOWED_PDF_HOSTS
SSRF warning (consistent with all other machine-readable instructions)
- backend/CLAUDE.md: restore ResponseStatusException note for simple controller
validation — avoids LLMs reaching for DomainException for trivial checks
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Security checklist: OCR_TRAINING_TOKEN → APP_OCR_TRAINING_TOKEN (backend)
plus TRAINING_TOKEN (OCR service); both must share the same value
- Bootstrap: clarify docker-compose.prod.yml is not committed — must be
created from docs/infrastructure/production-compose.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Use correct container name archive-db (not familienarchiv-db-1) in
§5 backup/restore commands — verified against docker-compose.yml
- Add KRAKEN_MODEL_PATH to OCR service env vars table (was missing;
set at docker-compose.yml:92 as /app/models/german_kurrent.mlmodel)
Refs #399
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Covers: topology diagram (Mermaid), OCR memory/VPS sizing table,
dev-vs-prod differences, complete env vars table (all vars verified
against docker-compose.yml and application.yaml, including APP_ADMIN_*
and ALLOWED_PDF_HOSTS gaps not in .env.example), security checklist
before first boot, bootstrap sequence, logs, backup current state vs
planned, common operational tasks, and known limitations with ADR links.
Closes#399
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds a temporary GLOSSARY link at the top of the C4 diagrams document.
DOC-2 (ARCHITECTURE.md) will own the permanent cross-reference when it lands.
Refs #397
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Disambiguates all overloaded terms in the codebase: Person vs AppUser,
Chronik (internal) vs Aktivität (user-facing), TranscriptionBlock polygon
vs bounding box, DocumentVersion append-only convention, OcrJob lifecycle,
SenderModel as persistent entity, Audit log DB-layer caveat, and more.
Includes Pending Terms section for audit follow-ups (#388–#392).
Refs #397
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The test was using tagId=nonexistent-tag-id which is not a recognised search parameter;
the correct param is tag= (tag name). Updated the test and the coverage report to
accurately describe what is verified: text + tag filter AND combination. The sender
filter test remains an acknowledged gap noted in the report.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds docs/audits/e2e-coverage-report.md mapping all 12 critical journeys
to their test files. Fills the 6 coverage gaps with new e2e tests:
- J1: Register via invite code (auth.spec.ts)
- J3: Edit document tags via TagInput (documents.spec.ts)
- J4: Create brand-new tag via TagInput (documents.spec.ts)
- J5: Add SPOUSE_OF relationship on person edit page (persons.spec.ts)
- J6: Multi-filter search (text + date, text + tagId) (documents.spec.ts)
- J10: Notification bell opens dropdown (notification-deep-link.spec.ts)
- J11: Non-admin blocked from /admin/* (permissions.spec.ts)
- J12: Mass import trigger shows status (admin.spec.ts)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
35/35 mutations DETECTED across document, person, tag, user, geschichte,
notification, and OCR domains. No tautological tests found — the suite
is trustworthy on all critical paths. Closes issue #403.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Markus #4 (PR #366 review). PersonDisplayNameChangedEvent is the first
custom application event in this codebase — the prior @EventListener
(OcrTrainingService.recoverOrphanedRuns) consumed Spring's built-in
ApplicationReadyEvent. The pattern is load-bearing for future cross-domain
decoupling and warrants a documented decision rather than a comment buried
in the listener.
Captures: synchronous-by-default rationale, package layout (event in
publisher's model/, listener in consumer's service/), saveAllAndFlush vs
saveAll for exception surfacing, the migration path to @TransactionalEvent
Listener + @Async if archive growth forces it, and the rejected
alternatives (direct call, DB trigger, Hibernate entity listener).
Refs #362#366
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Three standalone HTML spec files covering the initial Stammbaum release:
- stammbaum-tree-spec.html — desktop/tablet/mobile tree canvas with side panel, light + dark
- stammbaum-doc-badge-spec.html — inline relationship pill on document detail
- stammbaum-person-edit-spec.html — relationship editor card on person edit page
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Final UI/UX spec for the /hilfe/transkription page referenced from
the Transcribe panel coach card. Card-grid layout with per-rule
Beispiel boxes, Wikipedia info-card, "Noch in Klärung" strip, and
closing invitation. Includes impl-ref tables, Paraglide keys for
de/en/es, print styles, and Gherkin acceptance criteria.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds two specs for extending issue #294 with bulk uploads:
- bulk-upload-concepts.html — three concepts (stack, split-panel
with file switcher, progressive accordion) with a decision
matrix and the Concept B recommendation.
- bulk-upload-split-panel-spec.html — refined final spec for
Concept B. Covers all three states (N=0 empty · N=1 single ·
N≥2 multi) across 320 / 375 / 768 / 1280 viewports in both
light and dark mode, using the real tokens from layout.css.
Includes impl-ref tables for every new surface, Paraglide keys
in de/en/es, component tree, and backend contract.
The polymorphic-state model means /documents/new is a single
route: N=1 is byte-identical to #294, N=0 shows a whole-panel
drop zone with bulk-first copy, N≥2 grows a file-switcher strip
under the PDF preview plus a two-card form split.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Captures the reasoning behind persisting two scalar columns on
documents rather than deriving aspect client-side or standing up a
thumbnail_metadata table. Also documents the 1.1 landscape threshold,
the null-during-rollout state, and the ordering invariants inside
ThumbnailService.generate().
Refs #305
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The archive has ~4 persons over 100 letters and ~90% with five or
fewer — the original spec's 851-letter default fit no one.
Redesign introduces three tiers gated on letterCount (Compact ≤ 5,
Standard 6–49, Rich ≥ 50) sharing one dashboard block: navy header +
4-cell stats strip at every non-Empty tier, with Standard appending
direction bar + top correspondents and Rich further appending
histogram + top locations + tag cloud. Backend skips expensive
aggregations for non-Rich persons; histogram and tag cloud ship
lazy-loaded.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Addresses @mkeller (Markus) — fixes(adr): "the ADR doesn't mention
in-memory BackfillStatus" and "treat this as a layering exception,
acknowledge it explicitly". Two new paragraphs under Operational caveats.
Refs #307
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Captures why thumbnails render in-process rather than being delegated
to ocr-service. Prevents a future reviewer from rehashing the decision
or moving it to the Python side without knowing the trade-offs.
Refs #307
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two production-ready specs following the chronik-spec format
(scaled wireframes × 3 viewports + impl-ref tables with exact Tailwind
classes and pixel values + WCAG contrast verification):
- briefwechsel-thumbnail-rows-spec.html — /briefwechsel row redesign
with PDF thumbnail, summary-as-quote, bilateral distribution bar;
drops status lifecycle and script-type indicators.
- person-dashboard-spec.html — new Korrespondenz-Überblick block on
/persons/[id] with stats, activity histogram, direction split, top
correspondents/locations, tag cloud. Every tile deep-links to
/briefwechsel with filters.
Both specs share the DistributionBar.svelte component.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Brainstorming artifact: 5 HTML mockups comparing approaches to fill the
sparse right-hand space on /briefwechsel rows (reported by users as
"feels empty"):
1. Rich Rows — dense metadata, no images
2. Thumbnail Rows — PDF preview on the left
3. Master-Detail Split — list + persistent preview panel
4. Gallery Cards — grid of letter cards, album style
5. Person Dashboard — insights live on /persons/[id], not here
Picked: #2 (Thumbnail Rows) + #5 (Person Dashboard), followed up by
final specs in separate commit.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- docs/adr/003-chronik-unified-activity-feed.md: records the session-rollup
decision (LAG + 120-min gap), the dedupe deletion, the single-endpoint
composition, and the German-URL convention.
- frontend/messages/{de,en,es}.json: adds chronik_* keys for page title,
Für-dich box, filter pills, day headers, singleton/rollup verb variants
per kind, empty states, error card, Mehr-laden pagination, and the Bell
footer link retarget.
No pluralization via ICU match — separate singleton/rollup keys per verb,
per the Felix discussion (comment #3573).
Part of #285.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Design spec for a dashboard widget that surfaces documents
needing metadata after batch upload. Placed between Resume
strip and MissionControlStrip rather than as a 4th strip
column (strip at visual capacity; batch reality makes count
tiles useless for seniors).
Covers responsive behavior at 320/768/1440, row anatomy with
72/64px touch targets, state matrix (empty/loading/error/
after-upload), full a11y contract, dark-mode verification
notes, and an impl-ref table with exact Tailwind classes.
Refs #296
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Spec replaces /notifications with a unified /chronik page that merges ambient
archive activity (6 of 8 AuditKinds) and personal mentions/replies. Covers 11
content states across 320/768/1440px viewports, dark mode parity, row anatomy
close-ups, interaction states, WCAG contrast verification, and implementation
notes (routing, API calls, rollup logic, Svelte component structure, i18n keys).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pixel-accurate spec for the dashboard redesign: Resume + Family Pulse
layout with hero resume card, mission control 3-up, and activity feed.
Relates to #271
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Captures the centered-card registration design 1:1 from the claude.ai/design export. Covers all 10 sections: desktop overview, header, above-card copy, form fields, password states, notification card, submit button, success panel, mobile layout, and i18n/a11y/backend implementation notes.
Relates to #269
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Visual spec for tree-aware tag typeahead: parent matches expand to
show children, child matches surface ancestor path for context.
Covers backend enrichment strategy (TagService.search enrichment via
existing recursive CTEs) and frontend DFS ordering + depth-indent
rendering in TagInput.svelte.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds the design decision record for how to expand the dashboard without
pushing content below the fold: a full-width 3-column strip (Segmentierung /
Transkription / Lesefertig) below the existing grid.
- dashboard-expansion-patterns.html — four pattern alternatives evaluated
(Tabs, Accordion, Mission Control, Priority Queue) with annotated mockups,
engagement feature proposal, and final recommendation.
- mission-control-strip-final.html — clean implementation blueprint with
pipeline diagram, column definitions, seeded-weekly-shuffle sorting,
expert-flag escape hatch, all Tailwind impl-ref values, and backend
contracts.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ADR-001 documents the decision to use a separate Python container for
OCR (Surya + Kraken), the interface contract, and why alternatives
like Tess4J were rejected.
ADR-002 documents the decision to store polygon annotations as JSONB
with a 4-point CHECK constraint, backed by an AttributeConverter.
Refs #226, #227
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
