fotospiel-app/docs/archive/prp/07-guest-pwa.md

07 — Guest PWA

Goal

• Delight guests with a frictionless, installable photo experience that works offline, respects privacy, and requires no account.

Non-Goals (MVP)

• No comments or chat. No facial recognition. No public profiles. No videos.

Personas

• Guest (attendee) — scans QR, uploads photos, browses and likes.
• Host (tenant) — optionally shares event PIN with guests; moderates via Tenant Admin PWA.

Top Journeys

• Join: Scan QR → Open event → Accept terms → Optional PIN → Land on Gallery.
• Upload: Add photos → Review → Submit → Background upload → Success/Retry.
• Browse: Infinite gallery → Filter (emotion/task) → Open photo → Like/Share → Back.

Core Features

• Event access
  • Access token embedded in QR/link (short-lived, event-scoped); optional PIN challenge.
  • Token refresh if event remains open; server can revoke/close event at any time.
• Offline-first
  • App shell + last N gallery items cached; uploads queued with Background Sync.
  • Conflict-safe retries; user can pause/cancel queued uploads.
• Capture & upload
  • Choose from camera or library; limit file size; show remaining upload cap.
  • Client-side resize to sane max (e.g., 2560px longest edge); EXIF stripped client-side if available.
  • Assign optional emotion/task before submit; default to “Uncategorized”.
  • Upload screen shows quota cards (Photos, Guests) with traffic-light styling and friendly copy when nearing limits.
  • When the backend blocks uploads (limit reached, device blocked, gallery expired), surface localized dialogs with actionable hints.
• Gallery
  • Masonry grid, lazy-load, pull-to-refresh; open photo lightbox with swipe.
  • Like (heart) with optimistic UI; share system sheet (URL to CDN variant).
  • Filters: emotion, featured, mine (local-only tag for items uploaded from this device).
• Public share: host can hand out https://app.domain/g/\{token\}; guests see a themed, read-only gallery with per-photo downloads.
  • Banner on gallery header highlights approaching expiry (D-7/D-1) and offers CTA to upload remaining shots before the deadline.
• Safety & abuse controls
  • Rate limits per device and IP; content-length checks; mime/type sniffing.
  • Upload moderation state: pending → approved/hidden; show local status.
• Notification Center
  • Header bell opens a drawer that merges upload queue stats with server-driven notifications (photo highlights, major achievements, host broadcasts, upload failure hints, feedback reminders).
• Data fetched from /api/v1/events/\{token\}/notifications with X-Device-Id for per-device read receipts; guests can mark items as read/dismissed and follow CTAs (internal routes or external links).
  • Pull-to-refresh + background poll every 90s to keep single-day events reactive without WS infrastructure.
  • When push is available (VAPID keys configured) the drawer surfaces a push toggle, persists subscriptions via /push-subscriptions, and the service worker refreshes notifications after every push message.
  • Operations playbook: see docs/ops/guest-notification-ops.md for enabling push, required queues, and cron health checks.
• Privacy & legal
  • First run shows legal links (imprint/privacy); consent for push if enabled.
  • No PII stored; guest name is optional free text and not required by default.

Screens

• Splash/Loading: event lookup + token validation; friendly skeleton.
• Slug-based deep links are no longer accepted; guests must enter or scan a join token QR.
• Terms & PIN: legal links, optional PIN input; remember choice per event.
• Gallery: grid of approved photos; toolbar with filter, upload, settings.
• Upload Picker: camera/library, selection preview, emotion/task tagging.
• Upload Queue: items with progress, retry, remove; background sync toggle.
• Photo Lightbox: zoom, like, share; show emotion tags.
• Settings Sheet: Gear-Icon im Header oeffnet eine Sheet-Ansicht mit editierbarem Gastnamen, eingebetteten Rechtsdokumenten (inkl. Zurueck-Navigation) und Cache-Leeren; Theme-Umschalter bleibt im Header.

Wireframes

• See wireframes file at docs/wireframes/guest-pwa.md for low-fidelity layouts and flows.

Core Pages (Pflichtseiten)

• Landing / Einstieg
  • Purpose: Entry to event via QR/PIN; lowest friction.
  • UI: Single input (QR deep link preferred, fallback PIN field) and Join button.
  • States: invalid/expired token, event closed, offline (allow PIN entry and queue attempt).
• Profil-Setup (Name/Avatar)
  • Purpose: Optional personalisation fuer Likes/Statistiken; Name wird lokal im Browser gespeichert.
  • UI: Name-Feld mit Sofort-Validierung; Avatar folgt spaeter.
  • Behavior: Nicht verpflichtend, aber empfohlen; Name kann jederzeit im Settings Sheet angepasst oder geloescht werden.
• Startseite (Home/Feed)
  • Purpose: Central hub; begruesst Gaeste mit ihrem hinterlegten Namen und fuehrt zu den wichtigsten Aktionen.
• Header: Eventtitel plus Live-Kennzahlen (online Gaeste, geloeste Aufgaben); hero-card zeigt "Hey {Name}!".
  • Highlights: Drei CTA-Karten fuer Aufgabe ziehen, Direkt-Upload und Galerie sowie ein Button fuer die Upload-Warteschlange.
  • Content: EmotionPicker und GalleryPreview bilden weiterhin den Einstieg in Spielstimmung und aktuelle Fotos.
• Aufgaben-Flow
  • Aufgaben-Picker: Choose random task or emotion mood.
  • Aufgaben-Detail (Karte): Task text, emoji tag, estimated duration, suggested group size; actions: take photo, new task (same mood), change mood.
• Foto-Interaktion
  • Kamera/Upload: Capture or pick; progress + success message on completion; background sync.
  • Galerie/Ãœbersicht: Grid/Feed; filters: Neueste, Beliebt, Meine; Like hearts.
  • Foto-Detailansicht: Fullscreen; likes/reactions; linked task + (optional) uploader name.
• Motivation & Spiel
  • Achievements/Erfolge: Badges (e.g., Erstes Foto, 5 Aufgaben, Beliebtestes Foto); personal progress.
• Optionale Ergänzungen
  • Slideshow/Präsentationsmodus: Auto-rotating gallery for TV/Beamer with likes/task overlay.
  • Onboarding: 1–2 “So funktioniert das Spiel” hints the first time.
  • Event-Abschluss: “Danke fürs Mitmachen”, summary stats, link/QR to online gallery.

Technical Notes

• Installability: PWA manifest + service worker; prompt A2HS on supported browsers.
• Storage: IndexedDB for queue + cache; CacheStorage for shell/assets.
• Background Sync: use Background Sync API when available; fallback to retry on app open.
• Accessibility: large tap targets, high contrast, keyboard support, reduced motion.
• i18n: react-i18next with JSON files (public/lang/\{locale\}/guest.json); default de, fallback en; path-based detection (/de/, /en/); RTL not in MVP. Strings for UI (e.g., gallery, upload, tasks) extracted via i18next-scanner; integrate with prefixed routing and middleware.
• Media types: Photos only (no videos) — decision locked for MVP and v1.
• Realtime model: periodic polling (no WebSockets). Home counters every 10s; gallery delta every 30s with exponential backoff when tab hidden or offline.

API Touchpoints

• GET /api/v1/events/\{token\} — public event metadata (when open) + theme.
• GET /api/v1/events/\{token\}/photos — paginated gallery (approved only).
• POST /api/v1/events/\{token\}/photos — signed upload initiation; returns URL + fields.
• POST (S3) — direct upload to object storage; then backend finalize call.
• POST /api/v1/photos/\{id\}/like — idempotent like with device token.
• GET /api/v1/events/\{token\}/notifications — list guest notifications (requires X-Device-Id).
• POST /api/v1/events/\{token\}/notifications/\{notification\}/read|dismiss — mark/dismiss notification with device identity.
• POST /api/v1/events/\{token\}/push-subscriptions — register a browser push subscription (requires X-Device-Id + VAPID public key).
• DELETE /api/v1/events/\{token\}/push-subscriptions — revoke a stored push subscription by endpoint.

Limits (MVP defaults)

• Max uploads per device per event: 50
• Max file size (after client resize): 6 MB per photo
• Max resolution: 2560px longest edge per photo

Edge Cases

• Token expired/invalid → Show “Event closed/invalid link”; link to retry.
• No connectivity → Queue actions; show badge; retry policy with backoff.
• Storage full → Offer to clear cache or deselect files.
• Permission denied (camera/photos) → Explain and offer system shortcut.

Decisions

• Videos are not supported (capture/upload strictly photos).

Appendix: Page-to-Feature Mapping

• Landing: Access, validation, join; deep-link handling.
• Profile Setup: Local profile persistence; optional avatar assets.
• Home: Header, info bar, CTAs, feed preview.
• Tasks: Picker (random/emotion), detail card actions.
• Capture/Upload: Camera permissions, client resize, queue handling.
• Gallery: Filters, pagination, lightbox.
• Achievements: Local badges (MVP), server-backed later.
• Slideshow (optional): Read-only, auto-advance, idle-safe.