Gallery Module Guide

Purpose

Gallery is the first user-facing media-sharing module built on top of the shared Assets domain.

It provides:

• occasion-level installation through the module platform
• event-level gallery enablement
• guest-visible approved media feeds
• guest upload flows backed by shared assets
• planner moderation for pending media

Gallery does not own file storage or derivative processing. It owns gallery records, moderation state, and module-specific visibility behavior.

Scope model

Gallery is installed once per occasion and enabled per event.

That means:

• occasion installation sets the default upload and moderation posture
• each event enablement decides whether uploads are active for that event
• guests only see gallery items from events that both:
  • are accessible to their guest token
  • have Gallery enabled

If an occasion has Gallery installed but an event does not enable it, gallery items tied to that event stay hidden from the guest gallery feed.

Gallery item model

Each gallery item stores:

• the shared asset_id
• occasion and optional event scope
• the occasion installation id and event enablement id
• uploader context
• caption
• moderation status
• moderation metadata

Moderation states are:

• pending
• approved
• rejected

The shared asset remains the canonical media object. Gallery only adds module semantics around it.

Upload flow

Guest uploads use:

• POST /v1/guest/occasions/:occasion_slug/gallery/uploads

Baseline behavior:

• guest token must resolve to the same occasion
• the target event must be accessible to that guest
• Gallery must be enabled on the target event
• the uploaded file must be an image
• the baseline upload limit is 15 MB

Uploads create:

• one shared asset record
• one gallery item linked to that asset
• one asset attachment with resource_type = gallery_item

If the installation moderation mode is pre_moderation, new uploads start as pending. Otherwise they can be auto-approved.

Moderation model

Planner moderation uses:

• GET /v1/occasions/:occasion_id/gallery
• PATCH /v1/occasions/:occasion_id/gallery/items/:gallery_item_id/moderation

Planners with centralized permission grants can:

• list gallery items across the occasion
• filter by event and moderation state in the dashboard
• approve or reject uploaded items
• leave moderation notes

Guests do not see pending or rejected items in the public gallery feed. The current guest shell only shows upload feedback after submission; it does not expose a private "my pending uploads" area yet.

Planner flow

Planner moderation lives at:

• /occasions/:occasionId/gallery

The dashboard view shows:

• total gallery item volume
• pending moderation count
• event filters
• moderation status filters
• approve and reject actions

This is intentionally a moderation-first surface rather than a full media library manager.

Guest flow

Guest gallery lives at:

• /gallery

The guest app:

• loads approved gallery content from accessible enabled events
• shows upload status and event choices when uploads are allowed
• refreshes the gallery feed after a successful upload
• keeps event-boundary filtering authoritative on the server

Permissions and visibility

Planner authorization remains centralized.

The gallery task adds planner actions:

• gallery:list
• gallery:moderate

Guest gallery access is not planner auth. It depends on:

• valid guest token resolution
• occasion slug match
• accessible event ids
• gallery event enablement
• approved moderation status
• asset readiness
• allowed asset visibility rules

Relation to Assets

Gallery depends on Assets and must not bypass it.

Assets owns:

• file metadata
• storage keys
• asset status
• derivative variants
• visibility rules

Gallery owns:

• module installation and event enablement behavior
• upload posture
• moderation decisions
• gallery-specific metadata such as captions and uploader context