EventSnap/docs/USER_JOURNEYS.md

EventSnap — User Journeys

This document walks through every supported user scenario step-by-step. For a quick "who can do what" overview, see FEATURES.md. For manual QA, see TEST_GUIDE.md.

---

1. First-time guest (the happy path)

1. Guest scans the QR code / opens the event link.
2. Lands on the join page (/join), sees the event name. A small "Ich habe bereits einen Account" link is visible below the form for returning users — it routes to /recover.
3. Types display name → taps Beitreten.
4. Server creates the account, generates a 4-digit PIN, stores bcrypt(PIN), signs a 30-day JWT.
5. A PIN modal appears: large monospace digits, a Kopieren button, a warning that this PIN is the only way to sign in on another device. PIN is also written to localStorage.
6. Guest taps Weiter zur Galerie → lands in the feed (/feed).
7. The first-visit onboarding overlay appears: six dismissible steps (welcome, upload, hashtags, long-press for more actions, hell/dunkel design pick, and PIN — the PIN step also points at the Datenschutzhinweis in My Account when the admin has set one). localStorage('eventsnap_guide_seen') = 'true' after dismiss.
8. Guest sees the bottom nav: 🏠 Feed · [📷+ FAB] · 👤 Account.

2. Returning guest, same device

1. App finds a valid JWT in localStorage.
2. Redirected straight to /feed, no input required.

3. Returning guest, new device or cleared storage

1. Guest opens the event link on the new device → join page.
2. Types the same name they used before.
3. Server detects the existing account → the join page transforms into a recovery prompt: "„Name" ist bereits vergeben" with a PIN input and an Anmelden button, plus an Anderen Namen wählen escape hatch.
4. Guest types their PIN → bcrypt.verify succeeds → new JWT issued for the existing user_id. PIN is written to localStorage on this device too.
5. Wrong PIN: up to 3 attempts. After the third, the account is locked for 15 minutes (pin_locked_until is set; further attempts return HTTP 429 with a localized message).

4. PIN forgotten — Host or Admin resets it

The PIN is visible in My Account as long as localStorage is intact on at least one of the user's devices. If lost everywhere, the user asks a Host (or Admin) for a reset.

1. Guest approaches the Host: "I can't sign in on my new phone."
2. Host opens the Host Dashboard → Nutzerverwaltung and finds the user.
3. Host taps PIN zurücksetzen on that row.
4. A confirmation prompt explains what happens; on confirm the server generates a fresh 4-digit PIN, replaces recovery_pin_hash with the new bcrypt, clears any active pin_locked_until, and returns the new plaintext PIN in the response.
5. A modal shows the new PIN ONCE — large, with a copy button. The Host shows the screen to the guest or sends it via another channel (SMS, slip of paper, …). Closing the modal forgets the plaintext on the operator's device too.
6. Guest goes to /recover (or taps "Ich habe bereits einen Account" on /join), enters their name + the new PIN, signs in, and the PIN is persisted to localStorage on their device — exactly like a fresh join.

Permission rules:

• Host can reset PINs for guests only.
• Admin can reset PINs for hosts and guests (not other admins; admins use the password login).
• Anyone whose PIN was reset retains all their uploads, comments, and likes — only the PIN changes.

If no Host or Admin is reachable, the guest can still re-join under a new name (a clean account; their previous uploads remain attributed to the abandoned account, which the Host can clean up later).

5. Posting a photo / video

1. Guest taps the central 📷+ FAB in the bottom nav.
2. A bottom sheet slides up offering Kamera (in-app capture) or Galerie (file picker, multi-select). 3a. Camera path — CameraCapture opens the back camera (facingMode: 'environment'), with toggle for front camera, photo button, and a video-record button using MediaRecorder. 3b. Gallery path — native picker, multiple selection.
3. Preview screen (/upload) shows staged files as horizontal thumbnails. The user can:
   • Remove individual files.
   • Type a caption with #hashtags.
   • Tap quick-tag chips (derived from the caption) to copy a hashtag into the caption.
4. Taps Hochladen → returns immediately to the feed (optimistic UX). The slim progress bar above the bottom nav and the red badge on the FAB indicate active uploads.
5. The client uploads files one at a time (XHR with progress) from an IndexedDB queue.
6. Each upload triggers a server-side compression job; once the preview is ready the feed updates via upload-processed SSE — placeholders swap for actual previews.

6. Posting under rate limits

1. Hit the per-hour upload limit (default 10 / hour, configurable).
2. Server returns HTTP 429 with a Retry-After header on the next upload attempt.
3. Client parks pending items in Wartend state and shows an amber banner: "Upload-Limit erreicht. Wird in Xs automatisch fortgesetzt."
4. Countdown ticks down. When it reaches 0, the queue resumes automatically.

7. Liking and commenting

1. Tap the heart icon on a card or in the lightbox → like is recorded; count increments optimistically; server returns the canonical count via like-update SSE.
2. Tap the comment icon → opens the lightbox with the comments list.
3. Type a comment → POST /api/v1/upload/{id}/comment. Hashtags inside the comment are parsed and attached.
4. The user can delete their own comments (trash icon next to them).

8. Filtering the gallery

1. Toggle to grid view (icon top-right of the feed header).
2. A search bar appears below the header (auto-focused).
3. Type a name or #hashtag — autocomplete suggestions are derived in memory from the loaded uploads.
4. Tap a suggestion → it becomes an active filter chip and the search bar clears.
5. Filter logic:
   • Multiple hashtag chips: OR
   • Multiple uploader chips: OR
   • One uploader + one hashtag: AND
6. Open a post → swipe in the lightbox navigates the filtered set, not the full feed.

9. Hosting the event — moderation

1. Host opens My Account → taps ⭐ Host-Dashboard.
2. Stats section — guest count, upload count, lock status, release status.
3. Event settings — toggle to lock new uploads (likes / comments / browsing stay open; broadcasts event-closed SSE so all clients show a "uploads are locked" banner).
4. Galerie freigeben — releases the export. Enqueues two export jobs (ZIP + HTML viewer). Progress is visible on the Host dashboard and in the Admin dashboard's Export tab; SSE export-progress keeps it live; export-available notifies all guests when ready. Once released the button is disabled and reads "Galerie bereits freigegeben" — a second release is a 409. If a keepsake half fails, both dashboards show the reason and offer Erneut versuchen (rebuild); a ready keepsake can also be rebuilt behind a confirm, during which guest downloads are briefly unavailable.
5. Nutzerverwaltung — search users; per-user controls:
   • Sperren opens a confirmation modal. Banning always hides the user's existing uploads (a banned user's content is "gone" everywhere) — there is no opt-out. Submitting calls POST /host/users/{id}/ban (no body).
   • Entsperren lifts the ban — and does two further things the confirm sheet now spells out, because both are visible to the whole party: it clears uploads_hidden, so all of that user's previously hidden uploads reappear in the gallery, the diashow and the export; and it invalidates and rebuilds a released keepsake (invalidate_and_arm), so every guest's download is unavailable for as long as that takes. A ban does the mirror image of both. Same authority boundary as ban: a plain Host may only unban Guests; only an Admin may unban a Host.
   • Host promotes a guest to host (Hosts and Admins may do this).
   • Degradieren — demote a Host back to guest. Only an Admin may change a Host's role. A plain Host may not demote a peer Host: doing so would let them then ban or PIN-reset (→ /recover account-takeover) that ex-peer, since those guards key off the target's current role. So the backend rejects it (403) and the button is hidden for non-admin Hosts. Nobody may change their own role (self-lockout / self-escalation guard), and Admins are un-demotable and un-bannable by anyone. (This tightens an earlier "Hosts may demote other Hosts" design — see the F1 security fix.)
   • Sperren / PIN zurücksetzen — a plain Host may act on Guests only; an Admin may act on Guests + Hosts; nobody may act on an Admin. The buttons are hidden where they'd 403. PIN reset generates a new PIN, shows it once in a modal, and revokes the target's existing sessions (forcing re-auth with the new PIN). See journey §4.
6. Deleting content — Host can delete any upload or comment via the moderation routes (DELETE /host/upload/{id}, DELETE /host/comment/{id}). On mobile this is also reachable by long-pressing the content (planned, see §15).

10. Banned-guest experience

1. The ban takes effect immediately on the banned user's existing session — the auth layer re-reads the live is_banned flag on every request rather than trusting the JWT, so there's no 30-day token-lifetime window.
2. Their next authenticated write request returns HTTP 403 with a clear message ("Du bist gesperrt."). Ban enforcement lives on the write handlers and the host/admin extractors, not the base auth extractor.
3. They can still browse the read-only feed (and download the export once it's released). Their sessions are not revoked — this is a read-only ban, not a logout. Their own live SSE stream is dropped by the is_banned revalidation (no live pushes), but plain feed reads still work.
4. They cannot upload, like, or comment; a banned host also loses all host/admin actions (including unbanning themselves).
5. Banning always hides: the user's existing uploads are filtered out of the feed for everyone (v_feed, find_visible_media, and the export query all enforce is_banned = FALSE), and a live user-hidden SSE event evicts their cards from every open feed + the diashow without a reload. A client that was offline/disconnected during the live event doesn't miss the eviction: uploads_hidden_at is stamped at ban time (migration 013) and the reconnect delta (GET /feed/delta) returns the banned users in hidden_user_ids, so the feed and diashow replay the eviction on the next reconnect — the projector-missed-the-live-push case is exactly why this exists.

11. Admin — instance configuration

1. Admin opens /admin/login, types the admin password (compared against ADMIN_PASSWORD_HASH). Receives a separate 1-day admin JWT (in sessionStorage).
2. Admin dashboard has four inner tabs:
   • Stats: live counts and disk-usage widget (via sysinfo).
   • Config: per-file limits (image MB / video MB), rate limits (upload / feed / export), quota tolerance, estimated guest count, compression-worker concurrency, plus the colour-theme picker, the Datenschutzhinweis free-text editor and on/off toggles for the rate limiters and quotas (see §18). Whitelist on the server side rejects unknown keys. Values are read from the config table on each request — no restart needed.
   • Export: the gallery-release control plus the list of export jobs with status badges (pending / running / done / failed) and progress bars; refresh button re-polls. The release control mirrors the Host dashboard exactly — disabled once released (a second tap would only 409), live keepsake status with progress and the failure reason, and a Neu erstellen / Erneut versuchen rebuild as the recovery path for a failed or stale keepsake.
   • Nutzer: same user list as Host, with the additional Demote action (admin-only, see §9) and PIN-reset on host rows.

12. Releasing the export and downloading

1. Host (or Admin) taps Galerie freigeben in the dashboard.

2. Server sets event.export_released_at, locks uploads, bumps event.export_epoch, and enqueues two background jobs — all in ONE transaction (workers spawn after it commits, so a client disconnecting mid-request can never leave the event released with no export to build).

   The epoch is the whole generation model (migration 014). It is bumped in the same UPDATE as any change to export_released_at — release and reopen are its only writers — and each export_job row carries a copy of the epoch it was enqueued for. An export is downloadable iff released AND job.epoch = event.export_epoch AND job.status = 'done'. Readiness is therefore derived, never stored: it cannot drift, and a worker whose epoch has been retired (by a reopen, a re-release, or a takedown) is inert — anything it writes is simply invisible. A reopen retires the current keepsake instantly, which is why a reopened event serves no export until the host releases again.

3. ZIP job: streams Gallery.zip (Photos/ + Videos/, full-quality originals) directly to disk via async-zip. Progress updates via export-progress SSE.

4. HTML-viewer job: copies the pre-built viewer assets from backend/static/export-viewer/ (embedded via include_dir!), generates data.json from the database, processes _thumb/_full variants for each upload, and assembles Memories.zip.

5. Both jobs complete → server broadcasts export-available SSE. Takedowns: if a host deletes an upload (or a comment) while the gallery is released, the epoch is bumped and the keepsake is REGENERATED without it. Otherwise a photo removed on request would live on forever in the already-generated archive — the one place it most needs to be gone. The download 404s for the few seconds it takes to rebuild, which is the correct answer: serving the old archive would serve the deleted photo.

6. Any user opens /export:

   • Before release: friendly "Export not yet available" banner.
   • During generation: progress bars per artifact.
   • After completion: two cards (ZIP-Archiv and HTML-Viewer) with download buttons. Tapping the HTML download first shows an in-app guide modal explaining: "Entpacke die ZIP, öffne index.html". Tapping Herunterladen triggers the browser download.

7. Downloads are rate-limited per user (default 3 / day), keyed on the user id in enforce_export_rate — deliberately not per IP. At a venue where a hundred guests share one NAT'd wifi, a per-IP budget would be exhausted by the third person to tap Herunterladen and lock everyone else out of their own keepsake.

13. Diashow

See CONCEPT_DIASHOW.md. Summary of the flow:

1. User taps a Diashow / Präsentation action (feed header on tablet/desktop, Account on mobile).
2. Navigates to /diashow — fullscreen, bottom nav hidden, screen wake-lock acquired.
3. Initial pool fetched from GET /api/v1/feed. Slides crossfade every ~6 s.
4. New uploads (upload-processed SSE) push to a live queue; the next slide transition pops from the live queue first, otherwise from a shuffled queue.
5. upload-deleted removes that ID from both queues; if it's the current slide, advance immediately.
6. Tap or Escape reveals an overlay (pause, dwell selector, exit).

14. Picking a data mode

1. Guest opens My Account → scrolls to Datennutzung.
2. Two options: Datensparer (empfohlen) and Original. Saver is the default.
3. Selecting Original shows a one-time warning bottom-sheet: "Original-Dateien werden geladen — das kann deine mobile Datennutzung deutlich erhöhen. Trotzdem aktivieren?" with Abbrechen / Aktivieren buttons.
4. Choice persists in localStorage (per-device). The feed, lightbox, and diashow all read this flag and load originals instead of compressed previews when Original is on.
5. The viewer (offline HTML export) is unaffected — it already ships with its own pre- bundled _thumb / _full variants.

15. Signing out

The wording matters here: nothing is left and nothing is deleted. The account, the PIN and every uploaded photo survive — the user signs back in with name + PIN whenever they like. ("Event verlassen" read as leaving for good, which the confirmation sheet then contradicted by saying you can come back.)

1. User opens My Account → Konto section. Two separate actions:
   • Abmelden — this device only (DELETE /api/v1/session).
   • Auf allen Geräten abmelden — every session of theirs (DELETE /api/v1/sessions), for a lost or borrowed phone.
2. Bottom-sheet confirmation naming which of the two it is, with Abmelden / Abbrechen.
3. Confirming invalidates the session row(s), wipes the local JWT, PIN and the IndexedDB upload queue (so the next guest on a shared phone doesn't inherit pending uploads), and redirects to the join page. The session-delete call is best-effort: the token is gone locally either way, so a network failure never traps the user on the page.

16. Reading the Datenschutzhinweis

1. User opens My Account → scrolls to Datenschutzhinweis.
2. The note is rendered inside a preformatted block (<pre>-style: monospace, whitespace and newlines preserved exactly as the Admin typed them). No HTML, no markdown — the admin's plain text is shown verbatim.
3. The first-visit onboarding overlay carries a one-line reminder of where to find this: "Datenschutzhinweis findest du in deinem Account."
4. Admin sets / edits the note in Admin Dashboard → Config → Datenschutzhinweis: a tall textarea with a save button. Saved to a single config key.

17. Mobile-first gestures (partly shipped)

EventSnap's UI is mobile-first; gestures replace explicit buttons where they're more ergonomic. Buttons are always present as fallback for desktop and accessibility.

Shipped today: long-press context sheets on posts and comments, and lightbox navigation (on-screen prev/next controls, ← / → arrow keys, and left/right swipe). The remaining rows below are still planned.

Gesture	Action
Long-press on a post (own)	Bottom sheet → Löschen, Original anzeigen, Teilen
Long-press on a post (other)	Bottom sheet → Original anzeigen, Teilen, Melden (planned)
Long-press on a comment (own)	Bottom sheet → Löschen
Long-press on a comment (other)	Bottom sheet → Kopieren
Long-press on a user row (Host)	Bottom sheet → Sperren, Promote/Demote, PIN zurücksetzen
Swipe left/right in the lightbox	Navigate the filtered set
Swipe down on any bottom sheet	Dismiss
Pull-to-refresh on the feed	Force a delta-fetch
Double-tap on a post	Like (heart-burst animation)

On desktop the same actions surface as kebab/⋯ menus, click-able icons in card corners, and keyboard shortcuts in the lightbox (← → for navigate, Esc to close).

Inspiration: Instagram (double-tap heart, swipe stories), WhatsApp (long-press for context), Telegram (swipe-to-reply on messages — could inform comment threads if those land).

18. Admin toggles a rate limit or quota off

1. Admin opens Admin Dashboard → Config.
2. Rate-Limits section: a master switch and per-endpoint switches (upload / feed / export / join).
3. Admin flips, e.g., Upload-Limit aktiv off. The numeric input for "uploads per hour" stays visible but greyed out (still editable for when the toggle goes back on).
4. Speichern persists to the config table. The next upload request bypasses the limiter entirely.
5. Quoten section mirrors the pattern: master toggle plus per-area toggles (storage bytes / upload count).
6. When the storage-quota toggle is off, the "Speicher: X / Y" widget in My Account and on the upload screen hides itself (no quota → no number to show). That widget is staff-only in any case — guests never see it.

Suggested defaults at deploy time: all toggles on, sensible numeric limits. Toggling off is the explicit escape hatch for testing or trusted internal events.

---

Edge cases worth knowing

Case	Behaviour
Browser tab backgrounded for > 5 min	SSE closes on visibilitychange: hidden; reopens on visible
Upload finishes while user is on /account	Feed updates anyway — the queue + SSE are global stores
Event "closed" while files are still in the queue	Server rejects with a friendly error; client surfaces it in the queue UI
Network drops mid-upload	Queue retries the file; retry button available on permanent failure
New device but the PIN was lost	Either re-join under a new name, or Host manually re-links (no self-service)
Two guests pick the same name	Second one is offered the PIN-recovery form (case-insensitive UNIQUE, mig. 007)
Compression fails for a file	Server emits upload-error SSE; the upload is still listed but marked degraded
User deletes their own post (once UI is shipped)	Soft delete (deleted_at); SSE upload-deleted; vanishes from feed everywhere