fotospiel-app/docs/archive/prp/11-public-gallery.md

11 — Public Guest Gallery

Purpose

• Provide a shareable, mobile-friendly gallery for guests who only need to view and download approved photos.
• Respect existing join-token security and automatically disable access once a package’s gallery duration expires.

Access Model

• URL pattern: https://<app-domain>/g/{joinToken}. Tokens are the same join tokens tenants already issue; revoking or expiring a token immediately locks the gallery.
• Tokens expire when the associated event package’s gallery_expires_at passes; guests receive an explanatory message (HTTP 410).
• Only approved photos appear; pending/rejected items remain hidden.

Client Experience

• Responsive grid with lazy-loaded thumbnails (IntersectionObserver) and infinite scroll/pagination.
• Event branding colours (primary, secondary, background) are applied via CSS custom properties fetched from the API.
• Fullscreen lightbox shows creation timestamp + guest label when available and exposes a single-photo download button (streams the original asset).

API Touchpoints (see 03 — API Contract for details)

• GET /api/v1/gallery/{token} → event snapshot + branding.
• GET /api/v1/gallery/{token}/photos → cursor-based pagination of approved photos.
• GET /api/v1/gallery/{token}/photos/{photo}/download → single-photo download/redirect.

Tenant Admin Support

• Filament action “Download all photos” (Event resource) queues a server-side ZIP export via GET /tenant/events/{event}/photos/archive for authenticated tenants.
• Only approved photos are included; failed assets are skipped with logging.

Future Enhancements

• Background job + notification for large ZIP exports (current implementation streams synchronously).
• Optional passcode/PIN layered on top of join tokens for sensitive events.
• Aggregate analytics (views/downloads per photo) presented in Tenant Admin dashboards.