immich-folio/docs/journal-studio-design.md

Design-Spezifikation: Journal Studio (Foto-Essays & Stories)

Status: Entwurf genehmigt (Brainstorming abgeschlossen) · Datum: 2026-08-14

---

1. Understanding Summary

• Ziel & Vision: Bereitstellung eines intuitiven, erstklassigen Journal Studios für Fotografen, um Bild-Text-Reportagen, Reisetagebücher und Ausstellungsberichte (im Stil von Leica Journal / National Geographic) zu verfassen und zu veröffentlichen.
• Zielgruppe:
  • Besucher: Immersives, typografisch elegantes Leseerlebnis mit progressiv ladenden Bildern (ThumbHash), responsiven Layouts und Lightbox-Interaktion.
  • Fotograf: Mühelose Redaktion im Admin-Panel mit Live-Split-Screen-Vorschau und universeller Immich-Bildauswahl.
• Konzept: Reines Markdown mit Frontmatter im Content-Volume (content/journal/*.md), verwaltet über eine dedizierte Admin-UI und ausgeliefert über saubere Next.js Server Components.
• Kern-Vorteile:
  • Trennung von Galerie-Konfiguration (gallery.yaml) und redaktionellen Inhalten.
  • Volle Git- & Backup-Kompatibilität durch Standard-Markdown.
  • Schnelle Erstellung ohne manuelle UUID-Eingabe.

---

2. Annahmen (Assumptions)

1. Storage-Pfad: Journal-Einträge werden standardmäßig unter content/journal/[slug].md gespeichert.
2. Bild-Referenzierung: Bilder verweisen über ![Alt Text](asset:IMMICH_UUID) auf Immich-Assets und werden über den internen Image-Proxy mit Cache und ThumbHash ausgeliefert.
3. Theming: Die Leseansicht (/journal/[slug]) bindet sich nahtlos an das global konfigurierte Design-Theme an (CSS-Variablen, Fonts, Margins).
4. Resilienz: Nicht auffindbare Bilder führen nicht zu einem Seitenabsturz, sondern werden durch neutrale Platzhalter ersetzt.

---

3. Decision Log

#	Entscheidung	Alternativen	Begründung
1	Nomenklatur "Journal"	Stories, Photo Essays, Magazin	"Stories" wirkt wie flüchtige Social-Media-Inhalte. "Journal" spiegelt zeitlose, fotografische Wertigkeit (wie Leica Journal) wider.
2	Architektur-Ansatz 1 (Eigenständiges Studio)	Subpage-Drawer, Quick-Fix	Maximale Schreib- und Layout-Ergonomie durch echten Split-Screen und Entkopplung von gallery.yaml.
3	Persistenz als .md-Dateien	Strings in gallery.yaml, SQLite/DB	Behält das dateibasierte, zustandsarme Self-Hosting-Paradigma bei; einfache Versionierung via Git.
4	Bidirektionaler Editor (Blöcke ↔ Markdown)	Nur WYSIWYG, Nur Markdown	Fotografen können visuell Blöcke anordnen oder direkt mit Markdown-Code arbeiten, ohne Datenverlust.
5	Sicherheit via Slug-Sanitisierung	Ungeprüfte Dateinamen	Verhindert Path Traversal (../) im Docker-Container/Dateisystem.

---

4. Technische Architektur & Komponenten

A. Dateisystem & Datenmodell

Jeder Eintrag ist eine .md-Datei mit folgendem Schema:

---
title: 'Expedition Nordkap'
subtitle: 'Mit dem Bulli durch die Fjorde'
date: '2026-08-14'
author: 'Ralf'
coverAssetId: 'b8c2d111-0000-4000-8000-000000000000'
password: '' # Optionaler Passwortschutz (scrypt)
draft: false # Entwurf oder öffentlich
---

Hier beginnt der Text der Reportage...

![Fjord im Abendlicht](asset:93f812ab-1111-4000-8000-000000000000)

Unterstützte Block-Typen:

• Heading: # H1, ## H2, ### H3
• Paragraph: Fliesstext mit Inline-Markdown (**fett**, *kursiv*, [Link](url))
• Pullquote: > Zitattext mit optionalem — Autor
• Photo (Fullbleed / Wide / Contained): ![Caption](asset:UUID)
• Photo-Pair (2-Spaltig): Zwei aufeinanderfolgende asset:-Bilder

---

B. Admin API Endpunkte (/api/admin/journal)

• GET /api/admin/journal: Liefert Liste aller Einträge (geparstes Frontmatter, Slug, Cover-Thumbnail, Word Count / Read Time).
• GET /api/admin/journal/[slug]: Liefert vollen Inhalt & Metadaten eines spezifischen Eintrags.
• PUT /api/admin/journal/[slug]: Speichert den Eintrag atomar (Write to .tmp ➔ Rename), legt .bak-Sicherungen an und validiert den Markdown-Baum.
• DELETE /api/admin/journal/[slug]: Löscht die .md-Datei nach Bestätigung.

---

C. UI: Das Journal Studio (/admin ➔ Tab "Journal")

1. Journal Dashboard:
   • Übersicht aller Einträge als Karten mit Thumbnail, Status (Draft, Live, Protected), Erstellungsdatum.
   • Button + New Journal Entry.
2. Studio Split-Screen Editor:
   • Top Navigation: Titel-Eingabe, Slug, Status-Schalter, Metadaten-Modal (Autor, Datum, Passwort, Cover-Foto) und Save-Button (Cmd+S).
   • Linker Bereich (Authoring):
     • Umschaltbar zwischen [Visual Blocks] (Karten mit Drag & Drop Griffleisten) und [Raw Markdown].
     • Universeller Asset-Picker für Fotos aus allen Immich-Alben.
   • Rechter Bereich (Live Preview):
     • 1:1 Rendering via EssayView mit den CSS-Variablen des aktiven Themes.
     • Viewport-Umschalter (Desktop / Mobile).

---

D. Frontend Routing & Rendering

• /journal: Übersicht aller veröffentlichten Journal-Einträge mit Cover-Bildern und Exzerpten.
• /journal/[slug]: Detailansicht der Reportage mit Passwort-Gate (PasswordGate) bei geschützten Einträgen.
• Subpage-Integration: Kompatibilität mit gallery.yaml (essayFile: "nordkap.md") bleibt vollständig erhalten.

---

5. Test- & Absicherungsstrategie

1. Unit-Tests (lib/__tests__/journal.test.ts):
   • Frontmatter-Parsing & -Serialisierung.
   • XSS-Sanitisierung bei bösartigem Markdown-HTML.
   • Block-Transformation (Fullbleed, Pairs, Quotes).
2. API-Tests (app/api/admin/journal/__tests__/route.test.ts):
   • Auth-Schutz (401/403 bei nicht-angemeldeten Requests).
   • Path-Traversal-Abwehr (Rejection von ../, %2e%2e%2f).
   • Atomare Speicherung und Fehlerbehandlung bei Disk-Fehlern.
3. E2E / Integration:
   • Aufruf von /journal/[slug] im Browser und Verifikation des Lightbox-Klicks auf eingebettete Fotos.