Merge pull request #388 from the-luap/release-please--branches--beta

chore(beta): release 3.37.0-beta.0

.drone.yml

@@ -1,114 +0,0 @@
-kind: pipeline
-type: docker
-name: default
-
-steps:
-  # Build Backend Docker Image
-  - name: build-backend
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-backend
-      tags: 
-        - latest
-        - ${DRONE_COMMIT_SHA:0:8}
-        - ${DRONE_BRANCH}-latest
-      dockerfile: backend/Dockerfile
-      context: backend/
-      registry: registry.local.nothaft.cloud
-      build_args:
-        - VERSION=${DRONE_TAG:-dev}
-      
-  # Build Frontend Docker Image
-  - name: build-frontend
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-frontend
-      tags: 
-        - latest
-        - ${DRONE_COMMIT_SHA:0:8}
-        - ${DRONE_BRANCH}-latest
-      dockerfile: frontend/Dockerfile
-      context: frontend/
-      registry: registry.local.nothaft.cloud
-      build_args:
-        - VERSION=${DRONE_TAG:-dev}
-        - VITE_API_URL=${VITE_API_URL:-/api}
-
-trigger:
-  branch:
-    - main
-    - develop
-  event:
-    - push
-    - pull_request
-
----
-kind: pipeline
-type: docker
-name: release
-
-steps:
-  # Build Backend Release
-  - name: build-backend-release
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-backend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: backend/Dockerfile
-      context: backend/
-      registry: registry.local.nothaft.cloud
-      
-  # Build Frontend Release
-  - name: build-frontend-release
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-frontend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: frontend/Dockerfile
-      context: frontend/
-      registry: registry.local.nothaft.cloud
-
-  # -------- NEW: Publish Docker images to GitHub Container Registry --------
-  - name: push-backend-ghcr
-    image: plugins/docker
-    settings:
-      repo: ghcr.io/the-luap/picpeak-backend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: backend/Dockerfile
-      context: backend/
-      registry: ghcr.io
-      username:
-        from_secret: GITHUB_USERNAME
-      password:
-        from_secret: GITHUB_TOKEN
-      build_args:
-        - VERSION=${DRONE_TAG}
-
-  - name: push-frontend-ghcr
-    image: plugins/docker
-    settings:
-      repo: ghcr.io/the-luap/picpeak-frontend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: frontend/Dockerfile
-      context: frontend/
-      registry: ghcr.io
-      username:
-        from_secret: GITHUB_USERNAME
-      password:
-        from_secret: GITHUB_TOKEN
-      build_args:
-        - VERSION=${DRONE_TAG}
-        - VITE_API_URL=${VITE_API_URL:-/api}
-
-
-trigger:
-  event:
-    - tag

.env.example

@@ -7,6 +7,34 @@ NODE_ENV=production
 # JWT Secret (generate with: openssl rand -base64 64)
 JWT_SECRET=your_very_long_random_jwt_secret_here
 
+# Auth cookie Secure flag
+#   unset  - default: follows NODE_ENV (production=true, dev=false)
+#   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access)
+#   false  - never set Secure (allows HTTP; cookies not protected on HTTPS)
+#   auto   - decide per request: Secure on HTTPS, not on HTTP
+#
+# Use COOKIE_SECURE=auto if your deployment is reachable over both HTTPS
+# (via reverse proxy like Nginx Proxy Manager, Traefik, Caddy) AND plain
+# HTTP (e.g. LAN access at http://192.168.x.x:3010). The backend reads
+# req.secure from Express, which respects the X-Forwarded-Proto header
+# when the proxy is in the trust list.
+#
+# Requirements for auto mode:
+#   1. Your reverse proxy MUST send X-Forwarded-Proto: https on HTTPS
+#      requests. Standard configs for NPM/Traefik/Caddy do this by default.
+#   2. The proxy must be on a trusted IP range. By default PicPeak trusts
+#      loopback and private networks (127.0.0.1, 10.x, 172.16-31.x,
+#      192.168.x, link-local). Proxies outside those ranges need custom
+#      trust proxy configuration.
+# COOKIE_SECURE=auto
+
+# Cookie SameSite attribute (Lax | Strict | None). Default: Lax
+# COOKIE_SAMESITE=Lax
+
+# Cookie Domain — set this if serving auth cookies across subdomains.
+# Leave unset for same-origin setups.
+# COOKIE_DOMAIN=.example.com
+
 # Database Configuration (PostgreSQL)
 DATABASE_CLIENT=pg
 DB_USER=picpeak
@@ -22,6 +50,7 @@ REDIS_PASSWORD=your_secure_redis_password_here
 # Admin Account (initial setup)
 ADMIN_USERNAME=admin
 ADMIN_EMAIL=admin@yourdomain.com
+ADMIN_PASSWORD=your_secure_admin_password_here
 
 # Email Configuration
 # For Gmail: use app-specific password
@@ -39,6 +68,11 @@ EMAIL_FROM=noreply@yourdomain.com
 FRONTEND_URL=https://yourdomain.com
 ADMIN_URL=https://yourdomain.com
 
+# API URL for email assets (logos, images in notification emails)
+# This must be the publicly accessible URL where email recipients can load images.
+# If not set, defaults to http://localhost:3001 which will show broken images in emails.
+API_URL=https://yourdomain.com/api
+
 # Frontend API base
 # For pre-built images and production behind a reverse proxy, keep '/api'.
 # If you rebuild the frontend yourself, you may set a full URL at build time.
@@ -50,6 +84,16 @@ VITE_API_URL=/api
 # DB_PORT=5432
 # REDIS_PORT=6379
 
+# Release Channel
+# Options: 'stable' (default), 'beta', or specific version like 'v2.3.0'
+# 'stable' uses the :stable tag (same as :latest on main)
+# 'beta' uses the :beta tag for pre-release versions
+PICPEAK_CHANNEL=stable
+
+# Update Check Configuration
+# Set to 'false' to disable update notifications in admin UI
+UPDATE_CHECK_ENABLED=true
+
 # Timezone
 TZ=UTC
 
@@ -70,6 +114,85 @@ APP_STORAGE=./storage
 APP_DATA=./data
 LOGS=./logs
 
+# ─── Storage Backend ────────────────────────────────────────────────────────
+# PicPeak can store photos, thumbnails and archive zips on the local filesystem
+# (default) or on any S3-compatible object store (AWS S3, MinIO, Cloudflare R2,
+# Backblaze B2, Wasabi, DigitalOcean Spaces, …).
+#
+# STORAGE_BACKEND=local (default)
+#   Uses STORAGE_PATH on the local filesystem. Backwards compatible — every
+#   existing deployment keeps working unchanged.
+#
+# STORAGE_BACKEND=s3
+#   Reads STORAGE_S3_* below. Auto-import via the filesystem watcher is
+#   disabled in this mode (S3 has no inotify) — every photo must enter via the
+#   admin upload UI/API. Run `node backend/scripts/migrate-storage.js` to copy
+#   existing local content to S3 before flipping the env.
+#
+# STORAGE_BACKEND=local
+#
+# STORAGE_S3_BUCKET=picpeak
+# STORAGE_S3_REGION=us-east-1
+# STORAGE_S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
+# STORAGE_S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
+# Custom endpoint — set this for MinIO / R2 / B2 / Spaces. Leave unset for AWS.
+# STORAGE_S3_ENDPOINT=https://s3.us-west-002.backblazeb2.com
+# Optional namespace prefix inside the bucket — useful for multi-deployment buckets.
+# STORAGE_S3_PREFIX=picpeak
+# STORAGE_S3_FORCE_PATH_STYLE=false   # MinIO needs true; auto-on when endpoint is set
+# STORAGE_S3_SSL=true
+#
+# Minimum IAM policy (AWS S3) for the bucket above:
+#   {
+#     "Version": "2012-10-17",
+#     "Statement": [{
+#       "Effect": "Allow",
+#       "Action": [
+#         "s3:GetObject", "s3:PutObject", "s3:DeleteObject",
+#         "s3:ListBucket", "s3:GetBucketLocation"
+#       ],
+#       "Resource": [
+#         "arn:aws:s3:::picpeak",
+#         "arn:aws:s3:::picpeak/*"
+#       ]
+#     }]
+#   }
+#
+# EXTERNAL_MEDIA_ROOT (above) always lives on the local filesystem regardless
+# of STORAGE_BACKEND — reference-mode galleries are not migrated to S3 in v1.
+
+# ─── Outbound Webhooks (#327) ────────────────────────────────────────────────
+# PicPeak POSTs event/photo lifecycle notifications to URLs you configure
+# under Settings → Webhooks. Each delivery is signed HMAC-SHA256 with a
+# per-webhook secret in the X-PicPeak-Signature header.
+#
+# WEBHOOK_ALLOW_PRIVATE_URLS (default: false)
+#   Block URLs resolving to private IPs / loopback / .local etc. as an
+#   SSRF mitigation. Set to "true" ONLY in dev when your receiver is on
+#   the same docker network or localhost. Production deployments must
+#   leave this OFF.
+# WEBHOOK_ALLOW_PRIVATE_URLS=false
+#
+# WEBHOOK_DELIVERY_INTERVAL_MS (default: 5000)
+#   How often the worker polls webhook_deliveries for pending rows.
+# WEBHOOK_DELIVERY_INTERVAL_MS=5000
+#
+# WEBHOOK_DELIVERY_CONCURRENCY (default: 5)
+#   Maximum in-flight deliveries per worker tick. One slow consumer can
+#   monopolize all 5 slots — bump this if your receivers are slow OR ship
+#   a separate webhook-only deployment.
+# WEBHOOK_DELIVERY_CONCURRENCY=5
+#
+# WEBHOOK_HTTP_TIMEOUT_MS (default: 10000)
+#   Per-request timeout. Beyond this, the delivery is recorded as a
+#   network error and retried.
+# WEBHOOK_HTTP_TIMEOUT_MS=10000
+#
+# WEBHOOK_MAX_ATTEMPTS (default: 5)
+#   Total attempts before a delivery is marked failed. Backoff between
+#   attempts is exponential: 1m, 5m, 30m, 2h, 12h.
+# WEBHOOK_MAX_ATTEMPTS=5
+
 # Note on FRONTEND_API_URL (documentation only):
 # When using pre-built frontend images, runtime env vars cannot override the built JS.
 # Do NOT rely on FRONTEND_API_URL in Compose. Instead, keep VITE_API_URL=/api and

.gitea/workflows/mirror-to-github.yml

@@ -1,132 +0,0 @@
-name: Mirror to GitHub
-
-on:
-  workflow_dispatch:  # Allow manual triggering only
-
-jobs:
-  mirror:
-    runs-on: ubuntu-latest
-    # Note: For GitHub fine-grained tokens, ensure the token has:
-    # - Repository access to the-luap/picpeak
-    # - Repository permissions: Contents (Read and Write), Metadata (Read)
-    # For classic tokens: repo scope is sufficient
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0  # Full history for proper mirroring
-
-      - name: Setup Git
-        run: |
-          git config --global user.name "the-luap"
-          git config --global user.email "paul-nothaft@hotmail.de"
-
-      - name: Remove sensitive files and directories
-        run: |
-          echo "Current files before cleanup:"
-          ls -la | head -10 || true
-          echo "..."
-          
-          # Remove sensitive files/directories if they exist
-          echo "Removing sensitive files..."
-          rm -rf .gitea/ || true
-          rm -rf scripts/install-gitea-runner.sh || true
-          rm -rf .drone* || true
-          rm -rf photo-sharing-prd.md || true
-          rm -rf CLAUDE.md || true
-          rm -rf storage/ || true
-          rm -rf events/ || true
-          rm -rf .playwright-mcp/
-          rm -rf .swarm || true
-          rm -rf .claude-flow || true
-
-          
-          echo "Sensitive files removal completed"
-          
-          # Add and commit the cleanup if there are changes
-          git add -A
-          if ! git diff --cached --quiet; then
-            git commit -m "chore: remove sensitive files for GitHub mirror"
-            echo "✅ Committed cleanup of sensitive files"
-          else
-            echo "✅ No sensitive files to remove"
-          fi
-          
-          echo "Final file structure (top level):"
-          ls -la | head -10 || true
-
-      - name: Check GitHub token
-        env:
-          GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }}
-        run: |
-          if [ -z "$GITHUBTOKEN" ]; then
-            echo "ERROR: GITHUBTOKEN secret is not set!"
-            echo "Please add a GitHub Personal Access Token as a secret named GITHUBTOKEN"
-            echo ""
-            echo "For fine-grained tokens:"
-            echo "  - Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens"
-            echo "  - Create token with repository access to the-luap/picpeak"
-            echo "  - Grant permissions: Contents (Read and Write), Metadata (Read)"
-            echo ""
-            echo "For classic tokens:"
-            echo "  - Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)"
-            echo "  - Create token with 'repo' scope"
-            exit 1
-          else
-            echo "✅ GitHub token is available (length: ${#GITHUBTOKEN})"
-            # Try to detect token type (fine-grained tokens are typically longer)
-            if [ ${#GITHUBTOKEN} -gt 80 ]; then
-              echo "📌 Token appears to be a fine-grained personal access token"
-            else
-              echo "📌 Token appears to be a classic personal access token"
-            fi
-          fi
-
-      - name: Push to GitHub
-        env:
-          GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }}
-          GIT_TRACE: 1  # Enable Git trace for debugging if needed
-        run: |
-          # Remove existing github remote if it exists
-          git remote remove github || true
-          
-          # Configure Git to use the token for authentication
-          # This method works for both classic and fine-grained tokens
-          git config --global url."https://the-luap:${GITHUBTOKEN}@github.com/".insteadOf "https://github.com/"
-          
-          # Add GitHub remote (clean URL without credentials)
-          git remote add github https://github.com/the-luap/picpeak.git
-          
-          # Verify remote was added
-          echo "GitHub remote configuration:"
-          git remote -v
-          
-          # Push to GitHub main branch with error handling
-          echo "Pushing to GitHub..."
-          if git push github main --force 2>&1; then
-            echo "✅ Push to GitHub completed successfully!"
-          else
-            echo "❌ Push to GitHub failed!"
-            echo ""
-            echo "Common issues and solutions:"
-            echo "1. Token permissions: Ensure your token has 'Contents: write' permission"
-            echo "2. Token expiration: Check if your token has expired"
-            echo "3. Repository access: Verify the token has access to the-luap/picpeak repository"
-            echo ""
-            echo "For fine-grained tokens, required permissions:"
-            echo "  - Repository access: the-luap/picpeak"
-            echo "  - Repository permissions: Contents (Read and Write), Metadata (Read)"
-            echo ""
-            echo "For classic tokens, required scope: 'repo'"
-            exit 1
-          fi
-          
-          # Clean up the git config after push
-          git config --global --unset url."https://the-luap:${GITHUBTOKEN}@github.com/".insteadOf
-
-      - name: Workflow completed
-        run: |
-          echo "✅ Mirror to GitHub workflow completed successfully!"
-          echo "📊 Repository mirrored to: https://github.com/the-luap/picpeak"
-          echo "🔒 Sensitive files have been removed from the mirror"
-

.gitea/workflows/test.yml

@@ -1,52 +0,0 @@
-name: Test and Lint
-
-on:
-  push:
-    branches: [ main, develop ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  backend-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install backend dependencies
-        working-directory: ./backend
-        run: npm ci
-      
-      - name: Run backend linting
-        working-directory: ./backend
-        run: npm run lint || true  # Continue on lint errors for now
-      
-      - name: Run backend tests
-        working-directory: ./backend
-        run: npm test || true  # Continue on test failures for now
-  
-  frontend-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install frontend dependencies
-        working-directory: ./frontend
-        run: npm ci --legacy-peer-deps
-      
-      - name: Run frontend linting
-        working-directory: ./frontend
-        run: npm run lint || true  # Continue on lint errors for now
-      
-      - name: Build frontend
-        working-directory: ./frontend
-        run: npm run build

.gitea/workflows/version-and-release.yml

@@ -1,269 +0,0 @@
-name: Version and Release
-
-on:
-  workflow_dispatch:
-
-jobs:
-  version-bump:
-    runs-on: ubuntu-latest
-    outputs:
-      new_version: ${{ steps.version.outputs.new_version }}
-      version_changed: ${{ steps.version.outputs.version_changed }}
-      component_changed: ${{ steps.version.outputs.component_changed }}
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITEA_TOKEN || github.token }}
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Configure Git
-        run: |
-          git config --global user.name 'Gitea Actions Bot'
-          git config --global user.email 'actions@gitea.local'
-      
-      - name: Detect changes and bump version
-        id: version
-        run: |
-          set -e  # Exit on error
-          
-          echo "=== Debug Info ==="
-          echo "GitHub event before: ${{ github.event.before }}"
-          echo "GitHub SHA: ${{ github.sha }}"
-          echo "Current directory: $(pwd)"
-          echo "Git log (last 5): $(git log --oneline -5)"
-          
-          # Get the commit range for changed files
-          if [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ] && [ "${{ github.event.before }}" != "" ]; then
-            COMMIT_RANGE="${{ github.event.before }}..${{ github.sha }}"
-            echo "Using commit range: $COMMIT_RANGE"
-            CHANGED_FILES=$(git diff --name-only $COMMIT_RANGE || echo "")
-          else
-            # First commit or no previous commit, check against HEAD~1 if it exists
-            if git rev-parse HEAD~1 >/dev/null 2>&1; then
-              COMMIT_RANGE="HEAD~1..HEAD"
-              echo "Using commit range: $COMMIT_RANGE"
-              CHANGED_FILES=$(git diff --name-only $COMMIT_RANGE || echo "")
-            else
-              echo "First commit detected, checking all files"
-              CHANGED_FILES=$(git ls-files)
-            fi
-          fi
-          
-          echo "Changed files:"
-          echo "$CHANGED_FILES"
-          
-          # Check what changed (using echo to pipe to grep to avoid grep exit codes)
-          BACKEND_CHANGED=$(echo "$CHANGED_FILES" | grep -c '^backend/' || echo "0")
-          FRONTEND_CHANGED=$(echo "$CHANGED_FILES" | grep -c '^frontend/' || echo "0")
-          ROOT_CHANGED=$(echo "$CHANGED_FILES" | grep -c -E '^(package\.json|docker-compose|Dockerfile|scripts/)' || echo "0")
-          
-          echo "Backend files changed: $BACKEND_CHANGED"
-          echo "Frontend files changed: $FRONTEND_CHANGED"
-          echo "Root files changed: $ROOT_CHANGED"
-          
-          # Get current versions
-          BACKEND_VERSION=$(node -p "require('./backend/package.json').version" 2>/dev/null || echo "1.1.0")
-          FRONTEND_VERSION=$(node -p "require('./frontend/package.json').version" 2>/dev/null || echo "1.1.0")
-          
-          echo "Current backend version: $BACKEND_VERSION"
-          echo "Current frontend version: $FRONTEND_VERSION"
-          
-          # Determine what to update based on changes
-          BACKEND_UPDATE=false
-          FRONTEND_UPDATE=false
-          COMPONENT_CHANGED="none"
-          
-          if [ "$ROOT_CHANGED" -gt 0 ]; then
-            # Root changes affect both components
-            BACKEND_UPDATE=true
-            FRONTEND_UPDATE=true
-            COMPONENT_CHANGED="both"
-            SOURCE_VERSION=$BACKEND_VERSION
-            echo "Root changes detected - updating both components"
-          elif [ "$BACKEND_CHANGED" -gt 0 ] && [ "$FRONTEND_CHANGED" -gt 0 ]; then
-            # Both components changed
-            BACKEND_UPDATE=true
-            FRONTEND_UPDATE=true
-            COMPONENT_CHANGED="both"
-            # Use the higher version as source
-            if [ "$(printf '%s\n' "$BACKEND_VERSION" "$FRONTEND_VERSION" | sort -V | tail -n1)" = "$BACKEND_VERSION" ]; then
-              SOURCE_VERSION=$BACKEND_VERSION
-            else
-              SOURCE_VERSION=$FRONTEND_VERSION
-            fi
-            echo "Both backend and frontend changed - updating both"
-          elif [ "$BACKEND_CHANGED" -gt 0 ]; then
-            # Only backend changed
-            BACKEND_UPDATE=true
-            COMPONENT_CHANGED="backend"
-            SOURCE_VERSION=$BACKEND_VERSION
-            echo "Only backend changed - updating backend"
-          elif [ "$FRONTEND_CHANGED" -gt 0 ]; then
-            # Only frontend changed
-            FRONTEND_UPDATE=true
-            COMPONENT_CHANGED="frontend"
-            SOURCE_VERSION=$FRONTEND_VERSION
-            echo "Only frontend changed - updating frontend"
-          else
-            echo "No relevant changes detected"
-            echo "version_changed=false" >> $GITHUB_OUTPUT
-            echo "component_changed=none" >> $GITHUB_OUTPUT
-            echo "new_version=" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-          
-          echo "Component changed: $COMPONENT_CHANGED"
-          echo "Source version: $SOURCE_VERSION"
-          echo "Backend update: $BACKEND_UPDATE"
-          echo "Frontend update: $FRONTEND_UPDATE"
-          
-          # Calculate new version
-          IFS='.' read -r -a version_parts <<< "$SOURCE_VERSION"
-          MAJOR="${version_parts[0]}"
-          MINOR="${version_parts[1]}"
-          PATCH="${version_parts[2]}"
-          
-          # Increment patch version and ensure tag uniqueness
-          git fetch --tags --quiet || true
-          NEW_PATCH=$((PATCH + 1))
-          NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH"
-          
-          while git rev-parse "v${NEW_VERSION}" >/dev/null 2>&1; do
-            echo "Tag v${NEW_VERSION} already exists, bumping patch version again"
-            NEW_PATCH=$((NEW_PATCH + 1))
-            NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH"
-          done
-          
-          echo "New version: $NEW_VERSION"
-          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-          echo "component_changed=$COMPONENT_CHANGED" >> $GITHUB_OUTPUT
-          
-          # Update versions in package.json files
-          if [ "$BACKEND_UPDATE" = true ]; then
-            echo "Updating backend version to $NEW_VERSION"
-            cd backend && npm version $NEW_VERSION --no-git-tag-version
-            cd ..
-          fi
-          
-          if [ "$FRONTEND_UPDATE" = true ]; then
-            echo "Updating frontend version to $NEW_VERSION"
-            cd frontend && npm version $NEW_VERSION --no-git-tag-version
-            cd ..
-          fi
-          
-          # Check if there are changes to commit
-          if [[ -n $(git status --porcelain) ]]; then
-            echo "version_changed=true" >> $GITHUB_OUTPUT
-          else
-            echo "version_changed=false" >> $GITHUB_OUTPUT
-          fi
-      
-      - name: Commit version bump
-        if: steps.version.outputs.version_changed == 'true'
-        run: |
-          set -e  # Exit on any error
-          
-          # First, ensure we have the latest changes
-          echo "Fetching latest changes..."
-          git fetch origin main
-          
-          # Check if we're behind and need to update
-          LOCAL=$(git rev-parse HEAD)
-          REMOTE=$(git rev-parse origin/main)
-          
-          if [ "$LOCAL" != "$REMOTE" ]; then
-            echo "Local is behind remote, pulling changes..."
-            git pull origin main --no-rebase
-          fi
-          
-          COMPONENT="${{ steps.version.outputs.component_changed }}"
-          
-          if [ "$COMPONENT" = "both" ]; then
-            git add backend/package.json backend/package-lock.json frontend/package.json frontend/package-lock.json
-            git commit -m "chore: bump version to ${{ steps.version.outputs.new_version }} (backend + frontend)"
-          elif [ "$COMPONENT" = "backend" ]; then
-            git add backend/package.json backend/package-lock.json
-            git commit -m "chore: bump backend version to ${{ steps.version.outputs.new_version }}"
-          elif [ "$COMPONENT" = "frontend" ]; then
-            git add frontend/package.json frontend/package-lock.json
-            git commit -m "chore: bump frontend version to ${{ steps.version.outputs.new_version }}"
-          fi
-          
-          # Pull latest changes before pushing to avoid conflicts
-          echo "Pulling latest changes from origin/main..."
-          if ! git pull --rebase origin main; then
-            echo "Rebase failed, attempting to resolve..."
-            # If rebase fails, abort and try a regular merge
-            git rebase --abort || true
-            git pull origin main --no-rebase
-          fi
-          
-          # Push the changes with retry logic
-          echo "Pushing version bump..."
-          PUSH_SUCCESS=false
-          
-          for i in 1 2 3; do
-            echo "Push attempt $i of 3..."
-            
-            # Try to push
-            if git push origin main 2>&1; then
-              echo "Successfully pushed version bump on attempt $i"
-              PUSH_SUCCESS=true
-              break
-            else
-              echo "Push failed on attempt $i"
-              
-              if [ $i -lt 3 ]; then
-                echo "Waiting 5 seconds before retry..."
-                sleep 5
-                
-                echo "Pulling latest changes..."
-                git fetch origin main
-                
-                # Try rebase first, fall back to merge
-                if ! git rebase origin/main; then
-                  echo "Rebase failed, trying merge..."
-                  git rebase --abort 2>/dev/null || true
-                  git pull origin main --no-rebase
-                fi
-              fi
-            fi
-          done
-          
-          if [ "$PUSH_SUCCESS" = "false" ]; then
-            echo "ERROR: Failed to push after 3 attempts"
-            exit 1
-          fi
-      
-      - name: Create Git tag
-        if: steps.version.outputs.version_changed == 'true'
-        run: |
-          COMPONENT="${{ steps.version.outputs.component_changed }}"
-          
-          if [ "$COMPONENT" = "both" ]; then
-            TAG_MESSAGE="Release v${{ steps.version.outputs.new_version }} (backend + frontend)"
-          elif [ "$COMPONENT" = "backend" ]; then
-            TAG_MESSAGE="Release v${{ steps.version.outputs.new_version }} (backend)"
-          elif [ "$COMPONENT" = "frontend" ]; then
-            TAG_MESSAGE="Release v${{ steps.version.outputs.new_version }} (frontend)"
-          fi
-          
-          git tag -a "v${{ steps.version.outputs.new_version }}" -m "$TAG_MESSAGE"
-          git push origin "v${{ steps.version.outputs.new_version }}"
-  
-  trigger-drone:
-    needs: version-bump
-    if: needs.version-bump.outputs.version_changed == 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger Drone Build
-        run: |
-          echo "Version bumped to ${{ needs.version-bump.outputs.new_version }}"
-          echo "Component(s) changed: ${{ needs.version-bump.outputs.component_changed }}"
-          echo "Drone will automatically trigger on the new tag"
-          # Drone CI will automatically trigger on the tag push event

.github/ISSUE_TEMPLATE/security_vulnerability.md

@@ -9,7 +9,7 @@ assignees: ''
 
 ⚠️ **IMPORTANT: For serious security vulnerabilities, please DO NOT create a public issue.**
 
-Instead, please email security@example.com with the details.
+Instead, please use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new) or email **info@picpeak.app** with the details.
 
 For minor security improvements or questions, you can use this template:
 

.github/workflows/docker-build.yml

@@ -1,13 +1,31 @@
 name: Build and Push Docker Images
 
+# This workflow is triggered by:
+# - Push to main/beta branches (builds 'latest'/'stable' or 'beta' tagged images)
+# - Version tags from Release Please (e.g., v1.2.0 -> builds versioned images)
+# - GitHub Releases (created by Release Please)
+# - Pull requests (build verification only, no push by default)
+# - Manual workflow dispatch
+#
+# Multi-arch strategy:
+#   Each image (backend, frontend) is built once per architecture on a
+#   native runner — linux/amd64 on ubuntu-latest, linux/arm64 on
+#   ubuntu-24.04-arm. Each leg pushes by digest to GHCR. A follow-up
+#   merge job combines the digests into a multi-arch manifest and applies
+#   the human-readable tags. This is the pattern documented at
+#   https://docs.docker.com/build/ci/github-actions/multi-platform/
+#
+#   Native runners are used instead of QEMU because npm install under
+#   QEMU was previously too slow/unreliable for regular branch builds.
+
 on:
   push:
-    branches: [ main, develop ]
-    tags: [ 'v*.*.*' ]
+    branches: [ main, beta ]
+    tags: [ 'v*.*.*', 'v*.*.*-beta.*' ]  # Triggered by Release Please tags (stable and beta)
   pull_request:
-    branches: [ main ]
+    branches: [ main, beta ]
   release:
-    types: [ published ]
+    types: [ published ]  # Triggered when Release Please creates a release
   workflow_dispatch:
     inputs:
       push:
@@ -21,25 +39,47 @@ on:
 
 env:
   REGISTRY: ghcr.io
-  BACKEND_IMAGE_NAME: ${{ github.repository }}/backend
-  FRONTEND_IMAGE_NAME: ${{ github.repository }}/frontend
+  # BACKEND_IMAGE_NAME and FRONTEND_IMAGE_NAME are computed per job in the
+  # "Compute image names" step. GHCR requires all-lowercase repository names,
+  # but ${{ github.repository }} preserves the original case (e.g. "Luca-Timo/...").
+  # Computing them with bash parameter expansion (${VAR,,}) keeps the workflow
+  # working on forks regardless of the owner's name casing.
 
 jobs:
+  # -----------------------------------------------------------------------------
+  # Backend: per-arch build, then merge into a multi-arch manifest
+  # -----------------------------------------------------------------------------
   build-backend:
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
     permissions:
       contents: read
       packages: write
-      security-events: write
-    
+
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Prepare platform pair
+      run: |
+        platform="${{ matrix.platform }}"
+        echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
+
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
-      with:
-        platforms: linux/amd64,linux/arm64
 
     - name: Log in to Container Registry
       if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
@@ -51,6 +91,108 @@ jobs:
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
+    - name: Determine if pushing
+      id: push-decision
+      run: |
+        if [[ "${{ github.event_name }}" == "pull_request" && "${{ github.event.inputs.push }}" != "true" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        elif [[ "${{ steps.login-ghcr.outcome }}" != "success" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "push=true" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Extract metadata for Backend (labels only)
+      id: meta-backend
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}
+        labels: |
+          org.opencontainers.image.title=PicPeak Backend
+          org.opencontainers.image.description=PicPeak photo sharing platform backend service
+          org.opencontainers.image.vendor=PicPeak
+          maintainer=${{ github.repository_owner }}
+
+    - name: Build Backend image (push by digest)
+      id: build
+      uses: docker/build-push-action@v5
+      with:
+        context: ./backend
+        file: ./backend/Dockerfile
+        platforms: ${{ matrix.platform }}
+        labels: ${{ steps.meta-backend.outputs.labels }}
+        cache-from: type=gha,scope=backend-${{ env.PLATFORM_PAIR }}
+        cache-to: type=gha,mode=max,scope=backend-${{ env.PLATFORM_PAIR }}
+        outputs: ${{ steps.push-decision.outputs.push == 'true' && format('type=image,name={0}/{1},push-by-digest=true,name-canonical=true,push=true', env.REGISTRY, env.BACKEND_IMAGE_NAME) || 'type=cacheonly' }}
+        build-args: |
+          CACHEBUST=${{ github.run_number }}
+          BUILD_DATE=${{ github.event.head_commit.timestamp }}
+          VCS_REF=${{ github.sha }}
+          VERSION=${{ steps.meta-backend.outputs.version }}
+
+    - name: Export digest
+      if: steps.push-decision.outputs.push == 'true'
+      run: |
+        mkdir -p /tmp/digests
+        digest="${{ steps.build.outputs.digest }}"
+        touch "/tmp/digests/${digest#sha256:}"
+
+    - name: Upload digest artifact
+      if: steps.push-decision.outputs.push == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: digests-backend-${{ env.PLATFORM_PAIR }}
+        path: /tmp/digests/*
+        if-no-files-found: error
+        retention-days: 1
+
+  merge-backend:
+    needs: build-backend
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      security-events: write
+    # Only run when at least one digest was pushed (i.e. not on PRs without push intent).
+    if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
+
+    steps:
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Download digest artifacts
+      uses: actions/download-artifact@v4
+      with:
+        path: /tmp/digests
+        pattern: digests-backend-*
+        merge-multiple: true
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Container Registry
+      id: login-ghcr
+      continue-on-error: true
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Determine build context
+      id: context
+      run: |
+        if [[ "${{ github.ref }}" == refs/tags/v*-beta* ]] || [[ "${{ github.ref }}" == refs/heads/beta ]]; then
+          echo "channel=beta" >> $GITHUB_OUTPUT
+          echo "is_prerelease=true" >> $GITHUB_OUTPUT
+        else
+          echo "channel=stable" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+        fi
+
     - name: Extract metadata for Backend
       id: meta-backend
       uses: docker/metadata-action@v5
@@ -65,28 +207,22 @@ jobs:
           type=ref,event=branch
           type=ref,event=pr
           type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-          type=semver,pattern={{major}}
-          type=sha,prefix={{branch}}-,format=short
+          type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=sha,format=short
           type=raw,value=latest,enable={{is_default_branch}}
+          type=raw,value=stable,enable=${{ github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && steps.context.outputs.is_prerelease == 'false') }}
+          type=raw,value=beta,enable=${{ github.ref == 'refs/heads/beta' || steps.context.outputs.is_prerelease == 'true' }}
 
-    - name: Build and push Backend Docker image
-      uses: docker/build-push-action@v5
-      with:
-        context: ./backend
-        file: ./backend/Dockerfile
-        # Always build; only push when registry login succeeded
-        push: ${{ (github.event_name != 'pull_request' || github.event.inputs.push == 'true') && steps.login-ghcr.outcome == 'success' }}
-        tags: ${{ steps.meta-backend.outputs.tags }}
-        labels: ${{ steps.meta-backend.outputs.labels }}
-        platforms: linux/amd64,linux/arm64
-        cache-from: type=gha,scope=backend
-        cache-to: type=gha,mode=max,scope=backend
-        build-args: |
-          CACHEBUST=${{ github.run_number }}
-          BUILD_DATE=${{ github.event.head_commit.timestamp }}
-          VCS_REF=${{ github.sha }}
-          VERSION=${{ steps.meta-backend.outputs.version }}
+    - name: Create and push multi-arch manifest
+      working-directory: /tmp/digests
+      run: |
+        docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+          $(printf "${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}@sha256:%s " *)
+
+    - name: Inspect manifest
+      run: |
+        docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}:${{ steps.meta-backend.outputs.version }}
 
     - name: Run Trivy vulnerability scanner
       if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
@@ -100,26 +236,45 @@ jobs:
 
     - name: Upload Trivy scan results to GitHub Security tab
       if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: github/codeql-action/upload-sarif@v3
+      uses: github/codeql-action/upload-sarif@v4
       with:
         sarif_file: 'trivy-backend.sarif'
         category: 'backend-vulnerabilities'
 
+  # -----------------------------------------------------------------------------
+  # Frontend: per-arch build, then merge into a multi-arch manifest
+  # -----------------------------------------------------------------------------
   build-frontend:
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
     permissions:
       contents: read
       packages: write
-      security-events: write
-    
+
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Prepare platform pair
+      run: |
+        platform="${{ matrix.platform }}"
+        echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
+
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
-      with:
-        platforms: linux/amd64,linux/arm64
 
     - name: Log in to Container Registry
       if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
@@ -131,6 +286,107 @@ jobs:
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
+    - name: Determine if pushing
+      id: push-decision
+      run: |
+        if [[ "${{ github.event_name }}" == "pull_request" && "${{ github.event.inputs.push }}" != "true" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        elif [[ "${{ steps.login-ghcr.outcome }}" != "success" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "push=true" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Extract metadata for Frontend (labels only)
+      id: meta-frontend
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}
+        labels: |
+          org.opencontainers.image.title=PicPeak Frontend
+          org.opencontainers.image.description=PicPeak photo sharing platform frontend application
+          org.opencontainers.image.vendor=PicPeak
+          maintainer=${{ github.repository_owner }}
+
+    - name: Build Frontend image (push by digest)
+      id: build
+      uses: docker/build-push-action@v5
+      with:
+        context: ./frontend
+        file: ./frontend/Dockerfile
+        platforms: ${{ matrix.platform }}
+        labels: ${{ steps.meta-frontend.outputs.labels }}
+        cache-from: type=gha,scope=frontend-${{ env.PLATFORM_PAIR }}
+        cache-to: type=gha,mode=max,scope=frontend-${{ env.PLATFORM_PAIR }}
+        outputs: ${{ steps.push-decision.outputs.push == 'true' && format('type=image,name={0}/{1},push-by-digest=true,name-canonical=true,push=true', env.REGISTRY, env.FRONTEND_IMAGE_NAME) || 'type=cacheonly' }}
+        build-args: |
+          CACHEBUST=${{ github.run_number }}
+          BUILD_DATE=${{ github.event.head_commit.timestamp }}
+          VCS_REF=${{ github.sha }}
+          VERSION=${{ steps.meta-frontend.outputs.version }}
+
+    - name: Export digest
+      if: steps.push-decision.outputs.push == 'true'
+      run: |
+        mkdir -p /tmp/digests
+        digest="${{ steps.build.outputs.digest }}"
+        touch "/tmp/digests/${digest#sha256:}"
+
+    - name: Upload digest artifact
+      if: steps.push-decision.outputs.push == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: digests-frontend-${{ env.PLATFORM_PAIR }}
+        path: /tmp/digests/*
+        if-no-files-found: error
+        retention-days: 1
+
+  merge-frontend:
+    needs: build-frontend
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      security-events: write
+    if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
+
+    steps:
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Download digest artifacts
+      uses: actions/download-artifact@v4
+      with:
+        path: /tmp/digests
+        pattern: digests-frontend-*
+        merge-multiple: true
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Container Registry
+      id: login-ghcr
+      continue-on-error: true
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Determine build context
+      id: context
+      run: |
+        if [[ "${{ github.ref }}" == refs/tags/v*-beta* ]] || [[ "${{ github.ref }}" == refs/heads/beta ]]; then
+          echo "channel=beta" >> $GITHUB_OUTPUT
+          echo "is_prerelease=true" >> $GITHUB_OUTPUT
+        else
+          echo "channel=stable" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+        fi
+
     - name: Extract metadata for Frontend
       id: meta-frontend
       uses: docker/metadata-action@v5
@@ -145,28 +401,22 @@ jobs:
           type=ref,event=branch
           type=ref,event=pr
           type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-          type=semver,pattern={{major}}
-          type=sha,prefix={{branch}}-,format=short
+          type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=sha,format=short
           type=raw,value=latest,enable={{is_default_branch}}
+          type=raw,value=stable,enable=${{ github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && steps.context.outputs.is_prerelease == 'false') }}
+          type=raw,value=beta,enable=${{ github.ref == 'refs/heads/beta' || steps.context.outputs.is_prerelease == 'true' }}
 
-    - name: Build and push Frontend Docker image
-      uses: docker/build-push-action@v5
-      with:
-        context: ./frontend
-        file: ./frontend/Dockerfile
-        # Always build; only push when registry login succeeded
-        push: ${{ (github.event_name != 'pull_request' || github.event.inputs.push == 'true') && steps.login-ghcr.outcome == 'success' }}
-        tags: ${{ steps.meta-frontend.outputs.tags }}
-        labels: ${{ steps.meta-frontend.outputs.labels }}
-        platforms: linux/amd64,linux/arm64
-        cache-from: type=gha,scope=frontend
-        cache-to: type=gha,mode=max,scope=frontend
-        build-args: |
-          CACHEBUST=${{ github.run_number }}
-          BUILD_DATE=${{ github.event.head_commit.timestamp }}
-          VCS_REF=${{ github.sha }}
-          VERSION=${{ steps.meta-frontend.outputs.version }}
+    - name: Create and push multi-arch manifest
+      working-directory: /tmp/digests
+      run: |
+        docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+          $(printf "${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}@sha256:%s " *)
+
+    - name: Inspect manifest
+      run: |
+        docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}:${{ steps.meta-frontend.outputs.version }}
 
     - name: Run Trivy vulnerability scanner
       if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
@@ -180,50 +430,74 @@ jobs:
 
     - name: Upload Trivy scan results to GitHub Security tab
       if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: github/codeql-action/upload-sarif@v3
+      uses: github/codeql-action/upload-sarif@v4
       with:
         sarif_file: 'trivy-frontend.sarif'
         category: 'frontend-vulnerabilities'
 
-  # Note: The publish-manifest job is not needed since docker/build-push-action@v5
-  # automatically creates multi-arch manifests when building for multiple platforms.
-  # The images are already properly tagged and include all architectures.
-
   summary:
-    needs: [build-backend, build-frontend]
+    needs: [build-backend, merge-backend, build-frontend, merge-frontend]
     if: always()
     runs-on: ubuntu-latest
     permissions:
       contents: read
-    
+
     steps:
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
     - name: Build Summary
       run: |
         echo "## 🐳 Docker Build Summary" >> $GITHUB_STEP_SUMMARY
         echo "" >> $GITHUB_STEP_SUMMARY
-        
+
         if [[ "${{ needs.build-backend.result }}" == "success" ]]; then
-          echo "✅ **Backend**: Successfully built" >> $GITHUB_STEP_SUMMARY
+          echo "✅ **Backend build (per-arch)**: Successfully built" >> $GITHUB_STEP_SUMMARY
         else
-          echo "❌ **Backend**: Build failed" >> $GITHUB_STEP_SUMMARY
+          echo "❌ **Backend build (per-arch)**: ${{ needs.build-backend.result }}" >> $GITHUB_STEP_SUMMARY
         fi
-        
+
+        if [[ "${{ needs.merge-backend.result }}" == "success" ]]; then
+          echo "✅ **Backend manifest merge**: Successfully published" >> $GITHUB_STEP_SUMMARY
+        elif [[ "${{ needs.merge-backend.result }}" == "skipped" ]]; then
+          echo "ℹ️ **Backend manifest merge**: Skipped (verify-only build)" >> $GITHUB_STEP_SUMMARY
+        else
+          echo "❌ **Backend manifest merge**: ${{ needs.merge-backend.result }}" >> $GITHUB_STEP_SUMMARY
+        fi
+
         if [[ "${{ needs.build-frontend.result }}" == "success" ]]; then
-          echo "✅ **Frontend**: Successfully built" >> $GITHUB_STEP_SUMMARY
+          echo "✅ **Frontend build (per-arch)**: Successfully built" >> $GITHUB_STEP_SUMMARY
         else
-          echo "❌ **Frontend**: Build failed" >> $GITHUB_STEP_SUMMARY
+          echo "❌ **Frontend build (per-arch)**: ${{ needs.build-frontend.result }}" >> $GITHUB_STEP_SUMMARY
         fi
-        
+
+        if [[ "${{ needs.merge-frontend.result }}" == "success" ]]; then
+          echo "✅ **Frontend manifest merge**: Successfully published" >> $GITHUB_STEP_SUMMARY
+        elif [[ "${{ needs.merge-frontend.result }}" == "skipped" ]]; then
+          echo "ℹ️ **Frontend manifest merge**: Skipped (verify-only build)" >> $GITHUB_STEP_SUMMARY
+        else
+          echo "❌ **Frontend manifest merge**: ${{ needs.merge-frontend.result }}" >> $GITHUB_STEP_SUMMARY
+        fi
+
         echo "" >> $GITHUB_STEP_SUMMARY
         echo "### 📦 Images" >> $GITHUB_STEP_SUMMARY
         echo "- Backend: \`${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}\`" >> $GITHUB_STEP_SUMMARY
         echo "- Frontend: \`${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}\`" >> $GITHUB_STEP_SUMMARY
-        
+
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "### 🏗️ Architectures" >> $GITHUB_STEP_SUMMARY
+        echo "Published manifests include both \`linux/amd64\` and \`linux/arm64\` (built natively, no QEMU)." >> $GITHUB_STEP_SUMMARY
+
         echo "" >> $GITHUB_STEP_SUMMARY
         echo "### 🏷️ Tags" >> $GITHUB_STEP_SUMMARY
         echo "Images are tagged based on:" >> $GITHUB_STEP_SUMMARY
         echo "- Branch name (for branch pushes)" >> $GITHUB_STEP_SUMMARY
-        echo "- PR number (for pull requests)" >> $GITHUB_STEP_SUMMARY
+        echo "- PR number (for pull requests, when push is enabled)" >> $GITHUB_STEP_SUMMARY
         echo "- Version tags (for releases)" >> $GITHUB_STEP_SUMMARY
-        echo "- Short SHA with branch prefix" >> $GITHUB_STEP_SUMMARY
+        echo "- Short SHA" >> $GITHUB_STEP_SUMMARY
         echo "- \`latest\` (for main branch)" >> $GITHUB_STEP_SUMMARY
+        echo "- \`stable\` (for main branch and stable releases)" >> $GITHUB_STEP_SUMMARY
+        echo "- \`beta\` (for beta branch and pre-releases)" >> $GITHUB_STEP_SUMMARY

.github/workflows/release-please-beta.yml

@@ -0,0 +1,37 @@
+name: Release Please (Beta)
+
+on:
+  push:
+    branches: [beta]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Run Release Please
+        uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config-beta.json
+          manifest-file: .release-please-manifest-beta.json
+          target-branch: beta
+
+      - name: Output Release Info
+        if: ${{ steps.release.outputs.release_created }}
+        run: |
+          echo "## Beta Release Created!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tag:** ${{ steps.release.outputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ steps.release.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Docker images will be built and tagged with this beta version." >> $GITHUB_STEP_SUMMARY
+

.github/workflows/release-please.yml

@@ -0,0 +1,36 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }}
+    steps:
+      - name: Run Release Please
+        uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      - name: Output Release Info
+        if: ${{ steps.release.outputs.release_created }}
+        run: |
+          echo "## Release Created! " >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tag:** ${{ steps.release.outputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Docker images will be built and tagged with this version." >> $GITHUB_STEP_SUMMARY
+

.gitignore

@@ -69,15 +69,63 @@ backend/data/
 backend/docs/
 backend/logs/
 logs/
-storage/
+# Anchored to repo root: matches the top-level runtime storage dir,
+# NOT backend/src/services/storage/ (the storage backend abstraction code).
+/storage/
 data/
 certbot/
 
 # Ignore local contributor guide copy
 AGENTS.md
+CLAUDE.md
+
+# Working/planning documents (not for release)
+BUGS_AND_FEATURES.md
+frontend/TEST_PLAN.md
+docs/REFACTORING_PLAN.md
+docs/MULTIPLE_ADMINISTRATORS_PLAN.md
+docs/*_PLAN.md
+docs/test-*.md
+docs/feature-*.md
+
+# Scaffolding documentation (local development reference)
+docs/DATABASE_SCHEMA.md
+docs/BACKEND_SERVICES.md
+docs/API_ROUTES.md
+docs/FRONTEND_ARCHITECTURE.md
+docs/DEVELOPER_ONBOARDING.md
+docs/ENVIRONMENT_VARIABLES.md
+
+# Build artifact: OpenAPI spec generated locally + synced into the
+# picpeak-docs repo. Never tracked here — the docs site at
+# docs.picpeak.app is the source of truth.
+docs/openapi.json
+docs/openapi.yaml
+
+# Local backup directory (from testing)
+backup/
 
 # Local artifacts from browser tooling
 .playwright-mcp/
 
+# Local-only E2E suite (never pushed; runs as pre-push gate on this machine)
+tests/e2e/local/
+playwright-local-results/
+e2e-test.log
+scripts/e2e-local.sh
+
 # Local SQLite files in backend
 backend/*.sqlite*
+backend/*.db
+
+# Test files and artifacts
+test-images/
+test-logo*.jpg
+test-logo*.png
+test-results/
+
+# Development docker compose
+docker-compose.dev.yml
+
+# New layout development files
+new-layouts/

.release-please-manifest-beta.json

@@ -0,0 +1,3 @@
+{
+  ".": "3.37.0-beta.0"
+}

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.6.1"
+}

CLAUDE.md

@@ -1,386 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Product Overview
-
-A secure photo sharing platform designed for weddings and events, enabling photographers to share time-limited, password-protected galleries. The platform features automatic expiration, archiving, and a scrappbook.de-inspired modern, minimalist UI.
-
-## Architecture Overview
-
-- **Backend**: Node.js/Express API with SQLite/PostgreSQL, file-based photo storage
-- **Frontend**: React SPA with scrappbook.de-style design (requires implementation)
-- **Storage**: File-based with active/archived separation
-- **Services**: Background workers for email, archiving, file watching, and expiration monitoring
-- **Analytics**: Umami integration for engagement tracking
-
-## Essential Commands
-
-### Backend Development
-```bash
-cd backend
-npm install               # Install dependencies
-npm run migrate          # Initialize database schema
-npm run dev              # Start with hot-reload (port 3001)
-npm test                 # Run Jest tests
-npm run lint             # ESLint checks
-```
-
-### Running a Single Test
-```bash
-cd backend
-npm test -- path/to/test.test.js
-npm test -- --testNamePattern="test name"
-```
-
-### Production Deployment
-See [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) for comprehensive deployment instructions including:
-- Docker Compose deployment
-- PM2 deployment
-- Manual installation
-- Non-nginx deployment options
-- SSL/HTTPS setup
-- Troubleshooting guide
-
-**⚠️ CRITICAL PRODUCTION NOTICE:**
-- Production runs on a SEPARATE SERVER - never assume local changes affect production
-- ALWAYS request production server details before any troubleshooting
-- NO trial-and-error approaches in production - data loss is unacceptable
-- Every change must be thoroughly analyzed and tested locally first
-
-## Key Product Requirements (from PRD)
-
-### Core Features
-1. **File-Based System**: Drop photos in folders → automatic gallery creation
-2. **Automatic Expiration**: Default 30 days, with 7-day warning emails
-3. **Password Protection**: Secure access with customizable passwords
-4. **Automatic Archiving**: ZIP compression and storage after expiration
-5. **Email Notifications**: Creation, warning, and expiration notifications
-6. **Analytics**: Umami tracking for views, downloads, and engagement
-
-### Folder Structure
-```
-/events/
-  ├── active/
-  │   ├── wedding-smith-jones-2024-06-15/
-  │   │   ├── collages/
-  │   │   └── individual/
-  │   └── birthday-emma-2024-07-20/
-  └── archived/
-      └── wedding-smith-jones-2024-06-15.zip
-```
-
-## Frontend Implementation Requirements
-
-### Design Style (scrappbook.de-inspired)
-- **Color Palette**: Primary green (#5C8762), neutral backgrounds
-- **Typography**: Clean, modern sans-serif (Noto Sans or similar)
-- **Layout**: Minimalist, modular sections with grid-based photo displays
-- **Aesthetic**: Professional yet approachable, photographer-focused
-
-### Key Frontend Components to Build
-1. **Landing Page**: Password entry with event preview
-2. **Gallery View**: 
-   - Responsive photo grid with lazy loading
-   - Toggle between collages/individual photos
-   - Prominent expiration banner
-   - Download urgency indicators
-3. **Photo Lightbox**: Full-screen viewing with zoom
-4. **Mobile-First**: Responsive design with touch gestures
-5. **Personalization**: Dynamic theming per event type
-
-### User Experience Priorities
-- Clear expiration warnings (sticky banner)
-- One-click "Download All" for urgent galleries
-- Smooth image loading with skeleton screens
-- Intuitive navigation between photo categories
-- Professional presentation matching photographer branding
-
-## Key Architecture Patterns
-
-### Authentication Flow
-- JWT-based with separate tokens for admin and gallery access
-- Gallery tokens include event-specific claims
-- Auth middleware: `backend/src/middleware/auth.js`
-  - `adminAuth` - Admin panel protection
-  - `photoAuth` - Protected photo access  
-  - `verifyGalleryAccess` - Gallery-specific validation
-
-### Database Schema (Knex/SQLite)
-Main tables:
-- `events` - Gallery metadata with expiration, custom messages, themes
-- `photos` - Photo records linked to events
-- `access_logs` - IP-based usage tracking
-- `email_queue` - Async email processing
-- `admin_users` - Admin authentication
-
-### Service Architecture
-Background services run as separate processes:
-- **emailService**: Processes email queue with retry logic
-- **archiveService**: Creates ZIP archives of expired events
-- **expirationChecker**: Cron job for expiration warnings
-- **fileWatcher**: Monitors for new photo uploads
-- **backupService**: Scheduled backups with checksum-based change detection
-
-### API Structure
-- `/api/admin/*` - Admin panel endpoints (requires adminAuth)
-- `/api/gallery/*` - Public gallery endpoints  
-- `/api/auth/*` - Authentication endpoints
-- Rate limiting: 100 req/15min (general), 5 req/15min (auth)
-
-## Critical Implementation Notes
-
-1. **Security**: All gallery access requires valid JWT with event-specific claims
-2. **Expiration**: Events auto-expire based on `expires_at`, with 7-day email warnings
-3. **Email Queue**: Async processing with retry logic, check `email_queue` table
-4. **File Processing**: Sharp library for thumbnail generation (300x300)
-5. **Frontend Status**: Only skeleton exists - requires full implementation based on PRD
-6. **Umami Analytics**: Track password entries, downloads, views, expiration warnings
-
-## Troubleshooting Guidelines
-
-### Before ANY Production Troubleshooting:
-1. **ALWAYS request specific details**:
-   - Production server URL/IP
-   - Current error messages/logs
-   - Recent changes or deployments
-   - Affected users/galleries
-   - Time of issue occurrence
-
-2. **Thorough Analysis Required**:
-   - Use detailed thinking/analysis for EVERY troubleshooting task
-   - Review all related code before suggesting changes
-   - Consider all potential side effects
-   - Never make assumptions about production environment
-
-3. **Safe Troubleshooting Steps**:
-   - First, reproduce issue in local/dev environment
-   - Analyze logs without modifying production
-   - Create detailed action plan before any changes
-   - Always have rollback strategy ready
-   - Document every step taken
-
-### Common Issues & Safe Approaches:
-- **Email not sending**: Check email_queue table, SMTP settings, service status
-- **Photos not loading**: Verify file permissions, storage paths, nginx config
-- **Gallery access issues**: Check JWT tokens, expiration dates, access_logs
-- **Performance problems**: Analyze with monitoring tools first, never experiment
-
-### Data Safety Rules:
-- NEVER delete or modify production data without explicit backup confirmation
-- ALWAYS verify backups exist before any data operations
-- NO direct database modifications without transaction safety
-- Log all actions for audit trail
-
-## Environment Variables
-
-### Backend (.env)
-- `JWT_SECRET` - Token signing
-- `ADMIN_URL`, `FRONTEND_URL` - CORS origins
-- `SMTP_*` - Email configuration
-- `DB_*` - PostgreSQL credentials (production)
-- `UMAMI_URL` - Umami instance URL (for server-side tracking)
-- `UMAMI_WEBSITE_ID` - Website ID from Umami
-
-### Frontend (.env)
-- `VITE_API_URL` - Backend API URL
-- `VITE_UMAMI_URL` - Umami analytics URL
-- `VITE_UMAMI_WEBSITE_ID` - Website ID from Umami
-- `VITE_UMAMI_SHARE_URL` - (Optional) Public share URL for embedded dashboard
-
-## Testing Approach
-- Jest with Supertest for API testing
-- Test files in `__tests__` directories
-- Database migrations run before tests
-- Mock email sending in tests
-
-## Umami Analytics Integration
-
-The frontend includes comprehensive Umami analytics integration for tracking user behavior and gallery performance.
-
-### Tracked Events:
-- **Gallery Events**:
-  - `gallery_password_entry` - Password attempts (success/failure)
-  - `gallery_photo_view` - Individual photo views
-  - `gallery_photo_download` - Single photo downloads
-  - `gallery_bulk_download` - Bulk/all photo downloads
-  - `gallery_expired` - Expired gallery access attempts
-- **Admin Events**:
-  - `admin_login` - Admin authentication
-  - `admin_event_created` - New event creation
-  - `admin_event_archived` - Event archiving
-  - `admin_event_deleted` - Event deletion
-  - `admin_settings_updated` - Settings changes
-- **User Behavior**:
-  - Search queries (with debouncing)
-  - Expiration warning views
-  - Page views with automatic tracking
-
-### Setup:
-1. Install Umami (self-hosted or cloud)
-2. Create a website in Umami dashboard
-3. Set environment variables:
-   ```
-   VITE_UMAMI_URL=https://your-umami-instance.com
-   VITE_UMAMI_WEBSITE_ID=your-website-id
-   VITE_UMAMI_SHARE_URL=https://your-umami-instance.com/share/...
-   ```
-
-### Analytics Dashboard:
-- Admin panel includes analytics page at `/admin/analytics`
-- Summary view with key metrics
-- Option to embed full Umami dashboard
-- Real-time event tracking
-
-## Accessibility & Performance Features
-
-### Accessibility (WCAG 2.1 AA Compliance)
-- **Error Boundaries**: Graceful error handling with recovery options
-- **Skip Links**: Skip to main content for keyboard navigation
-- **ARIA Labels**: Proper labeling for screen readers
-- **Focus Management**: Focus trap in modals, visible focus indicators
-- **Keyboard Navigation**: Full keyboard support in gallery lightbox (arrows, escape, +/-, d for download)
-- **Loading States**: Skeleton screens instead of spinners for better UX
-- **Offline Support**: Visual indicator when offline
-- **Form Validation**: Accessible error messages with aria-describedby
-
-### Performance Optimizations
-- **Lazy Loading**: Images load on scroll with Intersection Observer
-- **Skeleton Screens**: Instant visual feedback during loading
-- **Error Recovery**: Component-level error boundaries prevent full page crashes
-- **Optimistic Updates**: Immediate UI updates with background sync
-- **Debounced Search**: Prevents excessive API calls
-- **Analytics**: Non-blocking Umami integration
-
-### Component Library Enhancements
-- `<ErrorBoundary>` - Catches and displays errors gracefully
-- `<PageErrorBoundary>` - Full-page error recovery
-- `<Skeleton>` - Flexible skeleton loader with variants
-- `<OfflineIndicator>` - Network status monitoring
-- `<SkipLink>` - Accessibility navigation
-- `useFocusTrap` - Modal focus management hook
-- `useOnlineStatus` - Network status hook
-
-## Theme System & Branding
-
-### Theme Features
-- **Dynamic Theming**: CSS variables for runtime theme switching
-- **Preset Themes**: Default, Wedding, Birthday, Corporate, Minimal
-- **Customization Options**:
-  - Primary/Accent/Background/Text colors
-  - Font family selection
-  - Border radius (none, sm, md, lg)
-  - Custom logo upload
-  - Custom CSS injection
-- **Event-Specific Themes**: Override global theme per gallery
-- **Live Preview**: Real-time theme changes in admin panel
-
-### Theme Context API
-```typescript
-const { theme, setTheme, setThemeByName } = useTheme();
-```
-
-### Branding Settings
-- Company name, tagline, and support email
-- Custom footer text
-- Optional watermarking on downloads
-- Logo upload for gallery header
-
-### CSS Variables
-```css
---color-primary: #5C8762;
---color-primary-light: #7aa583;
---color-primary-dark: #4a6f4f;
---color-accent: #22c55e;
---color-background: #fafafa;
---color-text: #171717;
---font-family: 'Inter', sans-serif;
---border-radius: 0.5rem;
-```
-
-## Backup Service
-
-### Overview
-The backup service provides automated, scheduled backups of all photo data with checksum-based change detection to minimize transfer overhead.
-
-### Features
-- **Multiple Destinations**: Local directory, remote server (rsync), S3-compatible storage
-- **Change Detection**: SHA256 checksums track file changes, only modified files are backed up
-- **Scheduled Execution**: Configurable cron-based scheduling (default: 2 AM daily)
-- **Email Notifications**: Alerts on backup failure, optional success notifications
-- **Retention Management**: Automatic cleanup of old backup runs based on retention policy
-- **Progress Tracking**: Database storage of backup history, file states, and statistics
-
-### Configuration
-Backup settings are stored in `app_settings` table with `backup_` prefix:
-- `backup_enabled`: Enable/disable the service
-- `backup_schedule`: Cron expression (e.g., '0 2 * * *')
-- `backup_destination_type`: 'local', 'rsync', or 's3'
-- `backup_retention_days`: How long to keep backup history
-- `backup_include_archived`: Whether to backup archived events
-- `backup_exclude_patterns`: File patterns to exclude
-
-### API Endpoints
-- `GET /api/admin/backup/config` - Get current configuration
-- `PUT /api/admin/backup/config` - Update configuration
-- `GET /api/admin/backup/status` - Get backup status and history
-- `POST /api/admin/backup/run` - Trigger manual backup
-- `POST /api/admin/backup/test-connection` - Test destination connectivity
-
-### Testing
-Run backup service test: `npm run test-backup`
-
-### Database Tables
-- `backup_runs`: Tracks each backup execution with statistics
-- `backup_file_states`: Stores file checksums for change detection
-
-## Thumbnail Generation
-
-### Square Thumbnail Implementation (Issue #12 Fix)
-The system now generates **square 300x300px thumbnails** to prevent blurry/stretched images in the gallery grid:
-
-- **Problem**: Previously generated 300px width with proportional height (e.g., 300x200 for 3:2 photos), but CSS forced square display causing distortion
-- **Solution**: Thumbnails now use `cover` fit mode to crop to exact 300x300px dimensions with center positioning
-- **Configuration**: Settings stored in `app_settings` table with keys: `thumbnail_width`, `thumbnail_height`, `thumbnail_fit`, `thumbnail_quality`, `thumbnail_format`
-- **Migration**: Run `040_add_thumbnail_settings.js` to add default square thumbnail settings
-- **Regeneration Script**: Use `scripts/regenerate-square-thumbnails.js` to update existing thumbnails
-
-### Thumbnail Settings API
-- `GET /api/admin/thumbnails/settings` - Get current thumbnail configuration
-- `PUT /api/admin/thumbnails/settings` - Update thumbnail settings (requires regeneration)
-- `POST /api/admin/thumbnails/regenerate` - Regenerate all thumbnails with new settings
-- `GET /api/admin/thumbnails/regenerate/status` - Check regeneration progress
-
-## Success Metrics (from PRD)
-- Time to generate gallery: <2 minutes
-- Guest satisfaction: >90%
-- System uptime: 99.9%
-- Email delivery rate: >98%
-- Successful archiving: 100%
-
-## Documentation & Development Practices
-
-### Documentation Guidelines:
-- **NEVER create new documentation files for simple tasks**
-- **ALWAYS update existing documentation (like this CLAUDE.md)**
-- Only create new .md files when explicitly requested
-- Avoid creating temporary scripts for one-off tasks
-
-### Development Best Practices:
-- Test all changes thoroughly in local environment first
-- Use version control for all changes
-- Keep commits atomic and well-described
-- Review impact on all integrated services
-- Consider backward compatibility
-- Update tests when changing functionality
-
-### Production Deployment Checklist:
-- [ ] All tests passing locally
-- [ ] Linting and type checks pass
-- [ ] Database migrations tested with rollback plan
-- [ ] Environment variables documented
-- [ ] Backup strategy confirmed
-- [ ] Monitoring alerts configured
-- [ ] Rollback procedure documented
-- [ ] Stakeholders notified of maintenance window
-- always use docker deployment for testing

DEPLOYMENT_GUIDE.md

@@ -1,819 +0,0 @@
-# 🚀 PicPeak Deployment Guide
-
-This guide covers multiple deployment options for PicPeak, from simple local setups to production-ready configurations.
-
-## 🎯 Quick Start - Simple Setup (Recommended for Beginners)
-
-For the easiest installation without Docker or complex configurations, use our **unified setup script**:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/setup.sh -o setup.sh && \
-chmod +x setup.sh && \
-sudo ./setup.sh
-```
-
-This automated script handles everything including:
-- Choice between Docker or Native installation
-- OS detection and dependency installation
-- Database setup and service configuration
-- SSL/HTTPS setup (optional)
-
-Perfect for:
-- Small to medium deployments
-- Local or VPS installations  
-- Users new to server management
-- Quick testing and evaluation
-
-👉 **See [SIMPLE_SETUP.md](./SIMPLE_SETUP.md) for detailed instructions.**
-
----
-
-## 🐳 Docker Compose Deployment
-
-### Option 1: Using Pre-built Images (Recommended)
-
-PicPeak provides official Docker images via GitHub Container Registry for quick deployment without building:
-
-```bash
-# Clone repository for configuration files
-git clone https://github.com/the-luap/picpeak.git
-cd picpeak
-
-# Copy and configure environment
-cp .env.example .env
-nano .env  # Edit with your values
-
-# Use pre-built images deployment
-docker compose -f docker-compose.production.yml up -d
-```
-
-The production compose file uses:
-- **Backend**: `ghcr.io/the-luap/picpeak/backend:latest`
-- **Frontend**: `ghcr.io/the-luap/picpeak/frontend:latest`
-
-Available tags:
-- `latest` - Latest stable release
-- `main` - Latest main branch build
-- `develop` - Development branch (may be unstable)
-- `v1.0.0` - Specific version tags
-
-### Option 2: Building from Source
-
-If you need to customize the application or the pre-built images aren't available, you can build locally:
-
-## 📋 Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Deployment](#deployment)
-- [First Login](#first-login)
-- [Reverse Proxy Setup](#reverse-proxy-setup)
-- [Maintenance](#maintenance)
-- [Troubleshooting](#troubleshooting)
- - [External Media Library](#external-media-library)
-
-## Prerequisites
-
-- Docker and Docker Compose installed
-- Domain name (for production)
-- SMTP server credentials for emails
-- At least 2GB RAM and 20GB storage
-
-## 🚀 Quick Start
-
-### Method 1: Using Pre-built Images (Fastest)
-
-1. **Clone the repository for configs**
-   ```bash
-   git clone https://github.com/the-luap/picpeak.git
-   cd picpeak
-   ```
-
-2. **Set up environment**
-   ```bash
-   cp .env.example .env
-   nano .env  # Edit with your values
-   ```
-
-3. **Create required directories**
-   ```bash
-   mkdir -p events/active events/archived data logs backup storage
-   chmod -R 755 events data logs backup storage
-   ```
-
-4. **Deploy using pre-built images**
-   ```bash
-   docker compose -f docker-compose.production.yml up -d
-   ```
-
-5. **Check logs**
-   ```bash
-   docker compose -f docker-compose.production.yml logs -f
-   ```
-
-## External Media Library
-
-PicPeak can reference an existing, read‑only media library mounted into the backend container. This avoids copying originals into PicPeak storage.
-
-- Map your host library path to the container as read‑only in `docker-compose.production.yml`:
-  - Add volume under `backend`: `- ${EXTERNAL_MEDIA}:/external-media:ro`
-  - Add backend env: `EXTERNAL_MEDIA_ROOT=/external-media`
-- In `.env`, set:
-  - `EXTERNAL_MEDIA=/mnt/photos` (example host path)
-  - `EXTERNAL_MEDIA_ROOT=/external-media`
-
-Usage:
-- In Admin → Events, set “Source Mode” to “Reference (external folder)”, select a folder under `/external-media`, then import to index and generate thumbnails. Originals stay in your library.
-
-Backups and Archives:
-- Backups only include data under `STORAGE_PATH` and exclude external originals. The backup manifest includes `metadata.external_references = { excluded: true, events: N, photos: M }` and the Admin UI surfaces a warning.
-- Archiving reference events creates a manifest‑only ZIP and deletes thumbnails for that event. External originals are never moved or deleted.
-
-Local (npm) setup (no Docker):
-
-1. Create or choose a folder that contains your external originals, e.g. `/Users/you/Pictures/picpeak-external` (macOS/Linux) or `C:\\Pictures\\picpeak-external` (Windows).
-2. In `backend/.env` (or your shell), set:
-   - `EXTERNAL_MEDIA_ROOT=/absolute/path/to/picpeak-external`
-   - Ensure `STORAGE_PATH` points to your PicPeak storage (defaults to `./storage`).
-3. Start services from source:
-   - Backend: `cd backend && npm install && npm run migrate && JWT_SECRET=... npm start`
-   - Frontend: `cd frontend && npm install && npm run dev` (or build + serve)
-4. In Admin → Events:
-   - Create an event, set “Source Mode” to “Reference (external folder)”.
-   - Use the folder picker to browse under your `EXTERNAL_MEDIA_ROOT` and select the subfolder to reference.
-   - Click “Import from selected folder” to index files and generate thumbnails on demand.
-
-Notes:
-- PicPeak only reads from `EXTERNAL_MEDIA_ROOT`; it never modifies or deletes your originals there.
-- Thumbnails are generated under `STORAGE_PATH/thumbnails` and are included in backups; originals in `EXTERNAL_MEDIA_ROOT` are excluded.
-- On Windows, use absolute paths (e.g., `C:\\Photos\\Library`) for `EXTERNAL_MEDIA_ROOT`.
-
-### Method 2: Building from Source
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/the-luap/picpeak.git
-   cd picpeak
-   ```
-
-2. **Set up environment**
-   ```bash
-   cp .env.example .env
-   nano .env  # Edit with your values
-   ```
-
-3. **Create required directories**
-   ```bash
-   mkdir -p events/active events/archived data logs backup storage
-   chmod -R 755 events data logs backup storage
-   ```
-
-4. **Build and deploy**
-   ```bash
-   docker compose build
-   docker compose up -d
-   ```
-
-5. **Check logs**
-   ```bash
-   docker compose logs -f
-   ```
-
-## 🔧 Configuration
-
-### Essential Environment Variables
-
-Generate secure values:
-```bash
-# JWT Secret
-openssl rand -base64 64
-
-# Database Password (avoid $ character - see warning below)
-openssl rand -base64 32 | tr -d '$'
-
-# Redis Password (avoid $ character - see warning below)
-openssl rand -base64 32 | tr -d '$'
-```
-
-⚠️ **PASSWORD WARNING**: Docker Compose interprets `$` as variable substitution. Either:
-- Avoid `$` in passwords (recommended - use the commands above)
-- Escape `$` as `$$` (e.g., `Pass$$word` instead of `Pass$word`)
-- Quote the entire value: `DB_PASSWORD='Pass$word'` (less reliable)
-
-### Public Landing Page
-
-- `npm run migrate` now seeds three general settings: `general_public_site_enabled`, `general_public_site_html`, and `general_public_site_custom_css` so existing installs stay disabled by default.
-- Configure the feature from **Admin → CMS Pages**. The landing page panel exposes the toggle, HTML editor, optional CSS overrides, preview, and a reset-to-default action.
-- All HTML and CSS submitted through the UI is sanitized server-side. Scripts, inline event handlers, disallowed attributes, `@import` rules, and `javascript:` URLs are stripped before content is cached or rendered.
-- Resetting via the UI (or calling `POST /api/admin/settings/public-site/reset`) restores the bundled template and clears custom CSS.
-- The landing page response is cached in-memory. Override the default 60s cache window by setting `PUBLIC_SITE_CACHE_TTL_MS` (milliseconds) in your environment if you need faster cache busting.
-- When the toggle is off PicPeak continues to serve the SPA/login redirect at `/`, preserving legacy behaviour until you explicitly enable the feature.
-
-### Backend Configuration (.env)
-Update `.env` with:
-- `JWT_SECRET` - Authentication secret (REQUIRED - generate a secure random value)
-- `DB_PASSWORD` - PostgreSQL password
-- `REDIS_PASSWORD` - Redis password
-- `SMTP_*` - Email configuration
-- **URL Configuration** (for backend CORS):
-  - `FRONTEND_URL` - Frontend origin (use full URL with scheme, no trailing slash)
-    - Example (Docker): `http://localhost:3000`
-  - `ADMIN_URL` - Admin origin (same as `FRONTEND_URL` for Docker; full URL, no trailing slash)
-    - Example (Docker): `http://localhost:3000`
-  
-  Notes:
-  - Do not include trailing `/` (e.g., use `http://host:3000`, not `http://host:3000/`).
-  - Always include the scheme (`http://` or `https://`).
-  - The backend compares origins strictly for CORS; malformed values will cause login requests to fail with 500.
-
-#### External Database Example
-To use an external PostgreSQL instead of the bundled container, set the following in `.env` and ensure the `postgres` service is disabled or removed:
-
-```env
-DB_HOST=db.example.com
-DB_PORT=5432
-DB_USER=picpeak
-DB_PASSWORD=change_me
-DB_NAME=picpeak_prod
-```
-
-Compose uses these values via `env_file: .env`. The backend service also defaults `DB_HOST=${DB_HOST:-postgres}` so if you don’t set `DB_HOST` it will use the bundled `postgres` container.
-
-### Frontend Configuration (frontend/.env)
-Create `frontend/.env` from `frontend/.env.example`:
-```bash
-cp frontend/.env.example frontend/.env
-```
-
-Update `frontend/.env` with:
-- `VITE_API_URL` - Backend API URL
-  - Docker (pre-built images) and production behind reverse proxy: `/api` (recommended; avoids CORS and matches the frontend Nginx proxy in the image)
-  - Local dev (Vite): `http://localhost:3001` or `/api` if proxying through a dev proxy
-
-Note: When using pre-built frontend images, runtime container env does not change the already-built JS. Prefer the default `/api` and let the frontend Nginx proxy forward to the backend.
-
-⚠️ **IMPORTANT PORT CONFIGURATION**: 
-- The frontend runs on port **3000** in Docker (exposed via nginx)
-- The backend API runs on port **3001**
-- The frontend `.env` file MUST point to the correct backend port (3001)
-- Default `.env.example` is configured for Docker deployment
-
-### Email Configuration Examples
-
-#### Gmail
-```env
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=your-email@gmail.com
-SMTP_PASS=your-app-specific-password
-```
-
-#### SendGrid
-```env
-SMTP_HOST=smtp.sendgrid.net
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=apikey
-SMTP_PASS=your-sendgrid-api-key
-```
-
-## 📦 Deployment
-
-### Using Pre-built Images (Fastest)
-
-```bash
-# Pull latest images from GitHub Container Registry
-docker pull ghcr.io/the-luap/picpeak/backend:latest
-docker pull ghcr.io/the-luap/picpeak/frontend:latest
-
-# Start services using production compose file
-docker compose -f docker-compose.production.yml up -d
-
-# View running containers
-docker compose ps
-```
-
-### Building from Source (For Customization)
-
-```bash
-# Build images locally
-docker compose build
-
-# Or build with no cache for clean build
-docker compose build --no-cache
-
-# Start all services
-docker compose up -d
-
-# View running containers
-docker compose ps
-```
-
-### Access Points
-
-By default, services are exposed on:
-- Frontend (UI + Admin): http://localhost:3000 (admin at `/admin`)
-- Backend/API: http://localhost:3001 (API only; no UI routes)
-- PostgreSQL: localhost:5432 (if needed)
-- Redis: localhost:6379 (if needed)
-
-### Initial Admin Setup
-
-When deploying for the first time, an admin account is automatically created with a secure, randomly generated password. This password is displayed in the Docker logs during initialization and **must be changed** on first login.
-
-#### Finding the Auto-Generated Admin Password
-
-The admin password is automatically generated during the first startup and displayed in the backend container logs. Here's how to find it:
-
-**Option 1: Search Docker logs for admin password** (recommended)
-```bash
-# Find the auto-generated admin password in logs
-docker compose logs backend | grep "Admin password"
-```
-
-You should see output like:
-```
-✅ Admin password generated: BraveTiger6231!
-```
-
-**Option 2: View the complete initialization logs**
-```bash
-# View the complete admin setup logs
-docker compose logs backend | grep -A 10 "Admin user created"
-```
-
-**Option 3: Check the saved credentials file**
-```bash
-# The password is also saved in the backend container
-docker exec picpeak-backend cat data/ADMIN_CREDENTIALS.txt
-```
-
-**Option 4: Use the helper script**
-```bash
-# Show current admin username and email (password is hidden)
-docker exec picpeak-backend node scripts/show-admin-credentials.js
-
-# Reset the admin password to a new random password
-docker exec picpeak-backend node scripts/show-admin-credentials.js --reset
-```
-
-#### Important Security Notes
-
-- **Login requires the email address**, not username
-- The admin password is only displayed once during initial setup
-- **Password change is MANDATORY** on first login - the system will force you to change it
-- If you lose the password before first login, use the `--reset` option to generate a new one
-- New password requirements: minimum 12 characters, mixed case, numbers, and special characters
-
-## 🔐 First Login
-
-After deployment, you must complete the first login process which includes mandatory password change for security.
-
-### Step 1: Locate Your Admin Password
-
-1. **Find the auto-generated password** from the credentials file:
-   ```bash
-   # Docker deployment
-   docker compose exec backend cat /app/data/ADMIN_CREDENTIALS.txt
-   
-   # Or directly from the host (if you have access)
-   cat data/ADMIN_CREDENTIALS.txt
-   ```
-
-2. **Note the admin email** (default: `admin@example.com` unless customized)
-
-### Step 2: Access Admin Panel
-
-1. Navigate to your frontend domain and open the admin section:
-   - `http://your-domain.com/admin` (behind reverse proxy)
-   - `http://localhost:3000/admin` (Docker local)
-   
-   The backend at `:3001` serves API only and does not serve the admin UI.
-2. Login using:
-   - **Email**: `admin@example.com` (or your custom admin email)
-   - **Password**: The auto-generated password from the logs
-
-### Step 3: Mandatory Password Change
-
-Upon first login, the system will **automatically redirect** you to change your password:
-
-1. **You cannot skip this step** - it's enforced for security
-2. Enter the current auto-generated password
-3. Create a new secure password meeting these requirements:
-   - Minimum 12 characters
-   - At least one uppercase letter
-   - At least one lowercase letter
-   - At least one number
-   - At least one special character (!@#$%^&*)
-
-### Security Best Practices for New Password
-
-- **Use a unique password** not used elsewhere
-- **Consider a password manager** for generation and storage
-- **Include mixed characters**: `MySecureP@ssw0rd2024!`
-- **Avoid personal information** (names, dates, etc.)
-- **Save securely** - you cannot recover this password easily
-
-### If You Lose Access
-
-If you lose your admin credentials after the first login, you'll need to manually reset the password in the database or create a new admin user through the database.
-
-**Note**: The credentials file (`ADMIN_CREDENTIALS.txt`) is only created during initial deployment and contains the first admin password. After changing the password, this file becomes outdated but is kept for reference. If you need to regenerate the password and file during a reinstall, re-run the installer with the `--force-admin-password-reset` flag:
-
-```bash
-# Native reinstall example
-sudo ./setup.sh --native --force-admin-password-reset
-
-# Docker reinstall example
-sudo ./setup.sh --docker --force-admin-password-reset
-```
-
-The flag calls `scripts/reset-admin-password.js` in non-interactive mode, writes a fresh random password into `data/ADMIN_CREDENTIALS.txt`, and prints the new credentials at the end of the installer run.
-
-#### Configuring Admin Email
-
-By default, the admin email is `admin@example.com`. To use a different email address, set it in your `.env` file before first deployment:
-
-```env
-# .env
-ADMIN_EMAIL=your-email@yourdomain.com
-```
-
-**Note**: This only works on first deployment. To change the admin email after deployment, you'll need to update it in the database or create a new admin user through the admin panel.
-
-## 🔒 Reverse Proxy Setup
-
-For production deployments, you should use a reverse proxy for SSL/HTTPS. The application exposes ports directly, allowing you to use any reverse proxy solution.
-
-### Option 1: Nginx
-
-Install nginx and create `/etc/nginx/sites-available/picpeak`:
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-    return 301 https://$server_name$request_uri;
-}
-
-server {
-    listen 443 ssl http2;
-    server_name your-domain.com;
-
-    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
-
-    # Frontend
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Frontend (serves UI and /admin/*)
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Backend API and protected resources
-    location /api {
-        proxy_pass http://localhost:3001;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-    location ~ ^/(photos|thumbnails|uploads) {
-        proxy_pass http://localhost:3001;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-Enable the site:
-```bash
-sudo ln -s /etc/nginx/sites-available/picpeak /etc/nginx/sites-enabled/
-sudo nginx -t
-sudo systemctl reload nginx
-```
-
-### Option 2: Traefik
-
-Add labels to `docker-compose.override.yml`:
-
-```yaml
-version: '3.8'
-
-services:
-  frontend:
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.picpeak.rule=Host(`your-domain.com`)"
-      - "traefik.http.routers.picpeak.entrypoints=websecure"
-      - "traefik.http.routers.picpeak.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak.loadbalancer.server.port=80"
-
-  backend:
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.picpeak-api.rule=Host(`your-domain.com`) && PathPrefix(`/api`)"
-      - "traefik.http.routers.picpeak-api.entrypoints=websecure"
-      - "traefik.http.routers.picpeak-api.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak-api.loadbalancer.server.port=3001"
-```
-
-### Option 3: Caddy
-
-Create a `Caddyfile`:
-
-```caddyfile
-your-domain.com {
-    # Frontend
-    handle /* {
-        reverse_proxy localhost:3000
-    }
-
-    # Backend API and admin
-    handle /api/* {
-        reverse_proxy localhost:3001
-    }
-    
-    handle /admin/* {
-        reverse_proxy localhost:3001
-    }
-
-    # Protected resources
-    handle /photos/* {
-        reverse_proxy localhost:3001
-    }
-
-    handle /thumbnails/* {
-        reverse_proxy localhost:3001
-    }
-
-    handle /uploads/* {
-        reverse_proxy localhost:3001
-    }
-}
-```
-
-### SSL Certificates
-
-For any reverse proxy, you can use Let's Encrypt:
-
-```bash
-# With Certbot
-sudo certbot certonly --webroot -w /var/www/certbot -d your-domain.com
-
-# Or use your reverse proxy's built-in ACME support
-```
-
-## 🔧 Maintenance
-
-### Viewing Logs
-
-```bash
-# All services
-docker compose logs -f
-
-# Specific service
-docker compose logs -f backend
-docker compose logs -f frontend
-```
-
-### Backup
-
-#### Manual Backup
-```bash
-# Database backup
-docker exec picpeak-postgres pg_dump -U picpeak picpeak_prod > backup/db_$(date +%Y%m%d_%H%M%S).sql
-
-# Files backup
-tar -czf backup/photos_$(date +%Y%m%d_%H%M%S).tar.gz events/
-```
-
-#### Automated Backup
-The application includes a built-in backup service. Configure it in the admin panel:
-1. Login to admin panel
-2. Go to Settings → Backup
-3. Configure destination and schedule
-4. Enable backup service
-
-### Updates
-
-#### Method 1: Using Pre-built Images (Recommended)
-
-```bash
-# Pull latest changes (for configuration updates)
-git pull
-
-# Pull latest images from GitHub Container Registry
-docker compose -f docker-compose.production.yml pull
-
-# Restart with new images
-docker compose -f docker-compose.production.yml down
-docker compose -f docker-compose.production.yml up -d
-
-# Verify services are healthy
-docker compose -f docker-compose.production.yml ps
-```
-
-#### Method 2: Building from Source
-
-```bash
-# Pull latest changes
-git pull
-
-# Rebuild and restart
-docker compose down
-docker compose build --no-cache
-docker compose up -d
-
-# Verify services are healthy
-docker compose ps
-```
-
-#### Specific Version Updates
-
-To use a specific version of the images:
-
-```bash
-# Edit docker-compose.production.yml to specify version tags
-# Change: ghcr.io/the-luap/picpeak/backend:latest
-# To:     ghcr.io/the-luap/picpeak/backend:v1.0.0
-
-# Then pull and restart
-docker compose -f docker-compose.production.yml pull
-docker compose -f docker-compose.production.yml up -d
-```
-
-### Database Migrations
-
-Migrations run automatically on startup, but you can run them manually:
-
-```bash
-docker exec picpeak-backend npm run migrate
-```
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-#### 502 Bad Gateway / Login Failures
-**This is the most common deployment issue!** Usually caused by misconfigured URLs or network problems:
-
-1. **CORS Configuration Errors**:
-   ```bash
-   # WRONG - Missing port will cause CORS errors
-   FRONTEND_URL=http://10.0.252.12
-   
-   # CORRECT - Include the port you're accessing from
-   FRONTEND_URL=http://10.0.252.12:3000
-   ```
-   
-   The backend validates Origin headers against `FRONTEND_URL` for CORS. If they don't match exactly, you'll get 500 errors on login.
-
-2. **After Container Restarts**:
-   - Nginx may have cached old container IPs
-   - Solution: `docker restart picpeak-frontend`
-   - Always wait 30-60 seconds for health checks
-
-3. **Backend Not Starting After Migrations**:
-   - The logs may only show migrations completed
-   - Check if server is actually running: `docker exec picpeak-backend ps aux | grep node`
-   - Should see `node server.js` process
-
-4. **Login After Fresh Install**:
-   - Check backend logs for auto-generated admin password: `docker compose logs backend | grep "Admin password"`
-   - Email: `admin@example.com` (or your custom admin email from .env)
-   - Password: Auto-generated and shown in logs (e.g., `BraveTiger6231!`)
-   - Remember: Password MUST be changed on first login
-
-5. **Complete Fix Sequence**:
-   ```bash
-   # 1. Fix your .env file URLs
-   # 2. Full restart
-   docker-compose down
-   docker-compose up -d
-   
-   # 3. Wait for healthy status
-   sleep 60
-   docker ps  # All should show (healthy)
-   
-   # 4. Test backend directly
-   curl http://localhost:3001/health
-   
-   # 5. Test through frontend
-   curl http://localhost:3000/api/public/settings
-   ```
-
-#### Port Already in Use
-```bash
-# Check what's using the port
-sudo lsof -i :3000
-sudo lsof -i :3001
-
-# Change ports in .env
-FRONTEND_PORT=3002
-BACKEND_PORT=3003
-```
-
-#### Docker Compose Variable Substitution Errors
-If you see warnings like:
-```
-WARN[0000] The "fgbf" variable is not set. Defaulting to a blank string.
-```
-
-This means your password contains `$` which Docker Compose interprets as a variable. Solutions:
-1. **Best**: Generate passwords without `$`: `openssl rand -base64 32 | tr -d '$'`
-2. **Alternative**: Escape `$` as `$$` in your .env file
-3. **Example**: `DB_PASSWORD=Pass@#$$fgbf` instead of `DB_PASSWORD=Pass@#$fgbf`
-
-#### Permission Errors
-```bash
-# Fix ownership
-sudo chown -R 1000:1000 events data logs backup storage
-chmod -R 755 events data logs backup storage
-```
-
-#### Database Connection Issues
-```bash
-# Check if database is running
-docker compose ps
-docker compose logs postgres
-
-# Test connection
-docker exec picpeak-postgres pg_isready
-```
-
-#### Email Not Sending
-- Verify SMTP settings in .env
-- Check email queue: `docker exec picpeak-backend psql -U picpeak -d picpeak_prod -c "SELECT * FROM email_queue ORDER BY created_at DESC LIMIT 10;"`
-- For Gmail, use app-specific password
-- Check logs: `docker compose logs backend | grep email`
-
-### Health Checks
-
-```bash
-# Backend health
-curl http://localhost:3001/api/health
-
-# Frontend health
-curl http://localhost:3000
-
-# Database health
-docker exec picpeak-postgres pg_isready
-```
-
-### Useful Commands
-
-```bash
-# Enter backend container
-docker exec -it picpeak-backend sh
-
-# Enter database
-docker exec -it picpeak-postgres psql -U picpeak picpeak_prod
-
-# Reset admin password
-docker exec picpeak-backend node scripts/show-admin-credentials.js --reset
-
-# Check disk usage
-df -h
-du -sh events/ storage/ backup/
-
-# View running processes
-docker compose top
-```
-
-## Security Recommendations
-
-1. **Use HTTPS**: Always use a reverse proxy with SSL in production
-2. **Firewall**: Only expose necessary ports (80, 443)
-3. **Secure passwords**: Use strong, unique passwords for all services
-4. **Regular updates**: Keep Docker images and system packages updated
-5. **Backup strategy**: Set up automated backups and test restoration
-6. **Monitor logs**: Regularly check logs for suspicious activity
-7. **Rate limiting**: The app includes built-in rate limiting, configure as needed
-
-## Support
-
-For issues and questions:
-- Check logs first: `docker compose logs`
-- Review documentation in the repository
-- Check existing issues on GitHub
-- Create a new issue with:
-  - Error messages
-  - Log output
-  - Environment details (without secrets)
-  - Steps to reproduce

README.md

@@ -7,12 +7,28 @@
   [![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://www.docker.com/)
   [![Node.js](https://img.shields.io/badge/node.js-6DA55F?style=flat&logo=node.js&logoColor=white)](https://nodejs.org/)
   [![React](https://img.shields.io/badge/react-%2320232a.svg?style=flat&logo=react&logoColor=%2361DAFB)](https://reactjs.org/)
+  [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-theluap-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/theluap)
+
+  [Homepage](https://www.picpeak.app) · [Live Demo](https://demo.picpeak.app) · [Documentation](https://docs.picpeak.app) · [Support the project ☕](https://buymeacoffee.com/theluap)
 </div>
 
 **PicPeak** is a powerful, self-hosted open-source alternative to commercial photo-sharing platforms like PicDrop.com and Scrapbook.de. Designed specifically for photographers and event organizers, PicPeak makes it simple to share beautiful, time-limited photo galleries with clients while maintaining full control over your data and branding.
 
 ![PicPeak Gallery Preview](docs/screenshot-gallery.png)
 
+## 🎮 Live Demo
+
+Try PicPeak without installing anything:
+
+| | |
+|---|---|
+| **Demo URL** | [demo.picpeak.app](https://demo.picpeak.app) |
+| **Admin Panel** | [demo.picpeak.app/admin](https://demo.picpeak.app/admin) |
+| **Email** | `demo@picpeak.app` |
+| **Password** | `Demo2026!` |
+
+> The demo resets periodically. Uploaded content may be removed without notice.
+
 ## 🌟 Why Choose PicPeak?
 
 Unlike expensive SaaS solutions, PicPeak gives you:
@@ -68,9 +84,9 @@ cp .env.example .env
 nano .env
 
 # Start with Docker Compose
-docker-compose up -d
+docker compose up -d
 
-# Access at http://localhost:3005
+# Access at http://localhost:3000
 ```
 
 Note on Docker file permissions (PUID/PGID)
@@ -79,12 +95,67 @@ Note on Docker file permissions (PUID/PGID)
 - Example in `.env`:
   - `PUID=1000`
   - `PGID=1000`
-- Without this, creating events, uploads, thumbnails, or logs can fail with “Permission denied”.
+- Without this, creating events, uploads, thumbnails, or logs can fail with "Permission denied".
+
+**ARM64 (aarch64) systems:** Pre-built images include native `linux/arm64`, no platform flags or emulation needed. If you're on an older image tag that's still amd64-only, see [docker-compose.amd64.override.yml](docker-compose.amd64.override.yml) for a transitional fallback.
+
+## 🔄 Release Channels
+
+PicPeak offers two release channels for different needs:
+
+### Stable Channel (Recommended)
+- Production-ready releases
+- Thoroughly tested before release
+- Docker tags: `stable`, `latest`, or specific version like `v2.3.0`
+
+### Beta Channel
+- Early access to new features
+- May contain bugs or incomplete functionality
+- Docker tags: `beta` or specific version like `v2.3.0-beta.1`
+
+### Switching Channels
+
+Set the `PICPEAK_CHANNEL` environment variable in your `.env` file:
+
+```bash
+# For stable releases (default)
+PICPEAK_CHANNEL=stable
+
+# For beta releases
+PICPEAK_CHANNEL=beta
+
+# For a specific version
+PICPEAK_CHANNEL=v2.3.0
+```
+
+Then update your containers:
+
+```bash
+docker compose -f docker-compose.production.yml pull
+docker compose -f docker-compose.production.yml up -d
+```
+
+### Update Notifications
+
+The admin dashboard automatically notifies you when updates are available for your channel. To disable update checks, set:
+
+```bash
+UPDATE_CHECK_ENABLED=false
+```
 
 ## 📖 Documentation
 
-- 📘 [**Deployment Guide**](DEPLOYMENT_GUIDE.md) - Detailed installation instructions
-  - Includes the new [External Media Library](DEPLOYMENT_GUIDE.md#external-media-library) reference mode
+Full documentation lives at **[docs.picpeak.app](https://docs.picpeak.app)** — deployment, admin settings reference, API docs, webhooks, archive lifecycle, branding, and everything else. Some quick links:
+
+- 🚀 [**Deployment**](https://docs.picpeak.app/deployment) - Docker, environment variables, reverse proxy, SSL
+- ⚙️ [**Admin Settings**](https://docs.picpeak.app/guides/admin-settings) - Every tab in the Settings panel
+- 🎯 [**Creating Events**](https://docs.picpeak.app/guides/creating-events) - Full event field reference
+- 💾 [**Backup & Restore**](https://docs.picpeak.app/guides/backup-restore) - Local, S3, rsync destinations
+- 🔌 [**API Reference**](https://docs.picpeak.app/api) - REST endpoints, OpenAPI spec, webhooks
+- 🪝 [**Webhooks**](https://docs.picpeak.app/features/webhooks) - Event payloads, signing, filters, templates
+
+Project meta:
+
 - 🤝 [**Contributing**](CONTRIBUTING.md) - How to contribute
 - 📜 [**License**](LICENSE) - MIT License
 - 🔒 [**Security**](SECURITY.md) - Security policies
@@ -115,10 +186,111 @@ Perfect for:
 
 - **Backend**: Node.js, Express, SQLite/PostgreSQL
 - **Frontend**: React, Tailwind CSS, Framer Motion
-- **Storage**: File-based with automatic archiving
+- **Storage**: Local filesystem (default) or S3-compatible object store (AWS S3, MinIO, R2, B2, Wasabi, Spaces) — see [Storage Backends](#storage-backends)
 - **Email**: SMTP with customizable templates
 - **Analytics**: Privacy-focused with Umami integration
 
+## 💾 Storage Backends
+
+PicPeak supports two storage backends for photos, thumbnails, hero images, watermarks, and archive zips. Both are configured via environment variables; no code change is required to switch.
+
+| Capability | `STORAGE_BACKEND=local` (default) | `STORAGE_BACKEND=s3` |
+|---|---|---|
+| Photo / thumbnail / hero storage | Local filesystem under `STORAGE_PATH` | Bucket on any S3-compatible service |
+| Admin UI upload | ✅ | ✅ |
+| Filesystem auto-import (chokidar watcher) | ✅ | ❌ — disabled (use the upload API) |
+| Watermarks, fingerprinting, fragmentation | ✅ | ✅ (materialized to a tmp file just-in-time) |
+| Bulk download zips (cached + on-the-fly) | ✅ | ✅ |
+| Backups | ✅ | ✅ |
+| External media reference mode (`EXTERNAL_MEDIA_ROOT`) | ✅ (always local) | ✅ (still local — not migrated) |
+
+### Switching to an S3-compatible backend
+
+1. Provision a bucket and credentials. The minimum IAM policy is documented in `.env.example`.
+2. Set `STORAGE_BACKEND=s3` plus `STORAGE_S3_BUCKET`, `STORAGE_S3_REGION`, `STORAGE_S3_ACCESS_KEY`, `STORAGE_S3_SECRET_KEY`. For non-AWS providers (MinIO, R2, B2, …) also set `STORAGE_S3_ENDPOINT`.
+3. If you have existing local content, copy it first: `node backend/scripts/migrate-storage.js --dry-run` then `node backend/scripts/migrate-storage.js`. The script is idempotent and writes a failures CSV.
+4. Restart the backend. The startup check pings the bucket and refuses to boot on misconfig.
+
+Note: presigned-URL serving (zero-bandwidth direct downloads from S3) is intentionally **not** in v1 — every request still streams through the backend so watermarks, devtools-detection, and access logging keep working.
+
+## 🔔 Webhooks
+
+PicPeak POSTs event/photo lifecycle notifications to URLs you configure under **Settings → Webhooks**. Each delivery is signed `HMAC-SHA256` with a per-webhook secret in the `X-PicPeak-Signature` header so receivers can verify the request really came from your PicPeak instance.
+
+### Event types
+
+| Event | Fires when |
+|---|---|
+| `event.created` | Gallery created (admin or API) |
+| `event.published` | Draft becomes live (`is_draft: true → false`) — also fires when an event is created with `is_draft=false` |
+| `event.archived` | Bulk-archive, manual archive, or auto-archive on expiry |
+| `event.expired` | Expiration checker marks the gallery inactive (fires before `event.archived` in the cascade) |
+| `photo.uploaded` | Admin upload, API upload, guest upload, or auto-import |
+| `photo.deleted` | Single delete, bulk delete (NOT fired per-photo when an event is archived — receivers infer from `event.archived` to avoid flooding) |
+
+### Payload shape
+
+```json
+{
+  "id": "delivery-uuid",
+  "type": "event.published",
+  "created_at": "2026-04-28T05:25:00.000Z",
+  "data": {
+    "event": { "id": 123, "slug": "wedding-smith", "share_url": "https://..." }
+  }
+}
+```
+
+Also sent on every request:
+- `X-PicPeak-Signature` — `HMAC-SHA256(secret, raw_body)` as hex
+- `X-PicPeak-Event` — the event type (handy for routing without parsing the body)
+- `X-PicPeak-Delivery` — UUID for idempotency on the receiver side
+- `User-Agent: PicPeak-Webhooks/1.0`
+
+### Verifying signatures
+
+**Node.js**
+```js
+const crypto = require('crypto');
+function verify(secret, rawBody, signature) {
+  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+  const a = Buffer.from(expected, 'hex');
+  const b = Buffer.from(signature, 'hex');
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+```
+
+**Python**
+```python
+import hmac, hashlib
+def verify(secret: str, raw_body: bytes, signature: str) -> bool:
+    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+```
+
+**curl + openssl** (one-liner for a quick replay)
+```sh
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
+[ "$SIG" = "$RECEIVED_SIG" ] && echo OK || echo MISMATCH
+```
+
+### Retries + observability
+
+- `2xx` → success, recorded with latency
+- Non-`2xx` or network error → exponential backoff: `1m → 5m → 30m → 2h → 12h`, max 5 attempts
+- After max attempts: status `failed`, surfaces in **Settings → Webhooks → Deliveries** with a "Replay" button
+- Up to 5 deliveries in flight at once; one slow consumer can't block others (configurable via `WEBHOOK_DELIVERY_CONCURRENCY`)
+- Response body truncated to 1KB before storage so chatty receivers don't bloat the audit log
+
+The deliveries page (`/admin/webhooks/:id/deliveries`) shows every attempt with timestamp, status, HTTP code, latency, payload sent, signature, and response. Click "Send test event" to fire a synthetic delivery for any event type.
+
+### SSRF protection
+
+Webhook URLs are validated against the same private-IP blocklist used elsewhere in the app — loopback, private RFC1918 ranges, link-local, `.local`/`.internal` hostnames, cloud metadata endpoints. The check runs both at create time and per-delivery (DNS-rebinding mitigation).
+
+For local development with a receiver on the same machine or docker network, set `WEBHOOK_ALLOW_PRIVATE_URLS=true`. Production deployments must leave this OFF.
+
 ## 💻 System Requirements
 
 ### Minimum Requirements
@@ -133,6 +305,31 @@ Perfect for:
 - **Docker**: v20.10.0+
 - **Docker Compose**: v2.0.0+
 
+### Video Support Requirements
+When enabling video uploads, consider these additional resources:
+
+| Resource | Recommendation | Notes |
+|----------|----------------|-------|
+| **RAM** | 4GB+ recommended | FFmpeg processing requires more memory |
+| **Storage** | Plan for 10-100x more | Videos are significantly larger than images |
+| **CPU** | Additional cores help | Video thumbnail extraction is CPU-intensive |
+| **Bandwidth** | Higher throughput | Video streaming requires more bandwidth |
+
+**Technical Notes:**
+- FFmpeg is bundled via npm (`@ffmpeg-installer/ffmpeg`) - no system installation required
+- Maximum upload size: **10GB per video file**
+- Chunked upload support for files >100MB (resumable uploads)
+- Supported formats: MP4, WebM, MOV, AVI
+- Video thumbnails are automatically generated from the first few seconds
+
+**For Nginx/Reverse Proxy:**
+If using Nginx, increase the client max body size:
+```nginx
+client_max_body_size 10G;
+proxy_read_timeout 3600;
+proxy_send_timeout 3600;
+```
+
 ## 🤝 Contributing
 
 We love contributions! PicPeak is built by photographers, for photographers. Whether you're fixing bugs, adding features, or improving documentation, your help is welcome.
@@ -208,7 +405,6 @@ These features are currently in beta testing and may have limited functionality
 
 | Feature | Description | Status |
 |---------|-------------|--------|
-| **Download Protection** | Advanced image protection system with canvas rendering, invisible watermarking, and right-click prevention to protect your photos from unauthorized downloads | 🧪 Beta |
 | **Simple Deployment Script** | One-click deployment script for quick server setup with automated configuration and dependency installation | 🧪 Beta |
 
 ### 📋 Future Enhancements
@@ -217,15 +413,28 @@ These features are currently in beta testing and may have limited functionality
 |---------|-------------|----------|---------|
 | **Backup & Restore** | Comprehensive backup system with S3/MinIO support, automated scheduling, and safe restore functionality | High | ✅ Implemented |
 | **External Media Library (Reference Mode)** | Use an external folder library as a read‑only source with import and on‑demand thumbnail generation | High | ✅ Implemented |
-| **Gallery Templates** | Additional gallery layouts and themes (masonry, slideshow, story-style) for different event types | Medium | 🔄 Open |
+| **Download Protection** | Advanced image protection system with canvas rendering, invisible watermarking, right-click prevention, and DevTools detection to protect photos from unauthorized downloads | High | ✅ Implemented |
+| **Gallery Templates** | Multiple gallery layouts (grid, masonry, carousel, timeline, hero, mosaic) with custom CSS styling support. Includes starter templates like Apple Liquid Glass for complete visual customization | Medium | ✅ Implemented |
 | **Face Recognition** | AI-powered face detection to help guests find their photos and create automatic person-based albums | Low | 🔄 Open |
 | **Gallery Feedback** | Allow guests to like, rate, and comment on photos with admin notifications and moderation | Medium | ✅ Implemented |
-| **Video Support** | Upload and display videos alongside photos in galleries with streaming support | Low | 🔄 Open |
-| **Multiple Administrators** | Support for multiple admin accounts with role-based permissions and activity tracking | Low | 📋 Planned |
-| **Filtering & Export Options** | Add filters to show only rated, liked, or marked photos and export filtered selections for Capture One or Lightroom workflows | Low | 🔄 Open |
+| **Video Support** | Upload and display videos alongside photos in galleries with streaming support | Low | ✅ Implemented |
+| **Multiple Administrators** | Support for multiple admin accounts with role-based permissions and activity tracking | Low | ✅ Implemented |
+| **Filtering & Export Options** | Filter photos by likes, ratings, comments, or favorites. Search by filename. Sort by date, name, size, or rating. Export filtered selections as ZIP or generate Capture One/Lightroom-compatible file lists for professional workflows | Medium | ✅ Implemented |
 
 **Status Legend:** ✅ Implemented | 🚧 In Progress | 🔄 Open | 📋 Planned
 
+## ☕ Support the Project
+
+PicPeak is free, open source, and self-hostable forever. If it saves you time or replaces a paid subscription, consider buying me a coffee — it directly funds the time spent on new features, bug fixes, and keeping the demo + docs running.
+
+<p align="left">
+  <a href="https://buymeacoffee.com/theluap" target="_blank">
+    <img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=theluap&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff" alt="Buy Me A Coffee" />
+  </a>
+</p>
+
+Other ways to support without spending anything: ⭐ star the repo, share it with photographer friends, file good bug reports, or open a PR.
+
 ## 🙏 Acknowledgments
 
 PicPeak is inspired by the best features of commercial platforms while remaining completely open source. Special thanks to all contributors who make this project possible.
@@ -247,7 +456,7 @@ PicPeak is released under the [MIT License](LICENSE). Use it freely for personal
 ## 🚀 Ready to Get Started?
 
 1. ⭐ **Star this repository** to show your support
-2. 📖 Read the [Deployment Guide](DEPLOYMENT_GUIDE.md)
+2. 📖 Read the [docs at docs.picpeak.app](https://docs.picpeak.app)
 3. 🐛 Report issues or request features
 4. 🤝 Join our community and contribute!
 
@@ -256,7 +465,9 @@ PicPeak is released under the [MIT License](LICENSE). Use it freely for personal
 <p align="center">
   Made with ❤️ by photographers, for photographers
   <br>
+  <a href="https://www.picpeak.app">Homepage</a> •
+  <a href="https://demo.picpeak.app">Live Demo</a> •
   <a href="https://github.com/the-luap/picpeak">GitHub</a> •
-  <a href="DEPLOYMENT_GUIDE.md">Documentation</a> •
+  <a href="https://docs.picpeak.app">Documentation</a> •
   <a href="https://github.com/the-luap/picpeak/issues">Support</a>
 </p>

SECURITY.md

@@ -6,8 +6,8 @@ We release patches for security vulnerabilities. Currently supported versions:
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.x.x   | :white_check_mark: |
-| < 1.0   | :x:                |
+| 2.x.x   | :white_check_mark: |
+| < 2.0   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -15,9 +15,9 @@ We take the security of PicPeak seriously. If you have discovered a security vul
 
 ### 1. **Do NOT create a public GitHub issue**
 
-### 2. Report the vulnerability by:
-- Opening a [security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
-- Mark it clearly as "SECURITY" in the title
+### 2. Report the vulnerability privately by:
+- **Preferred:** Use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new)
+- **Alternative:** Email us at **info@picpeak.app** with the details
 - Include:
   - Description of the vulnerability
   - Steps to reproduce
@@ -82,7 +82,7 @@ We believe in responsible disclosure. Once a vulnerability is fixed:
 
 ## Contact
 
-- Security issues: [Create a security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
+- Security issues: Email **info@picpeak.app** or use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new)
 - General support: [GitHub Issues](https://github.com/the-luap/picpeak/issues)
 
 Thank you for helping keep PicPeak and its users safe!

SIMPLE_SETUP.md

@@ -8,9 +8,9 @@ This guide provides easy installation instructions for PicPeak on Linux servers
 
 ```bash
 # Download and run the unified setup script
-curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/setup.sh -o setup.sh && \
-chmod +x setup.sh && \
-sudo ./setup.sh
+curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/picpeak-setup.sh -o picpeak-setup.sh && \
+chmod +x picpeak-setup.sh && \
+sudo ./picpeak-setup.sh
 ```
 
 The script will automatically detect your environment and recommend the best installation method.
@@ -21,7 +21,7 @@ The script will automatically detect your environment and recommend the best ins
 Best for: Most users, easy updates, isolated environment
 
 ```bash
-sudo ./setup.sh --docker
+sudo ./picpeak-setup.sh --docker
 ```
 
 **Pros:**
@@ -38,7 +38,7 @@ sudo ./setup.sh --docker
 Best for: Resource-constrained systems, Raspberry Pi, direct control
 
 ```bash
-sudo ./setup.sh --native
+sudo ./picpeak-setup.sh --native
 ```
 
 **Pros:**
@@ -73,7 +73,7 @@ sudo ./setup.sh --native
 
 ### Interactive Mode (Default)
 ```bash
-sudo ./setup.sh
+sudo ./picpeak-setup.sh
 ```
 
 The script will prompt you to choose:
@@ -87,7 +87,7 @@ The script will prompt you to choose:
 
 #### Docker with full configuration:
 ```bash
-sudo ./setup.sh --docker --unattended \
+sudo ./picpeak-setup.sh --docker --unattended \
   --domain photos.example.com \
   --email admin@example.com \
   --admin-password SecurePass123 \
@@ -100,7 +100,7 @@ sudo ./setup.sh --docker --unattended \
 
 #### Native with minimal configuration:
 ```bash
-sudo ./setup.sh --native --unattended \
+sudo ./picpeak-setup.sh --native --unattended \
   --email admin@example.com \
   --admin-password SecurePass123
 ```
@@ -219,29 +219,36 @@ location ~ ^/(photos|thumbnails|uploads) {
 
 ### Creating a Gallery
 
-#### Method 1: Via Admin Panel (Recommended)
-1. Login to admin panel
+#### Via Admin Panel
+1. Login to admin panel at `/admin`
 2. Click "Create New Event"
-3. Configure settings and upload photos
+3. Configure settings (name, date, password, customer email)
+4. Upload photos via drag & drop in the Photos tab
+5. Publish the gallery when ready
+
+#### Adding Photos via File System
+
+> **Important:** You must first create the event in the admin panel. The file watcher only detects new photos for events that already exist in the database. You cannot create a gallery by copying files alone.
+
+Once an event exists, you can add photos by copying them into the event's folder. PicPeak's built-in file watcher will automatically detect the new files, create database records, and generate thumbnails.
 
-#### Method 2: File System
 ```bash
-# Docker installation
-mkdir -p ~/picpeak/storage/events/active/wedding-smith-2024
-cp /path/to/photos/* ~/picpeak/storage/events/active/wedding-smith-2024/
+# Docker installation — copy photos into an existing event's folder
+cp /path/to/photos/*.jpg ~/picpeak/storage/events/active/<event-slug>/
 
 # Native installation
-sudo mkdir -p /opt/picpeak/events/active/wedding-smith-2024
-sudo cp /path/to/photos/* /opt/picpeak/events/active/wedding-smith-2024/
-sudo chown -R picpeak:picpeak /opt/picpeak/events/active/wedding-smith-2024
+sudo cp /path/to/photos/*.jpg /opt/picpeak/events/active/<event-slug>/
+sudo chown -R picpeak:picpeak /opt/picpeak/events/active/<event-slug>
 ```
 
+The event slug is visible in the admin panel URL or share link (e.g. `wedding-smith-2024`). Supported formats: `.jpg`, `.jpeg`, `.png`, `.webp`. The file watcher has a 2-second stability delay before processing new files.
+
 ### Gallery Structure
 ```
-wedding-smith-2024/
-├── collages/        # Group photos
-├── individual/      # Individual photos
-└── thumbnails/      # Auto-generated thumbnails
+<event-slug>/
+├── collages/        # Group photos (optional subfolder)
+├── individual/      # Individual photos (optional subfolder)
+└── photo.jpg        # Photos at root level also work
 ```
 
 ## 🔧 Service Management
@@ -293,7 +300,7 @@ sudo systemctl restart picpeak-backend picpeak-workers
 
 # Update PicPeak
 # (reruns migrations to pick up schema fixes for native installs)
-sudo ./setup.sh --update
+sudo ./picpeak-setup.sh --update
 ```
 
 ## ⚙️ Configuration
@@ -385,14 +392,14 @@ docker compose pull
 docker compose up -d
 
 # Native
-sudo ./setup.sh --update
+sudo ./picpeak-setup.sh --update
 ```
 
 ### Uninstall
 
 ```bash
 # Will prompt for confirmation and data removal options
-sudo ./setup.sh --uninstall
+sudo ./picpeak-setup.sh --uninstall
 ```
 
 ## 🐛 Troubleshooting
@@ -451,6 +458,8 @@ cd /opt/picpeak/app/backend
 sudo -u picpeak node scripts/reset-admin-password.js
 ```
 
+> **Note:** The new password will be displayed in the console output and saved to `ADMIN_PASSWORD_RESET.txt`. Save it immediately!
+
 ### Getting Help
 
 1. **Check logs:**
@@ -459,8 +468,8 @@ sudo -u picpeak node scripts/reset-admin-password.js
    - Installation: `/tmp/picpeak-setup-*.log`
 
 2. **Documentation:**
-   - [Full Documentation](https://github.com/the-luap/picpeak)
-   - [Deployment Guide](./DEPLOYMENT_GUIDE.md)
+   - [Full Documentation](https://docs.picpeak.app)
+   - [Deployment Guide](https://docs.picpeak.app/deployment)
 
 3. **Support:**
    - [GitHub Issues](https://github.com/the-luap/picpeak/issues)
@@ -508,13 +517,13 @@ sudo systemctl restart picpeak-backend
 ### Home/Office Network
 ```bash
 # Simple local setup without domain
-sudo ./setup.sh --native --email admin@local.com
+sudo ./picpeak-setup.sh --native --email admin@local.com
 ```
 
 ### Public Website with HTTPS
 ```bash
 # Full production setup
-sudo ./setup.sh --docker \
+sudo ./picpeak-setup.sh --docker \
   --domain photos.company.com \
   --email admin@company.com \
   --enable-ssl
@@ -523,7 +532,7 @@ sudo ./setup.sh --docker \
 ### Raspberry Pi Setup
 ```bash
 # Optimized for ARM devices
-sudo ./setup.sh --native \
+sudo ./picpeak-setup.sh --native \
   --port 8080 \
   --email pi@local.com
 ```

backend/.env.example

@@ -9,11 +9,44 @@ PORT=3001
 # Generate with: openssl rand -base64 32
 JWT_SECRET=your-very-secure-jwt-secret-at-least-32-characters-long-example123456
 
+# Auth cookie Secure flag
+#   unset  - default: follows NODE_ENV (production=true, dev=false)
+#   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access)
+#   false  - never set Secure (allows HTTP; cookies not protected on HTTPS)
+#   auto   - decide per request: Secure on HTTPS, not on HTTP
+#
+# Use COOKIE_SECURE=auto if your deployment is reachable over both HTTPS
+# (via a reverse proxy like Nginx Proxy Manager, Traefik, Caddy) AND plain
+# HTTP (e.g. LAN access at http://192.168.x.x:3001). The backend reads
+# req.secure from Express, which respects the X-Forwarded-Proto header
+# when the proxy is in the trust list.
+#
+# Requirements for auto mode:
+#   1. Your reverse proxy MUST send X-Forwarded-Proto: https on HTTPS
+#      requests. Standard configs for NPM/Traefik/Caddy do this by default.
+#   2. The proxy must be on a trusted IP range. By default PicPeak trusts
+#      loopback and private networks (127.0.0.1, 10.x, 172.16-31.x,
+#      192.168.x, link-local). Proxies outside those ranges need custom
+#      trust proxy configuration.
+# COOKIE_SECURE=auto
+
+# Cookie SameSite attribute (Lax | Strict | None). Default: Lax
+# COOKIE_SAMESITE=Lax
+
+# Cookie Domain — set this if serving auth cookies across subdomains.
+# Leave unset for same-origin setups.
+# COOKIE_DOMAIN=.example.com
+
 # URLs (adjust for your domain)
 ADMIN_URL=https://photos.example.com
 FRONTEND_URL=https://photos.example.com
 BACKEND_URL=https://photos.example.com  # Or https://api.photos.example.com if separate
 
+# API URL for email assets (logos, images in emails)
+# This must be the publicly accessible URL where recipients can load images
+# If not set, defaults to http://localhost:3001 which will break images in production emails
+API_URL=https://photos.example.com/api
+
 # Database Configuration
 DATABASE_CLIENT=pg
 DB_HOST=localhost
@@ -39,6 +72,7 @@ SMTP_PASS=your-sendgrid-api-key
 EMAIL_FROM=noreply@example.com
 
 # Storage Paths
+# IMPORTANT: STORAGE_PATH must be set to avoid file path resolution issues
 # Docker deployment:
 STORAGE_PATH=/app/storage
 EVENTS_PATH=/app/storage/events

backend/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-alpine AS builder
+FROM node:22-alpine AS builder
 
 # Add build arguments
 ARG CACHEBUST=1
@@ -16,19 +16,31 @@ WORKDIR /app
 # Copy package files
 COPY package*.json ./
 
-# Install dependencies
-RUN npm ci --only=production
+# Install dependencies (--omit=dev replaces deprecated --only=production)
+RUN npm ci --omit=dev
 
 # Copy application files
 COPY . .
 
 # Production stage
-FROM node:20-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 
-# Install dumb-init for proper signal handling and postgresql-client for database checks
-RUN apk add --no-cache dumb-init postgresql-client
+# Upgrade all packages to fix security vulnerabilities (OpenSSL, libexpat, BusyBox CVEs)
+RUN apk upgrade --no-cache
+
+# Upgrade npm to fix tar, minimatch, brace-expansion CVEs in npm's own deps
+# Pin to 10.x to stay compatible with Node 22 Alpine (npm 11.x has dependency issues)
+RUN npm install -g npm@10
+
+# Install dumb-init for proper signal handling, postgresql-client for database
+# checks, and ffmpeg for video upload support. Alpine's ffmpeg package ships
+# both `ffmpeg` and `ffprobe` built natively against musl libc — the npm
+# `@ffmpeg-installer/ffmpeg` binary is glibc-built and (a) doesn't reliably
+# run on Alpine and (b) only includes ffmpeg, not ffprobe (which the video
+# pipeline calls via fluent-ffmpeg.ffprobe()).
+RUN apk add --no-cache dumb-init postgresql-client ffmpeg
 
 # Create non-root user
 RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
@@ -37,8 +49,8 @@ RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
 COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
 COPY --chown=nodejs:nodejs . .
 
-# Make wait script executable
-RUN chmod +x wait-for-db.sh
+# Ensure all source files are readable and wait script is executable
+RUN chmod -R a+r /app && chmod +x wait-for-db.sh
 
 # Create necessary directories
 RUN mkdir -p storage/events/active storage/events/archived storage/thumbnails data logs && \

backend/Dockerfile.dev

@@ -1,9 +1,14 @@
-FROM node:18-alpine
+FROM node:20-alpine
 
 WORKDIR /app
 
-# Install dumb-init for proper signal handling
-RUN apk add --no-cache dumb-init
+# Upgrade all packages to fix security vulnerabilities (BusyBox CVEs)
+RUN apk upgrade --no-cache
+
+# Install dumb-init for proper signal handling and ffmpeg for video uploads.
+# Alpine's ffmpeg ships both ffmpeg + ffprobe built natively against musl;
+# the npm-bundled binary doesn't run reliably on Alpine. Match production.
+RUN apk add --no-cache dumb-init ffmpeg
 
 # Copy package files
 COPY package*.json ./

backend/__tests__/integration/backup-s3.test.js

@@ -7,12 +7,15 @@ const crypto = require('crypto');
 // Load services
 const backupService = require('../../src/services/backupService');
 const S3StorageAdapter = require('../../src/services/storage/s3Storage');
-const { db, initialize: initDb } = require('../../src/database/db');
+const { db, initializeDatabase: initDb } = require('../../src/database/db');
 const logger = require('../../src/utils/logger');
 
 // Test configuration
+// Defaults match the dev MinIO container in docker-compose.dev.yml (port 7104).
+// Override via TEST_S3_ENDPOINT / TEST_S3_ACCESS_KEY / TEST_S3_SECRET_KEY when running
+// against a different S3 endpoint (CI, hosted MinIO, real AWS, etc.).
 const TEST_CONFIG = {
-  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:9000',
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
   accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
   secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
   bucket: 'test-backup-bucket-' + Date.now(),
@@ -56,9 +59,17 @@ describe('S3 Backup Integration Tests', () => {
       }
     }
 
-    // Initialize database
-    await initDb();
-    await db.migrate.latest();
+    // Schema is expected to already be applied by `npm run migrate` against
+    // the dev database. db.migrate.latest() can't be used here because
+    // PicPeak's custom run-migrations.js tracks state in the `migrations`
+    // table (not knex's `knex_migrations`), so knex would try to re-apply
+    // every migration and crash on duplicate-table errors.
+    const ok = await db.schema.hasTable('events')
+      && await db.schema.hasTable('app_settings')
+      && await db.schema.hasTable('backup_runs');
+    if (!ok) {
+      throw new Error('Required tables missing — run `npm run migrate` against the dev DB first.');
+    }
 
     // Create test storage directory
     testStoragePath = path.join(__dirname, '../fixtures/test-storage');
@@ -69,10 +80,12 @@ describe('S3 Backup Integration Tests', () => {
     await setupTestData();
 
     // Mock logger to reduce noise
-    logger.info = jest.fn();
-    logger.debug = jest.fn();
-    logger.warn = jest.fn();
-    logger.error = jest.fn();
+    if (process.env.UNMOCK_LOGGER !== 'true') {
+      logger.info = jest.fn();
+      logger.debug = jest.fn();
+      logger.warn = jest.fn();
+      logger.error = jest.fn();
+    }
   });
 
   afterAll(async () => {
@@ -165,8 +178,9 @@ describe('S3 Backup Integration Tests', () => {
         .first();
 
       expect(backupRun.status).toBe('completed');
-      expect(backupRun.files_backed_up).toBeGreaterThan(0);
-      expect(backupRun.total_size_bytes).toBeGreaterThan(0);
+      // pg driver returns bigint columns as strings; coerce for the size assertion.
+      expect(Number(backupRun.files_backed_up)).toBeGreaterThan(0);
+      expect(Number(backupRun.total_size_bytes)).toBeGreaterThan(0);
 
       // Verify files in S3
       const s3Objects = await listS3Objects();
@@ -269,13 +283,16 @@ describe('S3 Backup Integration Tests', () => {
         .first();
 
       expect(secondRun.id).not.toBe(firstRun.id);
-      expect(secondRun.files_backed_up).toBe(1); // Only modified file
+      expect(Number(secondRun.files_backed_up)).toBe(1); // Only modified file
 
-      // Check manifest indicates incremental
+      // Check manifest indicates incremental. The current manifest schema
+      // groups counts under `incremental.changes.*` (added/modified/deleted/
+      // unchanged + size_difference) — see backupManifest.generateIncrementalManifest.
       if (secondRun.manifest_path) {
         const manifest = await backupService.getBackupManifest(secondRun.id);
         expect(manifest.manifest.incremental).toBeDefined();
-        expect(manifest.manifest.incremental.modified_files_count).toBe(1);
+        expect(manifest.manifest.incremental.changes).toBeDefined();
+        expect(manifest.manifest.incremental.changes.modified_files_count).toBe(1);
       }
     });
 
@@ -468,15 +485,16 @@ describe('S3 Backup Integration Tests', () => {
       { setting_key: 'backup_max_file_size_mb', setting_value: '100' }
     ];
 
+    // Schema drift: app_settings has no created_at column anymore and the
+    // unique constraint is on setting_key alone, not (setting_type, key).
     for (const setting of settings) {
       await db('app_settings')
         .insert({
           setting_type: 'backup',
           ...setting,
-          created_at: new Date(),
-          updated_at: new Date()
+          updated_at: new Date(),
         })
-        .onConflict(['setting_type', 'setting_key'])
+        .onConflict('setting_key')
         .merge();
     }
   }

backend/__tests__/integration/imageProcessor.storage.test.js

@@ -0,0 +1,165 @@
+const path = require('path');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const { S3Client, CreateBucketCommand, DeleteBucketCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+const sharp = require('sharp');
+
+const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../../src/services/storage/S3StorageBackend');
+const storageModule = require('../../src/services/storage');
+
+// Stub out the DB so getThumbnailSettings falls into its catch and uses defaults.
+jest.mock('../../src/database/db', () => ({
+  db: () => {
+    throw new Error('db disabled in this test');
+  },
+}));
+
+const TEST_S3 = {
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
+  accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
+  secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
+  region: 'us-east-1',
+};
+
+const skipS3 = process.env.SKIP_S3_TESTS === 'true';
+
+function backendCases() {
+  const cases = [
+    {
+      name: 'LocalFsStorage',
+      async setup() {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-imgproc-'));
+        const storage = new LocalFsStorage({ root });
+        await storage.init();
+        return { storage, cleanup: () => fs.rm(root, { recursive: true, force: true }) };
+      },
+    },
+  ];
+  if (!skipS3) {
+    cases.push({
+      name: 'S3StorageBackend (MinIO)',
+      async setup() {
+        const bucket = `picpeak-imgproc-${Date.now()}-${crypto.randomBytes(2).toString('hex')}`;
+        const s3Client = new S3Client({
+          endpoint: TEST_S3.endpoint,
+          region: TEST_S3.region,
+          credentials: { accessKeyId: TEST_S3.accessKeyId, secretAccessKey: TEST_S3.secretAccessKey },
+          forcePathStyle: true,
+        });
+        await s3Client.send(new CreateBucketCommand({ Bucket: bucket }));
+        const storage = new S3StorageBackend({
+          bucket,
+          region: TEST_S3.region,
+          endpoint: TEST_S3.endpoint,
+          accessKeyId: TEST_S3.accessKeyId,
+          secretAccessKey: TEST_S3.secretAccessKey,
+          forcePathStyle: true,
+          sslEnabled: false,
+        });
+        await storage.init();
+        return {
+          storage,
+          async cleanup() {
+            const list = await s3Client.send(new ListObjectsV2Command({ Bucket: bucket }));
+            if (list.Contents?.length) {
+              await s3Client.send(new DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: list.Contents.map((o) => ({ Key: o.Key })) },
+              }));
+            }
+            await s3Client.send(new DeleteBucketCommand({ Bucket: bucket }));
+          },
+        };
+      },
+    });
+  }
+  return cases;
+}
+
+async function makeSourceJpeg(targetDir, name) {
+  const localPath = path.join(targetDir, name);
+  // 800x600 random RGB image so sharp has something realistic to thumbnail.
+  const width = 800;
+  const height = 600;
+  const buf = Buffer.alloc(width * height * 3);
+  for (let i = 0; i < buf.length; i++) buf[i] = (i * 7) % 256;
+  await sharp(buf, { raw: { width, height, channels: 3 } })
+    .jpeg({ quality: 90 })
+    .toFile(localPath);
+  return localPath;
+}
+
+describe.each(backendCases())('imageProcessor through $name', ({ setup }) => {
+  let storage;
+  let cleanup;
+  let tmpDir;
+  let imageProcessor;
+
+  beforeAll(async () => {
+    ({ storage, cleanup } = await setup());
+    storageModule.setStorageForTesting(storage);
+    // Require AFTER setStorageForTesting so the module sees our injection.
+    delete require.cache[require.resolve('../../src/services/imageProcessor')];
+    imageProcessor = require('../../src/services/imageProcessor');
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-imgproc-src-'));
+  }, 30000);
+
+  afterAll(async () => {
+    storageModule.resetStorage();
+    if (tmpDir) await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    if (cleanup) await cleanup();
+  });
+
+  test('generateThumbnail writes through storage and returns a relative key', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'sample.jpg');
+    const key = await imageProcessor.generateThumbnail(src);
+    expect(key).toBe('thumbnails/thumb_sample.jpg');
+
+    expect(await storage.exists(key)).toBe(true);
+    const stat = await storage.stat(key);
+    expect(stat.size).toBeGreaterThan(100);
+
+    // Verify the bytes are a valid JPEG by re-parsing with sharp on local mode.
+    if (storage.kind() === 'local') {
+      const meta = await sharp(storage.resolveLocalPath(key)).metadata();
+      expect(meta.format).toBe('jpeg');
+      expect(meta.width).toBeLessThanOrEqual(300);
+    }
+  });
+
+  test('generateHeroImage writes through storage and returns a relative key', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'hero-source.jpg');
+    const key = await imageProcessor.generateHeroImage(src);
+    expect(key).toBe('heroes/hero_hero-source.jpg');
+    expect(await storage.exists(key)).toBe(true);
+  });
+
+  test('isThumbnailValid returns true for a good thumbnail and false for nothing', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'valid-check.jpg');
+    const key = await imageProcessor.generateThumbnail(src);
+    expect(await imageProcessor.isThumbnailValid(key)).toBe(true);
+    expect(await imageProcessor.isThumbnailValid('thumbnails/does-not-exist.jpg')).toBe(false);
+  });
+
+  test('generateVideoPlaceholder writes a thumbnail entirely from buffer', async () => {
+    const key = await imageProcessor.generateVideoPlaceholder('demo.mp4');
+    expect(key).toBe('thumbnails/thumb_demo.jpg');
+    expect(await storage.exists(key)).toBe(true);
+  });
+
+  test('withLocalCopy yields a usable local path on both backends', async () => {
+    const sourceKey = 'fixture/withlocal.jpg';
+    const src = await makeSourceJpeg(tmpDir, 'withlocal.jpg');
+    const buf = await fs.readFile(src);
+    await storage.put(sourceKey, buf, { contentType: 'image/jpeg' });
+
+    const seenSize = await imageProcessor.withLocalCopy(sourceKey, async (localPath) => {
+      const meta = await sharp(localPath).metadata();
+      return meta.width;
+    });
+    expect(seenSize).toBe(800);
+  });
+});

backend/__tests__/integration/storageBackend.test.js

@@ -0,0 +1,189 @@
+const path = require('path');
+const fs = require('fs');
+const fsp = require('fs').promises;
+const os = require('os');
+const crypto = require('crypto');
+const { Readable } = require('stream');
+const { S3Client, CreateBucketCommand, DeleteBucketCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+
+const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../../src/services/storage/S3StorageBackend');
+
+// MinIO defaults match docker-compose.dev.yml. Override via TEST_S3_* if needed.
+const TEST_S3 = {
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
+  accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
+  secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
+  region: 'us-east-1',
+};
+
+const skipS3 = process.env.SKIP_S3_TESTS === 'true';
+
+// Build the matrix of backends to test. Local always runs; S3 runs against MinIO
+// unless SKIP_S3_TESTS=true (CI default). The same suite runs against both so
+// every consumer can rely on identical semantics.
+function backendCases() {
+  const cases = [
+    {
+      name: 'LocalFsStorage',
+      async setup() {
+        const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'picpeak-storage-'));
+        const storage = new LocalFsStorage({ root });
+        await storage.init();
+        return { storage, cleanup: () => fsp.rm(root, { recursive: true, force: true }) };
+      },
+    },
+  ];
+
+  if (!skipS3) {
+    cases.push({
+      name: 'S3StorageBackend (MinIO)',
+      async setup() {
+        const bucket = `picpeak-test-${Date.now()}-${crypto.randomBytes(2).toString('hex')}`;
+        const s3Client = new S3Client({
+          endpoint: TEST_S3.endpoint,
+          region: TEST_S3.region,
+          credentials: { accessKeyId: TEST_S3.accessKeyId, secretAccessKey: TEST_S3.secretAccessKey },
+          forcePathStyle: true,
+        });
+        await s3Client.send(new CreateBucketCommand({ Bucket: bucket }));
+        const storage = new S3StorageBackend({
+          bucket,
+          region: TEST_S3.region,
+          endpoint: TEST_S3.endpoint,
+          accessKeyId: TEST_S3.accessKeyId,
+          secretAccessKey: TEST_S3.secretAccessKey,
+          forcePathStyle: true,
+          sslEnabled: false,
+        });
+        await storage.init();
+        return {
+          storage,
+          async cleanup() {
+            // Empty bucket then delete it.
+            const list = await s3Client.send(new ListObjectsV2Command({ Bucket: bucket }));
+            if (list.Contents?.length) {
+              await s3Client.send(new DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: list.Contents.map((o) => ({ Key: o.Key })) },
+              }));
+            }
+            await s3Client.send(new DeleteBucketCommand({ Bucket: bucket }));
+          },
+        };
+      },
+    });
+  }
+
+  return cases;
+}
+
+async function readToString(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+describe.each(backendCases())('StorageBackend contract: $name', ({ setup }) => {
+  let storage;
+  let cleanup;
+
+  beforeAll(async () => {
+    ({ storage, cleanup } = await setup());
+  }, 30000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  test('put + get + exists + stat + delete round-trip with a buffer body', async () => {
+    const key = 'photos/event-a/IMG_0001.jpg';
+    const body = Buffer.from('hello picpeak');
+
+    await storage.put(key, body, { contentType: 'image/jpeg' });
+
+    expect(await storage.exists(key)).toBe(true);
+
+    const stat = await storage.stat(key);
+    expect(stat).not.toBeNull();
+    expect(stat.size).toBe(body.length);
+
+    const stream = await storage.get(key);
+    const text = await readToString(stream);
+    expect(text).toBe('hello picpeak');
+
+    await storage.delete(key);
+    expect(await storage.exists(key)).toBe(false);
+    expect(await storage.stat(key)).toBeNull();
+  });
+
+  test('put accepts a Readable stream body', async () => {
+    const key = 'photos/event-b/streamed.bin';
+    const body = Readable.from(Buffer.from('streamed payload'));
+
+    await storage.put(key, body);
+
+    const got = await readToString(await storage.get(key));
+    expect(got).toBe('streamed payload');
+  });
+
+  test('putFromFile + getToFile round-trip', async () => {
+    const tmpIn = path.join(os.tmpdir(), `in-${Date.now()}.txt`);
+    const tmpOut = path.join(os.tmpdir(), `out-${Date.now()}.txt`);
+    await fsp.writeFile(tmpIn, 'file payload');
+
+    const key = 'thumbnails/thumb_x.jpg';
+    await storage.putFromFile(key, tmpIn, { contentType: 'image/jpeg' });
+
+    await storage.getToFile(key, tmpOut);
+    const text = await fsp.readFile(tmpOut, 'utf-8');
+    expect(text).toBe('file payload');
+
+    await fsp.unlink(tmpIn).catch(() => {});
+    await fsp.unlink(tmpOut).catch(() => {});
+  });
+
+  test('list returns entries under a prefix with size + key', async () => {
+    await storage.put('events/active/a/photo1.jpg', Buffer.from('a1'));
+    await storage.put('events/active/a/photo2.jpg', Buffer.from('a22'));
+    await storage.put('events/active/b/photo3.jpg', Buffer.from('b333'));
+
+    const entries = await storage.list('events/active/a');
+    const keys = entries.map((e) => e.key).sort();
+    expect(keys).toEqual(['events/active/a/photo1.jpg', 'events/active/a/photo2.jpg']);
+    const sizes = Object.fromEntries(entries.map((e) => [e.key, e.size]));
+    expect(sizes['events/active/a/photo1.jpg']).toBe(2);
+    expect(sizes['events/active/a/photo2.jpg']).toBe(3);
+  });
+
+  test('rename moves an object from src to dst (atomic on local; copy+delete on s3)', async () => {
+    await storage.put('uploads/temp.jpg', Buffer.from('rename-me'));
+    await storage.rename('uploads/temp.jpg', 'uploads/final.jpg');
+
+    expect(await storage.exists('uploads/temp.jpg')).toBe(false);
+    expect(await storage.exists('uploads/final.jpg')).toBe(true);
+    const text = await readToString(await storage.get('uploads/final.jpg'));
+    expect(text).toBe('rename-me');
+  });
+
+  test('copy duplicates an object without removing the source', async () => {
+    await storage.put('events/source.jpg', Buffer.from('src'));
+    await storage.copy('events/source.jpg', 'events/copied.jpg');
+
+    expect(await storage.exists('events/source.jpg')).toBe(true);
+    expect(await storage.exists('events/copied.jpg')).toBe(true);
+  });
+
+  test('delete on a missing key is a no-op (does not throw)', async () => {
+    await expect(storage.delete('does/not/exist.jpg')).resolves.toBeUndefined();
+  });
+
+  test('stat on a missing key returns null', async () => {
+    expect(await storage.stat('still/not/here.jpg')).toBeNull();
+  });
+
+  test('rejects path traversal attempts', async () => {
+    await expect(storage.put('../escape.txt', Buffer.from('x'))).rejects.toThrow(/traversal/i);
+    await expect(storage.get('../escape.txt')).rejects.toThrow(/traversal/i);
+  });
+});

backend/__tests__/integration/webhookDelivery.test.js

@@ -0,0 +1,239 @@
+// Worker reads WEBHOOK_ALLOW_PRIVATE_URLS at module-load. Set it BEFORE
+// requiring the worker so the local-stub URLs (127.0.0.1:<random>) pass
+// the SSRF check by default.
+process.env.WEBHOOK_ALLOW_PRIVATE_URLS = 'true';
+process.env.WEBHOOK_DELIVERY_INTERVAL_MS = '50';
+
+const http = require('http');
+const { db } = require('../../src/database/db');
+const webhookService = require('../../src/services/webhookService');
+const { __test, startWebhookDeliveryWorker, stopWebhookDeliveryWorker } = require('../../src/services/webhookDeliveryWorker');
+
+// Local-only test stub: matches what dev/webhook-receiver/server.js does
+// in the docker-compose flow but spun up inside the Jest process so the
+// suite is self-contained.
+function makeStub({ status = 200, delayMs = 0, bodyOverride = null } = {}) {
+  const requests = [];
+  const server = http.createServer(async (req, res) => {
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    const body = Buffer.concat(chunks).toString('utf8');
+    requests.push({ method: req.method, url: req.url, headers: req.headers, body });
+    if (delayMs) await new Promise((r) => setTimeout(r, delayMs));
+    res.writeHead(status, { 'Content-Type': 'text/plain' });
+    res.end(bodyOverride !== null ? bodyOverride : (status >= 200 && status < 300 ? 'ok' : 'forced'));
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      resolve({ url: `http://127.0.0.1:${port}/`, requests, close: () => new Promise((r) => server.close(r)) });
+    });
+  });
+}
+
+async function insertWebhook(url, events = ['event.published'], extras = {}) {
+  // Tests need the WORKER to bypass SSRF on 127.0.0.1 stubs, but the
+  // route layer's allowlist check is bypassed here since we insert
+  // straight into the DB.
+  const { plaintext, preview } = webhookService.generateSecret();
+  const insert = await db('webhooks').insert({
+    name: extras.name || 'test',
+    url,
+    secret: plaintext,
+    secret_preview: preview,
+    events: JSON.stringify(events),
+    active: extras.active !== false,
+    created_by: 1,
+  }).returning('id');
+  const id = insert[0]?.id || insert[0];
+  return { id, secret: plaintext };
+}
+
+async function clearWebhooks() {
+  await db('webhook_deliveries').del();
+  await db('webhooks').del();
+}
+
+describe('webhook delivery worker (#327)', () => {
+  beforeAll(async () => {
+    // Schema is expected to already be applied by `npm run migrate`. We
+    // just verify the webhooks tables exist; if not, the test harness has
+    // missed running migration 082.
+    const ok = await db.schema.hasTable('webhooks');
+    if (!ok) throw new Error('webhooks table missing — run `npm run migrate` first');
+  }, 30000);
+
+  afterAll(async () => {
+    stopWebhookDeliveryWorker();
+    await db.destroy();
+  });
+
+  beforeEach(async () => {
+    await clearWebhooks();
+  });
+
+  test('signs the body with HMAC-SHA256 and the receiver can verify', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      const { id, secret } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: { id: 1, slug: 'sig-test' } });
+      await __test.tick();
+
+      expect(stub.requests).toHaveLength(1);
+      const got = stub.requests[0];
+      const sig = got.headers['x-picpeak-signature'];
+      expect(sig).toBeTruthy();
+      // Receiver-side verification using the SAME helper we ship in the README.
+      expect(webhookService.verifySignature(secret, got.body, sig)).toBe(true);
+      // Tampering must fail.
+      expect(webhookService.verifySignature(secret, got.body + 'x', sig)).toBe(false);
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('success');
+      expect(row.attempt_count).toBe(1);
+      expect(row.response_status).toBe(200);
+      expect(row.latency_ms).toBeGreaterThanOrEqual(0);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('headers include event type and a unique delivery id', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      await insertWebhook(stub.url, ['photo.uploaded']);
+      await webhookService.fire('photo.uploaded', { photo: { id: 7 } });
+      await __test.tick();
+
+      const got = stub.requests[0];
+      expect(got.headers['x-picpeak-event']).toBe('photo.uploaded');
+      expect(got.headers['x-picpeak-delivery']).toBeTruthy();
+      expect(got.headers['user-agent']).toMatch(/PicPeak-Webhooks/);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('on 5xx, schedules a retry with exponential backoff and stays pending', async () => {
+    const stub = await makeStub({ status: 500 });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: { id: 2 } });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('pending');
+      expect(row.attempt_count).toBe(1);
+      expect(row.response_status).toBe(500);
+      // BACKOFF_MS[0] = 60s; next_retry_at should be ~60s in the future.
+      const dueIn = new Date(row.next_retry_at).getTime() - Date.now();
+      expect(dueIn).toBeGreaterThan(50_000);
+      expect(dueIn).toBeLessThan(70_000);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('after MAX_ATTEMPTS failures, status flips to failed and the row is closed', async () => {
+    const stub = await makeStub({ status: 500 });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      // Pre-seed a delivery already at attempt_count = 4 so a single tick
+      // takes it to 5 → failed (avoids waiting through backoffs).
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 4,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.attempt_count).toBe(5);
+      expect(row.completed_at).toBeTruthy();
+      expect(row.next_retry_at).toBeNull();
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('truncates response body to 1KB before storing', async () => {
+    const big = 'x'.repeat(5000);
+    const stub = await makeStub({ status: 200, bodyOverride: big });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: {} });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('success');
+      expect(Buffer.byteLength(row.response_body || '', 'utf8')).toBeLessThanOrEqual(1024);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('does not deliver to disabled webhooks (post-mortem state captured)', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      const { id } = await insertWebhook(stub.url, ['event.published'], { active: false });
+      // fire enqueues regardless of active state at fire-time, but we
+      // disabled BEFORE firing so nothing is enqueued. Direct insert to
+      // exercise the worker's mid-flight disable check:
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      expect(stub.requests).toHaveLength(0);
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.last_error).toMatch(/disabled/i);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('rejects loopback URLs when WEBHOOK_ALLOW_PRIVATE_URLS=false', async () => {
+    __test.setAllowPrivateUrls(false);
+    try {
+      const { id } = await insertWebhook('http://127.0.0.1:9/');
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.last_error).toMatch(/private|internal/i);
+    } finally {
+      __test.setAllowPrivateUrls(true);
+    }
+  });
+
+  test('worker can be started + stopped without leaking timers', async () => {
+    startWebhookDeliveryWorker();
+    startWebhookDeliveryWorker(); // idempotent
+    stopWebhookDeliveryWorker();
+    stopWebhookDeliveryWorker(); // idempotent
+    // If timers leaked the test runner would warn after force-exit; assertion
+    // is just "no throw".
+    expect(true).toBe(true);
+  });
+});

backend/__tests__/routes/authSession.symmetry.test.js

@@ -0,0 +1,302 @@
+/**
+ * Regression test for the /admin/login → /admin/dashboard → /admin/login
+ * redirect loop reported on v3.32.4-beta.0.
+ *
+ * Cause: GET /auth/session was less strict than the adminAuth middleware.
+ * The session endpoint accepted tokens that the protected endpoints
+ * subsequently rejected with 401, which the frontend's interceptor
+ * translated into a hard redirect to /admin/login. /auth/session then
+ * said "valid: true" again on the next page load and the cycle closed.
+ *
+ * /auth/session must reject the same admin tokens adminAuth would
+ * reject, specifically: deactivated admin user, deleted admin user,
+ * password changed since iat. Same for gallery: archived event.
+ */
+
+const express = require('express');
+const request = require('supertest');
+const jwt = require('jsonwebtoken');
+
+process.env.JWT_SECRET = 'session-symmetry-test-secret';
+
+const fakeDb = {
+  adminUsers: [],
+  events: [],
+  revokedTokens: [],
+};
+
+jest.mock('../../src/database/db', () => {
+  const formatBoolean = (v) => (v ? 1 : 0);
+  void formatBoolean;
+  function dbFn(table) {
+    if (table === 'admin_users') {
+      let rowFilter = () => true;
+      return {
+        where(criteria) {
+          rowFilter = (row) => {
+            return Object.entries(criteria).every(([k, v]) => {
+              if (k === 'is_active') return Boolean(row.is_active) === Boolean(v);
+              return row[k] === v;
+            });
+          };
+          return this;
+        },
+        select(...cols) {
+          this._cols = cols;
+          return this;
+        },
+        async first() {
+          const row = fakeDb.adminUsers.find(rowFilter);
+          if (!row) return undefined;
+          if (!this._cols) return row;
+          const out = {};
+          for (const c of this._cols) out[c] = row[c];
+          return out;
+        },
+      };
+    }
+    if (table === 'events') {
+      let rowFilter = () => true;
+      return {
+        where(criteria) {
+          rowFilter = (row) =>
+            Object.entries(criteria).every(([k, v]) => {
+              if (k === 'is_active') return Boolean(row.is_active) === Boolean(v);
+              if (k === 'is_archived') return Boolean(row.is_archived) === Boolean(v);
+              return row[k] === v;
+            });
+          return this;
+        },
+        async first() {
+          return fakeDb.events.find(rowFilter);
+        },
+      };
+    }
+    throw new Error(`Unexpected table: ${table}`);
+  }
+  return { db: dbFn, formatBoolean: () => 1 };
+});
+
+jest.mock('../../src/utils/dbCompat', () => ({
+  formatBoolean: (v) => (v ? 1 : 0),
+}));
+
+jest.mock('../../src/utils/tokenRevocation', () => ({
+  isTokenRevoked: jest.fn(async (decoded) => fakeDb.revokedTokens.includes(decoded.id)),
+  revokeToken: jest.fn(),
+}));
+
+jest.mock('../../src/utils/tokenUtils', () => ({
+  getAdminTokenFromRequest: (req) => {
+    const auth = req.headers.authorization;
+    if (auth && auth.startsWith('Bearer ')) return auth.slice(7);
+    return null;
+  },
+  getGalleryTokenFromRequest: () => null,
+  setAdminAuthCookie: jest.fn(),
+  setGalleryAuthCookies: jest.fn(),
+  clearAdminAuthCookie: jest.fn(),
+  clearGalleryAuthCookies: jest.fn(),
+  buildCookieOptionsWithExpiry: () => ({}),
+}));
+
+jest.mock('../../src/services/recaptcha', () => ({ verifyRecaptcha: () => Promise.resolve(true) }));
+jest.mock('../../src/middleware/sessionTimeout', () => ({ endSession: jest.fn() }));
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn(),
+}));
+
+const authRouter = require('../../src/routes/auth');
+
+function makeApp() {
+  const app = express();
+  app.use(express.json());
+  app.use('/auth', authRouter);
+  return app;
+}
+
+function signAdminToken({ id = 1, username = 'admin', iat, exp }) {
+  const issuedAt = iat ?? Math.floor(Date.now() / 1000);
+  // Note: do NOT pass noTimestamp:true here — that strips iat from the
+  // payload entirely, defeating the password-change comparison. Provide
+  // iat (and exp) via the payload directly instead.
+  return jwt.sign(
+    { id, username, type: 'admin', iat: issuedAt, exp: exp ?? issuedAt + 3600 },
+    process.env.JWT_SECRET,
+    { issuer: 'picpeak-auth' }
+  );
+}
+
+function signGalleryToken({ eventId = 100, eventSlug = 'wedding' } = {}) {
+  return jwt.sign(
+    { eventId, eventSlug, type: 'gallery' },
+    process.env.JWT_SECRET,
+    { expiresIn: '1h', issuer: 'picpeak-auth' }
+  );
+}
+
+describe('GET /auth/session — symmetry with protected middleware', () => {
+  beforeEach(() => {
+    fakeDb.adminUsers = [];
+    fakeDb.events = [];
+    fakeDb.revokedTokens = [];
+  });
+
+  it('returns valid:true for an active admin token', async () => {
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: true,
+      password_changed_at: null,
+    });
+    const token = signAdminToken({ id: 1 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(true);
+    expect(res.body.type).toBe('admin');
+  });
+
+  it('returns valid:false when the admin user has been deactivated', async () => {
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: false,
+      password_changed_at: null,
+    });
+    const token = signAdminToken({ id: 1 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:false when the admin user no longer exists', async () => {
+    // adminUsers is empty
+    const token = signAdminToken({ id: 999 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:false when password was changed after the token was issued', async () => {
+    // iat must be in the past, exp must be in the future so jwt.verify
+    // doesn't reject the token before /auth/session even gets to look
+    // at password_changed_at.
+    const tokenIssuedAt = Math.floor(Date.now() / 1000) - 60; // 1 min ago
+    const tokenExp = tokenIssuedAt + 86400;
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: true,
+      password_changed_at: new Date((tokenIssuedAt + 30) * 1000), // 30s after iat
+    });
+    const token = signAdminToken({ id: 1, iat: tokenIssuedAt, exp: tokenExp });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:true when password was changed BEFORE the token was issued', async () => {
+    const tokenIssuedAt = Math.floor(Date.now() / 1000) - 60;
+    const tokenExp = tokenIssuedAt + 86400;
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: true,
+      password_changed_at: new Date((tokenIssuedAt - 3600) * 1000), // 1h before iat
+    });
+    const token = signAdminToken({ id: 1, iat: tokenIssuedAt, exp: tokenExp });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(true);
+  });
+
+  it('returns valid:false for a gallery token whose event is archived', async () => {
+    fakeDb.events.push({
+      id: 100,
+      slug: 'wedding',
+      is_active: true,
+      is_archived: true,
+      expires_at: null,
+    });
+    const token = signGalleryToken();
+
+    const res = await request(makeApp())
+      .get('/auth/session?slug=wedding')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:false for a gallery token whose event is expired', async () => {
+    fakeDb.events.push({
+      id: 100,
+      slug: 'wedding',
+      is_active: true,
+      is_archived: false,
+      expires_at: new Date(Date.now() - 86400_000),
+    });
+    const token = signGalleryToken();
+
+    const res = await request(makeApp())
+      .get('/auth/session?slug=wedding')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:true for an active gallery token', async () => {
+    fakeDb.events.push({
+      id: 100,
+      slug: 'wedding',
+      is_active: true,
+      is_archived: false,
+      expires_at: new Date(Date.now() + 86400_000),
+    });
+    const token = signGalleryToken();
+
+    const res = await request(makeApp())
+      .get('/auth/session?slug=wedding')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(true);
+  });
+
+  it('returns valid:false when the token is revoked', async () => {
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      is_active: true,
+      password_changed_at: null,
+    });
+    fakeDb.revokedTokens.push(1);
+    const token = signAdminToken({ id: 1 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(401);
+    expect(res.body.valid).toBe(false);
+  });
+});

backend/__tests__/services/backgroundProcessor.test.js

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for backgroundProcessor.claimNextPhoto.
+ *
+ * Mocks the db so we don't need a live postgres/sqlite — focuses on
+ * the claim contract: returns null when no rows, returns row + flips
+ * status to 'processing' when one is available, returns null when a
+ * race loses the UPDATE-with-guard.
+ */
+
+jest.mock('../../src/services/photoProcessor', () => ({
+  processPhoto: jest.fn(),
+  processUploadedPhotos: jest.fn(),
+  queueFilesForProcessing: jest.fn(),
+}));
+
+// Build a fake knex instance whose .transaction() takes a callback we can
+// drive from the test, and whose query-builder records calls.
+function makeFakeDb({ pendingRow = null, updateResult = 1, clientName = 'pg' } = {}) {
+  const queries = [];
+
+  const builder = () => {
+    const recorded = { wheres: [], updates: null, ordered: false, locked: false, skipped: false };
+    queries.push(recorded);
+    const chain = {
+      where: jest.fn(function (...args) {
+        recorded.wheres.push(args);
+        return chain;
+      }),
+      orderBy: jest.fn(function () {
+        recorded.ordered = true;
+        return chain;
+      }),
+      forUpdate: jest.fn(function () {
+        recorded.locked = true;
+        return chain;
+      }),
+      skipLocked: jest.fn(function () {
+        recorded.skipped = true;
+        return chain;
+      }),
+      first: jest.fn(async function () {
+        // Only the SELECT chain returns the pending row; the UPDATE chain
+        // never calls .first().
+        return pendingRow ? { ...pendingRow } : null;
+      }),
+      update: jest.fn(async function (data) {
+        recorded.updates = data;
+        return updateResult;
+      }),
+    };
+    return chain;
+  };
+
+  const trxFn = (table) => builder(table);
+  trxFn.client = { config: { client: clientName } };
+  trxFn.transaction = async (cb) => cb(trxFn);
+
+  // Top-level db('photos') returns same builder for the janitor test path.
+  const db = trxFn;
+  return { db, queries };
+}
+
+describe('backgroundProcessor.claimNextPhoto', () => {
+  function loadProcessor(db) {
+    jest.resetModules();
+    jest.doMock('../../src/database/db', () => ({ db }));
+    return require('../../src/services/backgroundProcessor');
+  }
+
+  it('returns null when there are no pending photos (postgres path)', async () => {
+    const { db } = makeFakeDb({ pendingRow: null, clientName: 'pg' });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toBeNull();
+  });
+
+  it('returns the claimed row and flips status (postgres path)', async () => {
+    const pendingRow = { id: 42, processing_status: 'pending' };
+    const { db, queries } = makeFakeDb({ pendingRow, clientName: 'pg' });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toEqual(pendingRow);
+    // The first query is the SELECT FOR UPDATE SKIP LOCKED.
+    expect(queries[0].locked).toBe(true);
+    expect(queries[0].skipped).toBe(true);
+    // The second query is the status update.
+    expect(queries[1].updates.processing_status).toBe('processing');
+    expect(queries[1].updates.processing_started_at).toBeInstanceOf(Date);
+  });
+
+  it('returns null when the SQLite UPDATE-with-guard loses the race', async () => {
+    const pendingRow = { id: 7 };
+    const { db } = makeFakeDb({ pendingRow, clientName: 'better-sqlite3', updateResult: 0 });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toBeNull();
+  });
+
+  it('returns the row when SQLite UPDATE-with-guard wins', async () => {
+    const pendingRow = { id: 7 };
+    const { db, queries } = makeFakeDb({ pendingRow, clientName: 'better-sqlite3', updateResult: 1 });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toEqual(pendingRow);
+    // SQLite path: no FOR UPDATE / SKIP LOCKED.
+    expect(queries[0].locked).toBe(false);
+    expect(queries[0].skipped).toBe(false);
+  });
+});

backend/__tests__/services/emailProcessor.htmlToText.test.js

@@ -0,0 +1,75 @@
+/**
+ * Unit tests for emailProcessor.htmlToText.
+ *
+ * Regression: when a template ships without a body_text, sendTemplateEmail
+ * used `htmlBody.replace(/<[^>]*>/g, '')` to derive the plain-text fallback.
+ * That regex strips angle-bracket tags but leaves the *contents* of <style>
+ * and <script> blocks intact — so any HTML wrapped by wrapEmailHtml() (which
+ * embeds a 100+ line <style> block) produced a "plain-text" email starting
+ * with `body { margin: 0; padding: 0; … }`. htmlToText fixes that.
+ */
+
+jest.mock('../../src/database/db', () => ({ db: jest.fn() }));
+
+const { htmlToText } = require('../../src/services/emailProcessor');
+
+describe('htmlToText', () => {
+  it('returns empty string for empty input', () => {
+    expect(htmlToText('')).toBe('');
+    expect(htmlToText(null)).toBe('');
+    expect(htmlToText(undefined)).toBe('');
+  });
+
+  it('strips <style> blocks and their contents', () => {
+    const html = '<html><head><style>body { margin: 0; color: red; }</style></head><body>Hello</body></html>';
+    const out = htmlToText(html);
+    expect(out).toBe('Hello');
+    expect(out).not.toMatch(/margin/);
+    expect(out).not.toMatch(/color/);
+  });
+
+  it('strips <script> blocks and their contents', () => {
+    const html = '<body><script>alert("x")</script>Hi</body>';
+    expect(htmlToText(html)).toBe('Hi');
+  });
+
+  it('converts <br> tags to newlines', () => {
+    expect(htmlToText('a<br>b<br />c<BR/>d')).toBe('a\nb\nc\nd');
+  });
+
+  it('keeps a paragraph break between adjacent <p> tags', () => {
+    expect(htmlToText('<p>one</p><p>two</p>')).toBe('one\n\ntwo');
+  });
+
+  it('decodes the common HTML entities', () => {
+    expect(htmlToText('Tom &amp; Jerry &lt;3 &quot;hi&quot;'))
+      .toBe('Tom & Jerry <3 "hi"');
+  });
+
+  it('handles a fully-wrapped email body without leaking CSS rules', () => {
+    // Shape mirrors what wrapEmailHtml() produces: a <style> block with many
+    // CSS rules followed by the actual content.
+    const wrapped = `
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    body { margin: 0; padding: 0; font-family: sans-serif; background-color: #f5f5f5; }
+    .email-container { max-width: 600px; }
+    .button { background-color: #5C8762; color: white !important; }
+  </style>
+</head>
+<body>
+  <h2>Galerie erfolgreich erstellt</h2>
+  <p>Liebe(r) Natalie,</p>
+</body>
+</html>`;
+    const out = htmlToText(wrapped);
+    expect(out).toContain('Galerie erfolgreich erstellt');
+    expect(out).toContain('Liebe(r) Natalie');
+    expect(out).not.toMatch(/margin/);
+    expect(out).not.toMatch(/font-family/);
+    expect(out).not.toMatch(/background-color/);
+    expect(out).not.toMatch(/\.button/);
+  });
+});

backend/__tests__/services/emailProcessor.safeTemplateReplace.test.js

@@ -0,0 +1,138 @@
+/**
+ * Unit tests for emailProcessor.safeTemplateReplace.
+ *
+ * Covers the two regressions that hit picpeak.nothaft.cloud on the
+ * 3.32.x betas:
+ *   - {{#if VAR}}…{{/if}} blocks rendered as literal text in the email
+ *     because the renderer only handled {{var}} substitution and the
+ *     shipped templates use Handlebars-style conditionals.
+ *   - {{var}} substitution inside a kept conditional block.
+ *
+ * The publish-from-draft password localisation lives inside the wider
+ * processTemplate() pipeline (DB-backed), so it isn't covered here — the
+ * sentinel string '(set at creation)' is asserted only at the i18n-map
+ * level by integration in adminEvents.js.
+ */
+
+jest.mock('../../src/database/db', () => ({ db: jest.fn() }));
+
+const { safeTemplateReplace } = require('../../src/services/emailProcessor');
+
+describe('safeTemplateReplace', () => {
+  describe('flat variable substitution', () => {
+    it('replaces {{var}} with the variable value', () => {
+      expect(safeTemplateReplace('Hello {{name}}!', { name: 'Paul' }))
+        .toBe('Hello Paul!');
+    });
+
+    it('leaves unknown variables untouched', () => {
+      expect(safeTemplateReplace('Hello {{name}}!', {}))
+        .toBe('Hello {{name}}!');
+    });
+
+    it('coerces non-string values to string', () => {
+      expect(safeTemplateReplace('Count: {{n}}', { n: 42 }))
+        .toBe('Count: 42');
+    });
+
+    it('handles empty templates and missing variables map', () => {
+      expect(safeTemplateReplace('', { x: 1 })).toBe('');
+      expect(safeTemplateReplace('plain text', undefined)).toBe('plain text');
+      expect(safeTemplateReplace(null, {})).toBe(null);
+    });
+  });
+
+  describe('{{#if VAR}}…{{/if}} blocks', () => {
+    it('strips the block when the variable is missing', () => {
+      const tpl = 'before {{#if welcome}}HELLO {{welcome}}{{/if}} after';
+      expect(safeTemplateReplace(tpl, {})).toBe('before  after');
+    });
+
+    it('strips the block when the variable is an empty string', () => {
+      const tpl = 'before {{#if welcome}}HELLO {{welcome}}{{/if}} after';
+      expect(safeTemplateReplace(tpl, { welcome: '' })).toBe('before  after');
+    });
+
+    it('strips the block when the variable is null', () => {
+      const tpl = '{{#if x}}kept{{/if}}';
+      expect(safeTemplateReplace(tpl, { x: null })).toBe('');
+    });
+
+    it('keeps the block and substitutes inside it when truthy', () => {
+      const tpl = 'before {{#if welcome}}HELLO {{welcome}}{{/if}} after';
+      expect(safeTemplateReplace(tpl, { welcome: 'world' }))
+        .toBe('before HELLO world after');
+    });
+
+    it('handles multi-line conditional blocks', () => {
+      const tpl = [
+        'Liebe(r) {{host_name}},',
+        '',
+        '{{#if welcome_message}}',
+        'Persönliche Nachricht:',
+        '{{welcome_message}}',
+        '{{/if}}',
+        'Galerie-Details:',
+      ].join('\n');
+
+      const withMsg = safeTemplateReplace(tpl, {
+        host_name: 'Natalie',
+        welcome_message: 'Schön, dass ihr da seid!',
+      });
+      expect(withMsg).toContain('Persönliche Nachricht:');
+      expect(withMsg).toContain('Schön, dass ihr da seid!');
+      expect(withMsg).not.toContain('{{#if');
+      expect(withMsg).not.toContain('{{/if');
+
+      const withoutMsg = safeTemplateReplace(tpl, {
+        host_name: 'Natalie',
+        welcome_message: '',
+      });
+      expect(withoutMsg).not.toContain('Persönliche Nachricht');
+      expect(withoutMsg).not.toContain('{{#if');
+      expect(withoutMsg).not.toContain('{{/if');
+      expect(withoutMsg).toContain('Liebe(r) Natalie,');
+      expect(withoutMsg).toContain('Galerie-Details:');
+    });
+
+    it('handles multiple sibling conditionals independently', () => {
+      const tpl = '{{#if a}}A{{/if}}|{{#if b}}B{{/if}}|{{#if c}}C{{/if}}';
+      expect(safeTemplateReplace(tpl, { a: 1, c: 'yes' })).toBe('A||C');
+    });
+
+    it('treats numeric 0 as falsy', () => {
+      expect(safeTemplateReplace('{{#if n}}has-n{{/if}}', { n: 0 })).toBe('');
+    });
+  });
+
+  describe('HTML escaping (escapeHtml: true)', () => {
+    it('does not escape by default', () => {
+      const tpl = 'Welcome to {{event_name}}';
+      expect(safeTemplateReplace(tpl, { event_name: 'Test <script>' }))
+        .toBe('Welcome to Test <script>');
+    });
+
+    it('escapes admin-supplied values when opted in', () => {
+      const tpl = 'Welcome to {{event_name}}';
+      expect(safeTemplateReplace(tpl, { event_name: 'Test <script>alert(1)</script>' }, { escapeHtml: true }))
+        .toBe('Welcome to Test &lt;script&gt;alert(1)&lt;/script&gt;');
+    });
+
+    it('escapes both the < > and & characters and quotes', () => {
+      expect(safeTemplateReplace('{{x}}', { x: '<a href="evil">A & B\'s</a>' }, { escapeHtml: true }))
+        .toBe('&lt;a href=&quot;evil&quot;&gt;A &amp; B&#39;s&lt;/a&gt;');
+    });
+
+    it('passes welcome_message through unescaped (already HTML from formatWelcomeMessage)', () => {
+      const tpl = '<p>{{welcome_message}}</p>';
+      expect(safeTemplateReplace(tpl, { welcome_message: 'Hi<br />there' }, { escapeHtml: true }))
+        .toBe('<p>Hi<br />there</p>');
+    });
+
+    it('passes server-generated URLs through unescaped', () => {
+      const tpl = '<a href="{{gallery_link}}">link</a>';
+      expect(safeTemplateReplace(tpl, { gallery_link: 'https://example.com/g/abc?token=xyz&u=1' }, { escapeHtml: true }))
+        .toBe('<a href="https://example.com/g/abc?token=xyz&u=1">link</a>');
+    });
+  });
+});

backend/__tests__/services/photoProcessor.processPhoto.test.js

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for photoProcessor.processPhoto — the worker-mode entry
+ * point that runs after a row has been claimed by the background
+ * processor. Mocks every external dependency and validates the
+ * happy-path DB updates and side-effect ordering.
+ *
+ * jest.mock factories are evaluated before any local variables exist,
+ * so collaborators are kept inside the mock factories themselves and
+ * the test reaches into them via require() once they're set up.
+ */
+
+const path = require('path');
+
+jest.mock('../../src/database/db', () => {
+  const recorded = { whereCalls: [], updateCalls: [] };
+  let pendingWhere = null;
+  const photosState = { row: null };
+  const eventsState = { row: null };
+
+  function makePhotoQuery() {
+    return {
+      where(args) {
+        pendingWhere = args;
+        recorded.whereCalls.push(args);
+        return this;
+      },
+      async first() {
+        return photosState.row;
+      },
+      async update(data) {
+        recorded.updateCalls.push({ where: pendingWhere, data });
+        return 1;
+      },
+    };
+  }
+
+  function makeEventsQuery() {
+    return {
+      where() {
+        return this;
+      },
+      async first() {
+        return eventsState.row;
+      },
+    };
+  }
+
+  function dbFn(table) {
+    if (table === 'photos') return makePhotoQuery();
+    if (table === 'events') return makeEventsQuery();
+    throw new Error(`Unexpected table: ${table}`);
+  }
+  dbFn.client = { config: { client: 'pg' } };
+
+  return {
+    db: dbFn,
+    __setPhoto: (row) => { photosState.row = row; },
+    __setEvent: (row) => { eventsState.row = row; },
+    __reset: () => {
+      recorded.whereCalls = [];
+      recorded.updateCalls = [];
+      photosState.row = null;
+      eventsState.row = null;
+    },
+    __recorded: () => recorded,
+  };
+});
+
+jest.mock('../../src/services/imageProcessor', () => {
+  const mockGenerateThumbnail = jest.fn();
+  const mockExtractCaptureDate = jest.fn();
+  return {
+    generateThumbnail: mockGenerateThumbnail,
+    extractCaptureDate: mockExtractCaptureDate,
+    withLocalCopy: jest.fn(async (key, fn) =>
+      fn(`/tmp/local-copy-${require('path').basename(key)}`)
+    ),
+  };
+});
+
+jest.mock('../../src/services/videoProcessor', () => ({
+  processUploadedVideo: jest.fn(),
+  isVideoMimeType: (mime) => typeof mime === 'string' && mime.startsWith('video/'),
+}));
+
+jest.mock('../../src/services/storage', () => ({ getStorage: jest.fn() }));
+
+jest.mock('../../src/services/photoResolver', () => ({
+  resolvePhotoStorageKey: jest.fn(
+    (event, photo) => `events/active/${event.slug}/${photo.filename}`
+  ),
+}));
+
+jest.mock('../../src/utils/filenameSanitizer', () => ({
+  generatePhotoFilename: jest.fn(() => 'whatever.jpg'),
+}));
+
+jest.mock('../../src/services/watermarkGeneratorService', () => ({
+  generateForPhoto: jest.fn(() => Promise.resolve()),
+}));
+
+jest.mock('../../src/services/webhookService', () => ({
+  fire: jest.fn(() => Promise.resolve()),
+}));
+
+jest.mock('../../src/utils/logger', () => ({
+  warn: jest.fn(),
+  error: jest.fn(),
+  info: jest.fn(),
+  debug: jest.fn(),
+}));
+
+// Stub sharp so we don't actually read any image off disk.
+jest.mock('sharp', () => {
+  const mock = jest.fn(() => ({
+    metadata: jest.fn(async () => ({ width: 1920, height: 1080 })),
+  }));
+  return mock;
+});
+
+const dbModule = require('../../src/database/db');
+const imageProcessor = require('../../src/services/imageProcessor');
+const videoProcessor = require('../../src/services/videoProcessor');
+const watermarkService = require('../../src/services/watermarkGeneratorService');
+const webhookService = require('../../src/services/webhookService');
+
+beforeEach(() => {
+  dbModule.__reset();
+  jest.clearAllMocks();
+});
+
+describe('photoProcessor.processPhoto', () => {
+  it('marks an image complete with thumbnail and dimensions', async () => {
+    dbModule.__setPhoto({
+      id: 101,
+      event_id: 5,
+      filename: 'wedding-001.jpg',
+      original_filename: 'IMG_0001.jpg',
+      mime_type: 'image/jpeg',
+      media_type: 'image',
+      size_bytes: 12345,
+      captured_at: null,
+      processing_status: 'processing',
+    });
+    dbModule.__setEvent({ id: 5, slug: 'wedding', event_name: 'Wedding' });
+
+    imageProcessor.extractCaptureDate.mockResolvedValueOnce('2026-04-25T12:00:00Z');
+    imageProcessor.generateThumbnail.mockResolvedValueOnce('thumbnails/thumb_wedding-001.jpg');
+
+    const { processPhoto } = require('../../src/services/photoProcessor');
+    await processPhoto(101);
+
+    const finalUpdate = dbModule.__recorded().updateCalls.pop();
+    expect(finalUpdate.data.processing_status).toBe('complete');
+    expect(finalUpdate.data.processing_error).toBeNull();
+    expect(finalUpdate.data.thumbnail_path).toBe('thumbnails/thumb_wedding-001.jpg');
+    expect(finalUpdate.data.width).toBe(1920);
+    expect(finalUpdate.data.height).toBe(1080);
+    expect(finalUpdate.data.captured_at).toBe('2026-04-25T12:00:00Z');
+
+    expect(watermarkService.generateForPhoto).toHaveBeenCalledWith(101);
+    expect(webhookService.fire).toHaveBeenCalledWith(
+      'photo.uploaded',
+      expect.objectContaining({
+        event: expect.objectContaining({ slug: 'wedding' }),
+        photo: expect.objectContaining({ id: 101, filename: 'wedding-001.jpg' }),
+      })
+    );
+  });
+
+  it('handles videos with ffmpeg metadata path', async () => {
+    dbModule.__setPhoto({
+      id: 202,
+      event_id: 9,
+      filename: 'wedding-video-001.mp4',
+      original_filename: 'movie.mp4',
+      mime_type: 'video/mp4',
+      media_type: 'video',
+      size_bytes: 99999,
+      captured_at: null,
+    });
+    dbModule.__setEvent({ id: 9, slug: 'wedding', event_name: 'Wedding' });
+
+    videoProcessor.processUploadedVideo.mockResolvedValueOnce({
+      thumbnailKey: 'thumbnails/thumb_wedding-video-001.jpg',
+      metadata: {
+        duration: 12.5,
+        videoCodec: 'h264',
+        audioCodec: 'aac',
+        width: 1280,
+        height: 720,
+      },
+    });
+
+    const { processPhoto } = require('../../src/services/photoProcessor');
+    await processPhoto(202);
+
+    const finalUpdate = dbModule.__recorded().updateCalls.pop();
+    expect(finalUpdate.data.processing_status).toBe('complete');
+    expect(finalUpdate.data.duration).toBe(12.5);
+    expect(finalUpdate.data.video_codec).toBe('h264');
+    expect(finalUpdate.data.thumbnail_path).toBe('thumbnails/thumb_wedding-video-001.jpg');
+
+    // Watermark queue is image-only.
+    expect(watermarkService.generateForPhoto).not.toHaveBeenCalled();
+  });
+
+  it('throws when the photo row no longer exists', async () => {
+    dbModule.__setPhoto(null);
+    dbModule.__setEvent({ id: 1 });
+    const { processPhoto } = require('../../src/services/photoProcessor');
+    await expect(processPhoto(999)).rejects.toThrow(/Photo 999 not found/);
+  });
+});
+
+void path; // referenced indirectly via mocks

backend/__tests__/utils/formatters.test.js

@@ -0,0 +1,66 @@
+/**
+ * Unit tests for formatters.js — focused on the HTML-escape behaviour added
+ * so admin-supplied welcome messages can't inject markup into customer mail.
+ */
+
+const { escapeHtml, nl2br, formatWelcomeMessage } = require('../../src/utils/formatters');
+
+describe('escapeHtml', () => {
+  it('escapes the five HTML metacharacters', () => {
+    expect(escapeHtml('& < > " \'')).toBe('&amp; &lt; &gt; &quot; &#39;');
+  });
+
+  it('returns empty string for null/undefined', () => {
+    expect(escapeHtml(null)).toBe('');
+    expect(escapeHtml(undefined)).toBe('');
+  });
+
+  it('coerces non-string values', () => {
+    expect(escapeHtml(42)).toBe('42');
+  });
+
+  it('escapes & before introducing new entities', () => {
+    expect(escapeHtml('<&>')).toBe('&lt;&amp;&gt;');
+  });
+});
+
+describe('nl2br', () => {
+  it('joins non-empty lines with <br />', () => {
+    expect(nl2br('a\nb\nc')).toBe('a<br />b<br />c');
+  });
+
+  it('normalises CRLF and CR', () => {
+    expect(nl2br('a\r\nb\rc')).toBe('a<br />b<br />c');
+  });
+
+  it('drops empty lines', () => {
+    expect(nl2br('a\n\n\nb')).toBe('a<br />b');
+  });
+
+  it('returns empty for empty input', () => {
+    expect(nl2br('')).toBe('');
+    expect(nl2br(null)).toBe('');
+  });
+});
+
+describe('formatWelcomeMessage', () => {
+  it('returns empty string for empty input', () => {
+    expect(formatWelcomeMessage('')).toBe('');
+    expect(formatWelcomeMessage('   ')).toBe('');
+  });
+
+  it('escapes HTML metacharacters before nl2br', () => {
+    expect(formatWelcomeMessage('Hello <b>world</b>'))
+      .toBe('Hello &lt;b&gt;world&lt;/b&gt;');
+  });
+
+  it('renders newlines as <br /> while keeping content escaped', () => {
+    expect(formatWelcomeMessage('line 1\n<script>x</script>\nline 3'))
+      .toBe('line 1<br />&lt;script&gt;x&lt;/script&gt;<br />line 3');
+  });
+
+  it('escapes ampersands and quotes that would otherwise break HTML', () => {
+    expect(formatWelcomeMessage('Tom & Jerry\'s "show"'))
+      .toBe('Tom &amp; Jerry&#39;s &quot;show&quot;');
+  });
+});

backend/dependencies-backend.json

@@ -1831,8 +1831,8 @@
       }
     },
     "nodemailer": {
-      "version": "6.10.1",
-      "resolved": "https://registry.npmjs.org/nodemailer/-/nodemailer-6.10.1.tgz",
+      "version": "7.0.7",
+      "resolved": "https://registry.npmjs.org/nodemailer/-/nodemailer-7.0.7.tgz",
       "overridden": false
     },
     "nodemon": {
@@ -2086,8 +2086,8 @@
               "version": "4.0.1"
             },
             "tar-fs": {
-              "version": "2.1.3",
-              "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.3.tgz",
+              "version": "2.1.4",
+              "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.4.tgz",
               "overridden": false
             },
             "tunnel-agent": {

backend/migrations/README.md

@@ -1,6 +1,6 @@
 # Database Migrations
 
-This directory contains database migrations for the Wedding Photo Sharing platform.
+This directory contains database migrations for the PicPeak photo sharing platform.
 
 ## Directory Structure
 
@@ -9,6 +9,7 @@ Essential migrations that are always run for new deployments. These include:
 - `init.js` - Initial database schema creation
 - Backup service tables (029-035)
 - Gallery feedback tables (033)
+- Pre-generated watermarks (061)
 
 ### `/legacy`
 Migrations needed only when upgrading from older versions. New deployments can skip these as the core schema already includes all necessary tables and columns.

backend/migrations/core/001_init.js

@@ -14,8 +14,8 @@ exports.up = async function(knex) {
     // Create default admin user if none exists
     const adminExists = await knex('admin_users').first();
     if (!adminExists) {
-      // Generate a secure random password
-      const generatedPassword = generateReadablePassword();
+      // Use ADMIN_PASSWORD from environment if set, otherwise generate a random one
+      const generatedPassword = process.env.ADMIN_PASSWORD || generateReadablePassword();
       const passwordHash = await bcrypt.hash(generatedPassword, 12); // Increased rounds for better security
       
       // Get admin credentials from environment or use defaults

backend/migrations/core/045_add_max_files_per_upload_setting.js

@@ -0,0 +1,48 @@
+const { DEFAULT_MAX_FILES_PER_UPLOAD, MAX_ALLOWED_FILES_PER_UPLOAD } = require('../../src/services/uploadSettings');
+
+exports.up = async function up(knex) {
+  const settingKey = 'general_max_files_per_upload';
+
+  const existing = await knex('app_settings')
+    .where({ setting_key: settingKey })
+    .first();
+
+  if (existing) {
+    // Normalize existing value into allowed bounds
+    let parsedValue;
+    try {
+      parsedValue = existing.setting_value != null ? JSON.parse(existing.setting_value) : null;
+    } catch {
+      parsedValue = existing.setting_value;
+    }
+
+    const numeric = Number(parsedValue);
+    let normalized = DEFAULT_MAX_FILES_PER_UPLOAD;
+    if (Number.isFinite(numeric) && numeric >= 1) {
+      normalized = Math.min(MAX_ALLOWED_FILES_PER_UPLOAD, Math.floor(numeric));
+    }
+
+    if (normalized !== numeric) {
+      await knex('app_settings')
+        .where({ setting_key: settingKey })
+        .update({
+          setting_value: JSON.stringify(normalized),
+          updated_at: new Date()
+        });
+    }
+    return;
+  }
+
+  await knex('app_settings').insert({
+    setting_key: settingKey,
+    setting_value: JSON.stringify(DEFAULT_MAX_FILES_PER_UPLOAD),
+    setting_type: 'general',
+    updated_at: new Date()
+  });
+};
+
+exports.down = async function down(knex) {
+  await knex('app_settings')
+    .where({ setting_key: 'general_max_files_per_upload' })
+    .del();
+};

backend/migrations/core/046_add_customer_contact_fields.js

@@ -0,0 +1,44 @@
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function up(knex) {
+  await addColumnIfNotExists(knex, 'events', 'customer_name', (table) => {
+    table.string('customer_name');
+  });
+
+  await addColumnIfNotExists(knex, 'events', 'customer_email', (table) => {
+    table.string('customer_email');
+  });
+
+  // Backfill new columns from legacy host_* fields
+  const client = knex?.client?.config?.client;
+
+  if (client === 'pg') {
+    await knex.raw(`
+      UPDATE events
+      SET customer_name = COALESCE(customer_name, host_name),
+          customer_email = COALESCE(customer_email, host_email)
+    `);
+  } else {
+    // SQLite fallback
+    await knex('events').update({
+      customer_name: knex.raw('COALESCE(customer_name, host_name)'),
+      customer_email: knex.raw('COALESCE(customer_email, host_email)')
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  const hasCustomerName = await knex.schema.hasColumn('events', 'customer_name');
+  if (hasCustomerName) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('customer_name');
+    });
+  }
+
+  const hasCustomerEmail = await knex.schema.hasColumn('events', 'customer_email');
+  if (hasCustomerEmail) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('customer_email');
+    });
+  }
+};

backend/migrations/core/047_add_tls_reject_unauthorized.js

@@ -0,0 +1,18 @@
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function up(knex) {
+  // Add tls_reject_unauthorized column to email_configs table
+  // Default is true (validate certificates), false means ignore SSL/TLS certificate errors
+  await addColumnIfNotExists(knex, 'email_configs', 'tls_reject_unauthorized', (table) => {
+    table.boolean('tls_reject_unauthorized').defaultTo(true);
+  });
+};
+
+exports.down = async function down(knex) {
+  const hasColumn = await knex.schema.hasColumn('email_configs', 'tls_reject_unauthorized');
+  if (hasColumn) {
+    await knex.schema.alterTable('email_configs', (table) => {
+      table.dropColumn('tls_reject_unauthorized');
+    });
+  }
+};

backend/migrations/core/048_add_video_support.js

@@ -0,0 +1,109 @@
+const { addColumnIfNotExists } = require('../helpers');
+
+/**
+ * Migration: Add video support to photos table
+ * - Adds columns for video metadata (media_type, duration, codecs, dimensions)
+ * - Updates existing photos to have media_type 'image'
+ */
+
+exports.up = async function(knex) {
+  console.log('Running migration: 042_add_video_support');
+
+  // Add media_type column (image or video)
+  await addColumnIfNotExists(knex, 'photos', 'media_type', (table) => {
+    table.string('media_type').defaultTo('image');
+  });
+
+  // Add mime_type column if not exists
+  await addColumnIfNotExists(knex, 'photos', 'mime_type', (table) => {
+    table.string('mime_type');
+  });
+
+  // Add duration column (for videos, in seconds)
+  await addColumnIfNotExists(knex, 'photos', 'duration', (table) => {
+    table.integer('duration');
+  });
+
+  // Add video codec information
+  await addColumnIfNotExists(knex, 'photos', 'video_codec', (table) => {
+    table.string('video_codec');
+  });
+
+  // Add audio codec information
+  await addColumnIfNotExists(knex, 'photos', 'audio_codec', (table) => {
+    table.string('audio_codec');
+  });
+
+  // Add width dimension
+  await addColumnIfNotExists(knex, 'photos', 'width', (table) => {
+    table.integer('width');
+  });
+
+  // Add height dimension
+  await addColumnIfNotExists(knex, 'photos', 'height', (table) => {
+    table.integer('height');
+  });
+
+  // Update existing photos to have media_type 'image' if not set
+  const hasMediaType = await knex.schema.hasColumn('photos', 'media_type');
+  if (hasMediaType) {
+    await knex('photos')
+      .whereNull('media_type')
+      .orWhere('media_type', '')
+      .update({ media_type: 'image' });
+    console.log('Updated existing photos to have media_type "image"');
+  }
+
+  console.log('Migration 042_add_video_support completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rolling back migration: 042_add_video_support');
+
+  // Remove video support columns
+  const hasMediaType = await knex.schema.hasColumn('photos', 'media_type');
+  if (hasMediaType) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.dropColumn('media_type');
+    });
+  }
+
+  const hasDuration = await knex.schema.hasColumn('photos', 'duration');
+  if (hasDuration) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.dropColumn('duration');
+    });
+  }
+
+  const hasVideoCodec = await knex.schema.hasColumn('photos', 'video_codec');
+  if (hasVideoCodec) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.dropColumn('video_codec');
+    });
+  }
+
+  const hasAudioCodec = await knex.schema.hasColumn('photos', 'audio_codec');
+  if (hasAudioCodec) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.dropColumn('audio_codec');
+    });
+  }
+
+  const hasWidth = await knex.schema.hasColumn('photos', 'width');
+  if (hasWidth) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.dropColumn('width');
+    });
+  }
+
+  const hasHeight = await knex.schema.hasColumn('photos', 'height');
+  if (hasHeight) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.dropColumn('height');
+    });
+  }
+
+  // Note: We don't drop mime_type as it may be used by images as well
+
+  console.log('Rollback of 042_add_video_support completed');
+};

backend/migrations/core/049_add_slug_redirects.js

@@ -0,0 +1,21 @@
+/**
+ * Migration: Add slug_redirects table for event rename feature
+ * This table stores old slugs that should redirect to new slugs
+ */
+
+exports.up = function(knex) {
+  return knex.schema.createTable('slug_redirects', (table) => {
+    table.increments('id').primary();
+    table.string('old_slug', 255).notNullable().unique();
+    table.string('new_slug', 255).notNullable();
+    table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
+    table.timestamp('created_at').defaultTo(knex.fn.now());
+
+    // Index for fast lookup
+    table.index('old_slug');
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('slug_redirects');
+};

backend/migrations/core/050_add_optional_event_fields_settings.js

@@ -0,0 +1,33 @@
+/**
+ * Migration: Add optional event fields settings
+ * These settings control whether customer name, customer email, and admin email
+ * are required when creating new events.
+ */
+
+exports.up = async function(knex) {
+  const settings = [
+    { setting_key: 'event_require_customer_name', setting_value: JSON.stringify(true), setting_type: 'boolean' },
+    { setting_key: 'event_require_customer_email', setting_value: JSON.stringify(true), setting_type: 'boolean' },
+    { setting_key: 'event_require_admin_email', setting_value: JSON.stringify(true), setting_type: 'boolean' }
+  ];
+
+  for (const setting of settings) {
+    const exists = await knex('app_settings').where('setting_key', setting.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({
+        ...setting,
+        updated_at: knex.fn.now()
+      });
+    }
+  }
+};
+
+exports.down = function(knex) {
+  return knex('app_settings')
+    .whereIn('setting_key', [
+      'event_require_customer_name',
+      'event_require_customer_email',
+      'event_require_admin_email'
+    ])
+    .del();
+};

backend/migrations/core/051_add_photo_filter_indexes.js

@@ -0,0 +1,100 @@
+/**
+ * Migration: Add indexes for photo filtering performance
+ * These indexes optimize queries that filter by feedback metrics
+ */
+
+exports.up = async function(knex) {
+  // Add comment_count column if it doesn't exist
+  const hasCommentCount = await knex.schema.hasColumn('photos', 'comment_count');
+  if (!hasCommentCount) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.integer('comment_count').defaultTo(0);
+    });
+  }
+
+  // Add indexes for common filter queries
+  // Note: PostgreSQL supports partial indexes, SQLite does not
+  const client = knex.client.config.client;
+
+  if (client === 'pg' || client === 'postgresql') {
+    // Partial indexes for PostgreSQL
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_rating_filter
+      ON photos(event_id, average_rating)
+      WHERE average_rating > 0
+    `);
+
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_likes_filter
+      ON photos(event_id, like_count)
+      WHERE like_count > 0
+    `);
+
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_favorites_filter
+      ON photos(event_id, favorite_count)
+      WHERE favorite_count > 0
+    `);
+
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_comments_filter
+      ON photos(event_id, comment_count)
+      WHERE comment_count > 0
+    `);
+  } else {
+    // Regular indexes for SQLite
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_rating_filter
+      ON photos(event_id, average_rating)
+    `);
+
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_likes_filter
+      ON photos(event_id, like_count)
+    `);
+
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_favorites_filter
+      ON photos(event_id, favorite_count)
+    `);
+
+    await knex.raw(`
+      CREATE INDEX IF NOT EXISTS idx_photos_comments_filter
+      ON photos(event_id, comment_count)
+    `);
+  }
+
+  // Create export_jobs table for tracking large exports
+  const hasExportJobs = await knex.schema.hasTable('export_jobs');
+  if (!hasExportJobs) {
+    await knex.schema.createTable('export_jobs', (table) => {
+      table.increments('id').primary();
+      table.string('job_id', 50).unique().notNullable();
+      table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
+      table.integer('admin_user_id').references('id').inTable('admin_users').onDelete('SET NULL');
+      table.string('format', 20).notNullable();
+      table.string('status', 20).defaultTo('pending');
+      table.integer('progress').defaultTo(0);
+      table.integer('total_photos');
+      table.json('options');
+      table.string('file_path', 500);
+      table.bigInteger('file_size');
+      table.text('error_message');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('completed_at');
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  // Drop indexes
+  await knex.raw('DROP INDEX IF EXISTS idx_photos_rating_filter');
+  await knex.raw('DROP INDEX IF EXISTS idx_photos_likes_filter');
+  await knex.raw('DROP INDEX IF EXISTS idx_photos_favorites_filter');
+  await knex.raw('DROP INDEX IF EXISTS idx_photos_comments_filter');
+
+  // Drop export_jobs table
+  await knex.schema.dropTableIfExists('export_jobs');
+
+  // Note: We don't remove comment_count column as it might have data
+};

backend/migrations/core/052_add_css_templates.js

@@ -0,0 +1,192 @@
+/**
+ * Migration: Add CSS Templates feature
+ * Creates css_templates table and adds css_template_id to events table
+ */
+
+// Default CSS template content
+const DEFAULT_CSS_TEMPLATE = `/*
+ * PicPeak Custom CSS Template: Elegant Dark
+ *
+ * Available CSS Custom Properties:
+ * --gallery-bg: Background color
+ * --gallery-text: Primary text color
+ * --gallery-accent: Accent/highlight color
+ * --gallery-border: Border color
+ * --gallery-shadow: Box shadow value
+ * --gallery-radius: Border radius value
+ * --gallery-spacing: Base spacing unit
+ */
+
+/* ===== Base Theme Variables ===== */
+.gallery-page {
+  --gallery-bg: #1a1a2e;
+  --gallery-bg-secondary: #16213e;
+  --gallery-text: #eaeaea;
+  --gallery-text-muted: #8b8b9a;
+  --gallery-accent: #e94560;
+  --gallery-accent-hover: #ff6b6b;
+  --gallery-border: #2d2d44;
+  --gallery-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+  --gallery-radius: 12px;
+  --gallery-spacing: 16px;
+}
+
+/* ===== Page Background ===== */
+.gallery-page {
+  background: linear-gradient(135deg, var(--gallery-bg) 0%, var(--gallery-bg-secondary) 100%);
+  min-height: 100vh;
+  color: var(--gallery-text);
+}
+
+/* ===== Gallery Header ===== */
+.gallery-header {
+  background: rgba(22, 33, 62, 0.8);
+  backdrop-filter: blur(10px);
+  border-bottom: 1px solid var(--gallery-border);
+  padding: calc(var(--gallery-spacing) * 2);
+}
+
+.gallery-title {
+  color: var(--gallery-text);
+  font-size: 2rem;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+
+/* ===== Photo Grid ===== */
+.photo-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: var(--gallery-spacing);
+  padding: calc(var(--gallery-spacing) * 2);
+}
+
+/* ===== Photo Cards ===== */
+.photo-card {
+  background: var(--gallery-bg-secondary);
+  border-radius: var(--gallery-radius);
+  overflow: hidden;
+  transition: transform 0.3s ease, box-shadow 0.3s ease;
+  border: 1px solid var(--gallery-border);
+}
+
+.photo-card:hover {
+  transform: translateY(-4px);
+  box-shadow: var(--gallery-shadow);
+}
+
+.photo-card img {
+  width: 100%;
+  height: 200px;
+  object-fit: cover;
+  transition: transform 0.3s ease;
+}
+
+.photo-card:hover img {
+  transform: scale(1.05);
+}
+
+/* ===== Buttons ===== */
+.gallery-btn {
+  background: var(--gallery-accent);
+  color: white;
+  border: none;
+  border-radius: calc(var(--gallery-radius) / 2);
+  padding: calc(var(--gallery-spacing) / 2) var(--gallery-spacing);
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s ease, transform 0.2s ease;
+}
+
+.gallery-btn:hover {
+  background: var(--gallery-accent-hover);
+  transform: translateY(-2px);
+}
+
+/* ===== Lightbox ===== */
+.lightbox-overlay {
+  background: rgba(10, 10, 20, 0.95);
+  backdrop-filter: blur(20px);
+}
+
+/* ===== Responsive Adjustments ===== */
+@media (max-width: 768px) {
+  .gallery-page {
+    --gallery-spacing: 12px;
+  }
+
+  .photo-grid {
+    grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+  }
+
+  .gallery-title {
+    font-size: 1.5rem;
+  }
+}`;
+
+exports.up = async function(knex) {
+  // Create css_templates table
+  const hasTable = await knex.schema.hasTable('css_templates');
+  if (!hasTable) {
+    await knex.schema.createTable('css_templates', (table) => {
+      table.increments('id').primary();
+      table.integer('slot_number').notNullable();
+      table.string('name', 50).notNullable().defaultTo('Untitled');
+      table.text('css_content').notNullable().defaultTo('');
+      table.boolean('is_enabled').notNullable().defaultTo(false);
+      table.boolean('is_default').notNullable().defaultTo(false);
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+      table.unique('slot_number');
+    });
+
+    // Insert default templates
+    await knex('css_templates').insert([
+      {
+        slot_number: 1,
+        name: 'Elegant Dark',
+        css_content: DEFAULT_CSS_TEMPLATE,
+        is_enabled: true,
+        is_default: true
+      },
+      {
+        slot_number: 2,
+        name: 'Untitled',
+        css_content: '',
+        is_enabled: false,
+        is_default: false
+      },
+      {
+        slot_number: 3,
+        name: 'Untitled',
+        css_content: '',
+        is_enabled: false,
+        is_default: false
+      }
+    ]);
+  }
+
+  // Add css_template_id to events table
+  const hasColumn = await knex.schema.hasColumn('events', 'css_template_id');
+  if (!hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.integer('css_template_id').references('id').inTable('css_templates').onDelete('SET NULL');
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  // Remove css_template_id from events table
+  const hasColumn = await knex.schema.hasColumn('events', 'css_template_id');
+  if (hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('css_template_id');
+    });
+  }
+
+  // Drop css_templates table
+  await knex.schema.dropTableIfExists('css_templates');
+};
+
+// Export default template for use in reset functionality
+module.exports.DEFAULT_CSS_TEMPLATE = DEFAULT_CSS_TEMPLATE;

backend/migrations/core/053_add_liquid_glass_templates.js

@@ -0,0 +1,731 @@
+/**
+ * Migration: Add Liquid Glass CSS Templates
+ * Updates template slots 2 and 3 with Apple-inspired Liquid Glass designs
+ *
+ * These are starter example templates for new installations.
+ * Users can edit or replace them as needed.
+ */
+
+const APPLE_LIQUID_GLASS = `/*
+ * PicPeak Custom CSS Template: Apple Liquid Glass
+ * Authentic iOS 26 / macOS Tahoe Liquid Glass Design
+ */
+
+/* ===== Apple System Fonts ===== */
+.gallery-page,
+.gallery-page *,
+.gallery-sidebar,
+.gallery-sidebar * {
+  font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
+               "Helvetica Neue", Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* ===== CSS Variables ===== */
+:root {
+  --glass-blur: 20px;
+  --glass-blur-heavy: 40px;
+  --glass-saturation: 180%;
+  --glass-bg: rgba(255, 255, 255, 0.08);
+  --glass-bg-medium: rgba(255, 255, 255, 0.18);
+  --glass-bg-solid: rgba(255, 255, 255, 0.25);
+  --glass-border: rgba(255, 255, 255, 0.2);
+  --glass-border-light: rgba(255, 255, 255, 0.4);
+  --glass-shadow: 0 8px 32px rgba(31, 38, 135, 0.15);
+  --glass-inset: inset 0 1px 1px rgba(255, 255, 255, 0.4),
+                 inset 0 -1px 1px rgba(0, 0, 0, 0.05);
+  --gallery-gradient: linear-gradient(135deg, #667eea 0%, #764ba2 50%, #f093fb 100%);
+  --gallery-text: #1a1a2e;
+  --gallery-text-light: #ffffff;
+  --gallery-accent: #667eea;
+  --gallery-radius: 20px;
+  --gallery-radius-sm: 12px;
+}
+
+/* ===== Page Background ===== */
+.gallery-page {
+  background: var(--gallery-gradient) !important;
+  background-attachment: fixed !important;
+  min-height: 100vh;
+}
+
+.gallery-page::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  background:
+    radial-gradient(ellipse 600px 400px at 15% 85%, rgba(255, 255, 255, 0.2) 0%, transparent 50%),
+    radial-gradient(ellipse 500px 350px at 85% 15%, rgba(255, 255, 255, 0.15) 0%, transparent 45%);
+  pointer-events: none;
+  z-index: 0;
+}
+
+/* ===== TOP BAR / HEADER - Liquid Glass ===== */
+.gallery-page .gallery-header,
+.gallery-page header {
+  background: var(--glass-bg-medium) !important;
+  backdrop-filter: blur(var(--glass-blur-heavy)) saturate(var(--glass-saturation)) !important;
+  -webkit-backdrop-filter: blur(var(--glass-blur-heavy)) saturate(var(--glass-saturation)) !important;
+  border-bottom: 1px solid var(--glass-border) !important;
+  box-shadow: var(--glass-shadow), var(--glass-inset) !important;
+}
+
+.gallery-page .gallery-header > div {
+  background: transparent !important;
+  border: none !important;
+}
+
+/* ===== SIDEBAR - Liquid Glass ===== */
+.gallery-sidebar {
+  background: var(--glass-bg-medium) !important;
+  backdrop-filter: blur(var(--glass-blur-heavy)) saturate(var(--glass-saturation)) !important;
+  -webkit-backdrop-filter: blur(var(--glass-blur-heavy)) saturate(var(--glass-saturation)) !important;
+  border-right: 1px solid var(--glass-border) !important;
+  box-shadow: 4px 0 32px rgba(31, 38, 135, 0.1), var(--glass-inset) !important;
+}
+
+.gallery-sidebar h2,
+.gallery-sidebar h3 {
+  color: var(--gallery-text) !important;
+  font-weight: 600 !important;
+}
+
+/* ===== HERO LAYOUT - Transform to Glass Title Box ===== */
+/* Target the hero wrapper */
+.gallery-page .relative.-mt-6 {
+  margin-top: 0 !important;
+}
+
+/* Target the hero section (first child with h-[60vh]) */
+.gallery-page .relative.-mt-6 > .relative:first-child {
+  height: auto !important;
+  min-height: auto !important;
+  margin: 0 !important;
+  padding: 2rem !important;
+  display: flex !important;
+  justify-content: center !important;
+  align-items: center !important;
+  background: transparent !important;
+}
+
+/* Hide the hero background image */
+.gallery-page .relative.-mt-6 > .relative:first-child > img,
+.gallery-page .relative.-mt-6 > .relative:first-child > canvas {
+  display: none !important;
+}
+
+/* Hide the dark overlay */
+.gallery-page .relative.-mt-6 > .relative:first-child > .absolute.inset-0.bg-black {
+  display: none !important;
+}
+
+/* Style the content area as glass title box */
+.gallery-page .relative.-mt-6 > .relative:first-child > .absolute.inset-0.flex {
+  position: relative !important;
+  inset: auto !important;
+  background: var(--glass-bg-medium) !important;
+  backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation)) !important;
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation)) !important;
+  border: 1px solid var(--glass-border-light) !important;
+  border-radius: var(--gallery-radius) !important;
+  padding: 2rem 3rem !important;
+  box-shadow: var(--glass-shadow), var(--glass-inset) !important;
+  max-width: 600px !important;
+  width: auto !important;
+}
+
+/* Hide logo in glass title box */
+.gallery-page .relative.-mt-6 > .relative:first-child .mb-6 {
+  display: none !important;
+}
+
+/* Style title text */
+.gallery-page .relative.-mt-6 > .relative:first-child h1 {
+  color: var(--gallery-text) !important;
+  text-shadow: none !important;
+  font-weight: 700 !important;
+  font-size: 2.25rem !important;
+  margin-bottom: 0.75rem !important;
+}
+
+/* Style date text */
+.gallery-page .relative.-mt-6 > .relative:first-child .text-white\\/90 {
+  color: var(--gallery-text) !important;
+  opacity: 0.8;
+}
+
+/* Hide scroll down button */
+.gallery-page .relative.-mt-6 > .relative:first-child > .absolute.bottom-8,
+.gallery-page .relative.-mt-6 > .relative:first-child > button.absolute {
+  display: none !important;
+}
+
+/* ===== PHOTO GRID ===== */
+.gallery-page .photo-grid {
+  display: grid !important;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)) !important;
+  gap: 1.25rem !important;
+  padding: 1rem !important;
+}
+
+/* ===== PHOTO CARDS - Liquid Glass ===== */
+.gallery-page .photo-card {
+  background: var(--glass-bg) !important;
+  backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation)) !important;
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation)) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: var(--gallery-radius) !important;
+  overflow: hidden !important;
+  transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1) !important;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1), var(--glass-inset) !important;
+}
+
+.gallery-page .photo-card:hover {
+  transform: translateY(-6px) scale(1.02) !important;
+  box-shadow: 0 20px 40px rgba(102, 126, 234, 0.25),
+              0 8px 16px rgba(0, 0, 0, 0.1),
+              var(--glass-inset) !important;
+  border-color: var(--glass-border-light) !important;
+}
+
+.gallery-page .photo-card img {
+  transition: transform 0.4s ease !important;
+}
+
+.gallery-page .photo-card:hover img {
+  transform: scale(1.05) !important;
+}
+
+/* ===== BUTTONS - Glass Pill Style ===== */
+.gallery-page button,
+.gallery-page [role="button"],
+.gallery-sidebar button {
+  background: var(--glass-bg) !important;
+  backdrop-filter: blur(12px) saturate(150%) !important;
+  -webkit-backdrop-filter: blur(12px) saturate(150%) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: 9999px !important;
+  color: var(--gallery-text) !important;
+  font-weight: 500 !important;
+  transition: all 0.3s ease !important;
+}
+
+.gallery-page button:hover,
+.gallery-page [role="button"]:hover,
+.gallery-sidebar button:hover {
+  background: var(--glass-bg-medium) !important;
+  transform: translateY(-1px);
+  box-shadow: 0 4px 16px rgba(102, 126, 234, 0.2) !important;
+}
+
+.gallery-page button[class*="bg-primary"],
+.gallery-page .gallery-btn-download {
+  background: linear-gradient(135deg, var(--gallery-accent) 0%, #764ba2 100%) !important;
+  color: white !important;
+  border: none !important;
+}
+
+/* ===== INPUT FIELDS ===== */
+.gallery-page input,
+.gallery-page select,
+.gallery-sidebar input,
+.gallery-sidebar select {
+  background: rgba(255, 255, 255, 0.25) !important;
+  backdrop-filter: blur(8px) !important;
+  -webkit-backdrop-filter: blur(8px) !important;
+  border: 1px solid var(--glass-border) !important;
+  border-radius: var(--gallery-radius-sm) !important;
+  color: var(--gallery-text) !important;
+}
+
+/* Input placeholder text - make it visible */
+.gallery-page input::placeholder,
+.gallery-sidebar input::placeholder {
+  color: rgba(26, 26, 46, 0.6) !important;
+  opacity: 1 !important;
+}
+
+/* Input focus state */
+.gallery-page input:focus,
+.gallery-sidebar input:focus {
+  background: rgba(255, 255, 255, 0.35) !important;
+  border-color: var(--glass-border-light) !important;
+  outline: none !important;
+  box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.2) !important;
+}
+
+/* ===== FOOTER ===== */
+.gallery-page .gallery-footer,
+.gallery-page footer {
+  background: var(--glass-bg) !important;
+  backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation)) !important;
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation)) !important;
+  border-top: 1px solid var(--glass-border) !important;
+}
+
+/* ===== LIGHTBOX ===== */
+.gallery-page [class*="fixed"][class*="inset-0"][class*="z-50"] {
+  background: rgba(0, 0, 0, 0.7) !important;
+  backdrop-filter: blur(30px) !important;
+  -webkit-backdrop-filter: blur(30px) !important;
+}
+
+/* ===== SCROLLBAR ===== */
+.gallery-page ::-webkit-scrollbar,
+.gallery-sidebar ::-webkit-scrollbar {
+  width: 8px;
+}
+
+.gallery-page ::-webkit-scrollbar-track,
+.gallery-sidebar ::-webkit-scrollbar-track {
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.gallery-page ::-webkit-scrollbar-thumb,
+.gallery-sidebar ::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 4px;
+}
+
+/* ===== RESPONSIVE ===== */
+@media (max-width: 768px) {
+  :root {
+    --gallery-radius: 16px;
+    --glass-blur: 16px;
+  }
+
+  .gallery-page .relative.-mt-6 > .relative:first-child > .absolute.inset-0.flex {
+    padding: 1.5rem 2rem !important;
+    max-width: 90% !important;
+  }
+
+  .gallery-page .relative.-mt-6 > .relative:first-child h1 {
+    font-size: 1.5rem !important;
+  }
+
+  .gallery-page .photo-grid {
+    grid-template-columns: repeat(2, 1fr) !important;
+    gap: 0.75rem !important;
+  }
+}
+
+/* ===== ACCESSIBILITY ===== */
+@media (prefers-reduced-motion: reduce) {
+  .gallery-page .photo-card,
+  .gallery-page button {
+    transition: none !important;
+  }
+
+  .gallery-page .photo-card:hover {
+    transform: none !important;
+  }
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  .gallery-page .photo-card,
+  .gallery-page button,
+  .gallery-sidebar {
+    backdrop-filter: none !important;
+    -webkit-backdrop-filter: none !important;
+    background: rgba(255, 255, 255, 0.95) !important;
+  }
+}`;
+
+const LIQUID_GLASS_DARK = `/*
+ * PicPeak Custom CSS Template: Liquid Glass Dark
+ * Inspired by Apple's iOS 26 Liquid Glass Design Language
+ *
+ * Features:
+ * - Deep translucent dark surfaces
+ * - Neon accent highlights
+ * - Dramatic glass reflections
+ * - Subtle animated gradients
+ */
+
+/* ===== Base Theme Variables ===== */
+.gallery-page {
+  --glass-bg: rgba(15, 15, 35, 0.7);
+  --glass-bg-elevated: rgba(25, 25, 55, 0.85);
+  --glass-border: rgba(255, 255, 255, 0.1);
+  --glass-border-highlight: rgba(255, 255, 255, 0.2);
+  --glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  --glass-blur: 24px;
+  --glass-saturation: 150%;
+
+  --gallery-bg: #0a0a1a;
+  --gallery-text: #f0f0f5;
+  --gallery-text-muted: rgba(240, 240, 245, 0.6);
+  --gallery-accent: #00d4ff;
+  --gallery-accent-secondary: #ff00e5;
+  --gallery-accent-hover: #00ffea;
+  --gallery-radius: 20px;
+  --gallery-spacing: 20px;
+
+  /* Neon glow variables */
+  --neon-glow: 0 0 20px rgba(0, 212, 255, 0.5), 0 0 40px rgba(0, 212, 255, 0.2);
+  --neon-glow-secondary: 0 0 20px rgba(255, 0, 229, 0.5), 0 0 40px rgba(255, 0, 229, 0.2);
+}
+
+/* ===== Page Background ===== */
+.gallery-page {
+  background: var(--gallery-bg);
+  min-height: 100vh;
+  position: relative;
+  overflow-x: hidden;
+}
+
+/* Animated mesh gradient background */
+.gallery-page::before {
+  content: '';
+  position: fixed;
+  top: -50%;
+  left: -50%;
+  right: -50%;
+  bottom: -50%;
+  background:
+    radial-gradient(circle at 30% 20%, rgba(0, 212, 255, 0.15) 0%, transparent 40%),
+    radial-gradient(circle at 70% 80%, rgba(255, 0, 229, 0.1) 0%, transparent 40%),
+    radial-gradient(circle at 50% 50%, rgba(100, 100, 255, 0.05) 0%, transparent 60%);
+  animation: gradientShift 20s ease-in-out infinite;
+  pointer-events: none;
+  z-index: 0;
+}
+
+@keyframes gradientShift {
+  0%, 100% { transform: translate(0, 0) rotate(0deg); }
+  25% { transform: translate(2%, 2%) rotate(1deg); }
+  50% { transform: translate(-1%, 3%) rotate(-1deg); }
+  75% { transform: translate(3%, -2%) rotate(2deg); }
+}
+
+/* ===== Gallery Header ===== */
+.gallery-header {
+  background: var(--glass-bg-elevated);
+  backdrop-filter: blur(30px) saturate(var(--glass-saturation));
+  -webkit-backdrop-filter: blur(30px) saturate(var(--glass-saturation));
+  border-bottom: 1px solid var(--glass-border-highlight);
+  padding: calc(var(--gallery-spacing) * 1.5);
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  box-shadow:
+    0 4px 24px rgba(0, 0, 0, 0.3),
+    inset 0 1px 0 rgba(255, 255, 255, 0.1);
+}
+
+.gallery-title {
+  color: var(--gallery-text);
+  font-weight: 700;
+  font-size: 1.75rem;
+  letter-spacing: -0.02em;
+  background: linear-gradient(135deg, var(--gallery-text) 0%, var(--gallery-accent) 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+/* ===== Photo Grid ===== */
+.photo-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: var(--gallery-spacing);
+  padding: calc(var(--gallery-spacing) * 2);
+  position: relative;
+  z-index: 1;
+}
+
+/* ===== Photo Cards - Dark Glass Style ===== */
+.photo-card {
+  position: relative;
+  background: var(--glass-bg);
+  backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation));
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation));
+  border: 1px solid var(--glass-border);
+  border-radius: var(--gallery-radius);
+  overflow: hidden;
+  transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1);
+  box-shadow:
+    0 4px 24px rgba(0, 0, 0, 0.3),
+    inset 0 1px 0 rgba(255, 255, 255, 0.05);
+}
+
+/* Top highlight reflection */
+.photo-card::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 1px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    rgba(255, 255, 255, 0.3) 50%,
+    transparent 100%
+  );
+  z-index: 2;
+}
+
+/* Inner glow effect */
+.photo-card::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: var(--gallery-radius);
+  padding: 1px;
+  background: linear-gradient(
+    135deg,
+    rgba(0, 212, 255, 0) 0%,
+    rgba(0, 212, 255, 0) 40%,
+    rgba(0, 212, 255, 0.1) 100%
+  );
+  -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+  -webkit-mask-composite: xor;
+  mask-composite: exclude;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.4s ease;
+}
+
+.photo-card:hover {
+  transform: translateY(-8px) scale(1.02);
+  border-color: var(--glass-border-highlight);
+  box-shadow:
+    0 24px 48px rgba(0, 0, 0, 0.4),
+    0 0 0 1px rgba(0, 212, 255, 0.2),
+    var(--neon-glow);
+}
+
+.photo-card:hover::after {
+  opacity: 1;
+}
+
+.photo-card img {
+  width: 100%;
+  height: 240px;
+  object-fit: cover;
+  transition: transform 0.4s ease, filter 0.4s ease;
+  filter: brightness(0.9);
+}
+
+.photo-card:hover img {
+  transform: scale(1.05);
+  filter: brightness(1);
+}
+
+.photo-card-info {
+  padding: var(--gallery-spacing);
+  background: linear-gradient(
+    180deg,
+    rgba(0, 0, 0, 0.2) 0%,
+    rgba(0, 0, 0, 0.4) 100%
+  );
+  color: var(--gallery-text);
+}
+
+.photo-card-info p {
+  color: var(--gallery-text-muted);
+  font-size: 0.875rem;
+}
+
+/* ===== Buttons - Neon Glass Style ===== */
+.gallery-btn {
+  background: var(--glass-bg);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  border: 1px solid var(--glass-border);
+  border-radius: calc(var(--gallery-radius) / 2);
+  padding: 12px 24px;
+  color: var(--gallery-text);
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.3s ease;
+  position: relative;
+}
+
+.gallery-btn:hover {
+  border-color: var(--gallery-accent);
+  box-shadow: var(--neon-glow);
+  color: var(--gallery-accent);
+}
+
+.gallery-btn-primary {
+  background: linear-gradient(135deg, var(--gallery-accent) 0%, var(--gallery-accent-secondary) 100%);
+  color: white;
+  border: none;
+  box-shadow: var(--neon-glow);
+}
+
+.gallery-btn-primary:hover {
+  box-shadow:
+    0 0 30px rgba(0, 212, 255, 0.6),
+    0 0 60px rgba(0, 212, 255, 0.3),
+    0 0 90px rgba(255, 0, 229, 0.2);
+  transform: translateY(-2px);
+}
+
+/* ===== Lightbox - Dark Glass ===== */
+.lightbox-overlay {
+  background: rgba(5, 5, 15, 0.9);
+  backdrop-filter: blur(40px);
+  -webkit-backdrop-filter: blur(40px);
+}
+
+.lightbox-content {
+  background: var(--glass-bg-elevated);
+  backdrop-filter: blur(24px);
+  -webkit-backdrop-filter: blur(24px);
+  border: 1px solid var(--glass-border-highlight);
+  border-radius: var(--gallery-radius);
+  box-shadow:
+    0 24px 80px rgba(0, 0, 0, 0.5),
+    var(--neon-glow);
+}
+
+/* ===== Category Pills ===== */
+.category-pill {
+  background: var(--glass-bg);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  border: 1px solid var(--glass-border);
+  border-radius: 9999px;
+  padding: 8px 20px;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--gallery-text-muted);
+  transition: all 0.3s ease;
+}
+
+.category-pill:hover {
+  border-color: var(--gallery-accent);
+  color: var(--gallery-accent);
+  box-shadow: var(--neon-glow);
+}
+
+.category-pill.active {
+  background: linear-gradient(135deg, var(--gallery-accent) 0%, var(--gallery-accent-secondary) 100%);
+  color: white;
+  border-color: transparent;
+  box-shadow: var(--neon-glow);
+}
+
+/* ===== Scrollbar Styling ===== */
+.gallery-page ::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+.gallery-page ::-webkit-scrollbar-track {
+  background: var(--glass-bg);
+  border-radius: 4px;
+}
+
+.gallery-page ::-webkit-scrollbar-thumb {
+  background: linear-gradient(180deg, var(--gallery-accent) 0%, var(--gallery-accent-secondary) 100%);
+  border-radius: 4px;
+}
+
+/* ===== Responsive ===== */
+@media (max-width: 768px) {
+  .gallery-page {
+    --gallery-radius: 16px;
+    --gallery-spacing: 12px;
+    --glass-blur: 16px;
+  }
+
+  .photo-grid {
+    grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+  }
+
+  .photo-card img {
+    height: 180px;
+  }
+
+  /* Reduce animation complexity on mobile */
+  .gallery-page::before {
+    animation: none;
+  }
+}
+
+/* ===== Accessibility: Reduce Motion ===== */
+@media (prefers-reduced-motion: reduce) {
+  .gallery-page::before {
+    animation: none;
+  }
+
+  .photo-card,
+  .gallery-btn {
+    transition: none;
+  }
+
+  .photo-card:hover {
+    transform: none;
+  }
+}
+
+/* ===== Accessibility: Reduce Transparency ===== */
+@media (prefers-reduced-transparency: reduce) {
+  .photo-card,
+  .gallery-btn,
+  .gallery-header {
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+  }
+
+  .gallery-page {
+    --glass-bg: rgba(20, 20, 40, 0.98);
+    --glass-bg-elevated: rgba(30, 30, 60, 0.98);
+  }
+}`;
+
+exports.up = async function(knex) {
+  // Update template slot 2 with Apple Liquid Glass (Light)
+  await knex('css_templates')
+    .where({ slot_number: 2 })
+    .update({
+      name: 'Apple Liquid Glass',
+      css_content: APPLE_LIQUID_GLASS,
+      is_enabled: true,
+      is_default: false,
+      updated_at: knex.fn.now()
+    });
+
+  // Update template slot 3 with Liquid Glass Dark
+  await knex('css_templates')
+    .where({ slot_number: 3 })
+    .update({
+      name: 'Liquid Glass Dark',
+      css_content: LIQUID_GLASS_DARK,
+      is_enabled: true,
+      is_default: false,
+      updated_at: knex.fn.now()
+    });
+};
+
+exports.down = async function(knex) {
+  // Revert to empty templates
+  await knex('css_templates')
+    .where({ slot_number: 2 })
+    .update({
+      name: 'Untitled',
+      css_content: '',
+      is_enabled: false,
+      is_default: false,
+      updated_at: knex.fn.now()
+    });
+
+  await knex('css_templates')
+    .where({ slot_number: 3 })
+    .update({
+      name: 'Untitled',
+      css_content: '',
+      is_enabled: false,
+      is_default: false,
+      updated_at: knex.fn.now()
+    });
+};
+
+// Export templates for use elsewhere
+module.exports.APPLE_LIQUID_GLASS = APPLE_LIQUID_GLASS;
+module.exports.LIQUID_GLASS_DARK = LIQUID_GLASS_DARK;

backend/migrations/core/054_add_roles_table.js

@@ -0,0 +1,91 @@
+/**
+ * Migration: Add Roles Table
+ * Creates the roles table for RBAC multi-administrator support.
+ *
+ * Default roles:
+ * - super_admin (priority 100): Full system access including user management
+ * - admin (priority 80): Full event and photo management
+ * - editor (priority 50): Can edit events and photos but not create or delete
+ * - viewer (priority 20): Read-only access to dashboard and events
+ */
+
+exports.up = async function(knex) {
+  console.log('Creating roles table...');
+
+  // Check if table already exists
+  const hasRolesTable = await knex.schema.hasTable('roles');
+
+  if (!hasRolesTable) {
+    await knex.schema.createTable('roles', (table) => {
+      table.increments('id').primary();
+      table.string('name', 50).unique().notNullable(); // 'super_admin', 'admin', 'editor', 'viewer'
+      table.string('display_name', 100).notNullable(); // 'Super Admin', 'Admin', etc.
+      table.text('description');
+      table.boolean('is_system').defaultTo(false); // System roles cannot be deleted
+      table.integer('priority').defaultTo(0); // Higher = more privileged (for hierarchy)
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+
+      // Index for name lookups
+      table.index(['name']);
+      // Index for priority-based ordering
+      table.index(['priority']);
+    });
+
+    console.log('Roles table created');
+  }
+
+  // Insert default system roles
+  const existingRoles = await knex('roles').select('name');
+  const existingRoleNames = existingRoles.map(r => r.name);
+
+  const defaultRoles = [
+    {
+      name: 'super_admin',
+      display_name: 'Super Admin',
+      description: 'Full system access including user management',
+      is_system: true,
+      priority: 100
+    },
+    {
+      name: 'admin',
+      display_name: 'Admin',
+      description: 'Full event and photo management',
+      is_system: true,
+      priority: 80
+    },
+    {
+      name: 'editor',
+      display_name: 'Editor',
+      description: 'Can edit events and photos but not create or delete',
+      is_system: true,
+      priority: 50
+    },
+    {
+      name: 'viewer',
+      display_name: 'Viewer',
+      description: 'Read-only access to dashboard and events',
+      is_system: true,
+      priority: 20
+    }
+  ];
+
+  const rolesToInsert = defaultRoles.filter(role => !existingRoleNames.includes(role.name));
+
+  if (rolesToInsert.length > 0) {
+    await knex('roles').insert(rolesToInsert);
+    console.log(`Inserted ${rolesToInsert.length} default roles`);
+  }
+
+  console.log('Roles table migration completed successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing roles table...');
+
+  // Note: This will fail if there are foreign key references
+  // The role_permissions and admin_users tables must be rolled back first
+  await knex.schema.dropTableIfExists('roles');
+
+  console.log('Roles table removed');
+};

backend/migrations/core/055_add_permissions_table.js

@@ -0,0 +1,122 @@
+/**
+ * Migration: Add Permissions Table
+ * Creates the permissions table for granular access control.
+ *
+ * Permission categories:
+ * - events: View, create, edit, delete, archive events
+ * - photos: View, upload, edit, delete, download photos
+ * - archives: View, restore, download, delete archives
+ * - analytics: View analytics and statistics
+ * - email: View, edit, send emails
+ * - branding: View and edit branding settings
+ * - cms: View and edit CMS pages
+ * - settings: View and edit application settings
+ * - backup: View, create, restore, delete backups
+ * - users: View, create, edit, delete admin users (Super Admin only)
+ * - activity: View and export activity logs
+ */
+
+exports.up = async function(knex) {
+  console.log('Creating permissions table...');
+
+  // Check if table already exists
+  const hasPermissionsTable = await knex.schema.hasTable('permissions');
+
+  if (!hasPermissionsTable) {
+    await knex.schema.createTable('permissions', (table) => {
+      table.increments('id').primary();
+      table.string('name', 100).unique().notNullable(); // 'events.create', 'users.manage', etc.
+      table.string('display_name', 150).notNullable();
+      table.string('category', 50).notNullable(); // 'events', 'photos', 'users', 'settings'
+      table.text('description');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+
+      // Indexes for efficient lookups
+      table.index(['name']);
+      table.index(['category']);
+    });
+
+    console.log('Permissions table created');
+  }
+
+  // Check for existing permissions
+  const existingPermissions = await knex('permissions').select('name');
+  const existingPermissionNames = existingPermissions.map(p => p.name);
+
+  // Define all permissions
+  const permissions = [
+    // Events
+    { name: 'events.view', display_name: 'View Events', category: 'events', description: 'View event list and details' },
+    { name: 'events.create', display_name: 'Create Events', category: 'events', description: 'Create new events' },
+    { name: 'events.edit', display_name: 'Edit Events', category: 'events', description: 'Edit existing events' },
+    { name: 'events.delete', display_name: 'Delete Events', category: 'events', description: 'Delete events' },
+    { name: 'events.archive', display_name: 'Archive Events', category: 'events', description: 'Archive and restore events' },
+
+    // Photos
+    { name: 'photos.view', display_name: 'View Photos', category: 'photos', description: 'View photos in events' },
+    { name: 'photos.upload', display_name: 'Upload Photos', category: 'photos', description: 'Upload photos to events' },
+    { name: 'photos.edit', display_name: 'Edit Photos', category: 'photos', description: 'Edit photo metadata and categories' },
+    { name: 'photos.delete', display_name: 'Delete Photos', category: 'photos', description: 'Delete photos from events' },
+    { name: 'photos.download', display_name: 'Download Photos', category: 'photos', description: 'Download photos and bulk export' },
+
+    // Archives
+    { name: 'archives.view', display_name: 'View Archives', category: 'archives', description: 'View archived events' },
+    { name: 'archives.restore', display_name: 'Restore Archives', category: 'archives', description: 'Restore archived events' },
+    { name: 'archives.download', display_name: 'Download Archives', category: 'archives', description: 'Download archive files' },
+    { name: 'archives.delete', display_name: 'Delete Archives', category: 'archives', description: 'Permanently delete archives' },
+
+    // Analytics
+    { name: 'analytics.view', display_name: 'View Analytics', category: 'analytics', description: 'View analytics and statistics' },
+
+    // Email
+    { name: 'email.view', display_name: 'View Email Settings', category: 'email', description: 'View email configuration' },
+    { name: 'email.edit', display_name: 'Edit Email Settings', category: 'email', description: 'Configure email settings and templates' },
+    { name: 'email.send', display_name: 'Send Emails', category: 'email', description: 'Send and resend gallery emails' },
+
+    // Branding & CMS
+    { name: 'branding.view', display_name: 'View Branding', category: 'branding', description: 'View branding settings' },
+    { name: 'branding.edit', display_name: 'Edit Branding', category: 'branding', description: 'Edit branding and theme settings' },
+    { name: 'cms.view', display_name: 'View CMS Pages', category: 'cms', description: 'View CMS content pages' },
+    { name: 'cms.edit', display_name: 'Edit CMS Pages', category: 'cms', description: 'Edit CMS content pages' },
+
+    // Settings
+    { name: 'settings.view', display_name: 'View Settings', category: 'settings', description: 'View application settings' },
+    { name: 'settings.edit', display_name: 'Edit Settings', category: 'settings', description: 'Modify application settings' },
+
+    // Backup
+    { name: 'backup.view', display_name: 'View Backups', category: 'backup', description: 'View backup status and history' },
+    { name: 'backup.create', display_name: 'Create Backups', category: 'backup', description: 'Create new backups' },
+    { name: 'backup.restore', display_name: 'Restore Backups', category: 'backup', description: 'Restore from backups' },
+    { name: 'backup.delete', display_name: 'Delete Backups', category: 'backup', description: 'Delete backup files' },
+
+    // User Management (Super Admin only)
+    { name: 'users.view', display_name: 'View Users', category: 'users', description: 'View admin user list' },
+    { name: 'users.create', display_name: 'Create Users', category: 'users', description: 'Invite new admin users' },
+    { name: 'users.edit', display_name: 'Edit Users', category: 'users', description: 'Edit admin user details and roles' },
+    { name: 'users.delete', display_name: 'Delete Users', category: 'users', description: 'Deactivate or delete admin users' },
+
+    // Activity Logs
+    { name: 'activity.view', display_name: 'View Activity Logs', category: 'activity', description: 'View system activity logs' },
+    { name: 'activity.export', display_name: 'Export Activity Logs', category: 'activity', description: 'Export activity logs' }
+  ];
+
+  // Filter out already existing permissions
+  const permissionsToInsert = permissions.filter(p => !existingPermissionNames.includes(p.name));
+
+  if (permissionsToInsert.length > 0) {
+    await knex('permissions').insert(permissionsToInsert);
+    console.log(`Inserted ${permissionsToInsert.length} permissions`);
+  }
+
+  console.log('Permissions table migration completed successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing permissions table...');
+
+  // Note: This will fail if there are foreign key references
+  // The role_permissions table must be rolled back first
+  await knex.schema.dropTableIfExists('permissions');
+
+  console.log('Permissions table removed');
+};

backend/migrations/core/056_add_role_permissions_table.js

@@ -0,0 +1,134 @@
+/**
+ * Migration: Add Role Permissions Junction Table
+ * Creates the junction table mapping permissions to roles.
+ *
+ * Role permission mappings:
+ * - super_admin: All permissions
+ * - admin: Events, Photos, Archives, Analytics, Email, Branding, CMS, Settings (view), Backup (view/create), Activity (view)
+ * - editor: View/Create/Edit own events and photos, Analytics (view), Activity (view)
+ * - viewer: View-only access to events, photos, archives, analytics, branding, cms
+ */
+
+exports.up = async function(knex) {
+  console.log('Creating role_permissions junction table...');
+
+  // Check if table already exists
+  const hasRolePermissionsTable = await knex.schema.hasTable('role_permissions');
+
+  if (!hasRolePermissionsTable) {
+    await knex.schema.createTable('role_permissions', (table) => {
+      table.integer('role_id').unsigned().references('id').inTable('roles').onDelete('CASCADE');
+      table.integer('permission_id').unsigned().references('id').inTable('permissions').onDelete('CASCADE');
+      table.primary(['role_id', 'permission_id']);
+
+      // Indexes for efficient lookups
+      table.index(['role_id']);
+      table.index(['permission_id']);
+    });
+
+    console.log('Role permissions junction table created');
+  }
+
+  // Get role and permission IDs
+  const roles = await knex('roles').select('id', 'name');
+  const permissions = await knex('permissions').select('id', 'name');
+
+  if (roles.length === 0 || permissions.length === 0) {
+    console.log('No roles or permissions found, skipping permission mappings');
+    return;
+  }
+
+  const roleMap = Object.fromEntries(roles.map(r => [r.name, r.id]));
+  const permMap = Object.fromEntries(permissions.map(p => [p.name, p.id]));
+
+  // Define role-permission mappings
+  const rolePermissions = {
+    super_admin: permissions.map(p => p.name), // All permissions
+    admin: [
+      // Events - full access
+      'events.view', 'events.create', 'events.edit', 'events.delete', 'events.archive',
+      // Photos - full access
+      'photos.view', 'photos.upload', 'photos.edit', 'photos.delete', 'photos.download',
+      // Archives - full access
+      'archives.view', 'archives.restore', 'archives.download', 'archives.delete',
+      // Analytics - view only
+      'analytics.view',
+      // Email - full access
+      'email.view', 'email.edit', 'email.send',
+      // Branding - full access
+      'branding.view', 'branding.edit',
+      // CMS - full access
+      'cms.view', 'cms.edit',
+      // Settings - view only
+      'settings.view',
+      // Backup - view and create only
+      'backup.view', 'backup.create',
+      // Activity - view only
+      'activity.view'
+    ],
+    editor: [
+      // Events - view, create, and edit (can only see their own events)
+      'events.view', 'events.create', 'events.edit',
+      // Photos - view, upload, edit (no delete)
+      'photos.view', 'photos.upload', 'photos.edit',
+      // Analytics - view only
+      'analytics.view',
+      // Activity - view only
+      'activity.view'
+    ],
+    viewer: [
+      // Events - view only
+      'events.view',
+      // Photos - view only
+      'photos.view',
+      // Archives - view only
+      'archives.view',
+      // Analytics - view only
+      'analytics.view',
+      // Branding - view only
+      'branding.view',
+      // CMS - view only
+      'cms.view'
+    ]
+  };
+
+  // Check for existing mappings to avoid duplicates
+  const existingMappings = await knex('role_permissions').select('role_id', 'permission_id');
+  const existingSet = new Set(existingMappings.map(m => `${m.role_id}-${m.permission_id}`));
+
+  // Build insert list
+  const inserts = [];
+  for (const [roleName, perms] of Object.entries(rolePermissions)) {
+    for (const permName of perms) {
+      if (roleMap[roleName] && permMap[permName]) {
+        const key = `${roleMap[roleName]}-${permMap[permName]}`;
+        if (!existingSet.has(key)) {
+          inserts.push({
+            role_id: roleMap[roleName],
+            permission_id: permMap[permName]
+          });
+        }
+      }
+    }
+  }
+
+  if (inserts.length > 0) {
+    // Insert in batches to avoid hitting database limits
+    const batchSize = 50;
+    for (let i = 0; i < inserts.length; i += batchSize) {
+      const batch = inserts.slice(i, i + batchSize);
+      await knex('role_permissions').insert(batch);
+    }
+    console.log(`Inserted ${inserts.length} role-permission mappings`);
+  }
+
+  console.log('Role permissions junction table migration completed successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing role_permissions junction table...');
+
+  await knex.schema.dropTableIfExists('role_permissions');
+
+  console.log('Role permissions junction table removed');
+};

backend/migrations/core/057_add_role_to_admin_users.js

@@ -0,0 +1,115 @@
+/**
+ * Migration: Add Role to Admin Users
+ * Adds RBAC-related columns to the admin_users table:
+ * - role_id: Foreign key to roles table
+ * - created_by: Foreign key to admin_users (who invited this user)
+ * - invite_token: Token for invitation acceptance (64 chars = 256 bits)
+ * - invite_expires_at: When the invitation token expires
+ * - invite_accepted_at: When the user accepted the invitation
+ *
+ * Also migrates existing admin users to super_admin role.
+ */
+
+exports.up = async function(knex) {
+  console.log('Adding role columns to admin_users table...');
+
+  // Check if columns already exist
+  const hasRoleId = await knex.schema.hasColumn('admin_users', 'role_id');
+  const hasCreatedBy = await knex.schema.hasColumn('admin_users', 'created_by');
+  const hasInviteToken = await knex.schema.hasColumn('admin_users', 'invite_token');
+  const hasInviteExpiresAt = await knex.schema.hasColumn('admin_users', 'invite_expires_at');
+  const hasInviteAcceptedAt = await knex.schema.hasColumn('admin_users', 'invite_accepted_at');
+
+  // Add new columns if they don't exist
+  if (!hasRoleId || !hasCreatedBy || !hasInviteToken || !hasInviteExpiresAt || !hasInviteAcceptedAt) {
+    await knex.schema.alterTable('admin_users', (table) => {
+      if (!hasRoleId) {
+        // Note: We add as nullable first, then set values, then alter to not null
+        table.integer('role_id').unsigned().references('id').inTable('roles').onDelete('SET NULL');
+      }
+      if (!hasCreatedBy) {
+        table.integer('created_by').unsigned().references('id').inTable('admin_users').onDelete('SET NULL');
+      }
+      if (!hasInviteToken) {
+        // 64 characters = 32 bytes hex = 256 bits of entropy (cryptographically secure)
+        table.string('invite_token', 64);
+      }
+      if (!hasInviteExpiresAt) {
+        table.timestamp('invite_expires_at');
+      }
+      if (!hasInviteAcceptedAt) {
+        table.timestamp('invite_accepted_at');
+      }
+    });
+
+    console.log('Role columns added to admin_users table');
+  }
+
+  // Add index on invite_token for fast lookup
+  const hasInviteTokenIndex = await knex.schema.hasColumn('admin_users', 'invite_token');
+  if (hasInviteTokenIndex) {
+    // Create index if it doesn't exist (safe for both PostgreSQL and SQLite)
+    try {
+      await knex.schema.alterTable('admin_users', (table) => {
+        table.index(['invite_token']);
+      });
+    } catch (e) {
+      // Index may already exist
+      if (!e.message.includes('already exists')) {
+        console.log('Note: invite_token index may already exist');
+      }
+    }
+  }
+
+  // Get super_admin role ID
+  const superAdminRole = await knex('roles').where('name', 'super_admin').first();
+
+  if (superAdminRole) {
+    // Migrate existing admin users without a role to super_admin
+    const usersWithoutRole = await knex('admin_users')
+      .whereNull('role_id')
+      .select('id');
+
+    if (usersWithoutRole.length > 0) {
+      await knex('admin_users')
+        .whereNull('role_id')
+        .update({ role_id: superAdminRole.id });
+
+      console.log(`Migrated ${usersWithoutRole.length} existing admin user(s) to super_admin role`);
+    }
+  } else {
+    console.log('Warning: super_admin role not found. Run migration 054 first.');
+  }
+
+  console.log('Admin users role migration completed successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing role columns from admin_users table...');
+
+  const hasRoleId = await knex.schema.hasColumn('admin_users', 'role_id');
+  const hasCreatedBy = await knex.schema.hasColumn('admin_users', 'created_by');
+  const hasInviteToken = await knex.schema.hasColumn('admin_users', 'invite_token');
+  const hasInviteExpiresAt = await knex.schema.hasColumn('admin_users', 'invite_expires_at');
+  const hasInviteAcceptedAt = await knex.schema.hasColumn('admin_users', 'invite_accepted_at');
+
+  await knex.schema.alterTable('admin_users', (table) => {
+    if (hasInviteAcceptedAt) {
+      table.dropColumn('invite_accepted_at');
+    }
+    if (hasInviteExpiresAt) {
+      table.dropColumn('invite_expires_at');
+    }
+    if (hasInviteToken) {
+      table.dropColumn('invite_token');
+    }
+    if (hasCreatedBy) {
+      table.dropColumn('created_by');
+    }
+    if (hasRoleId) {
+      table.dropColumn('role_id');
+    }
+  });
+
+  console.log('Role columns removed from admin_users table');
+};

backend/migrations/core/058_add_admin_invitations_table.js

@@ -0,0 +1,68 @@
+/**
+ * Migration: Add Admin Invitations Table
+ * Creates the admin_invitations table for managing pending admin user invitations.
+ *
+ * Security features:
+ * - Token is 64 characters (32 bytes hex = 256 bits of entropy)
+ * - Tokens are unique and indexed for fast lookup
+ * - Invitations have expiration timestamps
+ * - Tracks who invited whom and when accepted
+ * - Foreign key constraints with appropriate CASCADE behavior
+ */
+
+exports.up = async function(knex) {
+  console.log('Creating admin_invitations table...');
+
+  // Check if table already exists
+  const hasAdminInvitationsTable = await knex.schema.hasTable('admin_invitations');
+
+  if (!hasAdminInvitationsTable) {
+    await knex.schema.createTable('admin_invitations', (table) => {
+      table.increments('id').primary();
+
+      // Email of the invited user
+      table.string('email', 255).notNullable();
+
+      // Invitation token - 64 characters = 32 bytes hex = 256 bits of entropy
+      // Cryptographically secure for one-time use tokens
+      table.string('token', 64).unique().notNullable();
+
+      // Role to assign when invitation is accepted
+      table.integer('role_id').unsigned().references('id').inTable('roles').onDelete('CASCADE').notNullable();
+
+      // Who created this invitation
+      table.integer('invited_by').unsigned().references('id').inTable('admin_users').onDelete('CASCADE').notNullable();
+
+      // When the invitation expires (typically 7 days from creation)
+      table.timestamp('expires_at').notNullable();
+
+      // When the invitation was accepted (null if pending)
+      table.timestamp('accepted_at');
+
+      // The admin_user ID created when invitation was accepted (for audit trail)
+      table.integer('accepted_user_id').unsigned().references('id').inTable('admin_users').onDelete('SET NULL');
+
+      // When the invitation was created
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+
+      // Indexes for efficient lookups
+      table.index(['token']); // Fast token validation
+      table.index(['email']); // Check for existing invitations by email
+      table.index(['expires_at']); // Cleanup expired invitations
+      table.index(['invited_by']); // List invitations by inviter
+      table.index(['accepted_at']); // Filter pending vs accepted
+    });
+
+    console.log('Admin invitations table created');
+  }
+
+  console.log('Admin invitations table migration completed successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing admin_invitations table...');
+
+  await knex.schema.dropTableIfExists('admin_invitations');
+
+  console.log('Admin invitations table removed');
+};

backend/migrations/core/059_add_admin_email_templates.js

@@ -0,0 +1,314 @@
+/**
+ * Migration to add email templates for admin invitation and password reset
+ * These templates support the RBAC (Role-Based Access Control) feature
+ */
+exports.up = async function(knex) {
+  // First, ensure the email_templates table has multilingual columns
+  // This is needed for fresh installations where legacy migrations don't run
+  const columnInfo = await knex('email_templates').columnInfo();
+
+  if (!columnInfo.subject_en) {
+    // Need to add multilingual columns
+    console.log('Adding multilingual columns to email_templates table...');
+
+    // Check if we're using SQLite or PostgreSQL
+    const client = knex.client.config.client;
+    const isSqlite = client === 'sqlite3' || client === 'better-sqlite3';
+
+    if (isSqlite) {
+      // SQLite doesn't support column rename directly in all versions
+      // We need to recreate the table with new structure
+
+      // Get existing data
+      const existingData = await knex('email_templates').select('*');
+
+      // Drop the old table
+      await knex.schema.dropTable('email_templates');
+
+      // Create new table with multilingual columns
+      await knex.schema.createTable('email_templates', (table) => {
+        table.increments('id').primary();
+        table.string('template_key').unique().notNullable();
+        table.string('subject_en');
+        table.string('subject_de');
+        table.text('body_html_en');
+        table.text('body_html_de');
+        table.text('body_text_en');
+        table.text('body_text_de');
+        table.json('variables');
+        table.datetime('updated_at').defaultTo(knex.fn.now());
+      });
+
+      // Re-insert existing data with column mapping
+      for (const row of existingData) {
+        await knex('email_templates').insert({
+          template_key: row.template_key,
+          subject_en: row.subject,
+          subject_de: row.subject, // Copy to German as default
+          body_html_en: row.body_html,
+          body_html_de: row.body_html,
+          body_text_en: row.body_text,
+          body_text_de: row.body_text,
+          variables: row.variables,
+          updated_at: row.updated_at
+        });
+      }
+
+      console.log('Migrated email_templates table to multilingual structure');
+    } else {
+      // PostgreSQL supports ALTER TABLE for column operations
+      await knex.schema.alterTable('email_templates', (table) => {
+        table.renameColumn('subject', 'subject_en');
+        table.renameColumn('body_html', 'body_html_en');
+        table.renameColumn('body_text', 'body_text_en');
+      });
+
+      await knex.schema.alterTable('email_templates', (table) => {
+        table.string('subject_de');
+        table.text('body_html_de');
+        table.text('body_text_de');
+      });
+
+      // Copy English values to German as defaults
+      await knex('email_templates').update({
+        subject_de: knex.raw('subject_en'),
+        body_html_de: knex.raw('body_html_en'),
+        body_text_de: knex.raw('body_text_en')
+      });
+    }
+  }
+
+  // Check which templates already exist
+  const existingTemplates = await knex('email_templates')
+    .select('template_key')
+    .whereIn('template_key', ['admin_invitation', 'admin_password_reset']);
+
+  const existingKeys = existingTemplates.map(t => t.template_key);
+
+  // Admin Invitation Email Template
+  if (!existingKeys.includes('admin_invitation')) {
+    await knex('email_templates').insert({
+      template_key: 'admin_invitation',
+      subject_en: 'You have been invited to join PicPeak as {{role_name}}',
+      subject_de: 'Sie wurden eingeladen, PicPeak als {{role_name}} beizutreten',
+      body_html_en: `
+<h2>Welcome to PicPeak!</h2>
+
+<p>You have been invited to join the PicPeak photo sharing platform as a <strong>{{role_name}}</strong>.</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Your Role:</strong> {{role_name}}</p>
+  <p style="margin: 10px 0 0 0;">This role grants you access to manage and administer the photo sharing platform.</p>
+</div>
+
+<p>To accept this invitation and set up your account, click the button below:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{invite_link}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">Accept Invitation</a>
+</div>
+
+<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; color: #856404; padding: 15px; border-radius: 4px; margin: 20px 0;">
+  <p style="margin: 0;"><strong>Important:</strong> This invitation expires on <strong>{{expires_at}}</strong>. Please accept the invitation before this date.</p>
+</div>
+
+<p>If you did not expect this invitation or believe it was sent in error, you can safely ignore this email.</p>
+
+<p style="color: #666; font-size: 13px; margin-top: 30px;">
+  If the button above does not work, copy and paste this link into your browser:<br>
+  <a href="{{invite_link}}" style="color: #5C8762; word-break: break-all;">{{invite_link}}</a>
+</p>
+
+<p>Best regards,<br>
+The PicPeak Team</p>`,
+      body_text_en: `Welcome to PicPeak!
+
+You have been invited to join the PicPeak photo sharing platform as a {{role_name}}.
+
+Your Role: {{role_name}}
+This role grants you access to manage and administer the photo sharing platform.
+
+To accept this invitation and set up your account, visit the following link:
+{{invite_link}}
+
+IMPORTANT: This invitation expires on {{expires_at}}. Please accept the invitation before this date.
+
+If you did not expect this invitation or believe it was sent in error, you can safely ignore this email.
+
+Best regards,
+The PicPeak Team`,
+      body_html_de: `
+<h2>Willkommen bei PicPeak!</h2>
+
+<p>Sie wurden eingeladen, der PicPeak Foto-Sharing-Plattform als <strong>{{role_name}}</strong> beizutreten.</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Ihre Rolle:</strong> {{role_name}}</p>
+  <p style="margin: 10px 0 0 0;">Diese Rolle gewahrt Ihnen Zugang zur Verwaltung und Administration der Foto-Sharing-Plattform.</p>
+</div>
+
+<p>Um diese Einladung anzunehmen und Ihr Konto einzurichten, klicken Sie auf die Schaltflache unten:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{invite_link}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">Einladung annehmen</a>
+</div>
+
+<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; color: #856404; padding: 15px; border-radius: 4px; margin: 20px 0;">
+  <p style="margin: 0;"><strong>Wichtig:</strong> Diese Einladung lauft am <strong>{{expires_at}}</strong> ab. Bitte nehmen Sie die Einladung vor diesem Datum an.</p>
+</div>
+
+<p>Wenn Sie diese Einladung nicht erwartet haben oder glauben, dass sie irrtumlicherweise gesendet wurde, konnen Sie diese E-Mail ignorieren.</p>
+
+<p style="color: #666; font-size: 13px; margin-top: 30px;">
+  Wenn die Schaltflache oben nicht funktioniert, kopieren Sie diesen Link in Ihren Browser:<br>
+  <a href="{{invite_link}}" style="color: #5C8762; word-break: break-all;">{{invite_link}}</a>
+</p>
+
+<p>Mit freundlichen Grussen,<br>
+Ihr PicPeak-Team</p>`,
+      body_text_de: `Willkommen bei PicPeak!
+
+Sie wurden eingeladen, der PicPeak Foto-Sharing-Plattform als {{role_name}} beizutreten.
+
+Ihre Rolle: {{role_name}}
+Diese Rolle gewahrt Ihnen Zugang zur Verwaltung und Administration der Foto-Sharing-Plattform.
+
+Um diese Einladung anzunehmen und Ihr Konto einzurichten, besuchen Sie den folgenden Link:
+{{invite_link}}
+
+WICHTIG: Diese Einladung lauft am {{expires_at}} ab. Bitte nehmen Sie die Einladung vor diesem Datum an.
+
+Wenn Sie diese Einladung nicht erwartet haben oder glauben, dass sie irrtumlicherweise gesendet wurde, konnen Sie diese E-Mail ignorieren.
+
+Mit freundlichen Grussen,
+Ihr PicPeak-Team`,
+      variables: JSON.stringify(['invite_link', 'role_name', 'expires_at'])
+    });
+  }
+
+  // Admin Password Reset Email Template
+  if (!existingKeys.includes('admin_password_reset')) {
+    await knex('email_templates').insert({
+      template_key: 'admin_password_reset',
+      subject_en: 'Your PicPeak administrator password has been reset',
+      subject_de: 'Ihr PicPeak-Administratorpasswort wurde zuruckgesetzt',
+      body_html_en: `
+<h2>Password Reset Notification</h2>
+
+<p>Hello <strong>{{username}}</strong>,</p>
+
+<p>Your administrator password for PicPeak has been reset by a system administrator.</p>
+
+<div style="background-color: #f9f9f9; padding: 20px; border-radius: 8px; margin: 20px 0;">
+  <h3 style="margin-top: 0;">Your New Login Credentials:</h3>
+  <ul style="list-style: none; padding: 0;">
+    <li style="margin-bottom: 10px;"><strong>Username:</strong> {{username}}</li>
+    <li style="margin-bottom: 10px;"><strong>Temporary Password:</strong> <code style="background-color: #e9ecef; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 14px;">{{new_password}}</code></li>
+  </ul>
+</div>
+
+<div style="background-color: #fee; border: 1px solid #fcc; color: #c33; padding: 20px; border-radius: 8px; margin: 20px 0;">
+  <p style="margin: 0; font-weight: bold; font-size: 16px;">Security Notice</p>
+  <ul style="margin: 10px 0 0 0; padding-left: 20px;">
+    <li>This is a temporary password. Please change it immediately after logging in.</li>
+    <li>Never share your password with anyone.</li>
+    <li>If you did not request this password reset, please contact your system administrator immediately.</li>
+  </ul>
+</div>
+
+<p>To log in to the admin panel, click the button below:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{admin_login_url}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">Log In Now</a>
+</div>
+
+<p style="color: #666; font-size: 13px;">After logging in, navigate to your profile settings to change your password to something secure that only you know.</p>
+
+<p>Best regards,<br>
+The PicPeak Team</p>`,
+      body_text_en: `Password Reset Notification
+
+Hello {{username}},
+
+Your administrator password for PicPeak has been reset by a system administrator.
+
+Your New Login Credentials:
+- Username: {{username}}
+- Temporary Password: {{new_password}}
+
+SECURITY NOTICE:
+- This is a temporary password. Please change it immediately after logging in.
+- Never share your password with anyone.
+- If you did not request this password reset, please contact your system administrator immediately.
+
+To log in to the admin panel, visit: {{admin_login_url}}
+
+After logging in, navigate to your profile settings to change your password to something secure that only you know.
+
+Best regards,
+The PicPeak Team`,
+      body_html_de: `
+<h2>Benachrichtigung uber Passwortzurucksetzung</h2>
+
+<p>Hallo <strong>{{username}}</strong>,</p>
+
+<p>Ihr Administratorpasswort fur PicPeak wurde von einem Systemadministrator zuruckgesetzt.</p>
+
+<div style="background-color: #f9f9f9; padding: 20px; border-radius: 8px; margin: 20px 0;">
+  <h3 style="margin-top: 0;">Ihre neuen Anmeldedaten:</h3>
+  <ul style="list-style: none; padding: 0;">
+    <li style="margin-bottom: 10px;"><strong>Benutzername:</strong> {{username}}</li>
+    <li style="margin-bottom: 10px;"><strong>Vorlaufiges Passwort:</strong> <code style="background-color: #e9ecef; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 14px;">{{new_password}}</code></li>
+  </ul>
+</div>
+
+<div style="background-color: #fee; border: 1px solid #fcc; color: #c33; padding: 20px; border-radius: 8px; margin: 20px 0;">
+  <p style="margin: 0; font-weight: bold; font-size: 16px;">Sicherheitshinweis</p>
+  <ul style="margin: 10px 0 0 0; padding-left: 20px;">
+    <li>Dies ist ein vorlaufiges Passwort. Bitte andern Sie es sofort nach der Anmeldung.</li>
+    <li>Teilen Sie Ihr Passwort niemals mit anderen.</li>
+    <li>Wenn Sie diese Passwortzurucksetzung nicht angefordert haben, wenden Sie sich bitte umgehend an Ihren Systemadministrator.</li>
+  </ul>
+</div>
+
+<p>Um sich im Admin-Panel anzumelden, klicken Sie auf die Schaltflache unten:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{admin_login_url}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">Jetzt anmelden</a>
+</div>
+
+<p style="color: #666; font-size: 13px;">Nach der Anmeldung navigieren Sie zu Ihren Profileinstellungen, um Ihr Passwort in ein sicheres Passwort zu andern, das nur Sie kennen.</p>
+
+<p>Mit freundlichen Grussen,<br>
+Ihr PicPeak-Team</p>`,
+      body_text_de: `Benachrichtigung uber Passwortzurucksetzung
+
+Hallo {{username}},
+
+Ihr Administratorpasswort fur PicPeak wurde von einem Systemadministrator zuruckgesetzt.
+
+Ihre neuen Anmeldedaten:
+- Benutzername: {{username}}
+- Vorlaufiges Passwort: {{new_password}}
+
+SICHERHEITSHINWEIS:
+- Dies ist ein vorlaufiges Passwort. Bitte andern Sie es sofort nach der Anmeldung.
+- Teilen Sie Ihr Passwort niemals mit anderen.
+- Wenn Sie diese Passwortzurucksetzung nicht angefordert haben, wenden Sie sich bitte umgehend an Ihren Systemadministrator.
+
+Um sich im Admin-Panel anzumelden, besuchen Sie: {{admin_login_url}}
+
+Nach der Anmeldung navigieren Sie zu Ihren Profileinstellungen, um Ihr Passwort in ein sicheres Passwort zu andern, das nur Sie kennen.
+
+Mit freundlichen Grussen,
+Ihr PicPeak-Team`,
+      variables: JSON.stringify(['username', 'new_password', 'admin_login_url'])
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  // Remove the admin email templates
+  await knex('email_templates')
+    .whereIn('template_key', ['admin_invitation', 'admin_password_reset'])
+    .delete();
+};

backend/migrations/core/060_add_events_created_by.js

@@ -0,0 +1,23 @@
+/**
+ * Migration: Add created_by column to events table
+ * This allows filtering events by owner for role-based access control
+ */
+
+exports.up = async function(knex) {
+  // Add created_by column to events table
+  await knex.schema.alterTable('events', (table) => {
+    table.integer('created_by').unsigned().references('id').inTable('admin_users').onDelete('SET NULL');
+  });
+  
+  // Set existing events to be owned by the first admin (super_admin)
+  const superAdmin = await knex('admin_users').where('role_id', 1).first();
+  if (superAdmin) {
+    await knex('events').update({ created_by: superAdmin.id });
+  }
+};
+
+exports.down = async function(knex) {
+  await knex.schema.alterTable('events', (table) => {
+    table.dropColumn('created_by');
+  });
+};

backend/migrations/core/061_add_event_types_table.js

@@ -0,0 +1,107 @@
+/**
+ * Migration: Add event_types table
+ *
+ * Creates a customizable event types system to replace hardcoded event types.
+ * This allows users to:
+ * - Rename existing event types (wedding, birthday, corporate, other)
+ * - Create custom event types with custom slug prefixes
+ * - Associate default theme presets with event types
+ *
+ * Backward compatible: Existing events keep their event_type strings.
+ * New events can use either legacy strings or custom event type slug_prefix.
+ */
+
+const { createTableIfNotExists, insertIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Creating event_types table...');
+
+  // Create event_types table
+  const hasEventTypesTable = await knex.schema.hasTable('event_types');
+  if (!hasEventTypesTable) {
+    await knex.schema.createTable('event_types', (table) => {
+      table.increments('id').primary();
+      table.string('name', 100).notNullable(); // Display name: "Family Shoot"
+      table.string('slug_prefix', 50).unique().notNullable(); // URL prefix: "family"
+      table.string('emoji', 10); // Icon emoji: "👨‍👩‍👧"
+      table.string('theme_preset', 50); // Default theme: "elegantWedding"
+      table.text('theme_config'); // Custom theme JSON overrides (optional)
+      table.integer('display_order').defaultTo(0); // Sorting in dropdowns
+      table.boolean('is_system').defaultTo(false); // Protect default types
+      table.boolean('is_active').defaultTo(true); // Allow hiding types
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+
+      // Indexes for performance
+      table.index('slug_prefix');
+      table.index('display_order');
+      table.index('is_active');
+    });
+    console.log('event_types table created');
+  } else {
+    console.log('event_types table already exists, skipping creation');
+  }
+
+  // Seed default event types (matching current hardcoded values)
+  const existingTypes = await knex('event_types').select('slug_prefix');
+  const existingSlugs = existingTypes.map(t => t.slug_prefix);
+
+  const defaultTypes = [
+    {
+      name: 'Wedding',
+      slug_prefix: 'wedding',
+      emoji: '💒',
+      theme_preset: 'elegantWedding',
+      display_order: 1,
+      is_system: true,
+      is_active: true
+    },
+    {
+      name: 'Birthday',
+      slug_prefix: 'birthday',
+      emoji: '🎂',
+      theme_preset: 'birthdayFun',
+      display_order: 2,
+      is_system: true,
+      is_active: true
+    },
+    {
+      name: 'Corporate',
+      slug_prefix: 'corporate',
+      emoji: '🏢',
+      theme_preset: 'corporateTimeline',
+      display_order: 3,
+      is_system: true,
+      is_active: true
+    },
+    {
+      name: 'Other',
+      slug_prefix: 'other',
+      emoji: '📸',
+      theme_preset: 'default',
+      display_order: 4,
+      is_system: true,
+      is_active: true
+    }
+  ];
+
+  const typesToInsert = defaultTypes.filter(type => !existingSlugs.includes(type.slug_prefix));
+
+  if (typesToInsert.length > 0) {
+    await knex('event_types').insert(typesToInsert);
+    console.log(`Inserted ${typesToInsert.length} default event types`);
+  } else {
+    console.log('Default event types already exist, skipping seed');
+  }
+
+  console.log('Migration 061_add_event_types_table completed successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Rolling back event_types table...');
+
+  // Drop the table (data will be lost)
+  await knex.schema.dropTableIfExists('event_types');
+
+  console.log('event_types table dropped');
+};

backend/migrations/core/061_add_optional_date_expiration_settings.js

@@ -0,0 +1,53 @@
+/**
+ * Migration: Add optional event date and expiration settings
+ * These settings control whether event_date and expiration are required
+ * when creating new events, supporting non-event use cases like portraits.
+ */
+
+exports.up = async function(knex) {
+  // Add new settings for optional date and expiration
+  const settings = [
+    { setting_key: 'event_require_event_date', setting_value: JSON.stringify(true), setting_type: 'boolean' },
+    { setting_key: 'event_require_expiration', setting_value: JSON.stringify(true), setting_type: 'boolean' }
+  ];
+
+  for (const setting of settings) {
+    const exists = await knex('app_settings').where('setting_key', setting.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({
+        ...setting,
+        updated_at: knex.fn.now()
+      });
+    }
+  }
+
+  // Make event_date and expires_at columns nullable
+  // PostgreSQL supports ALTER COLUMN ... DROP NOT NULL
+  // SQLite requires table recreation (handled differently)
+  const client = knex.client.config.client;
+
+  if (client === 'pg' || client === 'postgresql') {
+    // PostgreSQL: directly alter columns
+    await knex.raw('ALTER TABLE events ALTER COLUMN event_date DROP NOT NULL');
+    await knex.raw('ALTER TABLE events ALTER COLUMN expires_at DROP NOT NULL');
+  } else if (client === 'sqlite3' || client === 'better-sqlite3') {
+    // SQLite: columns are already effectively nullable in most cases
+    // SQLite doesn't enforce NOT NULL as strictly, and altering requires table recreation
+    // For safety, we'll skip the schema change for SQLite as it's complex
+    // The application logic will handle null values appropriately
+    console.log('SQLite detected - skipping schema alteration (columns will accept NULL values)');
+  }
+};
+
+exports.down = async function(knex) {
+  // Remove the settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'event_require_event_date',
+      'event_require_expiration'
+    ])
+    .del();
+
+  // Note: We don't restore NOT NULL constraints as that could fail
+  // if there are existing NULL values in the database
+};

backend/migrations/core/061_add_watermark_path.js

@@ -0,0 +1,28 @@
+/**
+ * Migration 061: Add pre-generated watermark path to photos table
+ * - photos.watermark_path: path to pre-generated watermarked image
+ * - photos.watermark_generated_at: timestamp of watermark generation
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 061_add_watermark_path');
+
+  // photos.watermark_path (nullable - path to pre-generated watermarked image)
+  await addColumnIfNotExists(knex, 'photos', 'watermark_path', (table) => {
+    table.string('watermark_path', 512);
+  });
+
+  // photos.watermark_generated_at (nullable - when watermark was last generated)
+  await addColumnIfNotExists(knex, 'photos', 'watermark_generated_at', (table) => {
+    table.timestamp('watermark_generated_at');
+  });
+
+  console.log('Migration 061_add_watermark_path completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 061_add_watermark_path');
+  // Keep columns (safe rollback not removing data). Intentionally no-op.
+};

backend/migrations/core/062_add_hero_logo_settings.js

@@ -0,0 +1,70 @@
+/**
+ * Migration: Add hero logo customization settings to events table
+ *
+ * Allows per-event customization of the hero gallery logo:
+ * - hero_logo_visible: Show/hide the logo overlay
+ * - hero_logo_size: Logo size (small, medium, large, xlarge)
+ * - hero_logo_position: Logo position (top, center, bottom)
+ *
+ * Addresses GitHub Issue #138: Add Option to customize the Hero gallery layout
+ */
+
+exports.up = async function (knex) {
+  console.log('Adding hero logo settings to events table...');
+
+  // Add hero_logo_visible column
+  const hasVisibleColumn = await knex.schema.hasColumn('events', 'hero_logo_visible');
+  if (!hasVisibleColumn) {
+    await knex.schema.table('events', (table) => {
+      table.boolean('hero_logo_visible').notNullable().defaultTo(true);
+    });
+    console.log('Added hero_logo_visible column');
+  }
+
+  // Add hero_logo_size column
+  const hasSizeColumn = await knex.schema.hasColumn('events', 'hero_logo_size');
+  if (!hasSizeColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_size', 20).notNullable().defaultTo('medium');
+    });
+    console.log('Added hero_logo_size column');
+  }
+
+  // Add hero_logo_position column
+  const hasPositionColumn = await knex.schema.hasColumn('events', 'hero_logo_position');
+  if (!hasPositionColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_position', 20).notNullable().defaultTo('top');
+    });
+    console.log('Added hero_logo_position column');
+  }
+
+  console.log('Migration 062_add_hero_logo_settings completed successfully');
+};
+
+exports.down = async function (knex) {
+  console.log('Rolling back hero logo settings...');
+
+  const hasVisibleColumn = await knex.schema.hasColumn('events', 'hero_logo_visible');
+  if (hasVisibleColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_visible');
+    });
+  }
+
+  const hasSizeColumn = await knex.schema.hasColumn('events', 'hero_logo_size');
+  if (hasSizeColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_size');
+    });
+  }
+
+  const hasPositionColumn = await knex.schema.hasColumn('events', 'hero_logo_position');
+  if (hasPositionColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_position');
+    });
+  }
+
+  console.log('Hero logo settings columns dropped');
+};

backend/migrations/core/062_add_original_filename.js

@@ -0,0 +1,23 @@
+/**
+ * Migration 062: Add original_filename to photos table
+ * - photos.original_filename: preserves the original filename from upload
+ *   This enables Lightroom integration by exporting filtered filenames
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 062_add_original_filename');
+
+  // photos.original_filename (nullable - original filename before renaming)
+  await addColumnIfNotExists(knex, 'photos', 'original_filename', (table) => {
+    table.string('original_filename', 512);
+  });
+
+  console.log('Migration 062_add_original_filename completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 062_add_original_filename');
+  // Keep column (safe rollback not removing data). Intentionally no-op.
+};

backend/migrations/core/063_add_event_custom_logo.js

@@ -0,0 +1,53 @@
+/**
+ * Migration: Add custom logo support to events table
+ *
+ * Allows per-event custom logo that overrides the global branding logo:
+ * - hero_logo_url: Public path to the uploaded custom logo
+ * - hero_logo_path: Full filesystem path to the custom logo
+ *
+ * Logo priority: Event custom logo > Global branding logo > Default PicPeak logo
+ *
+ * Addresses GitHub Issue #138: Per-event custom logo option
+ */
+
+exports.up = async function (knex) {
+  console.log('Adding custom logo columns to events table...');
+
+  const hasUrlColumn = await knex.schema.hasColumn('events', 'hero_logo_url');
+  if (!hasUrlColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_url', 500).nullable().defaultTo(null);
+    });
+    console.log('Added hero_logo_url column');
+  }
+
+  const hasPathColumn = await knex.schema.hasColumn('events', 'hero_logo_path');
+  if (!hasPathColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_path', 500).nullable().defaultTo(null);
+    });
+    console.log('Added hero_logo_path column');
+  }
+
+  console.log('Migration 063_add_event_custom_logo completed successfully');
+};
+
+exports.down = async function (knex) {
+  console.log('Rolling back custom logo columns...');
+
+  const hasUrlColumn = await knex.schema.hasColumn('events', 'hero_logo_url');
+  if (hasUrlColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_url');
+    });
+  }
+
+  const hasPathColumn = await knex.schema.hasColumn('events', 'hero_logo_path');
+  if (hasPathColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_path');
+    });
+  }
+
+  console.log('Custom logo columns dropped');
+};

backend/migrations/core/064_backfill_photo_dimensions.js

@@ -0,0 +1,105 @@
+/**
+ * Migration: Backfill photo dimensions
+ *
+ * This migration extracts width/height from existing photos that don't have
+ * these dimensions stored. This is needed for aspect-ratio-aware layouts
+ * (masonry, mosaic, justified) to work properly.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+exports.up = async function(knex) {
+  // Check if the width/height columns exist
+  const hasWidth = await knex.schema.hasColumn('photos', 'width');
+  const hasHeight = await knex.schema.hasColumn('photos', 'height');
+
+  if (!hasWidth || !hasHeight) {
+    console.log('[Migration 064] Width/height columns not found, skipping backfill');
+    return;
+  }
+
+  // Get storage path
+  const storagePath = process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
+
+  // Find photos without dimensions
+  const photos = await knex('photos')
+    .whereNull('width')
+    .orWhereNull('height')
+    .select('id', 'path', 'filename', 'media_type');
+
+  console.log(`[Migration 064] Found ${photos.length} photos without dimensions`);
+
+  if (photos.length === 0) {
+    return;
+  }
+
+  // Import sharp dynamically (only needed during migration)
+  let sharp;
+  try {
+    sharp = require('sharp');
+  } catch (err) {
+    console.error('[Migration 064] Sharp not available, skipping backfill:', err.message);
+    return;
+  }
+
+  let updated = 0;
+  let failed = 0;
+
+  for (const photo of photos) {
+    try {
+      // Skip videos - they need ffprobe for metadata
+      if (photo.media_type === 'video') {
+        continue;
+      }
+
+      // Construct the full file path
+      let fullPath;
+      if (photo.path) {
+        // Path is relative to events/active directory
+        fullPath = path.join(storagePath, 'events/active', photo.path);
+      } else {
+        console.warn(`[Migration 064] Photo ${photo.id} (${photo.filename}) has no path, skipping`);
+        continue;
+      }
+
+      // Check if file exists
+      if (!fs.existsSync(fullPath)) {
+        console.warn(`[Migration 064] Photo ${photo.id} file not found: ${fullPath}`);
+        failed++;
+        continue;
+      }
+
+      // Extract dimensions using sharp
+      const metadata = await sharp(fullPath).metadata();
+
+      if (metadata.width && metadata.height) {
+        await knex('photos')
+          .where('id', photo.id)
+          .update({
+            width: metadata.width,
+            height: metadata.height
+          });
+        updated++;
+
+        if (updated % 50 === 0) {
+          console.log(`[Migration 064] Updated ${updated} photos...`);
+        }
+      } else {
+        console.warn(`[Migration 064] Could not extract dimensions for photo ${photo.id}`);
+        failed++;
+      }
+    } catch (err) {
+      console.error(`[Migration 064] Error processing photo ${photo.id}:`, err.message);
+      failed++;
+    }
+  }
+
+  console.log(`[Migration 064] Completed: ${updated} updated, ${failed} failed`);
+};
+
+exports.down = async function(knex) {
+  // This migration only adds data, no rollback needed
+  // We don't want to null out dimensions on rollback as they're still valid
+  console.log('[Migration 064] Rollback: No action needed (data-only migration)');
+};

backend/migrations/core/065_add_header_style.js

@@ -0,0 +1,131 @@
+/**
+ * Migration: Add header_style and hero_divider_style columns
+ *
+ * This migration decouples the hero header style from gallery layout,
+ * allowing any combination of header style with any layout type.
+ */
+
+exports.up = async function(knex) {
+  console.log('[Migration 065] Adding header_style and hero_divider_style columns');
+
+  // Check if columns already exist
+  const hasHeaderStyle = await knex.schema.hasColumn('events', 'header_style');
+  const hasDividerStyle = await knex.schema.hasColumn('events', 'hero_divider_style');
+
+  if (!hasHeaderStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.string('header_style', 20).defaultTo('standard');
+    });
+    console.log('[Migration 065] Added header_style column');
+  }
+
+  if (!hasDividerStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.string('hero_divider_style', 20).defaultTo('wave');
+    });
+    console.log('[Migration 065] Added hero_divider_style column');
+  }
+
+  // Migrate existing events with hero layout in color_theme
+  console.log('[Migration 065] Migrating existing hero layouts...');
+
+  const events = await knex('events')
+    .whereNotNull('color_theme')
+    .select('id', 'color_theme');
+
+  let migratedCount = 0;
+
+  for (const event of events) {
+    try {
+      // Skip if color_theme is not JSON
+      if (!event.color_theme || !event.color_theme.startsWith('{')) {
+        continue;
+      }
+
+      const theme = JSON.parse(event.color_theme);
+
+      // Check if this event uses hero layout
+      if (theme.galleryLayout === 'hero') {
+        // Migrate: set headerStyle to 'hero' and galleryLayout to 'grid'
+        const updatedTheme = {
+          ...theme,
+          headerStyle: 'hero',
+          galleryLayout: 'grid',
+          heroDividerStyle: theme.heroDividerStyle || 'wave'
+        };
+
+        await knex('events')
+          .where('id', event.id)
+          .update({
+            color_theme: JSON.stringify(updatedTheme),
+            header_style: 'hero',
+            hero_divider_style: theme.heroDividerStyle || 'wave'
+          });
+
+        migratedCount++;
+      }
+    } catch (err) {
+      // Invalid JSON in color_theme, skip
+      console.warn(`[Migration 065] Could not parse color_theme for event ${event.id}: ${err.message}`);
+    }
+  }
+
+  console.log(`[Migration 065] Migrated ${migratedCount} events from hero layout`);
+  console.log('[Migration 065] Completed');
+};
+
+exports.down = async function(knex) {
+  console.log('[Migration 065] Removing header_style and hero_divider_style columns');
+
+  // First, migrate any hero header styles back to hero layout
+  const events = await knex('events')
+    .where('header_style', 'hero')
+    .whereNotNull('color_theme')
+    .select('id', 'color_theme');
+
+  for (const event of events) {
+    try {
+      if (!event.color_theme || !event.color_theme.startsWith('{')) {
+        continue;
+      }
+
+      const theme = JSON.parse(event.color_theme);
+
+      // Revert: set galleryLayout back to 'hero'
+      const revertedTheme = {
+        ...theme,
+        galleryLayout: 'hero'
+      };
+
+      // Remove the new properties
+      delete revertedTheme.headerStyle;
+      delete revertedTheme.heroDividerStyle;
+
+      await knex('events')
+        .where('id', event.id)
+        .update({
+          color_theme: JSON.stringify(revertedTheme)
+        });
+    } catch (err) {
+      console.warn(`[Migration 065] Could not revert color_theme for event ${event.id}: ${err.message}`);
+    }
+  }
+
+  // Remove the columns
+  const hasHeaderStyle = await knex.schema.hasColumn('events', 'header_style');
+  const hasDividerStyle = await knex.schema.hasColumn('events', 'hero_divider_style');
+
+  if (hasHeaderStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('header_style');
+    });
+  }
+
+  if (hasDividerStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('hero_divider_style');
+    });
+  }
+
+  console.log('[Migration 065] Rollback completed');
+};

backend/migrations/core/066_add_hero_anchor_and_category_hero.js

@@ -0,0 +1,48 @@
+/**
+ * Migration: Add hero image anchor position and category-specific hero images
+ *
+ * Issue #162: Add hero_image_anchor column to events table for controlling
+ *             how hero images are cropped (top/center/bottom)
+ *
+ * Issue #163: Add hero_photo_id column to photo_categories table for
+ *             category-specific hero images
+ */
+
+exports.up = async function(knex) {
+  // Add hero_image_anchor to events table (Issue #162)
+  const hasHeroAnchor = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasHeroAnchor) {
+    await knex.schema.alterTable('events', function(table) {
+      // Values: 'top', 'center', 'bottom' - defaults to 'center' for backward compatibility
+      table.string('hero_image_anchor', 10).defaultTo('center');
+    });
+    console.log('Added hero_image_anchor column to events table');
+  }
+
+  // Add hero_photo_id to photo_categories table (Issue #163)
+  const hasCategoryHero = await knex.schema.hasColumn('photo_categories', 'hero_photo_id');
+  if (!hasCategoryHero) {
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.integer('hero_photo_id').references('id').inTable('photos').onDelete('SET NULL');
+    });
+    console.log('Added hero_photo_id column to photo_categories table');
+  }
+};
+
+exports.down = async function(knex) {
+  // Remove hero_image_anchor from events table
+  const hasHeroAnchor = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (hasHeroAnchor) {
+    await knex.schema.alterTable('events', function(table) {
+      table.dropColumn('hero_image_anchor');
+    });
+  }
+
+  // Remove hero_photo_id from photo_categories table
+  const hasCategoryHero = await knex.schema.hasColumn('photo_categories', 'hero_photo_id');
+  if (hasCategoryHero) {
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.dropColumn('hero_photo_id');
+    });
+  }
+};

backend/migrations/core/067_expand_hero_image_anchor.js

@@ -0,0 +1,32 @@
+/**
+ * Migration: Expand hero_image_anchor column to support focal point percentages
+ *
+ * Changes string(10) to string(20) so values like "100% 100%" (9 chars) fit
+ * with room to spare. Existing 'top', 'center', 'bottom' values are preserved.
+ */
+
+exports.up = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasColumn) {
+    // Column doesn't exist yet – nothing to expand
+    return;
+  }
+
+  // SQLite doesn't truly support ALTER COLUMN, but Knex handles the
+  // rebuild-table strategy internally when we call alterTable.
+  await knex.schema.alterTable('events', function(table) {
+    table.string('hero_image_anchor', 20).defaultTo('center').alter();
+  });
+  console.log('Expanded hero_image_anchor column to string(20)');
+};
+
+exports.down = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasColumn) {
+    return;
+  }
+
+  await knex.schema.alterTable('events', function(table) {
+    table.string('hero_image_anchor', 10).defaultTo('center').alter();
+  });
+};

backend/migrations/core/068_add_seo_robots_settings.js

@@ -0,0 +1,54 @@
+const DEFAULT_AI_AGENTS = [
+  'GPTBot',
+  'ChatGPT-User',
+  'Google-Extended',
+  'Claude-Web',
+  'Anthropic-AI',
+  'CCBot',
+  'Bytespider',
+  'FacebookBot',
+  'Omgilibot',
+  'Diffbot',
+  'PetalBot',
+  'Amazonbot',
+  'PerplexityBot',
+  'YouBot',
+  'Applebot-Extended'
+];
+
+exports.up = async function(knex) {
+  const defaults = [
+    { setting_key: 'seo_allow_indexing', setting_value: JSON.stringify(false), setting_type: 'seo' },
+    { setting_key: 'seo_block_ai_crawlers', setting_value: JSON.stringify(true), setting_type: 'seo' },
+    { setting_key: 'seo_block_social_bots', setting_value: JSON.stringify(false), setting_type: 'seo' },
+    { setting_key: 'seo_blocked_ai_agents', setting_value: JSON.stringify(DEFAULT_AI_AGENTS), setting_type: 'seo' },
+    { setting_key: 'seo_custom_rules', setting_value: JSON.stringify([]), setting_type: 'seo' },
+    { setting_key: 'seo_meta_noindex', setting_value: JSON.stringify(true), setting_type: 'seo' },
+    { setting_key: 'seo_meta_nofollow', setting_value: JSON.stringify(false), setting_type: 'seo' },
+    { setting_key: 'seo_meta_noai', setting_value: JSON.stringify(true), setting_type: 'seo' },
+    { setting_key: 'seo_sitemap_url', setting_value: JSON.stringify(''), setting_type: 'seo' }
+  ];
+
+  for (const setting of defaults) {
+    const exists = await knex('app_settings').where('setting_key', setting.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({ ...setting, updated_at: knex.fn.now() });
+    }
+  }
+};
+
+exports.down = async function(knex) {
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'seo_allow_indexing',
+      'seo_block_ai_crawlers',
+      'seo_block_social_bots',
+      'seo_blocked_ai_agents',
+      'seo_custom_rules',
+      'seo_meta_noindex',
+      'seo_meta_nofollow',
+      'seo_meta_noai',
+      'seo_sitemap_url'
+    ])
+    .del();
+};

backend/migrations/core/069_add_hero_path.js

@@ -0,0 +1,22 @@
+/**
+ * Migration 069: Add hero image path to photos table
+ * - photos.hero_path: path to hero-optimized image (1920x1080) for gallery headers
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 069_add_hero_path');
+
+  // photos.hero_path (nullable - path to hero-optimized image)
+  await addColumnIfNotExists(knex, 'photos', 'hero_path', (table) => {
+    table.string('hero_path', 512);
+  });
+
+  console.log('Migration 069_add_hero_path completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 069_add_hero_path');
+  // Keep columns (safe rollback not removing data). Intentionally no-op.
+};

backend/migrations/core/070_add_update_notification_settings.js

@@ -0,0 +1,161 @@
+/**
+ * Migration 070: Add update notification settings and email template
+ * - Settings for email notifications when new versions are available
+ * - Email template for version update notifications
+ */
+
+exports.up = async function(knex) {
+  console.log('Running migration: 070_add_update_notification_settings');
+
+  // Add app_settings for update notifications
+  const settings = [
+    {
+      setting_key: 'update_email_notifications_enabled',
+      setting_value: JSON.stringify(false),
+      setting_type: 'notifications'
+    },
+    {
+      setting_key: 'update_email_recipients',
+      setting_value: JSON.stringify(''), // Comma-separated emails, or empty for all admin emails
+      setting_type: 'notifications'
+    },
+    {
+      setting_key: 'last_notified_version',
+      setting_value: JSON.stringify(''),
+      setting_type: 'notifications'
+    }
+  ];
+
+  for (const setting of settings) {
+    const exists = await knex('app_settings').where('setting_key', setting.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({ ...setting, updated_at: knex.fn.now() });
+    }
+  }
+
+  // Check if email template already exists
+  const existingTemplate = await knex('email_templates')
+    .where('template_key', 'version_update_available')
+    .first();
+
+  if (!existingTemplate) {
+    await knex('email_templates').insert({
+      template_key: 'version_update_available',
+      subject_en: 'PicPeak Update Available: Version {{new_version}}',
+      subject_de: 'PicPeak Update verfugbar: Version {{new_version}}',
+      body_html_en: `
+<h2>A New Version of PicPeak is Available</h2>
+
+<p>Great news! A new version of PicPeak is available for your installation.</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Current Version:</strong> {{current_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>New Version:</strong> {{new_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Channel:</strong> {{channel}}</p>
+</div>
+
+<h3>What's New?</h3>
+<p>Check the release notes to see what's included in this update:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{release_notes_url}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">View Release Notes</a>
+</div>
+
+<h3>How to Update</h3>
+<p>To update your installation, log in to the admin panel and click on the "Update Available" notification. You'll find environment-specific instructions there.</p>
+
+<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; color: #856404; padding: 15px; border-radius: 4px; margin: 20px 0;">
+  <p style="margin: 0;"><strong>Reminder:</strong> Always backup your database before updating to ensure you can recover if anything goes wrong.</p>
+</div>
+
+<p>Best regards,<br>
+Your PicPeak Installation</p>`,
+      body_text_en: `A New Version of PicPeak is Available
+
+Great news! A new version of PicPeak is available for your installation.
+
+Current Version: {{current_version}}
+New Version: {{new_version}}
+Channel: {{channel}}
+
+What's New?
+Check the release notes to see what's included in this update:
+{{release_notes_url}}
+
+How to Update
+To update your installation, log in to the admin panel and click on the "Update Available" notification. You'll find environment-specific instructions there.
+
+REMINDER: Always backup your database before updating to ensure you can recover if anything goes wrong.
+
+Best regards,
+Your PicPeak Installation`,
+      body_html_de: `
+<h2>Eine neue Version von PicPeak ist verfugbar</h2>
+
+<p>Gute Neuigkeiten! Eine neue Version von PicPeak ist fur Ihre Installation verfugbar.</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Aktuelle Version:</strong> {{current_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Neue Version:</strong> {{new_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Kanal:</strong> {{channel}}</p>
+</div>
+
+<h3>Was ist neu?</h3>
+<p>Schauen Sie sich die Versionshinweise an, um zu sehen, was in diesem Update enthalten ist:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{release_notes_url}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">Versionshinweise anzeigen</a>
+</div>
+
+<h3>So aktualisieren Sie</h3>
+<p>Um Ihre Installation zu aktualisieren, melden Sie sich im Admin-Panel an und klicken Sie auf die Benachrichtigung "Update verfugbar". Dort finden Sie umgebungsspezifische Anweisungen.</p>
+
+<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; color: #856404; padding: 15px; border-radius: 4px; margin: 20px 0;">
+  <p style="margin: 0;"><strong>Erinnerung:</strong> Erstellen Sie immer ein Backup Ihrer Datenbank, bevor Sie aktualisieren, um sicherzustellen, dass Sie im Fehlerfall wiederherstellen konnen.</p>
+</div>
+
+<p>Mit freundlichen Grussen,<br>
+Ihre PicPeak-Installation</p>`,
+      body_text_de: `Eine neue Version von PicPeak ist verfugbar
+
+Gute Neuigkeiten! Eine neue Version von PicPeak ist fur Ihre Installation verfugbar.
+
+Aktuelle Version: {{current_version}}
+Neue Version: {{new_version}}
+Kanal: {{channel}}
+
+Was ist neu?
+Schauen Sie sich die Versionshinweise an, um zu sehen, was in diesem Update enthalten ist:
+{{release_notes_url}}
+
+So aktualisieren Sie
+Um Ihre Installation zu aktualisieren, melden Sie sich im Admin-Panel an und klicken Sie auf die Benachrichtigung "Update verfugbar". Dort finden Sie umgebungsspezifische Anweisungen.
+
+ERINNERUNG: Erstellen Sie immer ein Backup Ihrer Datenbank, bevor Sie aktualisieren, um sicherzustellen, dass Sie im Fehlerfall wiederherstellen konnen.
+
+Mit freundlichen Grussen,
+Ihre PicPeak-Installation`,
+      variables: JSON.stringify(['current_version', 'new_version', 'channel', 'release_notes_url'])
+    });
+  }
+
+  console.log('Migration 070_add_update_notification_settings completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 070_add_update_notification_settings');
+
+  // Remove settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'update_email_notifications_enabled',
+      'update_email_recipients',
+      'last_notified_version'
+    ])
+    .del();
+
+  // Remove email template
+  await knex('email_templates')
+    .where('template_key', 'version_update_available')
+    .del();
+};

backend/migrations/core/071_add_captured_at.js

@@ -0,0 +1,42 @@
+/**
+ * Migration 071: Add captured_at column to photos table
+ * - Stores the original capture date from EXIF metadata
+ * - Enables sorting photos by capture date instead of upload date
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 071_add_captured_at');
+
+  // Add captured_at column to photos table
+  await addColumnIfNotExists(knex, 'photos', 'captured_at', (table) => {
+    table.datetime('captured_at').nullable();
+  });
+
+  // Add index for sorting performance
+  const indexExists = await knex.schema.hasIndex
+    ? await knex.schema.hasIndex('photos', 'idx_photos_captured_at')
+    : false;
+
+  if (!indexExists) {
+    // Use raw query for index creation with IF NOT EXISTS
+    const client = knex.client.config.client;
+    if (client === 'pg') {
+      await knex.raw('CREATE INDEX IF NOT EXISTS idx_photos_captured_at ON photos(captured_at)');
+    } else if (client === 'sqlite3' || client === 'better-sqlite3') {
+      // SQLite doesn't support IF NOT EXISTS for indexes, so we need to check first
+      const existingIndexes = await knex.raw("SELECT name FROM sqlite_master WHERE type='index' AND name='idx_photos_captured_at'");
+      if (existingIndexes.length === 0) {
+        await knex.raw('CREATE INDEX idx_photos_captured_at ON photos(captured_at)');
+      }
+    }
+  }
+
+  console.log('Migration 071_add_captured_at completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 071_add_captured_at');
+  // Keep column for safe rollback (intentionally no-op)
+};

backend/migrations/core/073_make_event_emails_nullable.js

@@ -0,0 +1,13 @@
+exports.up = async function(knex) {
+  await knex.schema.alterTable('events', (table) => {
+    table.string('host_email', 255).nullable().alter();
+    table.string('admin_email', 255).nullable().alter();
+  });
+};
+
+exports.down = async function(knex) {
+  await knex.schema.alterTable('events', (table) => {
+    table.string('host_email', 255).notNullable().defaultTo('').alter();
+    table.string('admin_email', 255).notNullable().defaultTo('').alter();
+  });
+};

backend/migrations/core/074_add_photo_cap.js

@@ -0,0 +1,13 @@
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 074_add_photo_cap');
+  await addColumnIfNotExists(knex, 'events', 'photo_cap', (table) => {
+    table.integer('photo_cap').nullable().defaultTo(null);
+  });
+  console.log('Migration 074_add_photo_cap completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 074_add_photo_cap');
+};

backend/migrations/core/074_photo_visibility_client_access.js

@@ -0,0 +1,28 @@
+const { addColumnIfNotExists, createIndexIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  // Add visibility column to photos table
+  await addColumnIfNotExists(knex, 'photos', 'visibility', (table) => {
+    table.string('visibility', 20).defaultTo('visible').notNullable();
+  });
+
+  // Add client access columns to events table
+  await addColumnIfNotExists(knex, 'events', 'client_access_enabled', (table) => {
+    table.boolean('client_access_enabled').defaultTo(false);
+  });
+
+  await addColumnIfNotExists(knex, 'events', 'client_password_hash', (table) => {
+    table.string('client_password_hash', 255).nullable();
+  });
+
+  await addColumnIfNotExists(knex, 'events', 'client_share_token', (table) => {
+    table.string('client_share_token', 64).nullable().unique();
+  });
+
+  // Index for filtering photos by visibility
+  await createIndexIfNotExists(knex, 'photos', ['event_id', 'visibility'], 'idx_photos_event_visibility');
+};
+
+exports.down = async function(knex) {
+  // Safe rollback - intentionally no-op to avoid data loss
+};

backend/migrations/core/075_email_template_translations.js

@@ -0,0 +1,281 @@
+/**
+ * Migration to create email_template_translations table
+ * Moves from per-column language support (subject_en, subject_de) to a
+ * normalized translations table where each language is a row.
+ * This allows adding new languages without schema changes.
+ */
+exports.up = async function(knex) {
+  // 1. Create the email_template_translations table
+  await knex.schema.createTable('email_template_translations', (table) => {
+    table.increments('id').primary();
+    table.integer('template_id').unsigned().notNullable()
+      .references('id').inTable('email_templates').onDelete('CASCADE');
+    table.string('language', 10).notNullable();
+    table.text('subject');
+    table.text('body_html');
+    table.text('body_text');
+    table.datetime('created_at').defaultTo(knex.fn.now());
+    table.datetime('updated_at').defaultTo(knex.fn.now());
+    table.unique(['template_id', 'language']);
+  });
+
+  console.log('Created email_template_translations table');
+
+  // 2. Migrate existing data from email_templates columns into rows
+  const templates = await knex('email_templates').select('*');
+  const columnInfo = await knex('email_templates').columnInfo();
+  const hasLangColumns = !!columnInfo.subject_en;
+
+  for (const template of templates) {
+    // Extract EN translation
+    const enSubject = hasLangColumns
+      ? (template.subject_en || template.subject || '')
+      : (template.subject || '');
+    const enHtml = hasLangColumns
+      ? (template.body_html_en || template.body_html || '')
+      : (template.body_html || '');
+    const enText = hasLangColumns
+      ? (template.body_text_en || template.body_text || '')
+      : (template.body_text || '');
+
+    // Insert EN translation
+    if (enSubject || enHtml) {
+      await knex('email_template_translations').insert({
+        template_id: template.id,
+        language: 'en',
+        subject: enSubject,
+        body_html: enHtml,
+        body_text: enText,
+        created_at: new Date(),
+        updated_at: new Date(),
+      });
+    }
+
+    // Extract DE translation (only if lang columns exist)
+    if (hasLangColumns) {
+      const deSubject = template.subject_de || '';
+      const deHtml = template.body_html_de || '';
+      const deText = template.body_text_de || '';
+
+      // Only insert if DE content differs from EN or has content
+      if (deSubject || deHtml) {
+        await knex('email_template_translations').insert({
+          template_id: template.id,
+          language: 'de',
+          subject: deSubject,
+          body_html: deHtml,
+          body_text: deText,
+          created_at: new Date(),
+          updated_at: new Date(),
+        });
+      }
+    }
+  }
+
+  console.log(`Migrated ${templates.length} templates to translations table`);
+
+  // 3. Seed NL, PT, RU translations for customer-facing templates
+  // Look up template IDs
+  const customerTemplates = await knex('email_templates')
+    .whereIn('template_key', [
+      'gallery_created', 'expiration_warning', 'gallery_expired', 'archive_complete'
+    ])
+    .select('id', 'template_key');
+
+  const templateMap = {};
+  customerTemplates.forEach(t => { templateMap[t.template_key] = t.id; });
+
+  const seedTranslations = [];
+
+  // --- gallery_created ---
+  if (templateMap.gallery_created) {
+    const id = templateMap.gallery_created;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Uw fotogalerij is klaar!',
+        body_html: `<h2>Galerij succesvol aangemaakt</h2>
+<p>Beste {{host_name}},</p>
+<p>Uw fotogalerij "{{event_name}}" is succesvol aangemaakt!</p>
+<p><strong>Galerij details:</strong></p>
+<ul>
+  <li>Evenementdatum: {{event_date}}</li>
+  <li>Galerij link: <a href="{{gallery_link}}">{{gallery_link}}</a></li>
+  <li>Wachtwoord: {{gallery_password}}</li>
+  <li>Verloopt op: {{expiry_date}}</li>
+</ul>
+<p>Deel deze link en het wachtwoord met uw gasten zodat zij de foto's kunnen bekijken en downloaden.</p>
+{{#if welcome_message}}<p><em>{{welcome_message}}</em></p>{{/if}}`,
+        body_text: `Galerij succesvol aangemaakt\n\nBeste {{host_name}},\n\nUw fotogalerij "{{event_name}}" is succesvol aangemaakt!\n\nGalerij link: {{gallery_link}}\nWachtwoord: {{gallery_password}}\nVerloopt op: {{expiry_date}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Sua galeria de fotos está pronta!',
+        body_html: `<h2>Galeria criada com sucesso</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>Sua galeria de fotos "{{event_name}}" foi criada com sucesso!</p>
+<p><strong>Detalhes da galeria:</strong></p>
+<ul>
+  <li>Data do evento: {{event_date}}</li>
+  <li>Link da galeria: <a href="{{gallery_link}}">{{gallery_link}}</a></li>
+  <li>Senha: {{gallery_password}}</li>
+  <li>Expira em: {{expiry_date}}</li>
+</ul>
+<p>Compartilhe este link e senha com seus convidados para que possam visualizar e baixar as fotos.</p>
+{{#if welcome_message}}<p><em>{{welcome_message}}</em></p>{{/if}}`,
+        body_text: `Galeria criada com sucesso\n\nPrezado(a) {{host_name}},\n\nSua galeria de fotos "{{event_name}}" foi criada com sucesso!\n\nLink da galeria: {{gallery_link}}\nSenha: {{gallery_password}}\nExpira em: {{expiry_date}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Ваша фотогалерея готова!',
+        body_html: `<h2>Галерея успешно создана</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Ваша фотогалерея "{{event_name}}" была успешно создана!</p>
+<p><strong>Детали галереи:</strong></p>
+<ul>
+  <li>Дата события: {{event_date}}</li>
+  <li>Ссылка на галерею: <a href="{{gallery_link}}">{{gallery_link}}</a></li>
+  <li>Пароль: {{gallery_password}}</li>
+  <li>Срок действия: {{expiry_date}}</li>
+</ul>
+<p>Поделитесь этой ссылкой и паролем с вашими гостями, чтобы они могли просматривать и скачивать фотографии.</p>
+{{#if welcome_message}}<p><em>{{welcome_message}}</em></p>{{/if}}`,
+        body_text: `Галерея успешно создана\n\nУважаемый(ая) {{host_name}},\n\nВаша фотогалерея "{{event_name}}" была успешно создана!\n\nСсылка: {{gallery_link}}\nПароль: {{gallery_password}}\nСрок действия: {{expiry_date}}`,
+      },
+    );
+  }
+
+  // --- expiration_warning ---
+  if (templateMap.expiration_warning) {
+    const id = templateMap.expiration_warning;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Uw fotogalerij verloopt binnenkort',
+        body_html: `<h2>Galerij verloopt binnenkort</h2>
+<p>Beste {{host_name}},</p>
+<p>Uw fotogalerij "{{event_name}}" verloopt over {{days_remaining}} dagen.</p>
+<p>Na het verlopen wordt de galerij gearchiveerd en is niet meer toegankelijk voor gasten.</p>
+<p><a href="{{gallery_link}}">Galerij bezoeken</a></p>`,
+        body_text: `Galerij verloopt binnenkort\n\nBeste {{host_name}},\n\nUw fotogalerij "{{event_name}}" verloopt over {{days_remaining}} dagen.\n\nGalerij: {{gallery_link}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Sua galeria de fotos expira em breve',
+        body_html: `<h2>Galeria expirando em breve</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>Sua galeria de fotos "{{event_name}}" expirará em {{days_remaining}} dias.</p>
+<p>Após a expiração, a galeria será arquivada e não estará mais acessível aos convidados.</p>
+<p><a href="{{gallery_link}}">Visitar galeria</a></p>`,
+        body_text: `Galeria expirando em breve\n\nPrezado(a) {{host_name}},\n\nSua galeria de fotos "{{event_name}}" expirará em {{days_remaining}} dias.\n\nGaleria: {{gallery_link}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Срок действия вашей фотогалереи скоро истекает',
+        body_html: `<h2>Срок действия галереи истекает</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Срок действия вашей фотогалереи "{{event_name}}" истекает через {{days_remaining}} дней.</p>
+<p>После истечения срока галерея будет архивирована и станет недоступна для гостей.</p>
+<p><a href="{{gallery_link}}">Перейти в галерею</a></p>`,
+        body_text: `Срок действия галереи истекает\n\nУважаемый(ая) {{host_name}},\n\nСрок действия вашей фотогалереи "{{event_name}}" истекает через {{days_remaining}} дней.\n\nГалерея: {{gallery_link}}`,
+      },
+    );
+  }
+
+  // --- gallery_expired ---
+  if (templateMap.gallery_expired) {
+    const id = templateMap.gallery_expired;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Uw fotogalerij {{event_name}} is verlopen',
+        body_html: `<h2>Galerij verlopen</h2>
+<p>Beste {{host_name}},</p>
+<p>Uw fotogalerij "{{event_name}}" is verlopen en niet meer toegankelijk.</p>
+<p>De foto's zijn gearchiveerd. Als u toegang nodig heeft, neem dan contact op met de beheerder via {{admin_email}}.</p>`,
+        body_text: `Galerij verlopen\n\nBeste {{host_name}},\n\nUw fotogalerij "{{event_name}}" is verlopen en niet meer toegankelijk.\n\nNeem contact op met: {{admin_email}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Sua galeria de fotos {{event_name}} expirou',
+        body_html: `<h2>Galeria expirada</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>Sua galeria de fotos "{{event_name}}" expirou e não está mais acessível.</p>
+<p>As fotos foram arquivadas. Se precisar de acesso, entre em contato com o administrador em {{admin_email}}.</p>`,
+        body_text: `Galeria expirada\n\nPrezado(a) {{host_name}},\n\nSua galeria de fotos "{{event_name}}" expirou e não está mais acessível.\n\nContato: {{admin_email}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Срок действия фотогалереи {{event_name}} истёк',
+        body_html: `<h2>Срок действия галереи истёк</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Срок действия вашей фотогалереи "{{event_name}}" истёк, и она больше недоступна.</p>
+<p>Фотографии были архивированы. Если вам нужен доступ, свяжитесь с администратором: {{admin_email}}.</p>`,
+        body_text: `Срок действия галереи истёк\n\nУважаемый(ая) {{host_name}},\n\nСрок действия вашей фотогалереи "{{event_name}}" истёк.\n\nКонтакт: {{admin_email}}`,
+      },
+    );
+  }
+
+  // --- archive_complete ---
+  if (templateMap.archive_complete) {
+    const id = templateMap.archive_complete;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Archivering voltooid: {{event_name}}',
+        body_html: `<h2>Archivering voltooid</h2>
+<p>Beste {{host_name}},</p>
+<p>De fotogalerij "{{event_name}}" is succesvol gearchiveerd.</p>
+<p><strong>Archief details:</strong></p>
+<ul>
+  <li>Aantal foto's: {{photo_count}}</li>
+  <li>Archiefgrootte: {{archive_size}}</li>
+  <li>Archiefdatum: {{archive_date}}</li>
+</ul>`,
+        body_text: `Archivering voltooid\n\nBeste {{host_name}},\n\nDe fotogalerij "{{event_name}}" is succesvol gearchiveerd.\n\nAantal foto's: {{photo_count}}\nGrootte: {{archive_size}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Arquivamento concluído: {{event_name}}',
+        body_html: `<h2>Arquivamento concluído</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>A galeria de fotos "{{event_name}}" foi arquivada com sucesso.</p>
+<p><strong>Detalhes do arquivo:</strong></p>
+<ul>
+  <li>Número de fotos: {{photo_count}}</li>
+  <li>Tamanho do arquivo: {{archive_size}}</li>
+  <li>Data do arquivamento: {{archive_date}}</li>
+</ul>`,
+        body_text: `Arquivamento concluído\n\nPrezado(a) {{host_name}},\n\nA galeria de fotos "{{event_name}}" foi arquivada com sucesso.\n\nFotos: {{photo_count}}\nTamanho: {{archive_size}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Архивация завершена: {{event_name}}',
+        body_html: `<h2>Архивация завершена</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Фотогалерея "{{event_name}}" была успешно архивирована.</p>
+<p><strong>Детали архива:</strong></p>
+<ul>
+  <li>Количество фото: {{photo_count}}</li>
+  <li>Размер архива: {{archive_size}}</li>
+  <li>Дата архивации: {{archive_date}}</li>
+</ul>`,
+        body_text: `Архивация завершена\n\nУважаемый(ая) {{host_name}},\n\nФотогалерея "{{event_name}}" была успешно архивирована.\n\nФото: {{photo_count}}\nРазмер: {{archive_size}}`,
+      },
+    );
+  }
+
+  // Insert all seed translations
+  const now = new Date();
+  for (const trans of seedTranslations) {
+    trans.created_at = now;
+    trans.updated_at = now;
+    await knex('email_template_translations').insert(trans);
+  }
+
+  console.log(`Seeded ${seedTranslations.length} translations for customer-facing templates`);
+};
+
+exports.down = async function(knex) {
+  await knex.schema.dropTableIfExists('email_template_translations');
+};

backend/migrations/core/076_add_is_draft_column.js

@@ -0,0 +1,21 @@
+/**
+ * Migration to add is_draft column to events table.
+ * Draft events are not visible to gallery visitors until published.
+ */
+exports.up = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'is_draft');
+  if (!hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.boolean('is_draft').defaultTo(false);
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'is_draft');
+  if (hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('is_draft');
+    });
+  }
+};

backend/migrations/core/077_add_default_photo_sort.js

@@ -0,0 +1,17 @@
+exports.up = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'default_photo_sort');
+  if (!hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.string('default_photo_sort', 50).defaultTo('upload_date_desc');
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'default_photo_sort');
+  if (hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('default_photo_sort');
+    });
+  }
+};

backend/migrations/core/078_add_guest_identity.js

@@ -0,0 +1,120 @@
+/**
+ * Add guest identity layer for per-person photo selections (issue #292).
+ *
+ * Adds:
+ *   - gallery_guests              — persistent guest profiles per event
+ *   - guest_invites               — pre-minted invite tokens (Phase 3.3)
+ *   - guest_verification_codes    — email-based identity recovery (Phase 3.2)
+ *   - event_feedback_settings.identity_mode ('simple' | 'guest', default 'simple')
+ *   - photo_feedback.guest_id FK  — links feedback to gallery_guests (nullable)
+ *
+ * All changes are additive. Existing events default to 'simple' mode so behavior
+ * is unchanged. Legacy photo_feedback rows keep NULL guest_id.
+ */
+
+exports.up = async function(knex) {
+  // 1. gallery_guests — persistent per-person identity within an event.
+  const hasGalleryGuests = await knex.schema.hasTable('gallery_guests');
+  if (!hasGalleryGuests) {
+    await knex.schema.createTable('gallery_guests', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').notNullable().references('id').inTable('events').onDelete('CASCADE');
+      table.string('name', 100).notNullable();
+      table.string('email', 255);
+      table.string('identifier', 64).notNullable(); // UUIDv4 issued server-side
+      table.string('ip_address_last', 45);
+      table.text('user_agent_last');
+      table.timestamp('email_verified_at');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('last_seen_at').defaultTo(knex.fn.now());
+      table.boolean('is_deleted').defaultTo(false);
+
+      table.unique(['event_id', 'identifier']);
+      table.index(['event_id']);
+      table.index(['event_id', 'email']);
+    });
+  }
+
+  // 2. guest_invites — pre-minted one-time-use tokens for invited guests.
+  const hasGuestInvites = await knex.schema.hasTable('guest_invites');
+  if (!hasGuestInvites) {
+    await knex.schema.createTable('guest_invites', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').notNullable().references('id').inTable('events').onDelete('CASCADE');
+      table.integer('guest_id').notNullable().references('id').inTable('gallery_guests').onDelete('CASCADE');
+      table.string('token', 64).notNullable().unique();
+      table.integer('created_by_admin_id').references('id').inTable('admin_users');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('redeemed_at');
+      table.timestamp('revoked_at');
+
+      table.index(['event_id']);
+      table.index(['guest_id']);
+    });
+  }
+
+  // 3. guest_verification_codes — short-lived codes for email-based recovery.
+  const hasGuestVerificationCodes = await knex.schema.hasTable('guest_verification_codes');
+  if (!hasGuestVerificationCodes) {
+    await knex.schema.createTable('guest_verification_codes', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').notNullable().references('id').inTable('events').onDelete('CASCADE');
+      table.string('email', 255).notNullable();
+      table.string('code_hash', 128).notNullable(); // bcrypt hash of 6-digit code
+      table.integer('attempts').defaultTo(0);
+      table.timestamp('expires_at').notNullable();
+      table.timestamp('consumed_at');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+
+      table.index(['event_id', 'email']);
+      table.index(['expires_at']);
+    });
+  }
+
+  // 4. event_feedback_settings.identity_mode
+  const hasIdentityMode = await knex.schema.hasColumn('event_feedback_settings', 'identity_mode');
+  if (!hasIdentityMode) {
+    await knex.schema.alterTable('event_feedback_settings', (table) => {
+      table.string('identity_mode', 16).notNullable().defaultTo('simple');
+    });
+    if (knex.client.config.client === 'pg') {
+      await knex.raw(`
+        ALTER TABLE event_feedback_settings
+        ADD CONSTRAINT event_feedback_settings_identity_mode_check
+        CHECK (identity_mode IN ('simple','guest'))
+      `);
+    }
+  }
+
+  // 5. photo_feedback.guest_id FK
+  const hasGuestIdColumn = await knex.schema.hasColumn('photo_feedback', 'guest_id');
+  if (!hasGuestIdColumn) {
+    await knex.schema.alterTable('photo_feedback', (table) => {
+      table.integer('guest_id').references('id').inTable('gallery_guests').onDelete('SET NULL');
+      table.index(['guest_id']);
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasGuestIdColumn = await knex.schema.hasColumn('photo_feedback', 'guest_id');
+  if (hasGuestIdColumn) {
+    await knex.schema.alterTable('photo_feedback', (table) => {
+      table.dropColumn('guest_id');
+    });
+  }
+
+  if (knex.client.config.client === 'pg') {
+    await knex.raw('ALTER TABLE event_feedback_settings DROP CONSTRAINT IF EXISTS event_feedback_settings_identity_mode_check');
+  }
+  const hasIdentityMode = await knex.schema.hasColumn('event_feedback_settings', 'identity_mode');
+  if (hasIdentityMode) {
+    await knex.schema.alterTable('event_feedback_settings', (table) => {
+      table.dropColumn('identity_mode');
+    });
+  }
+
+  await knex.schema.dropTableIfExists('guest_verification_codes');
+  await knex.schema.dropTableIfExists('guest_invites');
+  await knex.schema.dropTableIfExists('gallery_guests');
+};

backend/migrations/core/079_add_download_zip_cache.js

@@ -0,0 +1,26 @@
+/**
+ * Add download ZIP cache columns to events table.
+ *
+ * Enables pre-generated ZIP files for "Download All" so guests get
+ * instant downloads with Content-Length instead of on-the-fly streaming.
+ */
+
+exports.up = async function(knex) {
+  const hasZipPath = await knex.schema.hasColumn('events', 'download_zip_path');
+  if (!hasZipPath) {
+    await knex.schema.alterTable('events', (table) => {
+      table.text('download_zip_path').nullable().defaultTo(null);
+      table.datetime('download_zip_generated_at').nullable().defaultTo(null);
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasZipPath = await knex.schema.hasColumn('events', 'download_zip_path');
+  if (hasZipPath) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('download_zip_path');
+      table.dropColumn('download_zip_generated_at');
+    });
+  }
+};

backend/migrations/core/080_add_customer_phone.js

@@ -0,0 +1,33 @@
+const { addColumnIfNotExists } = require('../helpers');
+
+/**
+ * #322 — optional phone-number field on events. Off by default; surfaced
+ * only when the global `event_phone_field_enabled` app setting is true,
+ * so existing deployments see no UI change unless the admin opts in.
+ */
+exports.up = async function up(knex) {
+  await addColumnIfNotExists(knex, 'events', 'customer_phone', (table) => {
+    table.string('customer_phone', 32).nullable();
+  });
+
+  // Seed the global enable flag (default false).
+  const exists = await knex('app_settings')
+    .where('setting_key', 'event_phone_field_enabled')
+    .first();
+  if (!exists) {
+    await knex('app_settings').insert({
+      setting_key: 'event_phone_field_enabled',
+      setting_value: JSON.stringify(false),
+      setting_type: 'boolean'
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasColumn('events', 'customer_phone')) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('customer_phone');
+    });
+  }
+  await knex('app_settings').where('setting_key', 'event_phone_field_enabled').delete();
+};

backend/migrations/core/081_add_api_tokens.js

@@ -0,0 +1,41 @@
+/**
+ * #322 — long-lived API tokens for programmatic access (n8n, custom
+ * integrations, external apps). Each token belongs to an admin user; the
+ * token's effective permissions are the *intersection* of the user's
+ * role permissions and the token's own scope flags. That way revoking
+ * the user revokes the token, and scope flags let an admin issue a
+ * read-only token even if their account is super_admin.
+ */
+
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable('api_tokens'))) {
+    await knex.schema.createTable('api_tokens', (table) => {
+      table.increments('id').primary();
+      table.string('name', 100).notNullable();
+      // SHA-256 of the full token string (`pp_live_<random>`). Lookup
+      // hashes the incoming Authorization header and queries by this.
+      table.string('hashed_token', 64).notNullable().unique();
+      // Scope flags — comma-separated subset of: read, write, admin.
+      // 'read' allows GETs; 'write' adds POST/PATCH/DELETE on
+      // event/photo data; 'admin' allows creating/deleting events and
+      // anything else gated by admin.* permissions.
+      table.string('scopes', 64).notNullable().defaultTo('read');
+      table.integer('created_by').notNullable()
+        .references('id').inTable('admin_users').onDelete('CASCADE');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('expires_at').nullable();
+      table.timestamp('last_used_at').nullable();
+      table.timestamp('revoked_at').nullable();
+      // Cosmetic for the admin UI: first 8 chars of the plaintext
+      // token (after the prefix) so admins can identify which token is
+      // which without seeing the secret half.
+      table.string('preview', 16).nullable();
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasTable('api_tokens')) {
+    await knex.schema.dropTable('api_tokens');
+  }
+};

backend/migrations/core/082_add_webhooks.js

@@ -0,0 +1,80 @@
+/**
+ * #327 — outbound webhooks (push API) for the event/photo lifecycle.
+ *
+ * Two tables:
+ *   webhooks                — admin-managed subscriptions (URL + events + secret)
+ *   webhook_deliveries      — single source of truth for the delivery worker
+ *                              (audit log + retry queue in one).
+ */
+
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable('webhooks'))) {
+    await knex.schema.createTable('webhooks', (table) => {
+      table.increments('id').primary();
+      table.string('name', 100).notNullable();
+      // Validated via networkValidation.validateExternalUrl on create + per
+      // delivery (DNS-rebinding mitigation).
+      table.string('url', 2048).notNullable();
+      // Plaintext signing secret (`whsec_<random>`). Stored unencrypted
+      // because we need to recompute HMAC-SHA256 over every outbound body
+      // — a hash would make the secret unrecoverable. Same posture as
+      // SMTP passwords stored in app_settings; protect the DB. The
+      // plaintext is also returned to the admin once on create so they can
+      // configure the receiver to verify signatures.
+      table.string('secret', 100).notNullable();
+      // First 8 chars of the secret for the admin UI so operators can
+      // tell which webhook is which without revealing the full secret.
+      table.string('secret_preview', 16).nullable();
+      // JSON array of subscribed event types
+      // (e.g. ["event.published","photo.uploaded"]).
+      table.jsonb('events').notNullable().defaultTo('[]');
+      table.boolean('active').notNullable().defaultTo(true);
+      table.integer('created_by').notNullable()
+        .references('id').inTable('admin_users').onDelete('CASCADE');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+      table.timestamp('last_success_at').nullable();
+      table.timestamp('last_failure_at').nullable();
+      // Index for the delivery worker's "find subscriptions for this event"
+      // query — small set, but keeps the lookup constant-time as it grows.
+      table.index('active', 'webhooks_active_idx');
+    });
+  }
+
+  if (!(await knex.schema.hasTable('webhook_deliveries'))) {
+    await knex.schema.createTable('webhook_deliveries', (table) => {
+      table.increments('id').primary();
+      table.integer('webhook_id').notNullable()
+        .references('id').inTable('webhooks').onDelete('CASCADE');
+      table.string('event_type', 64).notNullable();
+      // Full signed payload (the JSON body that was POSTed).
+      table.jsonb('payload').notNullable();
+      table.integer('attempt_count').notNullable().defaultTo(0);
+      // pending → success | failed. pending rows with next_retry_at <= NOW()
+      // are picked up by the worker.
+      table.string('status', 16).notNullable().defaultTo('pending');
+      table.integer('response_status').nullable();
+      // Truncated to 1KB before storage so a verbose receiver can't blow
+      // up the row size.
+      table.text('response_body').nullable();
+      table.text('last_error').nullable();
+      table.integer('latency_ms').nullable();
+      table.timestamp('next_retry_at').nullable();
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('completed_at').nullable();
+      // Worker hot-path query: WHERE status='pending' AND next_retry_at <= NOW()
+      // ORDER BY next_retry_at LIMIT N. This composite index serves it directly.
+      table.index(['status', 'next_retry_at'], 'webhook_deliveries_status_retry_idx');
+      table.index('webhook_id', 'webhook_deliveries_webhook_idx');
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasTable('webhook_deliveries')) {
+    await knex.schema.dropTable('webhook_deliveries');
+  }
+  if (await knex.schema.hasTable('webhooks')) {
+    await knex.schema.dropTable('webhooks');
+  }
+};

backend/migrations/core/083_add_presigned_and_webhook_extras.js

@@ -0,0 +1,49 @@
+/**
+ * Adds:
+ *   - events.allow_presigned_download — per-event opt-in for the
+ *     presigned-URL "Download All" path (#328 follow-up). Off by default
+ *     because it bypasses watermarks; admins flip it knowingly.
+ *   - webhooks.filter — JSONB predicate evaluated against the payload at
+ *     fire time (#327 follow-up). Empty object = no filter, fire always.
+ *   - webhooks.template — optional ${dot.path} string template applied
+ *     to the request body before signing. NULL = use the default JSON
+ *     envelope (back-compat).
+ */
+
+exports.up = async function up(knex) {
+  if (await knex.schema.hasTable('events')) {
+    const hasCol = await knex.schema.hasColumn('events', 'allow_presigned_download');
+    if (!hasCol) {
+      await knex.schema.alterTable('events', (table) => {
+        table.boolean('allow_presigned_download').notNullable().defaultTo(false);
+      });
+    }
+  }
+
+  if (await knex.schema.hasTable('webhooks')) {
+    const hasFilter = await knex.schema.hasColumn('webhooks', 'filter');
+    if (!hasFilter) {
+      await knex.schema.alterTable('webhooks', (table) => {
+        table.jsonb('filter').notNullable().defaultTo('{}');
+      });
+    }
+    const hasTemplate = await knex.schema.hasColumn('webhooks', 'template');
+    if (!hasTemplate) {
+      await knex.schema.alterTable('webhooks', (table) => {
+        table.text('template').nullable();
+      });
+    }
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasColumn('webhooks', 'template')) {
+    await knex.schema.alterTable('webhooks', (t) => t.dropColumn('template'));
+  }
+  if (await knex.schema.hasColumn('webhooks', 'filter')) {
+    await knex.schema.alterTable('webhooks', (t) => t.dropColumn('filter'));
+  }
+  if (await knex.schema.hasColumn('events', 'allow_presigned_download')) {
+    await knex.schema.alterTable('events', (t) => t.dropColumn('allow_presigned_download'));
+  }
+};

backend/migrations/core/084_fix_hero_logo_position.js

@@ -0,0 +1,21 @@
+/**
+ * Heal events whose hero_logo_position contains a branding-style value
+ * (left/right) caused by a prior bug in adminEvents.js getBrandingDefaults
+ * that mapped branding_logo_position (left/center/right) onto
+ * hero_logo_position (top/center/bottom). Any non-canonical value is
+ * reset to 'top' so subsequent PUTs no longer fail validation.
+ */
+
+exports.up = async function up(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'hero_logo_position');
+  if (!hasColumn) return;
+
+  await knex('events')
+    .whereNotIn('hero_logo_position', ['top', 'center', 'bottom'])
+    .update({ hero_logo_position: 'top' });
+};
+
+exports.down = async function down() {
+  // Data correction is not reversible — the original (incorrect) values
+  // are not preserved.
+};

backend/migrations/core/085_async_photo_processing.js

@@ -0,0 +1,72 @@
+/**
+ * Async photo-processing infrastructure.
+ *
+ * Adds:
+ *   - photos.processing_status     — enum: pending | processing | complete | failed
+ *   - photos.processing_error      — text, populated on 'failed'
+ *   - photos.processing_started_at — claim timestamp for janitor recovery
+ *   - photos.upload_id             — groups all photos from one upload request
+ *                                    so the frontend can poll/stream by group
+ *
+ * All existing rows default to 'complete' (they were processed synchronously
+ * before this migration and there's nothing pending). New uploads insert
+ * with 'pending' and a background worker (services/backgroundProcessor.js)
+ * picks them up.
+ *
+ * Partial-style indexes keep lookups fast as the queue drains. We use plain
+ * indexes here instead of postgres-specific WHERE clauses so the migration
+ * works on SQLite too; the workload (only-pending rows) keeps the index small.
+ */
+
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable('photos'))) return;
+
+  const hasStatus = await knex.schema.hasColumn('photos', 'processing_status');
+  if (!hasStatus) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.string('processing_status', 16).notNullable().defaultTo('complete');
+      table.text('processing_error').nullable();
+      table.timestamp('processing_started_at').nullable();
+      table.string('upload_id', 64).nullable();
+    });
+  }
+
+  // Indexes — wrap in try/catch so re-running the migration on a partially
+  // applied schema is a no-op rather than an error.
+  try {
+    await knex.schema.alterTable('photos', (table) => {
+      table.index(['processing_status'], 'idx_photos_processing_status');
+    });
+  } catch (_) { /* already exists */ }
+
+  try {
+    await knex.schema.alterTable('photos', (table) => {
+      table.index(['upload_id'], 'idx_photos_upload_id');
+    });
+  } catch (_) { /* already exists */ }
+};
+
+exports.down = async function down(knex) {
+  if (!(await knex.schema.hasTable('photos'))) return;
+
+  // Drop indexes first (best-effort)
+  try {
+    await knex.schema.alterTable('photos', (t) => t.dropIndex([], 'idx_photos_upload_id'));
+  } catch (_) { /* not present */ }
+  try {
+    await knex.schema.alterTable('photos', (t) => t.dropIndex([], 'idx_photos_processing_status'));
+  } catch (_) { /* not present */ }
+
+  if (await knex.schema.hasColumn('photos', 'upload_id')) {
+    await knex.schema.alterTable('photos', (t) => t.dropColumn('upload_id'));
+  }
+  if (await knex.schema.hasColumn('photos', 'processing_started_at')) {
+    await knex.schema.alterTable('photos', (t) => t.dropColumn('processing_started_at'));
+  }
+  if (await knex.schema.hasColumn('photos', 'processing_error')) {
+    await knex.schema.alterTable('photos', (t) => t.dropColumn('processing_error'));
+  }
+  if (await knex.schema.hasColumn('photos', 'processing_status')) {
+    await knex.schema.alterTable('photos', (t) => t.dropColumn('processing_status'));
+  }
+};

backend/migrations/legacy/006_add_photo_counter_to_categories.js

@@ -1,22 +1,27 @@
 exports.up = async function(knex) {
-  // Add photo_counter column to photo_categories table
-  await knex.schema.alterTable('photo_categories', function(table) {
-    table.integer('photo_counter').defaultTo(0).notNullable();
-  });
+  // Check if photo_counter column already exists to make migration idempotent
+  const hasPhotoCounter = await knex.schema.hasColumn('photo_categories', 'photo_counter');
 
-  // Initialize counters based on existing photos
-  const categories = await knex('photo_categories').select('id');
-  
-  for (const category of categories) {
-    const photoCount = await knex('photos')
-      .where('category_id', category.id)
-      .count('id as count')
-      .first();
-    
-    if (photoCount && photoCount.count > 0) {
-      await knex('photo_categories')
-        .where('id', category.id)
-        .update({ photo_counter: photoCount.count });
+  if (!hasPhotoCounter) {
+    // Add photo_counter column to photo_categories table
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.integer('photo_counter').defaultTo(0).notNullable();
+    });
+
+    // Initialize counters based on existing photos
+    const categories = await knex('photo_categories').select('id');
+
+    for (const category of categories) {
+      const photoCount = await knex('photos')
+        .where('category_id', category.id)
+        .count('id as count')
+        .first();
+
+      if (photoCount && photoCount.count > 0) {
+        await knex('photo_categories')
+          .where('id', category.id)
+          .update({ photo_counter: photoCount.count });
+      }
     }
   }
 };

backend/migrations/legacy/008_add_language_support_to_email_templates.js

@@ -1,23 +1,33 @@
 exports.up = async function(knex) {
-  // Add language-specific columns to email_templates
-  await knex.schema.alterTable('email_templates', function(table) {
-    // Add English versions (rename existing columns for consistency)
-    table.renameColumn('subject', 'subject_en');
-    table.renameColumn('body_html', 'body_html_en');
-    table.renameColumn('body_text', 'body_text_en');
-    
-    // Add German versions
-    table.string('subject_de');
-    table.text('body_html_de');
-    table.text('body_text_de');
-  });
+  // Check which columns already exist to make migration idempotent
+  const hasSubjectEn = await knex.schema.hasColumn('email_templates', 'subject_en');
+  const hasSubjectDe = await knex.schema.hasColumn('email_templates', 'subject_de');
+  const hasSubjectOriginal = await knex.schema.hasColumn('email_templates', 'subject');
 
-  // Copy existing values to German columns as defaults
-  await knex('email_templates').update({
-    subject_de: knex.raw('subject_en'),
-    body_html_de: knex.raw('body_html_en'),
-    body_text_de: knex.raw('body_text_en')
-  });
+  // Only rename columns if they haven't been renamed yet
+  if (hasSubjectOriginal && !hasSubjectEn) {
+    await knex.schema.alterTable('email_templates', function(table) {
+      table.renameColumn('subject', 'subject_en');
+      table.renameColumn('body_html', 'body_html_en');
+      table.renameColumn('body_text', 'body_text_en');
+    });
+  }
+
+  // Only add German columns if they don't exist
+  if (!hasSubjectDe) {
+    await knex.schema.alterTable('email_templates', function(table) {
+      table.string('subject_de');
+      table.text('body_html_de');
+      table.text('body_text_de');
+    });
+
+    // Copy existing values to German columns as defaults
+    await knex('email_templates').update({
+      subject_de: knex.raw('subject_en'),
+      body_html_de: knex.raw('body_html_en'),
+      body_text_de: knex.raw('body_text_en')
+    });
+  }
 };
 
 exports.down = async function(knex) {

backend/migrations/legacy/011_add_user_upload_settings.js

@@ -1,23 +1,56 @@
 exports.up = async function(knex) {
-  // Add user upload settings to events table
-  await knex.schema.alterTable('events', function(table) {
-    table.boolean('allow_user_uploads').defaultTo(false);
-    table.integer('upload_category_id').references('id').inTable('photo_categories').onDelete('SET NULL');
-  });
-  
+  // Add user upload settings to events table (check if columns exist first)
+  const hasAllowUserUploads = await knex.schema.hasColumn('events', 'allow_user_uploads');
+  if (!hasAllowUserUploads) {
+    console.log('Adding allow_user_uploads column to events table...');
+    await knex.schema.alterTable('events', function(table) {
+      table.boolean('allow_user_uploads').defaultTo(false);
+    });
+  } else {
+    console.log('Column allow_user_uploads already exists in events table, skipping...');
+  }
+
+  const hasUploadCategoryId = await knex.schema.hasColumn('events', 'upload_category_id');
+  if (!hasUploadCategoryId) {
+    console.log('Adding upload_category_id column to events table...');
+    await knex.schema.alterTable('events', function(table) {
+      table.integer('upload_category_id').references('id').inTable('photo_categories').onDelete('SET NULL');
+    });
+  } else {
+    console.log('Column upload_category_id already exists in events table, skipping...');
+  }
+
   // Add uploaded_by field to photos table to track who uploaded
-  await knex.schema.alterTable('photos', function(table) {
-    table.string('uploaded_by').defaultTo('admin'); // 'admin' or guest identifier
-  });
+  const hasUploadedBy = await knex.schema.hasColumn('photos', 'uploaded_by');
+  if (!hasUploadedBy) {
+    console.log('Adding uploaded_by column to photos table...');
+    await knex.schema.alterTable('photos', function(table) {
+      table.string('uploaded_by').defaultTo('admin'); // 'admin' or guest identifier
+    });
+  } else {
+    console.log('Column uploaded_by already exists in photos table, skipping...');
+  }
 };
 
 exports.down = async function(knex) {
-  await knex.schema.alterTable('events', function(table) {
-    table.dropColumn('allow_user_uploads');
-    table.dropColumn('upload_category_id');
-  });
-  
-  await knex.schema.alterTable('photos', function(table) {
-    table.dropColumn('uploaded_by');
-  });
+  const hasAllowUserUploads = await knex.schema.hasColumn('events', 'allow_user_uploads');
+  if (hasAllowUserUploads) {
+    await knex.schema.alterTable('events', function(table) {
+      table.dropColumn('allow_user_uploads');
+    });
+  }
+
+  const hasUploadCategoryId = await knex.schema.hasColumn('events', 'upload_category_id');
+  if (hasUploadCategoryId) {
+    await knex.schema.alterTable('events', function(table) {
+      table.dropColumn('upload_category_id');
+    });
+  }
+
+  const hasUploadedBy = await knex.schema.hasColumn('photos', 'uploaded_by');
+  if (hasUploadedBy) {
+    await knex.schema.alterTable('photos', function(table) {
+      table.dropColumn('uploaded_by');
+    });
+  }
 };

backend/migrations/run-migrations-safe.js

@@ -67,26 +67,37 @@ async function runMigrationSafely(filepath) {
     const migrationPath = path.join(__dirname, filepath);
     const migration = require(migrationPath);
     const filename = path.basename(filepath);
-    
+
     if (migration.up) {
       console.log(`Running migration: ${filepath}`);
-      
+
       // Run migration in a transaction if possible
+      // IMPORTANT: Include the migrations table insert INSIDE the transaction
+      // to ensure atomicity between schema changes and tracking
       if (db.client.config.client === 'pg') {
         await db.transaction(async (trx) => {
           await migration.up(trx);
+          // Insert migration record inside transaction for atomicity
+          await trx('migrations').insert({ filename });
         });
       } else {
         await migration.up(db);
+        await db('migrations').insert({ filename });
       }
-      
-      await db('migrations').insert({ filename });
+
       console.log(`Migration ${filepath} completed successfully`);
     }
   } catch (error) {
     // Check if error is because schema already exists
-    if (error.code === '42P07' || // PostgreSQL: relation already exists
-        error.code === 'SQLITE_ERROR' && error.message.includes('already exists')) {
+    // PostgreSQL error codes:
+    // - 42P07: duplicate_table (relation already exists)
+    // - 42701: duplicate_column (column already exists)
+    // - 42710: duplicate_object (constraint, index, etc. already exists)
+    // - 23505: unique_violation (migration record already exists)
+    const schemaExistsErrors = ['42P07', '42701', '42710', '23505'];
+    const isSQLiteAlreadyExists = error.code === 'SQLITE_ERROR' && error.message.includes('already exists');
+
+    if (schemaExistsErrors.includes(error.code) || isSQLiteAlreadyExists) {
       console.log(`Migration ${filepath} - schema already exists, marking as applied`);
       await markMigrationAsApplied(path.basename(filepath));
     } else {

backend/migrations/run-migrations.js

@@ -26,11 +26,22 @@ async function runMigration(filepath) {
   const migrationPath = path.join(__dirname, filepath);
   const migration = require(migrationPath);
   const filename = path.basename(filepath);
-  
+
   if (migration.up) {
     console.log(`Running migration: ${filepath}`);
-    await migration.up(db);
-    await db('migrations').insert({ filename });
+
+    // Run migration in a transaction if PostgreSQL to ensure atomicity
+    // between schema changes and migration tracking
+    if (db.client.config.client === 'pg') {
+      await db.transaction(async (trx) => {
+        await migration.up(trx);
+        await trx('migrations').insert({ filename });
+      });
+    } else {
+      await migration.up(db);
+      await db('migrations').insert({ filename });
+    }
+
     console.log(`Migration ${filepath} completed`);
   }
 }

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picpeak-backend",
-  "version": "1.1.5",
+  "version": "3.37.0-beta.0",
   "description": "Backend for PicPeak event photo sharing platform",
   "main": "server.js",
   "scripts": {
@@ -8,7 +8,9 @@
     "dev": "nodemon server.js",
     "migrate": "node migrations/run-migrations.js",
     "migrate:safe": "node migrations/run-migrations-safe.js",
+    "generate:watermarks": "node scripts/generate-watermarks.js",
     "test": "jest",
+    "test:s3": "SKIP_S3_TESTS=false jest __tests__/integration/backup-s3",
     "lint": "eslint src/"
   },
   "dependencies": {
@@ -17,34 +19,39 @@
     "@aws-sdk/s3-request-presigner": "^3.850.0",
     "adm-zip": "^0.5.16",
     "archiver": "^5.3.1",
-    "axios": "^1.12.2",
+    "axios": "1.14.0",
     "bcrypt": "6.0.0",
     "chokidar": "4.0.3",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
     "dotenv": "^16.0.3",
+    "exifr": "^7.1.3",
     "express": "^4.18.2",
     "express-rate-limit": "^6.7.0",
     "express-validator": "^7.0.1",
+    "fluent-ffmpeg": "^2.1.3",
     "form-data": "^4.0.4",
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "helmet": "^7.0.0",
     "i18next": "25.3.2",
     "i18next-browser-languagedetector": "^8.2.0",
     "i18next-http-backend": "^3.0.2",
+    "ipaddr.js": "^2.3.0",
     "joi": "^17.9.1",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.1.1",
     "jsonwebtoken": "^9.0.0",
     "knex": "^2.4.2",
     "mime-types": "^3.0.1",
     "multer": "^2.0.2",
     "node-cron": "^3.0.2",
-    "nodemailer": "^7.0.10",
+    "nodemailer": "^7.0.13",
     "pg": "^8.16.3",
     "react-i18next": "^15.6.0",
     "sanitize-html": "^2.17.0",
     "sharp": "0.34.3",
     "sqlite3": "^5.1.6",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
     "uuid": "^11.1.0",
     "winston": "^3.8.2",
     "zxcvbn": "^4.4.2"
@@ -55,5 +62,19 @@
     "mock-fs": "^5.5.0",
     "nodemon": "^3.1.10",
     "supertest": "^6.3.3"
+  },
+  "overrides": {
+    "prebuild-install": {
+      "tar-fs": "2.1.4"
+    },
+    "glob": "^11.1.0",
+    "js-yaml": "^4.1.1",
+    "fast-xml-parser": ">=5.5.10",
+    "qs": ">=6.14.2",
+    "tar": ">=7.5.13",
+    "brace-expansion": ">=5.0.5",
+    "minimatch": ">=9.0.7",
+    "path-to-regexp": "0.1.13",
+    "lodash": ">=4.18.1"
   }
 }

backend/scripts/create-admin.js

@@ -44,28 +44,39 @@ async function createAdmin() {
       .orWhere('username', username)
       .first();
 
-    if (existingUser) {
-      console.error(`Error: User with email "${email}" or username "${username}" already exists`);
-      process.exit(1);
-    }
-
     // Hash password
     const passwordHash = await bcrypt.hash(password, 10);
 
-    // Create admin user
-    await db('admin_users').insert({
-      username,
-      email,
-      password_hash: passwordHash,
-      is_active: true,
-      created_at: new Date(),
-      updated_at: new Date()
-    });
+    if (existingUser) {
+      // Update existing user's password
+      await db('admin_users')
+        .where('id', existingUser.id)
+        .update({
+          password_hash: passwordHash,
+          updated_at: new Date()
+        });
 
-    console.log(`✅ Admin user created successfully!`);
-    console.log(`   Email: ${email}`);
-    console.log(`   Username: ${username}`);
-    console.log(`   Login URL: ${process.env.ADMIN_URL || 'http://localhost:3000'}/admin/login`);
+      console.log(`✅ Admin user updated successfully!`);
+      console.log(`   Email: ${existingUser.email}`);
+      console.log(`   Username: ${existingUser.username}`);
+      console.log(`   Password has been reset to the provided value`);
+      console.log(`   Login URL: ${process.env.ADMIN_URL || 'http://localhost:3000'}/admin/login`);
+    } else {
+      // Create new admin user
+      await db('admin_users').insert({
+        username,
+        email,
+        password_hash: passwordHash,
+        is_active: true,
+        created_at: new Date(),
+        updated_at: new Date()
+      });
+
+      console.log(`✅ Admin user created successfully!`);
+      console.log(`   Email: ${email}`);
+      console.log(`   Username: ${username}`);
+      console.log(`   Login URL: ${process.env.ADMIN_URL || 'http://localhost:3000'}/admin/login`);
+    }
     
     process.exit(0);
   } catch (error) {

backend/scripts/generate-openapi.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Generate the OpenAPI spec from JSDoc annotations in src/routes/v1/* and
+ * write it as YAML + JSON to ../docs/. Used by scripts/sync-api-docs.sh
+ * to keep the picpeak-docs site in lockstep with the running API.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Need yaml — runtime require so the script fails clearly with an
+// install hint instead of an opaque MODULE_NOT_FOUND.
+let yaml;
+try {
+  yaml = require('js-yaml');
+} catch {
+  console.error('generate-openapi: missing dependency `js-yaml`. Run `npm install --save-dev js-yaml` in /backend.');
+  process.exit(2);
+}
+
+const { getOpenApiSpec } = require('../src/openapi/spec');
+
+const outDir = path.resolve(__dirname, '../../docs');
+fs.mkdirSync(outDir, { recursive: true });
+
+const spec = getOpenApiSpec();
+fs.writeFileSync(path.join(outDir, 'openapi.json'), JSON.stringify(spec, null, 2));
+fs.writeFileSync(path.join(outDir, 'openapi.yaml'), yaml.dump(spec, { lineWidth: 100 }));
+
+console.log(`Wrote openapi.json + openapi.yaml to ${outDir}`);

backend/scripts/generate-watermarks.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * Script to generate pre-watermarked versions for existing photos
+ * This is a one-time migration script to populate watermarks for photos
+ * that existed before the pre-generation feature was implemented.
+ *
+ * Usage: node scripts/generate-watermarks.js [eventId]
+ *
+ * Options:
+ *   eventId - Optional: Only generate watermarks for a specific event
+ *
+ * Examples:
+ *   node scripts/generate-watermarks.js          # Generate for all photos
+ *   node scripts/generate-watermarks.js 5        # Generate for event ID 5
+ */
+
+const path = require('path');
+const { db } = require('../src/database/db');
+const watermarkService = require('../src/services/watermarkService');
+const watermarkGeneratorService = require('../src/services/watermarkGeneratorService');
+
+async function generateWatermarks(eventId = null) {
+  try {
+    console.log('='.repeat(60));
+    console.log('PicPeak Watermark Generation Script');
+    console.log('='.repeat(60));
+
+    // Check if watermarking is enabled
+    const settings = await watermarkService.getWatermarkSettings();
+
+    if (!settings || !settings.enabled) {
+      console.log('\nWatermarking is currently DISABLED in settings.');
+      console.log('Enable watermarking in Admin > Branding settings first.');
+      console.log('Exiting without generating watermarks.');
+      process.exit(0);
+    }
+
+    console.log('\nWatermark Settings:');
+    console.log(`  Enabled: ${settings.enabled}`);
+    console.log(`  Position: ${settings.position}`);
+    console.log(`  Opacity: ${settings.opacity}%`);
+    console.log(`  Size: ${settings.size}%`);
+    console.log(`  Logo: ${settings.logoPath || '(using text fallback)'}`);
+
+    // Build query
+    let query = db('photos')
+      .join('events', 'photos.event_id', 'events.id')
+      .whereNull('photos.watermark_path')
+      .whereNot(function() {
+        this.where('photos.media_type', 'video')
+          .orWhere('photos.mime_type', 'like', 'video/%');
+      })
+      .select(
+        'photos.id',
+        'photos.filename',
+        'photos.event_id',
+        'events.event_name'
+      );
+
+    if (eventId) {
+      query = query.where('photos.event_id', eventId);
+      console.log(`\nFiltering to event ID: ${eventId}`);
+    }
+
+    const photos = await query;
+
+    if (photos.length === 0) {
+      console.log('\nNo photos found without watermarks.');
+      if (eventId) {
+        console.log(`(Checked event ID: ${eventId})`);
+      }
+      console.log('All photos already have pre-generated watermarks or watermarking is disabled.');
+      process.exit(0);
+    }
+
+    console.log(`\nFound ${photos.length} photos without watermarks.`);
+
+    // Group by event for display
+    const eventCounts = {};
+    photos.forEach(p => {
+      eventCounts[p.event_name] = (eventCounts[p.event_name] || 0) + 1;
+    });
+
+    console.log('\nPhotos by event:');
+    Object.entries(eventCounts).forEach(([name, count]) => {
+      console.log(`  ${name}: ${count} photos`);
+    });
+
+    console.log('\nStarting watermark generation...\n');
+
+    let successCount = 0;
+    let failCount = 0;
+    const startTime = Date.now();
+
+    // Process photos with progress display
+    for (let i = 0; i < photos.length; i++) {
+      const photo = photos[i];
+      const progress = Math.round(((i + 1) / photos.length) * 100);
+
+      process.stdout.write(`\r[${progress}%] Processing photo ${i + 1}/${photos.length}: ${photo.filename.substring(0, 30)}...`);
+
+      try {
+        const result = await watermarkGeneratorService.generateForPhoto(photo.id);
+
+        if (result.success) {
+          successCount++;
+        } else {
+          failCount++;
+          console.log(`\n  Failed: ${photo.filename} - ${result.error}`);
+        }
+      } catch (error) {
+        failCount++;
+        console.log(`\n  Error: ${photo.filename} - ${error.message}`);
+      }
+    }
+
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    console.log('\n');
+    console.log('='.repeat(60));
+    console.log('Watermark Generation Complete');
+    console.log('='.repeat(60));
+    console.log(`  Total processed: ${photos.length}`);
+    console.log(`  Successful: ${successCount}`);
+    console.log(`  Failed: ${failCount}`);
+    console.log(`  Duration: ${duration} seconds`);
+    console.log(`  Average: ${(photos.length / parseFloat(duration)).toFixed(1)} photos/second`);
+
+    if (failCount > 0) {
+      console.log('\nSome watermarks failed to generate. Check the errors above.');
+      console.log('You can re-run this script to retry failed photos.');
+    }
+
+    process.exit(failCount > 0 ? 1 : 0);
+  } catch (error) {
+    console.error('\nFatal error:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const eventId = args[0] ? parseInt(args[0], 10) : null;
+
+if (args[0] && isNaN(eventId)) {
+  console.error('Error: eventId must be a number');
+  console.log('Usage: node scripts/generate-watermarks.js [eventId]');
+  process.exit(1);
+}
+
+// Run the script
+generateWatermarks(eventId)
+  .then(() => {
+    process.exit(0);
+  })
+  .catch(error => {
+    console.error('Unhandled error:', error);
+    process.exit(1);
+  });

backend/scripts/migrate-storage.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * migrate-storage.js
+ *
+ * One-shot migration tool to copy every PicPeak content file from the local
+ * filesystem (the legacy STORAGE_PATH) to a configured S3-compatible bucket.
+ *
+ * Reads the relative path of each known asset from the database:
+ *   photos.path
+ *   photos.thumbnail_path
+ *   photos.hero_path
+ *   photos.watermark_path
+ *   events.archive_path
+ *   events.download_zip_path
+ *
+ * For each, streams from local fs → S3, skipping files whose sha256 already
+ * matches a previously uploaded object (idempotent — safe to re-run).
+ *
+ * Does NOT flip STORAGE_BACKEND. After the migration completes clean, the
+ * operator updates their environment + restarts the backend explicitly.
+ *
+ * Usage:
+ *   node backend/scripts/migrate-storage.js                # live migration
+ *   node backend/scripts/migrate-storage.js --dry-run      # report only, no uploads
+ *   node backend/scripts/migrate-storage.js --failures-csv=/path/to/failures.csv
+ *   node backend/scripts/migrate-storage.js --concurrency=4
+ *
+ * Required env (S3 destination — same vars the backend reads with STORAGE_BACKEND=s3):
+ *   STORAGE_S3_BUCKET, STORAGE_S3_REGION, STORAGE_S3_ACCESS_KEY, STORAGE_S3_SECRET_KEY
+ *   STORAGE_S3_ENDPOINT (optional — for MinIO/R2/etc.)
+ *   STORAGE_S3_PREFIX (optional)
+ *
+ * STORAGE_PATH must point at the live local storage root. Postgres connection
+ * uses the same DB env vars the backend uses.
+ */
+
+require('dotenv').config();
+const fs = require('fs');
+const fsp = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+
+const { db } = require('../src/database/db');
+const LocalFsStorage = require('../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../src/services/storage/S3StorageBackend');
+const logger = require('../src/utils/logger');
+
+function parseArgs(argv) {
+  const args = { dryRun: false, concurrency: 4, failuresCsv: '/tmp/migrate-storage-failures.csv' };
+  for (const arg of argv) {
+    if (arg === '--dry-run') args.dryRun = true;
+    else if (arg.startsWith('--concurrency=')) args.concurrency = Math.max(1, parseInt(arg.split('=')[1], 10) || 4);
+    else if (arg.startsWith('--failures-csv=')) args.failuresCsv = arg.split('=')[1];
+    else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: node migrate-storage.js [--dry-run] [--concurrency=N] [--failures-csv=PATH]');
+      process.exit(0);
+    }
+  }
+  return args;
+}
+
+function buildLocalSource() {
+  const root = process.env.STORAGE_PATH;
+  if (!root) {
+    throw new Error('STORAGE_PATH must be set to the local storage root.');
+  }
+  return new LocalFsStorage({ root });
+}
+
+function buildS3Destination() {
+  const required = ['STORAGE_S3_BUCKET', 'STORAGE_S3_ACCESS_KEY', 'STORAGE_S3_SECRET_KEY'];
+  const missing = required.filter((v) => !process.env[v]);
+  if (missing.length) {
+    throw new Error(`Missing S3 env vars: ${missing.join(', ')}`);
+  }
+  return new S3StorageBackend({
+    bucket: process.env.STORAGE_S3_BUCKET,
+    region: process.env.STORAGE_S3_REGION || 'us-east-1',
+    endpoint: process.env.STORAGE_S3_ENDPOINT,
+    accessKeyId: process.env.STORAGE_S3_ACCESS_KEY,
+    secretAccessKey: process.env.STORAGE_S3_SECRET_KEY,
+    prefix: process.env.STORAGE_S3_PREFIX,
+    forcePathStyle: process.env.STORAGE_S3_FORCE_PATH_STYLE === 'true' ? true : undefined,
+    sslEnabled: process.env.STORAGE_S3_SSL !== 'false',
+  });
+}
+
+async function sha256OfFile(localPath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(localPath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+async function collectKeys() {
+  const keys = new Map(); // key -> { source, contentType }
+
+  const addKey = (key, source) => {
+    if (!key) return;
+    const normalized = key.replace(/\\/g, '/').replace(/^\/+/, '');
+    if (!normalized) return;
+    if (!keys.has(normalized)) keys.set(normalized, { source });
+  };
+
+  // photos: path (events/active/{slug}/{filename}), thumbnail_path, hero_path, watermark_path
+  const photoBatch = await db('photos').select('id', 'path', 'thumbnail_path', 'hero_path', 'watermark_path');
+  for (const p of photoBatch) {
+    if (p.path) {
+      const photoKey = p.path.startsWith('events/active/') ? p.path : path.posix.join('events/active', p.path);
+      addKey(photoKey, `photos.path[${p.id}]`);
+    }
+    addKey(p.thumbnail_path, `photos.thumbnail_path[${p.id}]`);
+    addKey(p.hero_path, `photos.hero_path[${p.id}]`);
+    addKey(p.watermark_path, `photos.watermark_path[${p.id}]`);
+  }
+
+  // events: archive_path, download_zip_path
+  const eventBatch = await db('events').select('id', 'archive_path', 'download_zip_path');
+  for (const e of eventBatch) {
+    addKey(e.archive_path, `events.archive_path[${e.id}]`);
+    addKey(e.download_zip_path, `events.download_zip_path[${e.id}]`);
+  }
+
+  return keys;
+}
+
+async function migrateOne(key, meta, { source, dest, dryRun }) {
+  // Source must exist on local disk.
+  const localPath = source.resolveLocalPath(key);
+  let localStat;
+  try {
+    localStat = await fsp.stat(localPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { key, status: 'missing-locally', source: meta.source };
+    }
+    throw err;
+  }
+
+  // Idempotent skip: if S3 already has matching size + sha256.
+  const remoteStat = await dest.stat(key);
+  if (remoteStat && remoteStat.size === localStat.size) {
+    // sha256 match check via metadata is expensive; we trust size match for now.
+    // Operators paranoid about content drift can `rm` the bucket and re-run.
+    return { key, status: 'already-uploaded', source: meta.source };
+  }
+
+  if (dryRun) {
+    return { key, status: 'would-upload', source: meta.source, size: localStat.size };
+  }
+
+  await dest.putFromFile(key, localPath);
+
+  const verify = await dest.stat(key);
+  if (!verify || verify.size !== localStat.size) {
+    return { key, status: 'size-mismatch-after-upload', source: meta.source, expected: localStat.size, got: verify?.size };
+  }
+
+  return { key, status: 'uploaded', source: meta.source, size: localStat.size };
+}
+
+async function processWithConcurrency(items, concurrency, fn) {
+  const results = [];
+  let i = 0;
+  const workers = Array.from({ length: concurrency }, async () => {
+    while (true) {
+      const idx = i++;
+      if (idx >= items.length) return;
+      const [key, meta] = items[idx];
+      try {
+        const r = await fn(key, meta);
+        results.push(r);
+      } catch (err) {
+        results.push({ key, status: 'error', source: meta.source, error: err.message });
+      }
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+function formatCsvCell(v) {
+  if (v == null) return '';
+  const s = String(v);
+  if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+    return `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+async function writeFailuresCsv(filePath, failures) {
+  if (failures.length === 0) {
+    // Touch an empty file with header so callers see a deterministic outcome.
+    await fsp.writeFile(filePath, 'key,source,status,error\n');
+    return;
+  }
+  const lines = ['key,source,status,error'];
+  for (const f of failures) {
+    lines.push([f.key, f.source, f.status, f.error || ''].map(formatCsvCell).join(','));
+  }
+  await fsp.writeFile(filePath, lines.join('\n') + '\n');
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  logger.info(`migrate-storage starting (dry-run=${args.dryRun}, concurrency=${args.concurrency})`);
+
+  const source = buildLocalSource();
+  await source.init();
+
+  const dest = buildS3Destination();
+  await dest.init();
+
+  logger.info('collecting key list from database…');
+  const keys = await collectKeys();
+  logger.info(`found ${keys.size} unique keys to process`);
+
+  const items = Array.from(keys.entries());
+  const results = await processWithConcurrency(items, args.concurrency, (key, meta) =>
+    migrateOne(key, meta, { source, dest, dryRun: args.dryRun })
+  );
+
+  const counts = results.reduce((acc, r) => {
+    acc[r.status] = (acc[r.status] || 0) + 1;
+    return acc;
+  }, {});
+
+  console.log('\n=== migrate-storage summary ===');
+  for (const [status, count] of Object.entries(counts).sort()) {
+    console.log(`  ${status.padEnd(28)} ${count}`);
+  }
+
+  const failureStatuses = new Set(['error', 'missing-locally', 'size-mismatch-after-upload']);
+  const failures = results.filter((r) => failureStatuses.has(r.status));
+  await writeFailuresCsv(args.failuresCsv, failures);
+
+  if (failures.length > 0) {
+    console.log(`\nWrote ${failures.length} failures to ${args.failuresCsv}`);
+    console.log('Re-run with --dry-run to triage; fix sources or remove DB rows that point at missing files.');
+    process.exitCode = 1;
+  } else if (args.dryRun) {
+    console.log(`\nDry-run complete. Re-run without --dry-run to perform the migration.`);
+    console.log(`(Empty failures CSV written to ${args.failuresCsv}.)`);
+  } else {
+    console.log(`\nMigration complete. Update STORAGE_BACKEND=s3 + restart the backend to switch over.`);
+  }
+
+  await db.destroy();
+}
+
+main().catch(async (err) => {
+  console.error('migrate-storage failed:', err);
+  try { await db.destroy(); } catch (_) { /* ignore */ }
+  process.exit(2);
+});

backend/scripts/set-admin-password.js

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+/**
+ * Script to set/reset admin password
+ *
+ * Usage:
+ *   node set-admin-password.js <new-password>
+ *   node set-admin-password.js --env  (uses ADMIN_PASSWORD environment variable)
+ *
+ * Security: Password must be at least 8 characters with mixed case, numbers, and special characters
+ */
+
 const bcrypt = require('bcrypt');
 const path = require('path');
 require('dotenv').config({ path: path.join(__dirname, '../.env') });
@@ -16,22 +26,108 @@ const db = knex({
   }
 });
 
+/**
+ * Validate password strength
+ */
+function validatePassword(password) {
+  if (!password || password.length < 8) {
+    return { valid: false, error: 'Password must be at least 8 characters long' };
+  }
+  if (!/[a-z]/.test(password)) {
+    return { valid: false, error: 'Password must contain at least one lowercase letter' };
+  }
+  if (!/[A-Z]/.test(password)) {
+    return { valid: false, error: 'Password must contain at least one uppercase letter' };
+  }
+  if (!/[0-9]/.test(password)) {
+    return { valid: false, error: 'Password must contain at least one number' };
+  }
+  if (!/[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]/.test(password)) {
+    return { valid: false, error: 'Password must contain at least one special character' };
+  }
+  return { valid: true };
+}
+
+function printUsage() {
+  console.log(`
+Usage:
+  node set-admin-password.js <new-password>
+  node set-admin-password.js --env
+
+Options:
+  <new-password>  The new password to set (must meet security requirements)
+  --env           Use ADMIN_PASSWORD environment variable
+
+Security Requirements:
+  - At least 8 characters
+  - At least one lowercase letter
+  - At least one uppercase letter
+  - At least one number
+  - At least one special character (!@#$%^&*()_+-=[]{}|;':\",./<>?)
+
+Examples:
+  node set-admin-password.js "MySecure@Pass123"
+  ADMIN_PASSWORD="MySecure@Pass123" node set-admin-password.js --env
+`);
+}
+
 async function setAdminPassword() {
   try {
-    const password = 'admin123';
-    const hashedPassword = await bcrypt.hash(password, 10);
-    
-    await db('admin_users')
+    // Get password from argument or environment
+    const args = process.argv.slice(2);
+    let password;
+
+    if (args.length === 0) {
+      console.error('❌ Error: No password provided\n');
+      printUsage();
+      process.exit(1);
+    }
+
+    if (args[0] === '--env') {
+      password = process.env.ADMIN_PASSWORD;
+      if (!password) {
+        console.error('❌ Error: ADMIN_PASSWORD environment variable not set');
+        process.exit(1);
+      }
+    } else if (args[0] === '--help' || args[0] === '-h') {
+      printUsage();
+      process.exit(0);
+    } else {
+      password = args[0];
+    }
+
+    // Validate password strength
+    const validation = validatePassword(password);
+    if (!validation.valid) {
+      console.error(`❌ Error: ${validation.error}`);
+      process.exit(1);
+    }
+
+    // Hash password
+    const hashedPassword = await bcrypt.hash(password, 12);
+
+    // Update database
+    const updated = await db('admin_users')
       .where('username', 'admin')
       .update({
         password_hash: hashedPassword,
+        password_changed_at: new Date(),
         updated_at: new Date()
       });
-    
-    console.log('✅ Admin password set to: admin123');
+
+    if (updated === 0) {
+      console.error('❌ Error: Admin user not found');
+      process.exit(1);
+    }
+
+    console.log('✅ Admin password updated successfully');
+    console.log('   Note: All existing sessions have been invalidated');
+
+    await db.destroy();
     process.exit(0);
   } catch (error) {
-    console.error('❌ Error setting password:', error);
+    console.error('❌ Error setting password:', error.message);
+    await db.destroy();
     process.exit(1);
   }
 }