marcel
49d8ab78b4
Some checks failed
CI / Unit & Component Tests (push) Successful in 7m35s
CI / OCR Service Tests (push) Successful in 36s
CI / Backend Unit Tests (push) Failing after 12m42s
CI / fail2ban Regex (push) Successful in 1m50s
CI / Semgrep Security Scan (push) Successful in 37s
CI / Compose Bucket Idempotency (push) Successful in 1m18s
Closes #850 ## Summary On `/zeitstrahl`, a curated event that has letters linked to it now renders as a contained event card — the event is the card header (accent glyph, title, `{date} · {kuratiert|abgeleitet}` subtitle, count, and a curator edit link), with its linked letters listed inside (first 5, then a keyboard-operable show-more/less toggle). Letters in a year *other* than the event's band get a lighter cross-year `✉ title` card. Every other letter stays a plain, alternating, density-folding chronological letter. There is **no grouping control** — clustering is automatic and always on. The meta-line drops its `Gruppierung: Datum` segment. This supersedes #827: it keeps that branch's event-card clustering and the computed `linkedEventId`, and drops the toggle, the Thema mode, and the "Weitere Briefe" drawer. ## What changed **Backend** - `TimelineEntryDTO` gains a nullable `linkedEventId` (UUID; not `@Schema(REQUIRED)`). - `TimelineService.resolveLetterEventLinks` resolves each letter's curated event in one batched pass over the events it already loads — no per-letter query, no new column, no Flyway migration. - Regenerated the single `linkedEventId?` field in `api.ts`. **Frontend** - New `eventClustering.ts` (`buildEventLookup`, `splitYearLetters`, `CLUSTER_PREVIEW=5`) — filter-then-cluster: a letter clusters only if its `linkedEventId` is set AND present in the lookup, otherwise it stays loose. - New `EventCluster.svelte` — the contained event card (same-year event header + edit link, or cross-year ✉ text header; first-5 + show-more). - `LetterCard.svelte` gains `compact` + `variant='event'` (the `.lcard.ev` in-card letter). - `YearBand.svelte` rebuilt to render event clusters inline; loose letters keep the alternating layout and density strip, and the strip counts **only** loose letters (no duplication). - `TimelineView.svelte` builds the event lookup once and threads it + `canWrite` to each band. - `+page.svelte` drops the grouping meta segment; the unused `timeline_grouping_date` key removed from de/en/es. - New `timeline_bucket_show_more`/`_less` keys in all locales. - REQ-010 `{@html}` grep gate over `lib/timeline/`. ## Tests (real runs) - Backend `TimelineServiceTest`: **30 passed** (incl. the 2 new `linkedEventId` tests); `DerivedEventsAssemblyTest`: 17 passed; backend main sources compile. - Frontend client sweep (`LetterCard`, `EventCluster`, `YearBand`, `TimelineView`, `zeitstrahl/page`): **81 passed** (5 files). - Frontend server sweep (`eventClustering`, `messages`, `timeline-no-raw-html`): **18 passed** (3 files). - `svelte-check`: no new errors in the touched files (pre-existing baseline noise elsewhere unchanged). RTM: thirteen `REQ-001..013` rows added for #850 (feature `inline-event-clustering`), Status Done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Marcel <marcel@familienarchiv> Reviewed-on: #851
Familienarchiv
Familienarchiv is a private web application for digitising, organising, and searching a family document collection — letters, postcards, and photographs from 1899 to 1950. Family members upload scans, transcribe handwritten text (Kurrent/Sütterlin), and read the archive from any device.
Subsystems
frontend/— SvelteKit 2 / Svelte 5 / TypeScript / Tailwind 4 web app (server-side rendered)backend/— Spring Boot 4 (Java 21) REST API; handles documents, persons, search, and user managementocr-service/— Python FastAPI microservice for OCR and handwritten text recognition (HTR); single-node by design — see ADR-001. Not part of the default dev stack (see Quick start below)infra/— Gitea Actions CI/CD config; future home for infrastructure-as-codescripts/— operational and data-pipeline helpers (reset-db.sh,clean-e2e-data.sh, import scripts)
Quick start
Prerequisites: Java 21, Node 24, Docker with the docker compose plugin (V2).
1. Configure environment
cp .env.example .env
# The defaults in .env.example work for local development without changes.
2. Start infrastructure
# Starts PostgreSQL, MinIO (object storage), and Mailpit (dev mail catcher)
docker compose up -d db minio mailpit
3. Start the backend
cd backend
./mvnw spring-boot:run
# Starts on http://localhost:8080
# API docs (dev profile, auto-enabled): http://localhost:8080/v3/api-docs
4. Start the frontend
cd frontend
npm install
npm run dev
# Starts on http://localhost:5173
Open http://localhost:5173 — you should see the Familienarchiv login screen.
Default development credentials:
# local dev only — change before any network-exposed deployment
Email: admin@familyarchive.local
Password: admin123
Development setup only. The default
docker composeconfig exposes the database port and uses root MinIO credentials. Do not connect this to a network without first readingdocs/DEPLOYMENT.md(coming: DOC-5, #399).
Running the full stack via Docker (optional)
To run everything including the backend and frontend in containers:
docker compose up -d
Note: the OCR service (ocr-service/) builds its Docker image locally and downloads ~6 GB of ML models on first start. Expect 30–60 minutes on a first run. The rest of the stack starts independently; OCR can be excluded with --scale ocr-service=0 on memory-constrained machines (requires ≥ 12 GB RAM).
Where to go next
| Resource | Purpose |
|---|---|
| docs/architecture/c4-diagrams.md | C4 container and component diagrams (current system view) |
| docs/ARCHITECTURE.md (coming: DOC-2, #396) | Full architecture guide with domain list |
| docs/GLOSSARY.md | Overloaded terms: Person vs AppUser, Chronik vs Aktivität, etc. |
| CONTRIBUTING.md (coming: DOC-4, #398) | How to add a domain, endpoint, or SvelteKit route |
| docs/DEPLOYMENT.md (coming: DOC-5, #399) | Production deployment checklist and secrets guide |
| docs/adr/ | Architecture Decision Records — the "why" behind key choices |
| Gitea issue tracker (internal — home network only) | Bug reports, feature requests, and project planning |
License
Private project — all rights reserved. Not licensed for redistribution.