familienarchiv/docs/superpowers/specs/2026-05-06-reader-dashboard-design.md

Reader Dashboard — Design Spec

Date: 2026-05-06 Status: Approved for implementation planning

---

Problem

The archive has two distinct user groups:

• Contributors — transcribe, annotate, upload. Comfortable with the current dashboard (MissionControlStrip, EnrichmentBlock, enrichment queue, activity feed).
• Readers — browse and consume finished content. Older, less technical. Currently overwhelmed by contribution-focused UI they cannot use and do not need.

---

Solution

Introduce a permission-gated reader dashboard that replaces the current dashboard for users without WRITE_ALL or ANNOTATE_ALL (including pure readers and story writers). The contributor dashboard remains unchanged.

---

Detection Logic

isReader     = !canWrite && !canAnnotate
showDrafts   = canBlogWrite   // overlays on reader dashboard only

BLOG_WRITE users land on the reader dashboard (not the contributor dashboard), because story writers are conceptually closer to readers than to transcribers. The drafts module appears on top of the reader layout when canBlogWrite is true.

canWrite, canAnnotate, canBlogWrite are already derived in +layout.server.ts and available in $page.data on all routes. No new backend work required for detection.

---

Reader Dashboard Layout

Five zones, rendered top-to-bottom:

1. Greeting

Unchanged from current dashboard — personalized, time-based greeting. Warm entry point for less technical users.

2. Stats Strip

Three linked stat tiles in a single row:

Tile	Value	Link
Dokumente	Total document count	/documents
Personen	Total person count	/persons
Geschichten	Total published story count	/geschichten

Each tile is a full-area anchor (<a>). Values come from the existing stats endpoint already called by the current dashboard.

3. Drafts Module (conditional — BLOG_WRITE only)

Shown only when canBlogWrite is true, between the stats strip and the person chips.

• Section heading: "Meine Entwürfe"
• Lists all draft stories authored by the current user, sorted by updated_at DESC
• Each entry shows: story title + "Entwurf · zuletzt bearbeitet vor X" relative timestamp
• Each entry links to /geschichten/[id]/edit
• Empty state: "Keine Entwürfe" (no empty-state CTA needed — they can create from /geschichten)

This module appears on the reader dashboard because a user can hold READ_ALL + BLOG_WRITE without WRITE_ALL.

4. Person Chips

Top 4 persons by total document count, each linking to /persons/[id]. Followed by an overflow link "Alle N Personen →" pointing to /persons.

• Chip content: display name + document count (e.g., "Käthe Raddatz · 23 Dok.")
• Layout: flex flex-wrap gap-2 — chips reflow gracefully at narrower viewports
• Data source: persons list endpoint, sorted by document count DESC, limit 4

Rationale: readers most often browse by person rather than searching for a specific document. Surfacing the most-documented family members at the top answers "where do I start?"

5. Two-Column Content Row

Side-by-side at desktop; stacks to single column on mobile (below md breakpoint).

Left column — "Zuletzt aktualisiert" (flex: 3)

5 most recently updated documents, sorted by updated_at DESC. No status filter — uploads and transcription updates are both relevant.

Each row shows:

• Document thumbnail placeholder (or actual thumbnail if available)
• Document title (linked to /documents/[id])
• Sender name (linked to /persons/[id]) if present; omitted if document has no sender + relative timestamp

Right column — "Geschichten" (flex: 2)

3 most recently published stories.

Each entry shows:

• Story title (italic serif, linked to /geschichten/[id])
• First ~150 characters of body text as excerpt
• Relative publication timestamp

---

What Is Hidden from Readers

Component	Reason
MissionControlStrip	Transcription queue — contributor-only
EnrichmentBlock	Incomplete-document workflow — contributor-only
DashboardResumeStrip	Contribution resume metric — meaningless to readers
DashboardFamilyPulse	Contribution-focused activity metrics
DashboardActivityFeed	Replaced by the simpler "Zuletzt aktualisiert" feed
DropZone	Already gated on canWrite — unchanged

---

Backend Changes

The reader dashboard reuses data from endpoints already called by the existing dashboard where possible. New or adapted calls:

Data	Endpoint	Notes
Stats (docs, persons, stories)	Existing stats endpoint	Already fetched
Top 4 persons by doc count	GET /api/persons?sort=documentCount,desc&size=4	Verify sort param exists; add if not
Recent 5 documents	GET /api/documents?sort=updatedAt,desc&size=5	Verify sort param exists; add if not
Recent 3 stories	GET /api/geschichten?published=true&sort=updatedAt,desc&size=3	Verify sort param and published filter
Draft stories (BLOG_WRITE only)	GET /api/geschichten?published=false&authorId=currentUser&size=10	Verify author filter exists; add if not

The +page.server.ts load function should branch on isReader: fetch the reader data set instead of the contributor data set. This avoids loading transcription queues, enrichment data, and weekly stats for users who will never see them.

---

Frontend Changes

• +page.server.ts: add isReader flag derived from layout data; branch fetch logic
• +page.svelte: conditional render — reader layout vs. current contributor layout
• New components (all in src/lib/shared/dashboard/):
  • ReaderStatsStrip.svelte — the three linked stat tiles
  • ReaderPersonChips.svelte — top-N person chips + overflow link
  • ReaderRecentDocs.svelte — recent documents feed
  • ReaderRecentStories.svelte — recent stories feed
  • ReaderDraftsModule.svelte — draft stories (rendered conditionally on canBlogWrite)

---

Non-Functional Requirements

• NFR-PERF-001: Reader dashboard must load in ≤ 2 s on broadband (time-to-interactive). Achieved by fetching only the 4 lean endpoints above instead of the current 10.
• NFR-A11Y-001: All stat tiles and person chips must be keyboard-navigable (<a> elements, not <div onclick>).
• NFR-RESP-001: Two-column row stacks to single column at < md (768 px). Person chips wrap via flex-wrap.
• NFR-I18N-001: All new section headings and labels must have keys in messages/{de,en,es}.json.

---

Out of Scope

• Mobile-specific reader dashboard (responsive reflow is sufficient for now)
• Admin dashboard variant
• Any change to the contributor dashboard
• Personalization / "favourite persons" feature (possible future enhancement)
• Notification or messaging features for readers

---

Open Questions

ID	Question	Blocks
OQ-01	Does GET /api/persons support sort=documentCount,desc?	ReaderPersonChips data
OQ-02	Does GET /api/documents support sort=updatedAt,desc?	ReaderRecentDocs data
OQ-03	Does the stories endpoint support published=false + author filter for drafts?	ReaderDraftsModule data
OQ-04	Should the "Zuletzt aktualisiert" label distinguish uploads from transcription updates (e.g., badge)?	ReaderRecentDocs UX