# Familienarchiv — Application Analysis

_2026-04-12_

> Analysis of the family archive application for polish issues, missing features, and improvements across research, discoverability, and collaboration. Each item was discussed and triaged — only actionable items were kept, the rest are documented as "skipped" with reasoning.

---

## 1. Polish Issues (Regressions & Rough Edges)

_Items 1.1–1.5 were identified but not discussed in detail during triage._

### 1.1 Archive Box & Folder fields missing from UI

The backend `Document` entity has `archiveBox` and `archiveFolder` fields but they're not in the `DocumentUpdateDTO`, not in any form, not in the detail view, and not in search results. The `documentLocation` free-text field exists but the structured pair is unused.

### 1.2 Legacy transcription textarea on edit/create pages

The edit and create pages include a `<TranscriptionSection>` plain textarea that writes to `Document.transcription`, while the detail view uses the annotation-based `TranscriptionBlock` system. The two are disconnected — editing the textarea could overwrite or conflict with block-based transcriptions.

### 1.3 Person `title` field not in frontend forms

The `title` field (honorifics like "Dr.", "Prof.") was added to the backend but the person edit/create forms don't expose it.

### 1.4 Person `personType` not editable

Person type (`PERSON`, `INSTITUTION`, `GROUP`) is displayed as a badge but cannot be changed on the edit page.

### 1.5 Document detail doesn't show summary, documentLocation, or tags prominently

The metadata drawer shows date, location, status, persons, and tags but not `documentLocation`, `summary`, or `archiveBox`/`archiveFolder`.

### 1.6 Dashboard stats are minimal — SKIPPED

The recent activity box already shows total document and person counts in context. Dashboard elements should earn their space by driving action, not just displaying numbers. Current setup is sufficient.

---

## 2. Research (Finding Specific Documents)

_Goal: A user has a specific question — "Who wrote to Großvater in 1943?" or "Where is the contract about the house?" — and wants precise answers._

### 2.1 No status filter in search — SKIPPED

The document status system (`PLACEHOLDER`, `UPLOADED`, `TRANSCRIBED`, `REVIEWED`, `ARCHIVED`) is mostly technical and adds no real value to the user. The status concept itself needs rethinking or removal — that's a separate design question, not a missing search filter.

### 2.2 Search result snippets with match highlighting — [#219](http://heim-nas:3005/marcel/familienarchiv/issues/219)

Search results show title, date, sender, receivers, and tags but not _why_ a document matched. With 1500+ documents, users can't evaluate results without opening each one. Show a short text snippet with the matching term highlighted.

**Priority:** Low — nice-to-have for later.

### 2.3 No pagination — SKIPPED

Not a problem yet at current scale.

### 2.4 Year/group headers in date-sorted results — [#220](http://heim-nas:3005/marcel/familienarchiv/issues/220)

The briefwechsel page already has a timeline and works with a single person. For the main search results, adding year headers (e.g. "1938", "1939") when sorted by date gives chronological structure without building a full timeline view.

### 2.5 Improved tag system — AND/OR + hierarchy — [#221](http://heim-nas:3005/marcel/familienarchiv/issues/221)

Power users would benefit from AND/OR tag filtering, tag hierarchy (parent/child relationships), and a tag overview page with document counts.

### 2.6 Upgrade search to PostgreSQL full-text search — [#222](http://heim-nas:3005/marcel/familienarchiv/issues/222)

Current search uses `ILIKE %query%` — no stemming, no ranking, no boolean operators. Upgrading to PostgreSQL's `tsvector`/`tsquery` with the German dictionary gives stemming ("Briefe" matches "Brief"), relevance ranking, boolean operators, prefix matching, and phrase matching. Zero new infrastructure needed.

### 2.7 No related documents — SKIPPED

The person detail page and briefwechsel page already surface document connections. Cross-references from the document view aren't needed.

---

## 3. Discoverability (Browsing Without a Goal)

_Goal: A user wants to explore old family documents — maybe browse Opa's letters, look through documents from the 1920s, or just see what's interesting._

### 3.1 Sorting options on person list page — [#223](http://heim-nas:3005/marcel/familienarchiv/issues/223)

The person list only supports search by name. Adding sort options (most documents, last document date, recently updated) helps users discover prominent persons without needing a dashboard widget.

### 3.2 Person detail page lacks a narrative — SKIPPED

The page already shows at-a-glance stats, co-correspondents (top 5), and sent/received document lists. Sufficient as-is.

### 3.3 No visual browsing mode — SKIPPED

The archive is primarily text documents (letters, contracts). Thumbnail galleries and map views are not a good fit.

### 3.4 Top conversation pairs on briefwechsel entry state — [#224](http://heim-nas:3005/marcel/familienarchiv/issues/224)

The briefwechsel page works with a single person, but the entry/empty state could show the most active conversation pairs ranked by document count. Clicking a pair pre-fills both persons and loads the timeline — a low-effort discoverability win.

### 3.5 No tag-based navigation — covered by [#221](http://heim-nas:3005/marcel/familienarchiv/issues/221)

The tag overview page proposed in #221 covers this.

### 3.6 Dashboard doesn't surface interesting content — SKIPPED

Current dashboard is action-oriented (resume, incomplete docs, recent docs). Adding "fun" widgets would be clutter.

### 3.7 No era grouping — covered by [#220](http://heim-nas:3005/marcel/familienarchiv/issues/220)

Year headers in search results cover this use case.

---

## 4. Collaboration (Working Together to Preserve)

_Goal: Family members want to divide work — transcribing handwritten letters, identifying unknown persons, correcting metadata — and track collective progress._

### 4.1 No assignment or claim system for enrichment — SKIPPED

Enrichment typically takes only a few minutes per document, so the collision risk is low. Not worth the overhead of a claiming system.

### 4.2 Transcription has no review workflow — SKIPPED

The `[unleserlich]` convention for unreadable text plus comment threads with @mentions already cover the "I need help reading this" case. Sufficient for now.

### 4.3 Comments not surfaced for action — SKIPPED

The notification page with mention/reply filtering is sufficient for now.

### 4.4 No activity feed — SKIPPED

Not enough benefit for the effort to track and display it.

### 4.5 No progress tracking — SKIPPED

Hard to track accurately and not needed yet.

### 4.6 Batch operations for documents — [#225](http://heim-nas:3005/marcel/familienarchiv/issues/225)

When importing or processing batches from the same physical location or sender, editing one-at-a-time is tedious. Multi-select in the document list with bulk tag, sender, and archive location assignment.

### 4.7 Person merge is hidden — SKIPPED

Manual merge via the person edit page works fine for current needs.

### 4.8 No "help needed" signals — SKIPPED

Duplicate of 4.2 — `[unleserlich]` + comment mentions already cover this.

---

## 5. Summary

### Issues created

| # | Title | Category | Labels |
|---|-------|----------|--------|
| [#219](http://heim-nas:3005/marcel/familienarchiv/issues/219) | Search result snippets with match highlighting | Research | feature, ui |
| [#220](http://heim-nas:3005/marcel/familienarchiv/issues/220) | Year/group headers in date-sorted results | Research | feature, ui |
| [#221](http://heim-nas:3005/marcel/familienarchiv/issues/221) | Improved tag system — AND/OR + hierarchy | Research | feature |
| [#222](http://heim-nas:3005/marcel/familienarchiv/issues/222) | Upgrade search to PostgreSQL full-text search | Research | feature |
| [#223](http://heim-nas:3005/marcel/familienarchiv/issues/223) | Sorting options on person list page | Discoverability | feature, person |
| [#224](http://heim-nas:3005/marcel/familienarchiv/issues/224) | Top conversation pairs on briefwechsel entry state | Discoverability | feature, conversation |
| [#225](http://heim-nas:3005/marcel/familienarchiv/issues/225) | Batch operations for documents | Collaboration | feature, collaboration |

### Skipped items (with reasoning)

| Item | Why skipped |
|------|-------------|
| Dashboard stats minimal | Stats already shown in recent activity box |
| Status filter in search | Status is technical, needs rethinking not filtering |
| No pagination | Not a problem at current scale |
| No related documents | Person page + briefwechsel already cover this |
| Person detail lacks narrative | Already has stats, co-correspondents, document lists |
| No visual browsing | Not a fit for text-heavy archive |
| Dashboard interesting content | Would be clutter, current dashboard is action-oriented |
| Enrichment claiming | Low collision risk, enrichment is quick |
| Transcription review workflow | [unleserlich] + comment mentions sufficient |
| Comments not surfaced | Notification page sufficient |
| Activity feed | Effort/benefit ratio too low |
| Progress tracking | Hard to track, not needed yet |
| Person merge hidden | Manual workflow works fine |
| Help needed signals | Covered by [unleserlich] + mentions |
