Ereignis-Editor & Brief-Gruppierung · Quick-Action im Dokument
+
Wie kuratierte Zeitstrahl-Ereignisse entstehen und wie Briefe gruppiert werden — von zwei Seiten in ein Datenmodell (TimelineEvent.documents): der Ereignis-Editor unter /zeitstrahl/events/[id]/edit (Kurator baut, verlinkt viele Briefe) und die Quick-Action im Dokument-Detail (beim Lesen schnell zuordnen). Beide bauen auf bereits ausgelieferten Komponenten auf.
Familienarchiv · 2026-06-08 · Leonie Voss, UX Lead · gegründet auf Code: GeschichteEditor.svelte · DocumentMetadataDrawer.svelte · DocumentMultiSelect.svelte
+
+
+
+
+
+
1 · Zwei Einstiegspunkte, ein Datenmodell
+
Manuelle Gruppierung = ein TimelineEvent mit verknüpften Dokumenten. Kuratoren arbeiten in beide Richtungen — wir bauen beide, statt eine zu erzwingen.
+
+
+
+ A · Ereignis-zuerst — der Kurator baut den Zeitstrahl. /zeitstrahl/events/new · [id]/edit mit Dokument-Mehrfach-Picker = Bulk-Linking vieler Briefe auf einmal. Spiegelt 1:1 den GeschichteEditor (gleiche zwei-Spalten-Form, Sidebar-Picker, Sticky-Save-Bar).
+
+
+ B · Dokument-zuerst — beim Lesen eines Briefs. Quick-Action im Dokument-Detail: bestehendes Ereignis wählen oder neu anlegen, verlinkt diesen einen Brief. Spiegelt die bestehende Geschichten-Spalte im Details-Drawer (DocumentMetadataDrawer.svelte).
+
Bei „Zeitspanne" erscheint ein zweites End-Datum-Feld. Bei „ca." / „Saison" passt sich nur das Label an.
+
+
+
+
+
④ Beschreibung · optional
+
Karls Feldpost von der Westfront, 1915 — wöchentliche Briefe an Elfriede und den neugeborenen Hans. Eine zusammenhängende Korrespondenz, die hier als Cluster gebündelt wird …
+
Schlichtes Textfeld (kein Rich-Text wie Geschichten) — Ereignisse sind kurze Notizen, keine Langform.
+
+
+
+
+
+
+
+
+
+ Änderungen werden erst beim Speichern übernommen.
+
+ Löschen
+ Abbrechen
+ Speichern
+
+
+
+
+
+
+
①Titel — großes Serifen-Feld, wie der Geschichten-Titel. Pflichtfeld (Validierung bei Blur).
+
②Typ — PERSONAL / HISTORICAL Segmented-Control. Steuert Rendering (Mint-Pille vs. Welt-Band).
+
③Datum + Präzision — geteilte DatePrecisionInput (gleiche Logik wie Dokument-Datum, metaDatePrecision). „Zeitspanne" blendet End-Datum ein.
⑤Verknüpfte Briefe — hier wird gruppiert. Wiederverwendung von DocumentMultiSelect (Typeahead, Chips, Hidden-Inputs).
+
⑥Beteiligte Personen — PersonMultiSelect. Bestimmt, in welchem „Lebensweg" das Ereignis auftaucht.
+
⑦Sticky-Save-Bar — Speichern primär, Abbrechen sekundär, Löschen nur im Edit-Modus (mit Bestätigung).
+
＋/new — leeres Formular. Mit ?documentId=… ist Feld ⑤ vorbefüllt (aus der Quick-Action, §4-D).
+
+
+
+
+
+
3 · Brief-Gruppierung im Editor — der Dokument-Picker
+
Feld ⑤ ist der unveränderte DocumentMultiSelect: Tippen sucht über /api/documents/search?q=… (debounced 300 ms), Treffer mit ehrlichem Datums-Label, bereits gewählte werden gefiltert. Jeder Klick fügt einen Brief zum Cluster.
Brief aus dem Verdun-Lazarett · Brief · August 1916
+
Rückkehr aus Verdun · Brief · ca. 1917
+
+
Label = title · formatDocumentDate(precision). Bereits verknüpfte Briefe erscheinen nicht in den Treffern (Dedup).
+
+
+
+
+
Inline „＋ Ereignis" am Jahres-BandZeitstrahl
+
+
+
+
1915
+
✉ 24 Briefe
Monats-Dichte ▾
+
+
+
Kuratoren können auch direkt im Zeitstrahl ein Ereignis anlegen — öffnet denselben Editor, Jahr & Briefe des Bandes vorbefüllt.
+
+
+
+
+
+
+
+
+
+
4 · Quick-Action im Dokument-Detail — wo sie lebt
+
Die Dokument-Detailseite ist ein vollflächiger Viewer ohne Sidebar (fixed inset). Aktions-Flächen gibt es nur zwei: die DocumentTopBar und den aufklappbaren Details-Drawer. Die Quick-Action lebt an beiden — primär als „Zeitstrahl"-Spalte im Drawer (spiegelt die Geschichten-Spalte), plus ein Top-Bar-Button für den Ein-Klick-Weg.
+
+
+
Warum der Details-Drawer der richtige Ort ist: Er zeigt heute schon, wozu ein Brief gehört — Personen, Schlagwörter und Geschichten (mit „Zuordnen"-Aktion, gegated über canBlogWrite, DocumentMetadataDrawer.svelte:210). Zeitstrahl-Ereignisse sind strukturell identisch („dieser Brief gehört zu diesen Ereignissen") und bekommen daher eine gleichwertige vierte/fünfte Spalte. Konsistent & auffindbar dort, wo Nutzer ohnehin „Zugehörigkeit" suchen.
ATop-Bar-Button „⊕ Zeitstrahl" — Mint-Akzent im Aktions-Cluster (DocumentTopBarActions). Öffnet ein kleines Popover zum Ein-Klick-Zuordnen, ohne den Drawer zu öffnen. Im Mobile-Menü als Eintrag.
+
B„Zeitstrahl"-Spalte im Details-Drawer — neue Spalte neben Geschichten. Zeigt verknüpfte Ereignisse (Titel · Datum · Tag-Chip), Unlink über ×, plus Quick-Add-Zeile. Nur sichtbar/aktiv bei canWrite.
D„＋ Neu" → /zeitstrahl/events/new?documentId={id} — öffnet den Editor (§2) mit diesem Brief in Feld ⑤ vorbefüllt. Spiegelt /geschichten/new?documentId=.
+
+
+
+
+
5 · Quick-Action — Zustände
Der Typeahead in der Zeitstrahl-Spalte (oder im Top-Bar-Popover). Gleiches Muster wie DocumentMultiSelect, nur sucht es Ereignisse statt Dokumente.
TimelineEventController, WRITE_ALL; TimelineEventRequest mit documentIds / personIds
+
Backend — Link/Unlink
PUT /api/timeline/events/{id}
Verlinken/Lösen läuft über das Event-Update (documents-Set); kein neuer ErrorCode nötig
+
Barrierefreiheit
—
Picker-Dropdowns Tastatur-navigierbar (↑↓↵), aria-live für „verknüpft/gelöst"; 44px-Ziele; sichtbarer Fokus-Ring; Löschen/Unlink mit Bestätigung
+
+
+
Offene Designentscheidung: Soll der Top-Bar-Button (A) MVP sein oder reicht zunächst die Drawer-Spalte (B)? Empfehlung: B als MVP (spiegelt Geschichten exakt, geringster Aufwand), A als schneller Nachzug.
Kanonische Spezifikation für /zeitstrahl auf Basis von Konzept A „Der Lebensfaden": eine durchgehende vertikale Achse, die Personen-Lebensereignisse, kuratierte Ereignisse und Briefe zu einer Erzählung in der Zeit verwebt. Dieselbe Komponente betreibt den globalen Zeitstrahl und den per-Person „Lebensweg". Enthält die vollständige Fall-Abdeckung (leere Jahre, wenige Briefe, hunderte Briefe, undatiert) und die drei Gruppierungs-Modi.
+
+ Milestone #14 · Zeitstrahl
+ Konzept A — final
+ Phone-first · honest DatePrecision
+
+
Familienarchiv · 2026-06-08 · Leonie Voss, UX Lead · ersetzt die A/B/C-Exploration zeitstrahl-global-concepts.html
+
+
+
+
+
+
1 · Anatomie von Konzept A
+
Eine Achse, sieben Bausteine. Die Zeit ist die Achse — Lebensereignisse & Jahre als zentrierte Pillen unterbrechen den Faden (Text wird nie von der Linie gekreuzt), Welt-Ereignisse legen sich als Bänder quer, Briefe verdichten sich adaptiv.
+
+
+
+
⚭
Lebensereignis-Pille
Geburt * · Tod † · Heirat ⚭. Abgeleitet aus Person-Daten. Zentriert, gefüllt — unterbricht die Achse. Glyphen aus personLifeDates.ts.
+
★
Kuratierte Ereignis-Pille
PERSONAL — Umzug, Auswanderung. Mint-Rand. Editierbar im Kurator-Editor.
+
◍
Welt-Band
HISTORICAL — Krieg, Inflation. Gedämpftes Band quer über die Achse als Kontext.
+
Einzel-Brief
Kleiner Punkt + Karte, alternierend links/rechts. Wurzel-Tag-Farbchip. Link zu /documents/[id].
Ruhige/leere Jahre als dünne Span-Zeile gefaltet; UNKNOWN-Briefe im „Ohne Datum"-Eimer am Ende.
+
+
+
Gruppierungs-Umschalter (oben rechts im Zeitstrahl): DatumEreignisThema steuert nur, wie lose Briefe gebündelt werden. Lebensereignisse, kuratierte Ereignisse und Welt-Bänder bleiben in allen Modi gleich auf der Achse. Standard = Datum.
+
+
+
+
+
2 · Die drei Gruppierungs-Modi
+
Gleicher Ausschnitt (1914–1915), dreimal gerendert. Nur die losen Briefe ordnen sich um — die Achse bleibt stabil. Schmale Spaltenbreite = Phone-/Lebensweg-Form derselben Komponente.
+
+
+
+
+
+
+
Datum Chronologisch
+
Standard. Briefe nach Datum; dichte Jahre verdichten zum Strip. Reine Zeit-Reihung.
+
+
+
1914
+
⚭
Heirat: Karl & Elfriede
1914 · abgeleitet
+
◍ Erster Weltkrieg
1914–1918
+
✉ Kriegsausbruch — Brief an die Familie
Karl → Elfriede · 4. Aug 1914
+
+
1915
+
*
Geburt: Hans Raddatz
Sommer 1915 · abgeleitet
+
+
✉ 24 BriefeMonate ▾
+
+
+
+
+
+
+
+
+
Ereignis Kuratiert
+
Briefe bündeln unter kuratierte Ereignisse (TimelineEvent.documents). Erzählende Cluster statt Listen.
+
+
+
1914
+
⚭
Heirat: Karl & Elfriede
1914 · abgeleitet
+
◍ Erster Weltkrieg
1914–1918
+
+
1915
+
*
Geburt: Hans Raddatz
Sommer 1915 · abgeleitet
+
✉ Briefe von der Front · 24
Karl ⇄ Elfriede & Hans · 1915 ▾
Krieg
+
✉ Weihnachten 1915 · 3
kuratiertes Ereignis ▾
Weihnachten
+
+
+
+
+
+
+
Thema Nach Wurzel-Tag
+
Optional (Post-MVP). Lose Briefe je Jahr in Wurzel-Tag-Eimer; Mehrfach-Tags dedupliziert auf den primären.
+
+
+
1914
+
⚭
Heirat: Karl & Elfriede
1914 · abgeleitet
+
◍ Erster Weltkrieg
1914–1918
+
Krieg6 ▾
+
+
1915
+
*
Geburt: Hans Raddatz
Sommer 1915 · abgeleitet
+
Krieg › Briefe von der Front24 ▾
+
Weihnachten3 ▾
+
Familie2 ▾
+
+
+
Hinweis im UI: „Brief mit mehreren Tags erscheint unter seinem primären Tag."
+
+
+
+
+
+
+
+
3 · Vollständige Vorschau — alle Dichte-Fälle
+
Ein durchgehender Zeitstrahl (Desktop, zentrale Achse) von 1899 bis „Ohne Datum". Jeder Dichte-Fall kommt genau einmal vor — von leeren Jahren bis zu hunderten Briefen.
+
+
+
+ Abgedeckte Fälle:
+ ① leere Jahre (gefaltete Lücke) ·
+ ② wenige Briefe ≤ 3 (einzelne Karten) ·
+ ③ hunderte Briefe (Jahres-Strip + Sparkline) ·
+ ④ kuratiertes Ereignis & Welt-Band ·
+ ⑤ ungenaue Präzision (Sommer, ca.) ·
+ ⑥ undatierte Briefe (Ohne-Datum-Eimer).
+
+
+
+
Zeitstrahl
+
Die Familie Raddatz · 1899–1950 · 412 Briefe · 38 Ereignisse · Gruppierung: Datum
+
+
① Leere Jahre → gefaltet
+
+
+
+
1899 – 1908 · keine Einträge
+
+
+
1909
+
② Wenige Briefe → einzeln
+
✉ Brief aus Stettin
Elfriede → Karl · Mai 1909
Familie
+
✉ Geburtstagsgruß
Karl → Hans · Sep 1909
+
✉ Brief zum Jahresende
Karl → Elfriede · Dez 1909
Weihnachten
+
+
+
1914
+
⚭Heirat: Karl & Elfriede Raddatz1914 · abgeleitet aus Beziehung
+
④ Welt-Band (RANGE 1914–1918)
+
◍ Erster Weltkrieg1914–1918 · historisch · 187 Briefe in dieser Zeit
+
+
+
1915
+
③ Hunderte Briefe → Jahres-Strip⑤ „Sommer 1915"
+
*Geburt: Hans RaddatzSommer 1915 · abgeleitet · SEASON
★Auswanderung nach ArgentinienFrühjahr 1924 · persönlich · kuratiert
+
+
+
1925 – 1950 · keine Einträge
+
+
+
+
⑥ Undatiert → eigener Eimer am Ende
+
+
Ohne Datum · 11 Briefe
+
Brief ohne JahresangabePräzision UNKNOWN
+
Fragment, Absender unklar+ 9 weitere ▾
+
+
+
Kein erfundenes Datum: undatierte Briefe wandern nie spekulativ in ein Jahr, sondern bleiben sichtbar im Eimer. RANGE-Einträge (Krieg) erscheinen einmal im Start-Jahr mit Spannen-Marker, nicht in jedem überspannten Jahr.
+
+
+
+
4 · Datums-Präzision (geteilt von Ereignissen & Briefen)
Eine Render-Logik für alle datierten Einträge — dateLabel.ts, gespeist von DatePrecision.
+
+
+
DatePrecision
Darstellung
Beispiel
Wirkung auf der Achse
+
DAY
vollständiges Datum
28. Juli 1914
exakte Sortierung im Jahres-Band
+
MONTH
Monat + Jahr
Juli 1914
Monats-Sortierung
+
SEASON
Jahreszeit + Jahr
Sommer 1914
grobe Reihung
+
YEAR
nur Jahr
1914
ans Band-Ende
+
APPROX
„ca." + Jahr
ca. 1914
mit „ca."-Marker
+
RANGE
Start–Ende
1914–1918
Start-Jahr, Spannen-Marker, nicht dupliziert
+
UNKNOWN
undatiert
Ohne Datum
eigener Eimer am Ende
+
+
+
+
+
+
5 · Responsiv — eine Komponente, drei Breiten
Identisches Markup & identische Daten. Nur die Achs-Position wechselt per Container-Query.
+
+
▏
≥ 1024px · Desktop
Zentrale Achse, Briefe alternierend links/rechts, Welt-Bänder über volle Breite. Pillen unterbrechen die Linie.
Der „Zeitstrahl" unter /zeitstrahl ist die globale Familien-Chronik. Diese Exploration beantwortet zuerst die entscheidende Frage — warum sollte jemand den Zeitstrahl benutzen statt einfach durch die sortierte Suchliste zu scrollen? — und zeigt dann drei Layout-Konzepte, die genau das tun, was die Suche nicht kann: drei Ebenen zu einer Erzählung in der Zeit verweben.
Die Gefahr: zwei Seiten, die wie dasselbe wirken. Wenn der Zeitstrahl nur „Briefe, chronologisch" zeigt, fragt jeder zu Recht — wozu? Der Unterschied ist nicht die Sortierung. Es sind die drei Ebenen und der historische Kontext, die nur hier zusammenkommen.
+
+
+
+
+
+
/documents · nach Datum sortiertEINE EBENE
+
+
Brief über die Lage an der Westfront
Karl → Elfriede Raddatz
Mär 1915
+
Feldpost aus Verdun
Hans → Karl Raddatz
Jul 1915
+
Brief an die Eltern
Karl → Elfriede Raddatz
Sep 1915
+
Päckchen-Dank
Karl → Elfriede Raddatz
Nov 1915
+
Nur Briefe. Keine Geburten, keine Hochzeiten, kein Krieg. Warum 1915 so viele Feldpostbriefe? Die Liste sagt es nicht — man muss es wissen.
+
+
+
+
vs
+
+
+
+
/zeitstrahl · die Familie in der ZeitDREI EBENEN
+
+
+
1914
+
⚭ Heirat: Karl & Elfriede Raddatz· abgeleitet
+
Erster Weltkrieg 1914–1918 · historisch
+
1915
+
4 Briefe· Feldpost von der Westfront
+
* Geburt: Hans Raddatz· abgeleitet
+
1918
+
Kriegsende Nov 1918 · historisch
+
+
+
+
+
+
Der Aha-Moment: Plötzlich ergeben die vier Feldpostbriefe von 1915 Sinn — sie liegen zwischen Hochzeit und Kriegsende, neben der Geburt des Sohnes. Die Suche findet Dokumente. Der Zeitstrahl erzählt, was mit der Familie geschah. Das ist kein sortierter Listenfilter — es ist eine Erzählung, die die Suche strukturell nicht leisten kann.
+
+
+ Fünf Dinge, die nur der Zeitstrahl kann — und die jede Konzept-Variante sichtbar machen muss:
+
+
① Personen-Lebensereignisse (Geburt *, Tod †, Heirat ⚭) — abgeleitet aus kuratierten Personendaten, gibt es in der Suche gar nicht.
+
② Kuratierte Ereignisse — persönlich (Umzug, Auswanderung) & historisch (Krieg, Inflation), redaktionell, immer korrekt.
+
③ Historischer Kontext-Hintergrund — Weltereignisse als Bänder hinter den Briefen erklären, warum Briefe sich häufen.
+
④ Ehrliche Datums-Präzision — ca. 1914, Sommer 1914, „Ohne Datum"-Eimer. Nie ein erfundenes Datum.
+
⑤ Verwobene Erzählung statt Trefferliste — eine durchgehende vertikale Geschichte über 50 Jahre, kein paginiertes Suchergebnis.
+
+
+
+
+
+
+
2 · Die drei Ebenen — visuelle Sprache
+
Jede Ebene muss auf den ersten Blick unterscheidbar sein. Diese Kodierung gilt in allen drei Konzepten gleich — nur das Layout ändert sich, nicht die Bedeutung der Farben & Glyphen.
+
+
+
+
+
⚭
+
Abgeleitetes Lebensereignis
Geburt * · Tod † · Heirat ⚭ — automatisch aus Person.birthDate / deathDate / SPOUSE_OF.fromYear. Große Navy-Knoten auf der Achse. Glyphen * / † aus personLifeDates.ts. Badge „abgeleitet", nicht im Zeitstrahl editierbar.
+
+
+
★
+
Kuratiertes persönliches Ereignis
EventType.PERSONAL — von der Familie geschrieben (Umzug, Krankheit, Auswanderung). Mint-Akzent, Serifen-Titel, optionaler Beschreibungstext. Editierbar über /zeitstrahl/events/[id]/edit.
+
+
+
◍
+
Historisches Ereignis (Welt)
EventType.HISTORICAL — Krieg, Inflation. Gedämpftes Slate-Band quer über die Achse als Kontext-Hintergrund. Bewusst zurückhaltend, damit Familie im Vordergrund bleibt.
+
+
+
✉
+
Brief
Platziert nach Document.documentDate. Kleine Mint-Punkte, kompakte Karte (Absender → Empfänger), verlinkt zu /documents/[id]. Häufungen clustern unter dem Ereignis, zu dem sie gehören.
+
+
+
+
+
+
DatePrecision
Deutsche Darstellung
Beispiel
Wirkung auf der Achse
+
DAY
vollständiges Datum
28. Juli 1914
sortiert exakt innerhalb des Jahres-Bandes
+
MONTH
Monat + Jahr
Juli 1914
sortiert nach Monat innerhalb des Bandes
+
SEASON
Jahreszeit + Jahr
Sommer 1914
grobe Reihung im Band
+
YEAR
nur Jahr
1914
ans Ende des Jahres-Bandes
+
APPROX
„ca." + Jahr
ca. 1914
mit „ca."-Marker, Jahres-Band
+
RANGE
Start–Ende
1914–1918
im Start-Jahr mit Spannen-Marker, nicht dupliziert
+
UNKNOWN
undatiert
Ohne Datum
eigener Eimer ganz am Ende
+
+
+
+
+
+
+
+
+
A
+
+
Konzept A · Erzählend
+
Der Lebensfaden — eine durchgehende Achse
+
Eine einzige vertikale Spine läuft von oben nach unten durch alle Jahre. Lebensereignisse sitzen als große Knoten auf dem Faden, historische Ereignisse legen sich als Bänder dahinter, Briefe zweigen als kleine Punkte ab. Liest sich wie eine Familien-Saga, von 1899 bis 1950 am Stück scrollbar.
+
DifferenzierungMaximaler Abstand zur Suche — gar keine Listen-Anmutung. Der Faden ist eine Geschichte, kein Suchergebnis.
+
Trade-off: bei dichten Brief-Jahren kann der Faden lang werden — braucht eine Quiet-Year-Kompression (mehrere ereignislose Jahre als ein dünner Abschnitt).
+
+
+
+
+
+
+
Familienarchiv
+
+
+
Zeitstrahl
+
Die Familie Raddatz · 1899–1950 · 412 Briefe, 38 Ereignisse
+
+
+
+
+
+
+
+
*
+
Geburt: Karl Raddatz
+
14. März 1901 · abgeleitet
+
+
+
+
+
⚭
+
Heirat: Karl & Elfriede
+
1914 · abgeleitet
+
+
+
+
+
◍ Erster Weltkrieg
+
1914–1918 · historisch
+
+
+
+
+
+
1915
+
+
✉ Brief über die Westfront
+
Karl → Elfriede · Mär 1915
+
Krieg › Briefe von der Front
+
+
+
✉ Feldpost aus Verdun
+
Hans → Karl · Jul 1915 · +2 weitere
+
Krieg › Briefe von der Front
+
+
+
+
+
+
◍ Hyperinflation
+
1923 · historisch
+
+
+
+
+
★
+
Auswanderung nach Argentinien
+
Frühjahr 1924 · persönlich
+
+
+
+
+
+
+
+
+
Warum dieses Layout
+
+
Ein Faden, keine Karten-Liste. Schon die Silhouette signalisiert „Geschichte", nicht „Suchtreffer".
+
Hierarchie über Knotengröße: Lebensereignisse 16px-Knoten, kuratierte 11px, Briefe 7px-Punkte. Das Auge liest zuerst die Meilensteine.
+
Welt-Bänder hinterlegt in gedämpftem Slate — präsent, aber nie konkurrierend mit der Familie.
+
Brief-Cluster fassen Häufungen zusammen („+2 weitere") statt 24 Zeilen zu zeigen — genau hier unterscheidet es sich von der Liste.
+
+
Offene Fragen
+
+
Quiet-Year-Kompression: ereignislose Jahre als dünner „1925–1929"-Abschnitt zusammenfalten?
+
Tap auf Cluster → expandiert inline oder springt in die gefilterte Suche?
+
+
+
+
+
+
+
+
+
+
+
B
+
+
Konzept B · Strukturiert
+
Jahres-Bänder — drei Spuren pro Jahr
+
Jedes Jahr ist ein volle-Breite-Abschnitt (wie die bestehende ChronikTimeline). Innerhalb des Bandes machen drei Spuren — Personen · Welt · Briefe — das Verweben explizit und scannbar. Auf dem Desktop nebeneinander, auf dem Phone gestapelt. Sehr lesbar, senioren-freundlich.
+
DifferenzierungDie drei Spuren zeigen die drei Ebenen als Struktur — man sieht sofort, dass hier mehr als Briefe leben.
+
Trade-off: bändriger, weniger „flüssige Saga" als A. Leere Spuren in ruhigen Jahren brauchen eine elegante Leer-Behandlung.
+
+
+
+
+
+
+
Familienarchiv
+
+
+
Zeitstrahl
+
Die Familie Raddatz · 1899–1950
+
+
+
+
+ 1914
+ 2 EREIGNISSE · 6 BRIEFE
+
+
+
+
Personen
+
⚭Heirat: Karl & Elfriede Raddatz
+
+
+
+
Welt
+
◍Erster Weltkrieg beginnt · 28. Juli 1914
+
+
+
+
Briefe · 6
+
+
+
+
+ Kriegsausbruch — Brief an die Familie →
+
+
+
+
+
+
+
+ 1915
+ 1 EREIGNIS · 24 BRIEFE
+
+
+
Personen
+
*Geburt: Hans Raddatz
+
+
+
Briefe · 24 Feldpost
+
✉ Brief über die Lage an der Westfront
Karl → Elfriede · März 1915 · 23 weitere ▾
Krieg › Briefe von der Front
+
+
+
+
+
+ 1916 – 1918ruhige Jahre · 9 Briefe ▾
+
+
+
+
+
+
+
Warum dieses Layout
+
+
Drei benannte Spuren machen das Versprechen explizit — „hier sind Personen, Welt und Briefe", nicht nur Dokumente.
+
Baut auf vorhandenem Idiom: Jahres-Band = ChronikTimeline-Sektion mit Navy-Header. Schnell umsetzbar, vertraut.
+
Senioren-stark: klare Boxen, große Jahreszahl, ruhiges Raster — kein überlagertes Spine-Lesen nötig.
+
Ruhige Jahre kollabieren zu einer dünnen Zeile — hält das Scrollen kurz.
+
+
Desktop-Enhancement
+
+
Die drei Spuren werden drei Spalten nebeneinander (Personen | Welt | Briefe) statt gestapelt — das Verweben wird horizontal lesbar.
+
+
+
+
+
+
+
+
+
+
+
C
+
+
Konzept C · Navigierbar
+
Spine + Dichte-Schiene — 50 Jahre im Griff
+
Eine dünne vertikale Dichte-Schiene am linken Rand (dieselbe Balken-Sprache wie der Such-Dichtefilter, nur hochkant) zeigt Brief-Volumen pro Jahr plus Ereignis-Markierungen — und dient zugleich als Mini-Map & Sprung-Navigation. Rechts die verwobene Erzählung. Verbindet Vertrautheit mit dem Dichtefilter und ist doch klar eine andere Oberfläche.
+
DifferenzierungÜber 50 Jahre at-a-glance navigierbar — etwas, das eine paginierte Suchliste nie bietet. Dichte wird zur Landkarte.
+
Trade-off: Die Schiene kostet horizontale Breite — auf 320px muss sie sehr schmal (oder ausklappbar) sein. Nähe zum Dichtefilter könnte verwirren, wenn nicht klar getrennt.
+
+
+
+
+
+
+
Familienarchiv
+
+
+
+
+
DICHTE
+
+
+
1900
+
+
+
+
1915
+
+
+
+
1923
+
+
+
1950
+
+
+
+
+
+
Zeitstrahl
+
Familie Raddatz · 1915 ▾
+
+
+
+
+
+
*
+
Geburt: Hans Raddatz
+
Sommer 1915 · abgeleitet
+
+
+
+
◍ Erster Weltkrieg
+
1914–1918
+
+
+
+
+
✉ Brief über die Westfront
Karl → Elfriede · Mär 1915
+
✉ Feldpost aus Verdun
Hans → Karl · Jul 1915 · +22 ▾
+
+
+
+
+
+
+
+
+
Warum dieses Layout
+
+
Dichte-Schiene als Mini-Map: 50 Jahre Brief-Volumen auf einen Blick, Tap springt zum Jahr. Das kann keine Suchliste.
+
Ereignis-Marker (weiß = Lebensereignis, slate = Welt) auf der Schiene zeigen, wo etwas passiert ist — nicht nur wo Briefe sind.
+
Vertraute Sprache, klar getrennter Kontext: dieselben Balken wie /documents, aber hochkant + als Navigation, nicht als Filter.
+
Hier in Dark Mode gezeigt — Mint wird zum Auswahl-/Akzentton, wie im Dichtefilter-Spec.
+
+
320px-Verhalten
+
+
Schiene schrumpft auf ~24px (nur Balken + Jahrzehnt-Ticks) oder klappt hinter ein „Karte"-Icon.
+
+
+
+
+
+
+
+
+
+
+
+
3 · Desktop-Ansichten — A vs. B im direkten Vergleich
+
Auf /zeitstrahl gibt es Breite, die das Phone nicht hat. Hier entscheidet sich A gegen B: A nutzt die Breite für eine dramatische, alternierende Erzähl-Achse; B nutzt sie, um die drei Ebenen als drei echte Spalten nebeneinander lesbar zu machen.
persönlich · Herbst 1915 · „Die Wohnung in der Kastanienallee …"
+
+
+
+
+
+
+
+
+
+
Was die Breite hier gewinnt
+
+
Alternierende Seiten — Briefe links, kuratierte Ereignisse rechts; das Auge zickzackt die Geschichte entlang. Maximal un-listenhaft.
+
Lebensereignisse & Jahre als zentrierte Meilenstein-Pillen, deren gefüllter Hintergrund die Achse unterbricht — der Spine läuft nie durch den Text, sondern endet sauber an der Pille.
+
Welt-Bänder über die volle Breite — der historische Kontext umschließt buchstäblich die Briefe darunter.
+
+
+
+
Risiken für Senioren / A11y
+
+
Alternierende Lese-Richtung ist anstrengender. Mitigation: nie wichtige Info nur rechtsbündig; auf <1024px kollabiert A in die einseitige Phone-Achse.
+
DOM-Reihenfolge bleibt streng chronologisch (eine <ol>) — Screenreader liest die Saga linear, egal welche Seite.
6 Briefe · „Kriegsausbruch — Brief an die Familie" →
+
+
+
+
+
+
1915
+
+
*Geburt: Hans Raddatz
+
+
+ — im Krieg —
+
+
+
✉ Brief über die Westfront
Karl → Elfriede · Mär 1915 · 23 weitere ▾
Krieg
+
+
+
+
+
+
1923
+
—
+
+
◍Hyperinflation ca. 1923
+
+
3 Briefe
+
+
+
+
+
+
+
+
Was die Breite hier gewinnt
+
+
Drei Spalten = drei Ebenen, dauerhaft sichtbar. Das Verweben wird zur lesbaren Tabelle: Auge wandert pro Jahr quer durch Familie → Welt → Briefe.
+
Gemeinsame Jahres-Achse links bindet die Spalten — man sieht sofort „1915: Geburt, Krieg läuft, 24 Feldpost".
+
Leere Zellen erzählen mit („— im Krieg —") statt zu verschwinden.
+
+
+
+
Risiken / A11y
+
+
Tabellarischer, weniger „Saga". Dafür senioren-stärker: ruhige Spalten, keine alternierende Lese-Richtung.
+
<1024px: die drei Spalten stapeln zu den drei Spuren aus dem Phone-Konzept (siehe §B oben) — ein Markup, zwei Layouts via Container-Query.
+
+
+
+
+
+
+
+
4 · Wiederverwendung: „Lebensweg" in der Personenansicht
+
Dieselbe TimelineView-Komponente mit personId-Prop, gefiltert auf eine Person. Sie zieht in die linke 35%-Spalte der Personenseite ein, direkt unter die PersonCard (persons/[id]/+page.svelte:60–67). Weil diese Spalte schmal ist, ist es exakt das Phone-Layout in Spaltenbreite — kein zweites Design nötig.
+
+
+
Platzierung im echten Layout: Die Personenseite ist lg:grid-cols-[35%_65%]. Links: PersonCard + NameHistoryCard → wird zu PersonCard + Lebensweg. Rechts (65%): Korrespondenten, Beziehungen, Dokumente bleiben unverändert. Der Lebensweg filtert auf diese Person: ihre Geburt/Heirat/Tod, Ereignisse an denen sie beteiligt ist, ihre gesendeten/empfangenen Briefe.
Der Lebensweg sitzt unter der PersonCard in der 35%-Spalte. Gefiltert auf Karl: eigene Geburt/Heirat/Tod, beteiligte Welt-Ereignisse als Kontext, eigene Brief-Cluster. <TimelineView personId={person.id} />
+
+
+
… und so verhalten sich A vs. B in der schmalen Lebensweg-Spalte
Bei Spaltenbreite (~330px) ist die Entscheidung wichtig: A bleibt eine klare Faden-Achse, B muss seine drei Spuren stapeln.
Spuren stapeln zu Mini-Sektionen pro Jahr. Mehr Struktur, aber höher & mehr Scroll im engen Rail.
+
+
+
+
Konsequenz für die Wahl
+
+
A skaliert nahtlos von Rail (330px) über Phone bis Desktop — ein Layout-Idiom, drei Breiten.
+
B braucht zwei Modi: gestapelt im Rail/Phone, Spalten auf Desktop. Mehr Code, aber explizitere Ebenen-Trennung.
+
Da der Lebensweg denselben Component nutzt, zählt die Rail-Tauglichkeit doppelt — sie ist ein echtes Argument für A.
+
+
+
+
+
+
+
+
+
5 · Brief-Gruppierung & Tag-Farben
+
Die Zeit ist die Achse — nicht das Thema. Briefe gruppieren wir nach Datum (Standard), echte Bündel entstehen über kuratierte Ereignisse, und Tags dienen als Farb-Akzent & Filter. So bleibt der Zeitstrahl eine Zeit-Oberfläche und konkurriert nicht mit der /themen-Seite.
+
+
+
+ Warum nicht primär nach Tags gruppieren? Ein Dokument hat mehrere Tags (ManyToMany). Ein Brief mit WeihnachtenundLazarett hätte keinen eindeutigen Eimer — duplizieren verfälscht Zählungen, willkürlich wählen verfälscht die Bedeutung. Daten sind exklusiv, Themen nicht. Außerdem spannt Weihnachten jeden Dezember 1899–1950 — das ist genau die Themen-Seite, nicht der Zeitstrahl.
+
+
+
+
+
+
+
① Gruppierungs-Umschalter
+
+ Datum
+ Ereignis
+ Thema
+
+
Standard = Datum. „Ereignis" bündelt unter kuratierte Ereignisse, „Thema" (optional, Post-MVP) nach Wurzel-Tag.
+
+
② Cluster-Karte (Ereignis)
+
+
+ ✉
+ Briefe von der Front
+ Krieg
+ 24 Briefe
+ ▾
+
+
+
Brief über die Lage an der WestfrontMär 1915
+
Feldpost aus VerdunJul 1915
+
+ 22 weitere · alle öffnen →
+
+
+
Ein Jahr mit 24 Feldpostbriefen wird zu einer erzählenden Zeile statt 24 Treffern — der schärfste Unterschied zur Suche. Quelle: TimelineEvent.documents.
+
+
+
+
+
③ Tag-Farb-Chips am Brief
+
Die Farbe kommt vom Wurzel-Tag (Tag.color ist nur auf Root gesetzt). Kinder erben sie: Lazarett & Briefe von der Front tragen die Farbe von Krieg. Nie Farbe allein — immer Punkt + Label.
+
+
+
+
✉ Weihnachtsgruß an Elfriede
+
Karl → Elfriede · Dez 1915
+ Weihnachten › Weihnachtsgrüße
+
+
+
✉ Brief aus dem Lazarett
+
Hans → Karl · Aug 1916
+ Krieg › Lazarett
+
+
+
✉ Brief zum neuen Jahr
+
Elfriede → Karl · Jan 1916 · 2 Tags
+ Weihnachten
+ Familie
+
+
+
Mehrere Tags → mehrere Chips. Unter „Thema"-Gruppierung erscheint der Brief nur unter seinem primären Tag (dedupliziert, mit Hinweis).
+
+
+
+
+
④ Lose Briefe ohne Cluster — adaptive Verdichtung
+
Lose Briefe (kein Ereignis, Modus „Datum") nie einzeln auflisten — 412 Briefe würden die Erzählung sprengen. Stattdessen verdichtet der Zeitstrahl nach Datum, adaptiv: wenige Briefe pro Jahr einzeln, viele als verdichteter Jahres-Strip mit 12-Monats-Sparkline. Gleiche Daten & Logik wie der Such-Dichtefilter — MonthBucket + aggregateToYears aus lib/document/timeline.ts.
+
+
+
+
+
Ruhiges Jahr · ≤ 3 lose Briefe → einzeln
+
+
1909
+
✉ Brief aus Stettin
Elfriede → Karl · Mai 1909
+
✉ Geburtstagsgruß
Karl → Hans · Sep 1909
+
+
Unter dem Schwellwert: jeder Brief als eigene Karte mit Tag-Chip.
+
+
+
+
Dichtes Jahr · > 3 → Jahres-Strip mit Sparkline
+
+
1915
+
+
+ ✉ 24 Briefe
+ Monats-Dichte ▾
+
+
+
+
+
JanDez
+
+
+
Über dem Schwellwert: ein Strip mit 12-Monats-Sparkline. Tap → Monate → einzelne Briefe, oder „im Suchergebnis öffnen →".
+
+
+
+
Disclosure-Leiter: Jahres-Strip → Monats-Gruppen → einzelne Briefe. Auf jeder Stufe gilt der Schwellwert; die unterste Stufe verlinkt in die gefilterte Dokumentsuche (/documents?from=1915-01-01&to=1915-12-31) — die Brücke zur dritten Oberfläche, dem Dichtefilter. So bleibt der Zeitstrahl Erzählung und delegiert die vollständige Liste an die Suche, die genau dafür gebaut ist.
+
+
+
⑤ Wie Cluster entstehen — Kuratierung von zwei Seiten
+
Manuelle Gruppierung = ein TimelineEvent mit verknüpften Dokumenten. Zwei Einstiegspunkte, ein Datenmodell (TimelineEvent.documents): Ereignis-zuerst (Kurator baut den Zeitstrahl, verlinkt viele Briefe auf einmal) und Dokument-zuerst (beim Lesen eines Briefs schnell zuordnen).
Form-Actions-Muster, WRITE_ALL. Dokument-Mehrfach-Picker = Bulk-Linking. Auch inline „＋ Ereignis" auf jedem Jahres-Band.
+
+
+
+
+
B · Quick-Add · /documents/[id]
+
+
… Dokument-Detail · Seitenleiste …
+
+
Zeitstrahl-Ereignis
+
✉Briefe von der Front✓ verknüpft
+
Ereignis wählen ▾＋ Neues Ereignis
+
+
+
Beim Lesen eines Briefs: bestehendes Ereignis wählen oder direkt neu anlegen — verlinkt diesen einen Brief. Schreibt dieselbe TimelineEvent.documents-Relation.
+
+
+
+
+ Wo Tags stark sind — als Filter: „nur Krieg" verengt den gesamten Zeitstrahl über alle 50 Jahre auf Kriegsbriefe — die Zeit-Achse bleibt erhalten. Genau das kann die Themen-Seite nicht. Tag-Filter ist additiv, nicht duplikativ.
+
+
+
+
+
+
6 · Empfehlung & nächster Schritt
+
+
Konzept A als Basis, mit der Spur-Klarheit von B und der Schiene von C als Stufe 2.
+
A (Lebensfaden) trifft die Differenzierungs-Frage am direktesten: es sieht null wie eine Suchliste aus und macht die verwobene Erzählung zur Hauptfigur. Die drei benannten Spuren aus B sind die beste Antwort, falls Nutzer-Tests zeigen, dass „welche Ebene ist das?" unklar bleibt — sie lassen sich als Desktop-Enhancement in A einziehen. Die Dichte-Schiene aus C ist die richtige Lösung für „50 Jahre navigieren", aber Stufe 2 — sie löst Navigation, nicht Differenzierung, und kann nachgerüstet werden.
+
Für alle gilt: Brief-Cluster statt Brief-Listen sind der schärfste Unterschied zur Suche — ein Jahr mit 24 Feldpostbriefen wird zu einer erzählenden Zeile („24 Feldpost, Westfront"), nicht zu 24 Treffern. Genau hier hört der Zeitstrahl auf, eine sortierte Suche zu sein. Nächster Schritt: dieses Konzept für die Person-Detail-„Lebensweg"-Ansicht (gefilterte Variante) durchdeklinieren.
+
+
+
+
+
7 · Design-Tokens (echte, ausgelieferte Werte)
Direkt aus frontend/src/routes/layout.css. Keine Hardcodes in den Komponenten — nur diese Tokens.
+
+
+
Rolle
Token / Utility
Wert
Einsatz im Zeitstrahl
+
Spine / Knoten / Header
brand-navy · --palette-navy
#012851
Achsen-Spine, Lebensereignis-Knoten, Jahres-Header, Titel
Spine = <ol>; Knoten erreichbar; ◍/✉/* nie nur als Farbe — immer Glyphe+Text; 44px-Tap-Ziele; prefers-reduced-motion; axe in Light & Dark
+
+
+
+
+
+
diff --git a/docs/superpowers/specs/2026-06-07-family-timeline-design.md b/docs/superpowers/specs/2026-06-07-family-timeline-design.md
new file mode 100644
index 00000000..c0316093
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-07-family-timeline-design.md
@@ -0,0 +1,182 @@
+# Family Timeline (Zeitstrahl) — Design Spec
+
+**Date:** 2026-06-07
+**Status:** Approved — pending implementation plan
+
+## Problem
+
+The archive can capture, transcribe, organize, and browse letters, but the transcribed material does not yet add up to a *story in time*. Readers (younger, phone-first) have no way to feel the family's history unfold; transcribers don't see their work become something larger. A previous attempt to derive meaning automatically (LLM search) was slow and low-quality, so the family is wary of auto-extraction from handwriting.
+
+## Goal
+
+A **hand-curated, year-banded vertical timeline** — the "Zeitstrahl" — that weaves three layers into one chronological view:
+
+1. **Person life-events** derived from already-curated structured data (`Person` birth/death dates, marriage years from `PersonRelationship.fromYear`). Trusted, free, no extra entry. (Requires the Person birth/death fields to move from year-integers to date + precision — see foundational issue 1.)
+2. **Hand-curated events** the family writes — both **personal** (a move, an illness, emigration) and **historical** (a war, hyperinflation). Editorially controlled, always correct.
+3. **Letters**, auto-placed by their existing `documentDate`, optionally hand-linked to an event to cluster them.
+
+Two surfaces, one component:
+- **Global timeline** at `/zeitstrahl`.
+- **Per-person "Lebensweg"** — the same view filtered to one person, embedded on the Person detail page.
+
+Built for phones (vertical scroll), honest about date precision, with no fabricated dates.
+
+### Non-goals (YAGNI)
+
+- ❌ Auto-extracting events from transcription text — explicitly avoided; this is what makes the feature trustworthy.
+- ❌ Importing an external historical-events dataset — historical events are hand-entered too.
+- ❌ A map / geographic view — that is a separate future feature (B2).
+- ❌ Per-derived-event hide/override toggle — deferred refinement; MVP shows all derived events.
+- ❌ Day-resolution timeline axis — the axis is the **year**; finer dates only affect within-band ordering and label text.
+
+## Core principle: the year is the axis
+
+Most dates in the archive are year-only (birth/death/marriage years are years by nature; many letters carry `YEAR`/`APPROX` precision). Therefore:
+
+- The timeline spine is a **sequence of year bands**. Everything for a given year lives in that band.
+- **Finer ordering only when we have it.** A `DAY`-precision letter (`1923-04-12`) sorts above a `YEAR`-precision one (`1923`) *within* the 1923 band; we never invent a day we don't have.
+- **An "Ohne Datum" bucket** at the end holds items with `UNKNOWN` precision.
+- **Honest precision rendering** reuses the existing `DatePrecision` enum for every dated item (events and letters share one rendering path).
+
+### Date rendering (shared by events and letters)
+
+| `DatePrecision` | German render | Example |
+|---|---|---|
+| `DAY` | full date | `28. Juli 1914` |
+| `MONTH` | month + year | `Juli 1914` |
+| `SEASON` | season + year | `Sommer 1914` |
+| `YEAR` | year only | `1914` |
+| `APPROX` | "ca." + year | `ca. 1914` |
+| `RANGE` | start–end year | `1914–1918` |
+| `UNKNOWN` | undated bucket | `Ohne Datum` |
+
+A `RANGE` item is shown in its **start year's band** with a span marker; it is not duplicated across every year it covers.
+
+## Data model
+
+A new `timeline/` domain package on the backend (kept deliberately separate from the in-flight Lesereisen/`Geschichte` work in #750–753).
+
+### `TimelineEvent` entity
+
+Mirrors the `Document` date model for consistency, so events and letters use one date-handling code path.
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `UUID` | `@GeneratedValue(UUID)` |
+| `title` | `String` | required |
+| `type` | `EventType` enum | `PERSONAL`, `HISTORICAL` |
+| `eventDate` | `LocalDate` | required — most precise date known (WW1 → `1914-07-28`; vague year → `1920-01-01`) |
+| `precision` | `DatePrecision` | reuse existing enum; default `YEAR` — governs rendering & whether the day matters |
+| `eventDateEnd` | `LocalDate` (nullable) | only set when `precision == RANGE` |
+| `description` | `TEXT` (nullable) | free-text narrative for the event |
+| `persons` | ManyToMany `Person` | who the event involves; drives the per-person view & filtering |
+| `documents` | ManyToMany `Document` | optional hand-linked supporting letters (the "cluster letters to an event" feature) |
+| `createdBy` / `createdAt` / `updatedBy` / `updatedAt` / `version` | audit | standard entity conventions |
+
+- `@Schema(requiredMode = REQUIRED)` on every always-populated field (`id`, `title`, `type`, `eventDate`, `precision`).
+- Collections use `@Builder.Default new HashSet<>()`.
+- New Flyway migration adds `timeline_events`, `timeline_event_persons`, `timeline_event_documents` join tables.
+
+### `EventType` enum
+
+`PERSONAL` | `HISTORICAL`. Personal events render with a person/family accent; historical events with a "world" accent and muted styling so the two layers are visually separable.
+
+### Prerequisite: migrate `Person` birth/death to date + precision
+
+Today `Person` stores `birthYear`/`deathYear` as `Integer`, so a known exact birthday (e.g. `1901-03-14`) has nowhere to live and derived events are stuck at year precision. This is fixed by a **foundational Person-domain migration** that the timeline depends on (and which delivers value on its own — precise dates then render on person cards, hover cards, and the Stammbaum).
+
+**Change:** replace `birthYear`/`deathYear` (`Integer`) with:
+
+| Field | Type | Notes |
+|---|---|---|
+| `birthDate` | `LocalDate` (nullable) | most precise date known |
+| `birthDatePrecision` | `DatePrecision` (nullable) | `YEAR` for year-only, `DAY` for exact birthdays, etc. |
+| `deathDate` | `LocalDate` (nullable) | |
+| `deathDatePrecision` | `DatePrecision` (nullable) | |
+
+**Flyway data migration:** existing `birth_year` → `birth_date = '{year}-01-01'`, `birth_date_precision = 'YEAR'` (same for death); then drop the year columns.
+
+**Re-import preservation (ADR-025):** the canonical importer (`PersonRegisterImporter` / `tools/import-normalizer/persons_tree.py`) only carries the *year*. On re-import it must **not** clobber a hand-entered finer-than-`YEAR` date — if the existing precision is `DAY`/`MONTH`/`SEASON`, preserve it; only refresh from the spreadsheet year when the field is empty or still `YEAR`-from-import.
+
+**Bounding the blast radius:** `PersonNodeDTO` keeps exposing an `Integer birthYear`/`deathYear` *derived* from the new date (`birthDate.getYear()`), so the Stammbaum layout (`familyForest.ts` et al.) is untouched. Display surfaces (person card, hover card) move to a shared precision-aware formatter — extend the existing `frontend/src/lib/person/personLifeDates.ts`. The person edit/new forms gain date inputs with a precision selector.
+
+**Scope note:** `PersonRelationship.fromYear` (marriage year) stays `Integer`/`YEAR` for MVP — precise marriage dates are a later, parallel extension if wanted.
+
+### Derived person-events (not persisted)
+
+Assembled on read from the migrated `Person` data; never stored:
+
+| Source | Derived event | `eventDate` | precision |
+|---|---|---|---|
+| `Person.birthDate` | *Geburt: {name}* | `Person.birthDate` | `Person.birthDatePrecision` |
+| `Person.deathDate` | *Tod: {name}* | `Person.deathDate` | `Person.deathDatePrecision` |
+| `PersonRelationship` `SPOUSE_OF.fromYear` | *Heirat: {A} & {B}* | `{fromYear}-01-01` | `YEAR` |
+
+Emitted in the same DTO shape as a curated event, flagged `derived: true`, `type = PERSONAL`. They cannot be edited from the timeline (they are edited at their source: Person record / relationship). A marriage is derived once per `SPOUSE_OF` edge (symmetric edges are stored once — see existing relationship rules).
+
+### Letters
+
+Placed by `Document.documentDate`:
+- Band = `documentDate.getYear()`; `UNKNOWN` precision → "Ohne Datum" bucket.
+- Sub-ordered within a band by full date when precision allows.
+- A letter may also appear under an event it's linked to (via `TimelineEvent.documents`) as a cluster, in addition to its own band placement.
+
+## Assembly & API
+
+A `TimelineService` merges the three layers into a year-bucketed DTO for the requested scope and filters. Layering rules apply: the service owns `TimelineEventRepository` and reaches Person/Document/Relationship data through their **services**, never their repositories.
+
+### DTOs
+
+- `TimelineEntryDTO` — one renderable item: `kind` (`EVENT` | `LETTER`), `eventDate`, `precision`, `eventDateEnd`, `title`, `type` (for events), `derived` flag, plus the source id (eventId / documentId) and minimal display fields (sender/receiver names for letters, linked person ids for events).
+- `TimelineYearDTO` — `{ year: int, entries: TimelineEntryDTO[] }`.
+- `TimelineDTO` — `{ years: TimelineYearDTO[], undated: TimelineEntryDTO[] }`.
+
+### Endpoints
+
+- `GET /api/timeline` — global timeline. Query params (all optional): `personId`, `generation`, `type` (`PERSONAL`/`HISTORICAL`), `fromYear`, `toYear`. The per-person "Lebensweg" is just `GET /api/timeline?personId=…` — no separate endpoint. Requires `READ_ALL`.
+- `POST /api/timeline/events` — create a curated event. `@RequirePermission(Permission.WRITE_ALL)`.
+- `PUT /api/timeline/events/{id}` — update. `@RequirePermission(Permission.WRITE_ALL)`.
+- `DELETE /api/timeline/events/{id}` — delete. `@RequirePermission(Permission.WRITE_ALL)`.
+- `GET /api/timeline/events/{id}` — fetch a single event for the edit form. Requires `READ_ALL`.
+
+Input DTO `TimelineEventRequest` lives flat in the `timeline/` package. Errors use `DomainException.notFound/...`; **no new `ErrorCode`** is required. Run `npm run generate:api` after backend model/endpoint changes.
+
+## Frontend
+
+- New domain dir `frontend/src/lib/timeline/`:
+ - `TimelineView.svelte` — orchestrator; accepts an optional `personId` prop so the same component powers both global and per-person views.
+ - `YearBand.svelte` — one year section header + its entries.
+ - `EventCard.svelte` — renders a `PERSONAL`/`HISTORICAL`/derived event with precision-aware date label.
+ - `LetterCard.svelte` — compact letter row (sender → receiver, snippet/title, date), links to `/documents/[id]`.
+ - `TimelineFilters.svelte` — person, generation, layer toggles, year range.
+ - `dateLabel.ts` — the shared precision→label helper (reuse/extend `lib/document/timeline.ts` helpers like `formatTickLabel` where they fit).
+- Routes:
+ - `/zeitstrahl` — global timeline (`+page.server.ts` loads `/api/timeline`).
+ - `/zeitstrahl/events/new` and `/zeitstrahl/events/[id]/edit` — curator forms, gated to `WRITE_ALL`, using the form-actions pattern.
+- Person detail page gains a **Lebensweg** card section embedding ``.
+- Styling per project conventions (card pattern, brand tokens, `font-serif` for names/titles, `BackButton`, mobile-first at 375px, dark-mode tokens).
+- i18n keys added to `messages/{de,en,es}.json` (German primary).
+
+## Testing
+
+- Backend: `TimelineService` assembly/merge/sort/precision-bucketing (unit + `@DataJpaTest` against Postgres via Testcontainers); controller permission gating; derived-event assembly (birth/death/marriage, symmetric marriage dedup).
+- Frontend: `dateLabel.ts` precision rendering; `TimelineView` global vs `personId` modes (`*.svelte.spec.ts`); filter behavior.
+- Follow project test discipline: targeted single-file runs locally only; full sweep left to CI.
+
+## Proposed issue breakdown (milestone "Zeitstrahl / Family Timeline")
+
+Ordered so each issue is independently shippable and reviewable; later issues depend on earlier ones. Issue 1 is a standalone Person-domain improvement and a hard prerequisite for the timeline's derived events.
+
+1. **Person birth/death → date + precision (foundational)** — replace `birthYear`/`deathYear` with `birthDate`/`deathDate` + precision on `Person`; Flyway data migration (year → `YYYY-01-01`, `YEAR`); update importer with re-import preservation rule; derive year in `PersonNodeDTO` (Stammbaum untouched); move person card / hover card to a precision-aware `personLifeDates.ts`; add date+precision inputs to person new/edit forms. Ships value on its own.
+2. **Backend: `TimelineEvent` entity + migration** — entity, `EventType`, Flyway migration + join tables, repository.
+3. **Backend: TimelineEvent CRUD API** — `TimelineEventController` + `TimelineService` write methods, `TimelineEventRequest` DTO, permission gating, `GET /events/{id}`.
+4. **Backend: derived person-events** — assemble Geburt/Tod/Heirat from migrated Person + relationship data via their services; unit-tested dedup.
+5. **Backend: timeline assembly endpoint** — `GET /api/timeline` merging events + derived events + letters into `TimelineDTO`; year-bucketing, precision sort, undated bucket, filters.
+6. **Frontend: shared date-label helper + types** — `dateLabel.ts`, regen API types.
+7. **Frontend: global `/zeitstrahl` view** — `TimelineView`, `YearBand`, `EventCard`, `LetterCard`, server load.
+8. **Frontend: filters** — `TimelineFilters` (person / generation / layer / year range).
+9. **Frontend: curator event forms** — `/zeitstrahl/events/new` + `/[id]/edit`, gated, with document & person pickers.
+10. **Frontend: per-person Lebensweg** — embed `` on Person detail.
+11. **Polish & a11y** — mobile layout at 375px, dark mode, axe checks, i18n completeness (de/en/es).
+
+> An ADR may be warranted for the new `timeline/` domain + entity (per `docs/CLAUDE.md`, significant data-model change). Add as the next sequential ADR number when implementation starts.
diff --git a/frontend/.gitignore b/frontend/.gitignore
index 8617ce82..39081d9a 100644
--- a/frontend/.gitignore
+++ b/frontend/.gitignore
@@ -13,6 +13,9 @@ node_modules
.DS_Store
Thumbs.db
+# Leftover directory from branch work
+/src.main/
+
# Env
.env
.env.*
diff --git a/frontend/.prettierignore b/frontend/.prettierignore
index 2b6ddd63..02d65194 100644
--- a/frontend/.prettierignore
+++ b/frontend/.prettierignore
@@ -7,6 +7,7 @@ bun.lockb
# Miscellaneous
/static/
+/src.main/
# Build artifacts
/.svelte-kit/
diff --git a/frontend/messages/de.json b/frontend/messages/de.json
index 9e008600..961597fe 100644
--- a/frontend/messages/de.json
+++ b/frontend/messages/de.json
@@ -1039,6 +1039,9 @@
"geschichten_empty_for_person": "Keine Geschichten für {name} gefunden.",
"geschichten_empty_for_persons": "Keine Geschichten für {names} gefunden.",
"geschichten_empty_no_filter": "Es gibt noch keine veröffentlichten Geschichten.",
+ "geschichten_filter_document_chip": "Gefiltert nach Brief:",
+ "geschichten_filter_remove_document_chip": "Brief {title} aus Filter entfernen",
+ "geschichten_empty_for_document": "Noch keine Geschichten zu diesem Brief",
"geschichten_back_to_index": "Zurück zu Geschichten",
"geschichten_published_on": "veröffentlicht am {date}",
"journey_compiled_on": "zusammengestellt am {date}",
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index c837b5cc..7d957e6a 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -1039,6 +1039,9 @@
"geschichten_empty_for_person": "No stories found for {name}.",
"geschichten_empty_for_persons": "No stories found for {names}.",
"geschichten_empty_no_filter": "There are no published stories yet.",
+ "geschichten_filter_document_chip": "Filtered by letter:",
+ "geschichten_filter_remove_document_chip": "Remove letter {title} from filter",
+ "geschichten_empty_for_document": "No stories reference this letter yet",
"geschichten_back_to_index": "Back to stories",
"geschichten_published_on": "published on {date}",
"journey_compiled_on": "compiled on {date}",
diff --git a/frontend/messages/es.json b/frontend/messages/es.json
index b133a089..6ad45fcc 100644
--- a/frontend/messages/es.json
+++ b/frontend/messages/es.json
@@ -1039,6 +1039,9 @@
"geschichten_empty_for_person": "No hay historias para {name}.",
"geschichten_empty_for_persons": "No hay historias para {names}.",
"geschichten_empty_no_filter": "Aún no hay historias publicadas.",
+ "geschichten_filter_document_chip": "Filtrado por carta:",
+ "geschichten_filter_remove_document_chip": "Quitar la carta {title} del filtro",
+ "geschichten_empty_for_document": "Aún no hay historias sobre esta carta",
"geschichten_back_to_index": "Volver a Historias",
"geschichten_published_on": "publicada el {date}",
"journey_compiled_on": "recopilada el {date}",
diff --git a/frontend/src/routes/geschichten/+page.server.ts b/frontend/src/routes/geschichten/+page.server.ts
index b0550b91..76828641 100644
--- a/frontend/src/routes/geschichten/+page.server.ts
+++ b/frontend/src/routes/geschichten/+page.server.ts
@@ -14,7 +14,7 @@ export const load: PageServerLoad = async ({ url, fetch }) => {
const rawDocumentId = url.searchParams.get('documentId');
const documentId = rawDocumentId && UUID_PATTERN.test(rawDocumentId) ? rawDocumentId : null;
- const [listResult, ...personResults] = await Promise.all([
+ const [listResult, docResult, ...personResults] = await Promise.all([
api.GET('/api/geschichten', {
params: {
query: {
@@ -24,6 +24,9 @@ export const load: PageServerLoad = async ({ url, fetch }) => {
}
}
}),
+ documentId
+ ? api.GET('/api/documents/{id}', { params: { path: { id: documentId } } })
+ : Promise.resolve(null),
...personIds.map((id) => api.GET('/api/persons/{id}', { params: { path: { id } } }))
]);
@@ -35,9 +38,22 @@ export const load: PageServerLoad = async ({ url, fetch }) => {
.filter((r) => r && r.response.ok && r.data)
.map((r) => r!.data!) as Person[];
+ let documentFilter: { id: string; title: string | null } | null = null;
+ if (documentId) {
+ if (docResult && docResult.response.ok && docResult.data) {
+ const doc = docResult.data;
+ documentFilter = {
+ id: documentId,
+ title: doc.title ?? doc.originalFilename ?? null
+ };
+ } else {
+ documentFilter = { id: documentId, title: null };
+ }
+ }
+
return {
geschichten: listResult.data ?? [],
personFilters,
- documentIdFilter: documentId
+ documentFilter
};
};
diff --git a/frontend/src/routes/geschichten/+page.svelte b/frontend/src/routes/geschichten/+page.svelte
index 3e4e681a..35ea31fa 100644
--- a/frontend/src/routes/geschichten/+page.svelte
+++ b/frontend/src/routes/geschichten/+page.svelte
@@ -3,6 +3,7 @@ import { goto } from '$app/navigation';
import { m } from '$lib/paraglide/messages.js';
import PersonTypeahead from '$lib/person/PersonTypeahead.svelte';
import GeschichteListRow from '$lib/geschichte/GeschichteListRow.svelte';
+import DocumentFilterChip from './DocumentFilterChip.svelte';
import type { PageData } from './$types';
let { data }: { data: PageData } = $props();
@@ -10,7 +11,19 @@ let { data }: { data: PageData } = $props();
let showPersonPicker = $state(false);
const selectedPersonIds = $derived(data.personFilters.map((p) => p.id!));
-const hasFilters = $derived(data.personFilters.length > 0);
+const hasFilters = $derived(data.personFilters.length > 0 || data.documentFilter !== null);
+
+const emptyMessage = $derived.by(() => {
+ if (data.personFilters.length > 0) {
+ return m.geschichten_empty_for_persons({
+ names: data.personFilters.map((p) => p.displayName).join(' & ')
+ });
+ }
+ if (data.documentFilter) {
+ return m.geschichten_empty_for_document();
+ }
+ return m.geschichten_empty_no_filter();
+});
function rebuildUrl(personIds: string[]) {
const url = new URL(window.location.href);
@@ -20,7 +33,10 @@ function rebuildUrl(personIds: string[]) {
}
function clearAll() {
- goto(rebuildUrl([]), { replaceState: true });
+ const url = new URL(window.location.href);
+ url.searchParams.delete('personId');
+ url.searchParams.delete('documentId');
+ goto(url.pathname + url.search, { replaceState: true });
}
function addPerson(personId: string) {
@@ -35,6 +51,12 @@ function addPerson(personId: string) {
function removePerson(personId: string) {
goto(rebuildUrl(selectedPersonIds.filter((id) => id !== personId)));
}
+
+function removeDocument() {
+ const url = new URL(window.location.href);
+ url.searchParams.delete('documentId');
+ goto(url.pathname + url.search);
+}