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

chore(beta): release 3.42.2-beta.0

.claudedocs/scans/security-20250713.md

@@ -1,286 +0,0 @@
-# Security Scan Report - Wedding Photo Sharing Application
-**Date**: July 13, 2025  
-**Scanner**: Claude Security Audit with --security --validate flags  
-**Overall Risk Level**: MEDIUM-HIGH  
-
-## Executive Summary
-
-The wedding photo sharing application demonstrates strong security fundamentals with comprehensive input validation, proper authentication mechanisms, and good file security practices. However, several critical issues require immediate attention, particularly around hardcoded secrets, token storage, and Content Security Policy configuration.
-
-### Security Score: 6.5/10
-
-**Strengths**: Excellent input validation, parameterized queries, file security, rate limiting  
-**Critical Issues**: Hardcoded JWT secrets, localStorage token storage, weak CSP, console logging in production
-
----
-
-## 🔴 CRITICAL FINDINGS (Immediate Action Required)
-
-### 1. Hardcoded JWT Secret in Development
-- **Location**: Backend `.env` file
-- **Risk**: Token forgery, authentication bypass
-- **Impact**: Complete authentication compromise
-- **Remediation**: 
-  ```bash
-  # Generate secure secret
-  openssl rand -base64 32
-  # Never commit to repository
-  echo ".env" >> .gitignore
-  ```
-
-### 2. Gallery Tokens in localStorage
-- **Location**: Frontend `api.ts` and auth contexts
-- **Risk**: XSS token theft
-- **Impact**: Gallery access compromise
-- **Remediation**: Move to httpOnly cookies:
-  ```typescript
-  Cookies.set(`gallery_token_${slug}`, token, {
-    httpOnly: true,
-    secure: true,
-    sameSite: 'strict'
-  });
-  ```
-
-### 3. Weak Content Security Policy
-- **Location**: Frontend `nginx.conf`
-- **Risk**: XSS, code injection
-- **Current**: `unsafe-inline` and `unsafe-eval` allowed
-- **Remediation**: Implement strict CSP (see detailed recommendations below)
-
----
-
-## 🟠 HIGH SEVERITY FINDINGS
-
-### 1. Console Logging in Production
-- **Locations**: 61 instances across frontend
-- **Risk**: Information disclosure
-- **Impact**: Leaking sensitive data, debugging info
-- **Remediation**: Implement environment-aware logging
-
-### 2. Token Revocation Vulnerability
-- **Location**: Backend `tokenRevocation.js`
-- **Risk**: Token manipulation
-- **Impact**: Bypass revocation checks
-- **Remediation**: Verify token signature before decoding
-
-### 3. Source Maps in Production
-- **Location**: Frontend build configuration
-- **Risk**: Source code exposure
-- **Impact**: Reveals application structure
-- **Remediation**: Disable in production builds
-
-### 4. Missing Security Headers
-- **Location**: nginx configuration
-- **Missing**: HSTS, Permissions-Policy
-- **Impact**: Various client-side attacks
-- **Remediation**: Add comprehensive security headers
-
----
-
-## 🟡 MEDIUM SEVERITY FINDINGS
-
-### 1. Rate Limiting Bypass Potential
-- **Location**: Backend rate limiter
-- **Risk**: DoS attacks
-- **Current**: JWT validation in rate limiter
-- **Remediation**: Use IP-based limiting only
-
-### 2. Incomplete SQL Injection Protection
-- **Location**: Complex dashboard queries
-- **Risk**: Potential injection in edge cases
-- **Current**: Mostly parameterized
-- **Remediation**: Use query builder exclusively
-
-### 3. Session Management
-- **Issue**: No gallery token invalidation on password change
-- **Risk**: Persistent access after compromise
-- **Remediation**: Implement token revocation
-
-### 4. Path Traversal in Gallery Slugs
-- **Location**: Frontend gallery routes
-- **Risk**: Directory traversal attempts
-- **Remediation**: Validate and sanitize slugs
-
----
-
-## 🟢 LOW SEVERITY FINDINGS
-
-### 1. Verbose Error Messages
-- **Location**: Multiple API endpoints
-- **Risk**: Information disclosure
-- **Remediation**: Generic client errors, detailed server logs
-
-### 2. Weak Gallery Passwords
-- **Current**: zxcvbn score 2/4 allowed
-- **Risk**: Brute force attacks
-- **Remediation**: Increase to score 3/4
-
-### 3. Missing File Size Validation
-- **Location**: Frontend upload components
-- **Risk**: DoS via large uploads
-- **Remediation**: Add client-side size checks
-
----
-
-## ✅ SECURITY STRENGTHS
-
-### Authentication & Authorization
-- JWT with proper expiration (24h/7d)
-- Token type validation
-- IP tracking and validation
-- Password change detection
-- Token revocation system
-- Bcrypt with 12 rounds
-- zxcvbn password strength checking
-
-### Input Validation & SQL Security
-- express-validator on all endpoints
-- Parameterized queries via Knex
-- SQL injection protection utilities
-- Path traversal prevention
-- Comprehensive input sanitization
-
-### File Security
-- Magic number verification
-- MIME type validation
-- Safe filename generation
-- Directory traversal protection
-- File extension whitelist
-
-### Rate Limiting & DoS Protection
-- General: 100 req/15min
-- Auth endpoints: 5 req/15min
-- Account lockout after failed attempts
-- Suspicious activity detection
-
-### Frontend Security
-- React's built-in XSS protection
-- DOMPurify for HTML content
-- No eval() or innerHTML usage
-- Proper error boundaries
-- ReCAPTCHA integration
-
----
-
-## 📊 DEPENDENCY ANALYSIS
-
-### Current Status
-- **Backend**: 0 vulnerabilities (691 packages)
-- **Frontend**: 0 vulnerabilities (434 packages)
-
-### Recommended Updates
-1. **bcrypt** 5.1.1 → 6.0.0 (performance, compatibility)
-2. **helmet** 7.2.0 → 8.1.0 (new security features)
-3. **@tiptap** 2.x → 3.x (security improvements)
-
-### Supply Chain Assessment
-- All major dependencies from trusted sources
-- No typosquatting detected
-- Regular maintenance observed
-- MIT/ISC/Apache licenses only
-
----
-
-## 🛠️ REMEDIATION PLAN
-
-### Phase 1: Critical (Within 24 hours)
-1. Replace hardcoded JWT secret with secure random value
-2. Move gallery tokens from localStorage to httpOnly cookies
-3. Implement strict CSP without unsafe-eval
-4. Remove or wrap console.log statements
-
-### Phase 2: High Priority (Within 1 week)
-1. Disable source maps in production
-2. Add missing security headers (HSTS, Permissions-Policy)
-3. Fix token revocation vulnerability
-4. Update critical dependencies (bcrypt, helmet)
-
-### Phase 3: Medium Priority (Within 1 month)
-1. Implement comprehensive logging strategy
-2. Add gallery slug validation
-3. Enhance rate limiting logic
-4. Implement session invalidation on password change
-
-### Phase 4: Ongoing
-1. Weekly dependency scanning
-2. Implement security testing in CI/CD
-3. Regular penetration testing
-4. Security awareness training
-
----
-
-## 🔒 RECOMMENDED CSP CONFIGURATION
-
-```nginx
-add_header Content-Security-Policy "
-  default-src 'self';
-  script-src 'self' 'nonce-{RANDOM}' https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/;
-  style-src 'self' 'unsafe-inline';
-  img-src 'self' data: blob: https:;
-  font-src 'self';
-  connect-src 'self' https://analytics.domain.com;
-  frame-src https://www.google.com/recaptcha/;
-  object-src 'none';
-  base-uri 'self';
-  form-action 'self';
-  frame-ancestors 'none';
-  upgrade-insecure-requests;
-" always;
-```
-
----
-
-## 🚀 SECURITY IMPROVEMENTS ROADMAP
-
-### Immediate Implementation
-```bash
-# 1. Generate secure secrets
-openssl rand -base64 32 > jwt-secret.txt
-
-# 2. Update dependencies
-cd backend && npm install bcrypt@^6.0.0 helmet@^8.1.0
-cd ../frontend && npm update
-
-# 3. Add security scanning
-npm install -D npm-audit-resolver
-```
-
-### CI/CD Integration
-```yaml
-# Add to CI pipeline
-- name: Security Scan
-  run: |
-    npm audit --audit-level=moderate
-    npm run test:security
-```
-
-### Monitoring & Alerting
-1. Implement fail2ban for repeated auth failures
-2. Set up log analysis for suspicious patterns
-3. Configure alerts for security events
-4. Regular vulnerability scanning
-
----
-
-## 📋 COMPLIANCE CHECKLIST
-
-- [ ] OWASP Top 10 addressed
-- [ ] GDPR compliance (data minimization, right to erasure)
-- [ ] Security headers implemented
-- [ ] Dependency scanning automated
-- [ ] Incident response plan documented
-- [ ] Security documentation maintained
-- [ ] Regular security reviews scheduled
-
----
-
-## 🎯 CONCLUSION
-
-The wedding photo sharing application has a solid security foundation with excellent input validation and authentication mechanisms. However, operational security practices need immediate attention. The critical issues around secret management and token storage must be addressed before production deployment.
-
-Implementing the recommended fixes will raise the security score from 6.5/10 to approximately 8.5/10, providing a robust and secure platform for wedding photo sharing.
-
----
-
-*Generated by Claude Security Scanner v1.0*  
-*Next scan recommended: After Phase 1 remediation completion*

.drone.yml

@@ -1,159 +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}
-
-  # -------- NEW: Create GitHub Release --------
-  - name: github-release
-    image: plugins/github-release
-    when:
-      event: tag
-    settings:
-      api_key:
-        from_secret: GITHUB_TOKEN
-      files: []
-      title: PicPeak ${DRONE_TAG}
-      note: |
-        # PicPeak ${DRONE_TAG}
-
-        ## 🐳 Docker Images
-
-        This release includes Docker images published to GitHub Container Registry:
-
-        ```bash
-        # Backend
-        docker pull ghcr.io/the-luap/picpeak-backend:${DRONE_TAG}
-        docker pull ghcr.io/the-luap/picpeak-backend:latest
-
-        # Frontend
-        docker pull ghcr.io/the-luap/picpeak-frontend:${DRONE_TAG}
-        docker pull ghcr.io/the-luap/picpeak-frontend:latest
-        ```
-
-        ## 📦 What's New
-
-        See the [README](https://github.com/the-luap/picpeak#readme) for features and documentation.
-
-        ## 🚀 Quick Start
-
-        ```bash
-        # Clone and deploy
-        git clone https://github.com/the-luap/picpeak.git
-        cd picpeak
-
-        # Use the tagged version
-        docker-compose -f docker-compose.prod.yml up -d
-        ```
-
-        ---
-
-        For detailed deployment instructions, see the [Deployment Guide](https://github.com/the-luap/picpeak/blob/main/DEPLOYMENT.md).
-
-trigger:
-  event:
-    - tag

.env.example

@@ -1,47 +1,200 @@
-# PicPeak Development Environment Configuration
-# Copy this file to .env for local development
+# PicPeak Environment Configuration
+# Copy this file to .env and update with your values
 
-# SECURITY WARNING: This configuration is for development only!
-# For production, use .env.production.example
+# Environment
+NODE_ENV=production
 
-# JWT Secret (Change in production!)
-# Generate secure secret with: openssl rand -base64 32
-JWT_SECRET=dev-secret-DO-NOT-USE-IN-PRODUCTION
+# JWT Secret (generate with: openssl rand -base64 64)
+JWT_SECRET=your_very_long_random_jwt_secret_here
 
-# Application URLs (Docker Compose development setup)
-ADMIN_URL=http://localhost:3005
-FRONTEND_URL=http://localhost:3005
-BACKEND_URL=http://localhost:3001
+# 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
 
-# Database Configuration (SQLite for development)
-DATABASE_CLIENT=sqlite3
-DATABASE_PATH=./data/photo_sharing.db
+# Cookie SameSite attribute (Lax | Strict | None). Default: Lax
+# COOKIE_SAMESITE=Lax
 
-# Email Configuration (Mailhog for development)
-# Access Mailhog UI at: http://localhost:8025
-SMTP_HOST=mailhog
-SMTP_PORT=1025
+# 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
+# IMPORTANT: Avoid $ character in passwords - Docker Compose interprets it as variable substitution
+# If you must use $, escape it as $$ (e.g., Pass$$word instead of Pass$word)
+DB_PASSWORD=your_secure_postgres_password_here
+DB_NAME=picpeak_prod
+
+# Redis Configuration
+# IMPORTANT: Same warning applies - avoid $ or escape as $$
+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
+# For SendGrid: SMTP_USER=apikey, SMTP_PASS=your-api-key
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
 SMTP_SECURE=false
-SMTP_USER=
-SMTP_PASS=
-EMAIL_FROM=noreply@localhost
+SMTP_USER=your-email@gmail.com
+SMTP_PASS=your-app-specific-password
+EMAIL_FROM=noreply@yourdomain.com
 
-# Backend Port Configuration
-PORT=3001
+# Application URLs
+# Use full origin with scheme, no trailing slash.
+# Admin UI is served by the frontend at /admin.
+FRONTEND_URL=https://yourdomain.com
+ADMIN_URL=https://yourdomain.com
 
-# Optional: Umami Analytics Backend Config
-# NOTE: Primary configuration through Admin UI > Settings > Analytics
-# These are fallback values for server-side tracking
-# UMAMI_URL=https://analytics.example.com
-# UMAMI_WEBSITE_ID=your-website-id
-# UMAMI_HASH_SALT=your-hash-salt
+# 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
 
-# Development Features
-NODE_ENV=development
-LOG_LEVEL=debug
+# 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.
+VITE_API_URL=/api
 
-# Admin Setup Notes:
-# 1. Run 'npm run migrate' in backend folder
-# 2. Admin credentials will be auto-generated
-# 3. Check ADMIN_CREDENTIALS.txt for login details
-# 4. Change password on first login (required)
+# Port Configuration (optional)
+# BACKEND_PORT=3001
+# FRONTEND_PORT=3000
+# 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
+
+# Runtime user mapping for Docker (optional)
+# Set these to your host user's UID/GID to avoid permission issues on bind mounts.
+# Run `id -u` and `id -g` on host to get values. Defaults to 1001.
+PUID=1001
+PGID=1001
+
+# Analytics (Optional - Umami)
+VITE_UMAMI_URL=
+VITE_UMAMI_WEBSITE_ID=
+VITE_UMAMI_SHARE_URL=
+
+# Storage variables (host paths)
+# These control where data is stored on the host. Defaults are local folders.
+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
+# let the frontend Nginx proxy /api to the backend. Only if you rebuild the frontend
+# should you change VITE_API_URL at build time.

.env.production.example

@@ -1,100 +0,0 @@
-# PicPeak Production Configuration
-# Copy this file to .env and update with your production values
-
-# ============================================
-# CRITICAL SECURITY - MUST CHANGE ALL VALUES!
-# ============================================
-
-# JWT Secret - REQUIRED (minimum 32 characters)
-# Generate with: openssl rand -base64 32
-JWT_SECRET=CHANGE-THIS-PRODUCTION-SECRET-USE-OPENSSL-COMMAND
-
-# Application URLs - REQUIRED (your actual domain)
-FRONTEND_URL=https://your-domain.com
-BACKEND_URL=https://your-domain.com
-ADMIN_URL=https://your-domain.com
-
-# ============================================
-# DATABASE CONFIGURATION - REQUIRED
-# ============================================
-
-# PostgreSQL Configuration (Recommended for production)
-DATABASE_CLIENT=pg
-DB_HOST=postgres  # or your database host
-DB_PORT=5432
-DB_NAME=picpeak
-DB_USER=picpeak
-DB_PASSWORD=CHANGE-THIS-SECURE-DATABASE-PASSWORD
-
-# ============================================
-# EMAIL CONFIGURATION - REQUIRED
-# ============================================
-
-# Example: Gmail with App Password
-# SMTP_HOST=smtp.gmail.com
-# SMTP_PORT=587
-# SMTP_SECURE=false
-# SMTP_USER=your-email@gmail.com
-# SMTP_PASS=your-16-char-app-password
-# EMAIL_FROM=Your Name <your-email@gmail.com>
-
-# Example: SendGrid
-SMTP_HOST=smtp.sendgrid.net
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=apikey
-SMTP_PASS=YOUR-SENDGRID-API-KEY
-EMAIL_FROM=PicPeak <noreply@your-domain.com>
-
-# ============================================
-# ADMIN SETUP - AUTO-GENERATED
-# ============================================
-# NOTE: Admin credentials are automatically generated during setup
-# DO NOT set ADMIN_EMAIL or ADMIN_PASSWORD anymore!
-# Run 'npm run migrate' and check ADMIN_CREDENTIALS.txt
-
-# ============================================
-# OPTIONAL CONFIGURATION
-# ============================================
-
-# Umami Analytics (Optional - Fallback values)
-# Primary config via Admin UI > Settings > Analytics
-# UMAMI_URL=https://analytics.your-domain.com
-# UMAMI_WEBSITE_ID=your-website-id
-# UMAMI_HASH_SALT=your-hash-salt
-
-# Frontend Analytics (Optional - Fallback values)
-# VITE_UMAMI_URL=https://analytics.your-domain.com
-# VITE_UMAMI_WEBSITE_ID=your-website-id
-# VITE_UMAMI_SHARE_URL=https://analytics.your-domain.com/share/xyz/gallery
-
-# ============================================
-# PERFORMANCE & SECURITY TUNING
-# ============================================
-
-NODE_ENV=production
-PORT=3001
-LOG_LEVEL=info
-
-# Security Settings (Defaults are secure)
-BCRYPT_ROUNDS=12
-SESSION_TIMEOUT_MINUTES=60
-RATE_LIMIT_WINDOW_MS=900000     # 15 minutes
-RATE_LIMIT_MAX_REQUESTS=100      # per window
-
-# Connection Pool (Adjust based on load)
-DB_POOL_MIN=5
-DB_POOL_MAX=25
-
-# ============================================
-# DOCKER COMPOSE SPECIFIC
-# ============================================
-
-# Traefik Configuration (if using Traefik)
-DOMAIN=your-domain.com
-LETSENCRYPT_EMAIL=admin@your-domain.com
-
-# Volume Paths (Docker)
-STORAGE_PATH=/app/storage
-EVENTS_PATH=/app/storage/events
-ARCHIVE_PATH=/app/storage/events/archived

.gitattributes-github

@@ -1,12 +0,0 @@
-# Files to exclude from GitHub mirror
-.env* export-ignore
-docker-compose.prod.yml export-ignore
-.claudedocs/ export-ignore
-backend/data/ export-ignore
-backend/storage/ export-ignore
-backend/.env* export-ignore
-frontend/.env* export-ignore
-secrets/ export-ignore
-*.key export-ignore
-*.pem export-ignore
-.gitea/ export-ignore

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

@@ -1,220 +0,0 @@
-name: Mirror to GitHub
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:  # Allow manual triggering
-
-jobs:
-  mirror:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository with full history
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0  # Full history needed for finding the commit
-
-      - name: Setup Git
-        run: |
-          git config --global user.name "the-luap"
-          git config --global user.email "paul-nothaft@hotmail.de"
-
-      - name: Debug - Show current branch and status
-        run: |
-          echo "Current branch:"
-          git branch -a
-          echo "Git status:"
-          git status
-          echo "Remote info:"
-          git remote -v
-          echo "Checking target commit exists:"
-          git show --oneline 7aca927937 || echo "Target commit not found!"
-
-      - name: Create completely new history from specific commit
-        run: |
-          TARGET_COMMIT="7aca927937"
-          
-          # Verify the target commit exists
-          if ! git cat-file -e $TARGET_COMMIT^{commit}; then
-            echo "ERROR: Target commit $TARGET_COMMIT does not exist!"
-            exit 1
-          fi
-          
-          echo "✅ Target commit found: $(git log --oneline -1 $TARGET_COMMIT)"
-          
-          # Clean up any existing github-mirror branch
-          git branch -D github-mirror || true
-          
-          # Create a completely new orphan branch (no history)
-          git checkout --orphan github-mirror
-          
-          # Clear the staging area completely
-          git rm -rf . || true
-          
-          # Get the file tree from the target commit and create initial commit
-          echo "Creating new history starting from $TARGET_COMMIT..."
-          git read-tree $TARGET_COMMIT
-          git commit -m "Initial commit - imported from $(git log --oneline -1 $TARGET_COMMIT)"
-          
-          echo "✅ Created new initial commit: $(git log --oneline -1)"
-          
-          # Now get all commits after the target commit and apply their changes
-          COMMITS_AFTER_TARGET=$(git rev-list --reverse --no-merges $TARGET_COMMIT..main)
-          
-          if [ -n "$COMMITS_AFTER_TARGET" ]; then
-            echo "📋 Applying changes from commits after $TARGET_COMMIT (excluding Claude commits):"
-            
-            for commit in $COMMITS_AFTER_TARGET; do
-              # Get the commit author name
-              COMMIT_AUTHOR_NAME=$(git log --format="%an" -n 1 $commit)
-              
-              # Skip commits by Claude
-              if [ "$COMMIT_AUTHOR_NAME" = "Claude" ]; then
-                echo "⚠️ Skipping commit by Claude: $(git log --oneline -1 $commit)"
-                continue
-              fi
-              
-              echo "Processing: $(git log --oneline -1 $commit)"
-              
-              # Get the commit message and author info
-              COMMIT_MSG=$(git log --format="%B" -n 1 $commit)
-              COMMIT_AUTHOR=$(git log --format="%an <%ae>" -n 1 $commit)
-              COMMIT_DATE=$(git log --format="%ad" -n 1 $commit)
-              
-              # Apply the changes from this commit
-              if git diff-tree --no-commit-id --name-only -r $commit | xargs -I {} git show $commit:{} > /dev/null 2>&1; then
-                # Apply file changes
-                git checkout $commit -- . || true
-                
-                # Stage all changes
-                git add -A
-                
-                # Only commit if there are changes
-                if ! git diff --cached --quiet; then
-                  # Create new commit with original metadata but new SHA
-                  GIT_AUTHOR_NAME=$(echo "$COMMIT_AUTHOR" | cut -d'<' -f1 | xargs)
-                  GIT_AUTHOR_EMAIL=$(echo "$COMMIT_AUTHOR" | cut -d'<' -f2 | cut -d'>' -f1)
-                  GIT_AUTHOR_DATE="$COMMIT_DATE"
-                  
-                  export GIT_AUTHOR_NAME GIT_AUTHOR_EMAIL GIT_AUTHOR_DATE
-                  git commit -m "$COMMIT_MSG"
-                  echo "✅ Applied changes as new commit: $(git log --oneline -1)"
-                else
-                  echo "⚠️ No changes to commit for $commit"
-                fi
-              else
-                echo "⚠️ Skipping problematic commit $commit"
-              fi
-            done
-            
-            echo "✅ Finished creating new history"
-          else
-            echo "✅ No commits after target commit - history starts fresh"
-          fi
-          
-          echo ""
-          echo "=== New History Summary ==="
-          echo "Total commits in new history: $(git rev-list --count github-mirror)"
-          echo "History starts with: $(git log --oneline --reverse | head -1)"
-          echo "Latest commit: $(git log --oneline -1)"
-
-      - name: Remove sensitive files and directories
-        run: |
-          # Switch to the github-mirror branch
-          git checkout github-mirror
-          
-          echo "Current files before cleanup:"
-          ls -la | head -10 || true
-          echo "..."
-          
-          # Remove sensitive files/directories if they exist
-          echo "Removing sensitive files..."
-          rm -rf .env || true
-          rm -rf backend/.env* || true
-          rm -rf frontend/.env* || true
-          rm -rf docker-compose.prod.yml || true
-          rm -rf .claudedocs/ || true
-          rm -rf backend/data/ || true
-          rm -rf backend/storage/ || true
-          rm -rf .gitea/ || true
-          rm -rf scripts/install-gitea-runner.sh || true
-          rm -rf .drone* || true
-          rm -rf .github-mirror-exclude || true
-          rm -rf .gitattributes-github || true
-          rm -rf photo-sharing-prd.md || true
-          rm -rf CLAUDE.md || true
-          rm -rf PRODUCTION_DEPLOYMENT_GUIDE.md || true
-          rm -rf logs/ || true
-          rm -rf frontend/.claudedocs/ || true
-          rm -rf test-maintenance.sh || true
-          rm -rf storage/ || 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: Verify completely new history
-        run: |
-          git checkout github-mirror
-          echo "=== Final History Verification ==="
-          echo "Total commits in new github-mirror branch: $(git rev-list --count github-mirror)"
-          echo ""
-          echo "Complete commit history (should start from target commit content):"
-          git log --oneline --reverse
-          echo ""
-          echo "⚠️ Note: This is a completely NEW history with new commit SHAs"
-          echo "🔍 Original target commit content preserved but with new commit ID"
-
-      - name: Check GitHub token
-        env:
-          GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }}
-        run: |
-          if [ -z "$GITHUBTOKEN" ]; then
-            echo "ERROR: GITHUBTOKEN secret is not set!"
-            exit 1
-          else
-            echo "GitHub token is available (length: ${#GITHUBTOKEN})"
-          fi
-
-      - name: Force push completely new history to GitHub
-        env:
-          GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }}
-        run: |
-          # Switch to github-mirror branch
-          git checkout github-mirror
-          
-          # Remove existing github remote if it exists
-          git remote remove github || true
-          
-          # Add GitHub remote
-          git remote add github https://x-access-token:${GITHUBTOKEN}@github.com/the-luap/picpeak.git
-          
-          # Verify remote was added
-          echo "GitHub remote added:"
-          git remote -v
-          
-          # Force push the completely new history to GitHub main
-          echo "🔥 FORCE PUSHING completely new history to GitHub..."
-          echo "⚠️ This will COMPLETELY REPLACE all history on GitHub!"
-          git push github github-mirror:main --force
-          echo "✅ Force push completed - GitHub now has completely new history!"
-
-      - name: Workflow completed
-        run: |
-          echo "✅ Mirror to GitHub workflow completed successfully!"
-          echo "🔥 COMPLETE HISTORY REPLACEMENT: GitHub now has entirely new history"
-          echo "📊 History starts from commit content: 7aca927937"
-          echo "🔍 Check https://github.com/the-luap/picpeak to verify the new history"
-          echo "📈 Total commits pushed: $(git rev-list --count github-mirror)"
-          echo "🆕 All commit SHAs are NEW - no connection to previous history"

.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,267 +0,0 @@
-name: Version and Release
-
-on:
-  push:
-    branches: [ main ]
-    paths-ignore:
-      - '**.md'
-      - '.gitea/**'
-      - '.drone.yml'
-
-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.0.0")
-          FRONTEND_VERSION=$(node -p "require('./frontend/package.json').version" 2>/dev/null || echo "1.0.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
-          NEW_PATCH=$((PATCH + 1))
-          NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH"
-          
-          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-mirror-exclude

@@ -1,24 +0,0 @@
-# Exclude patterns for GitHub mirror
-.env
-.env.*
-.env*
-docker-compose.prod.yml
-docker-compose.traefik.yml
-.claudedocs/
-backend/data/
-backend/storage/
-backend/.env*
-frontend/.env*
-secrets/
-*.key
-*.pem
-.gitea/
-node_modules/
-dist/
-build/
-*.log
-.DS_Store
-deploy/
-certbot/
-nginx/
-photo-sharing-prd.md

.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/README-DOCKER.md

@@ -0,0 +1,213 @@
+# Docker Build and Push Workflow
+
+This GitHub Actions workflow automatically builds and pushes Docker images for both the backend and frontend to GitHub Container Registry (ghcr.io).
+
+## Features
+
+- 🔧 **Automatic builds** on push to main/develop branches, PRs, and releases
+- 🏗️ **Multi-architecture support** (linux/amd64 and linux/arm64)
+- 🏷️ **Smart tagging** based on branches, versions, and commits
+- 🔒 **Security scanning** with Trivy vulnerability scanner
+- 💾 **Build caching** for faster subsequent builds
+- 📊 **Build summaries** in GitHub Actions UI
+
+## Authentication
+
+The workflow uses the built-in `GITHUB_TOKEN` for authentication with GitHub Container Registry. No additional setup or personal access tokens are required.
+
+### Required Permissions
+
+The workflow automatically sets the necessary permissions:
+- `contents: read` - To checkout the repository
+- `packages: write` - To push images to ghcr.io
+- `security-events: write` - To upload security scan results
+
+## Image Tags
+
+Images are automatically tagged based on the trigger event:
+
+| Event | Tags Generated |
+|-------|---------------|
+| Push to main | `latest`, `main`, `main-<short-sha>` |
+| Push to develop | `develop`, `develop-<short-sha>` |
+| Pull Request | `pr-<number>` |
+| Release (v1.2.3) | `1.2.3`, `1.2`, `1`, `latest` |
+| Manual trigger | Based on branch + optional push |
+
+## Usage
+
+### Pull Images
+
+Once published, images can be pulled using:
+
+```bash
+# Pull backend image
+docker pull ghcr.io/the-luap/picpeak/backend:latest
+
+# Pull frontend image
+docker pull ghcr.io/the-luap/picpeak/frontend:latest
+
+# Pull specific version
+docker pull ghcr.io/the-luap/picpeak/backend:v1.0.0
+
+# Pull for specific architecture
+docker pull --platform linux/arm64 ghcr.io/the-luap/picpeak/backend:latest
+```
+
+### Using in Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  backend:
+    image: ghcr.io/the-luap/picpeak/backend:latest
+    environment:
+      - NODE_ENV=production
+    ports:
+      - "3001:3000"
+
+  frontend:
+    image: ghcr.io/the-luap/picpeak/frontend:latest
+    ports:
+      - "80:80"
+```
+
+### Using in Kubernetes
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: picpeak-backend
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+      - name: backend
+        image: ghcr.io/the-luap/picpeak/backend:latest
+        imagePullPolicy: Always
+```
+
+## Manual Workflow Trigger
+
+You can manually trigger the workflow from the Actions tab:
+
+1. Go to Actions → "Build and Push Docker Images"
+2. Click "Run workflow"
+3. Select branch and whether to push images
+4. Click "Run workflow"
+
+## Security Scanning
+
+The workflow includes Trivy vulnerability scanning that:
+- Scans for CRITICAL and HIGH severity vulnerabilities
+- Uploads results to GitHub Security tab
+- Available under Security → Code scanning alerts
+
+## Build Optimization
+
+The workflow uses several optimization techniques:
+
+1. **GitHub Actions Cache**: Speeds up builds by caching layers
+2. **Multi-stage builds**: Reduces final image size
+3. **Parallel builds**: Backend and frontend build simultaneously
+4. **Smart rebuilds**: Only rebuilds changed components
+
+## Troubleshooting
+
+### Permission Denied Errors
+
+If you encounter permission errors when pushing images:
+
+1. **First-time setup**: The first push creates a private package. You may need to:
+   - Go to your package settings at `https://github.com/users/YOUR_USERNAME/packages`
+   - Link the package to your repository
+   - Set package visibility (public/private)
+
+2. **Organization repositories**: Ensure the organization allows GitHub Actions to create packages
+
+### Build Failures
+
+Check the workflow logs in the Actions tab for detailed error messages. Common issues:
+- Missing dependencies in package.json
+- Dockerfile syntax errors
+- Network issues during package installation
+
+### Image Not Found
+
+If images aren't visible after successful push:
+- Check package visibility settings
+- Ensure you're authenticated to pull private images:
+  ```bash
+  echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin
+  ```
+
+## Package Management
+
+### View Packages
+
+Your Docker images are available at:
+- Backend: `https://github.com/users/the-luap/packages/container/package/picpeak%2Fbackend`
+- Frontend: `https://github.com/users/the-luap/packages/container/package/picpeak%2Ffrontend`
+
+### Delete Old Versions
+
+To save storage, you can delete old versions:
+1. Go to package settings
+2. Click on "Manage versions"
+3. Select versions to delete
+4. Click "Delete selected versions"
+
+### Set Retention Policy
+
+Configure automatic cleanup in package settings:
+1. Go to package settings
+2. Click on "Manage Actions access"
+3. Set retention days for untagged versions
+
+## Best Practices
+
+1. **Use semantic versioning** for releases (e.g., v1.2.3)
+2. **Test images locally** before pushing to production
+3. **Monitor security alerts** from Trivy scans
+4. **Clean up old images** regularly to save storage
+5. **Use specific tags** in production (avoid `latest`)
+
+## Advanced Configuration
+
+### Custom Registry
+
+To use a different registry, update the workflow:
+
+```yaml
+env:
+  REGISTRY: docker.io  # or your custom registry
+  BACKEND_IMAGE_NAME: yourusername/picpeak-backend
+```
+
+### Additional Platforms
+
+To build for more platforms:
+
+```yaml
+platforms: linux/amd64,linux/arm64,linux/arm/v7
+```
+
+### Custom Build Arguments
+
+Add build arguments in the workflow:
+
+```yaml
+build-args: |
+  NODE_VERSION=20
+  API_URL=${{ secrets.API_URL }}
+```
+
+## Related Documentation
+
+- [GitHub Container Registry Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
+- [Docker Build Action](https://github.com/docker/build-push-action)
+- [Trivy Security Scanner](https://github.com/aquasecurity/trivy)
+- [Multi-platform Builds](https://docs.docker.com/build/building/multi-platform/)

.github/workflows/docker-build.yml

@@ -0,0 +1,503 @@
+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, beta ]
+    tags: [ 'v*.*.*', 'v*.*.*-beta.*' ]  # Triggered by Release Please tags (stable and beta)
+  pull_request:
+    branches: [ main, beta ]
+  release:
+    types: [ published ]  # Triggered when Release Please creates a release
+  workflow_dispatch:
+    inputs:
+      push:
+        description: 'Push images to registry'
+        required: false
+        default: 'false'
+        type: choice
+        options:
+          - 'true'
+          - 'false'
+
+env:
+  REGISTRY: ghcr.io
+  # 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:
+    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
+
+    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
+
+    - name: Log in to Container Registry
+      if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
+      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 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
+      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 }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=semver,pattern={{version}}
+          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: 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'
+      uses: aquasecurity/trivy-action@master
+      with:
+        image-ref: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}:${{ steps.meta-backend.outputs.version }}
+        format: 'sarif'
+        output: 'trivy-backend.sarif'
+        severity: 'CRITICAL,HIGH'
+        timeout: '10m'
+
+    - 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@v4
+      with:
+        sarif_file: 'trivy-backend.sarif'
+        category: 'backend-vulnerabilities'
+
+  # -----------------------------------------------------------------------------
+  # Frontend: per-arch build, then merge into a multi-arch manifest
+  # -----------------------------------------------------------------------------
+  build-frontend:
+    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
+
+    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
+
+    - name: Log in to Container Registry
+      if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
+      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 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
+      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 }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=semver,pattern={{version}}
+          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: 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'
+      uses: aquasecurity/trivy-action@master
+      with:
+        image-ref: ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}:${{ steps.meta-frontend.outputs.version }}
+        format: 'sarif'
+        output: 'trivy-frontend.sarif'
+        severity: 'CRITICAL,HIGH'
+        timeout: '10m'
+
+    - 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@v4
+      with:
+        sarif_file: 'trivy-frontend.sarif'
+        category: 'frontend-vulnerabilities'
+
+  summary:
+    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 build (per-arch)**: Successfully built" >> $GITHUB_STEP_SUMMARY
+        else
+          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 build (per-arch)**: Successfully built" >> $GITHUB_STEP_SUMMARY
+        else
+          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, when push is enabled)" >> $GITHUB_STEP_SUMMARY
+        echo "- Version tags (for releases)" >> $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

@@ -11,6 +11,9 @@ yarn-error.log*
 .env.test.local
 .env.production.local
 
+# Docker override file
+docker-compose.override.yml
+
 # Security - Never commit credentials
 ADMIN_CREDENTIALS.txt
 ADMIN_PASSWORD_RESET.txt
@@ -59,4 +62,70 @@ test-archiver/
 !data/.gitkeep
 !logs/.gitkeep
 
-PRODUCTION_DEPLOYMENT_GUIDE.md
+# development files
+backend/.swarm/
+.claudedocs/
+backend/data/
+backend/docs/
+backend/logs/
+logs/
+# 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.42.2-beta.0"
+}

.release-please-manifest.json

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

BACKUP_VERSION_TRACKING.md

@@ -1,152 +0,0 @@
-# Backup Version Tracking Implementation
-
-## Overview
-Version tracking has been added to the backup system to ensure safe restoration by tracking application versions, Node.js versions, and database schema versions at the time of backup.
-
-## Implementation Details
-
-### 1. Database Schema Changes (Migration 034)
-
-Added version tracking columns to backup tables:
-
-#### `database_backup_runs` table:
-- `app_version` - Application version from package.json
-- `node_version` - Node.js runtime version
-- `db_schema_version` - Latest migration name
-- `environment_info` - JSON with additional environment details
-
-#### `backup_runs` table:
-- `app_version` - Application version
-- `node_version` - Node.js version
-- `db_schema_version` - Database schema version
-- `manifest_info` - Summary of manifest information
-
-#### New `restore_history` table:
-Tracks all restore attempts with comprehensive version information:
-- Backup versions vs current versions
-- Compatibility check results
-- Warnings and errors
-- Restore outcome
-
-### 2. Version Information Captured
-
-During each backup, the system now records:
-- **Application Version**: From `package.json` (e.g., "1.0.77")
-- **Node.js Version**: Runtime version (e.g., "v18.17.0")
-- **Database Schema**: Latest migration file (e.g., "034_add_version_to_backups.js")
-- **Environment Info**: Platform, architecture, environment mode
-
-### 3. Backup Services Updated
-
-#### Database Backup Service (`databaseBackup.js`):
-- Records version info when creating backups
-- Includes versions in statistics JSON
-- New method: `checkVersionCompatibility()` for restore safety
-- New method: `getCurrentSchemaVersion()` to track migrations
-
-#### File Backup Service (`backupService.js`):
-- Records version info in backup_runs table
-- Integrates with manifest system
-- Stores manifest summary with version details
-
-### 4. Existing Manifest System
-
-The `backupManifest.js` already provides comprehensive version tracking:
-- Application version and Node.js version
-- System information (OS, platform, architecture)
-- Database schema version
-- Detailed file and database metadata
-
-### 5. Version Compatibility Checking
-
-When restoring, the system can now:
-- Compare backup version vs current version
-- Detect major/minor version differences
-- Identify schema mismatches
-- Provide warnings and recommendations
-
-### 6. Configuration Settings
-
-New backup settings for version control:
-- `backup_require_version_match` - Enforce exact version matching
-- `backup_allow_minor_version_mismatch` - Allow same major version
-- `backup_warn_on_version_mismatch` - Show warnings on mismatch
-- `backup_check_schema_compatibility` - Validate schema versions
-
-## Usage
-
-### Creating Backups
-Backups automatically capture version information - no changes needed to existing backup workflows.
-
-### Checking Version Before Restore
-
-1. **For Database Backups**:
-```javascript
-const compatibility = await databaseBackupService.checkVersionCompatibility({
-  app_version: '1.0.75',
-  node_version: 'v16.14.0',
-  db_schema_version: '032_add_feedback.js'
-});
-
-if (!compatibility.compatible) {
-  console.error('Version mismatch:', compatibility.errors);
-}
-```
-
-2. **For File Backups**:
-Check the manifest file which contains all version information:
-```bash
-cat /backup/path/manifest-backup-20250122-123456.json | jq '.application'
-```
-
-### Restore History
-All restore attempts are logged in the `restore_history` table with:
-- Version compatibility results
-- Warnings encountered
-- Success/failure status
-- Who performed the restore
-
-## Best Practices
-
-1. **Always Check Compatibility**: Before restoring, verify version compatibility
-2. **Document Version Changes**: Keep changelog updated with breaking changes
-3. **Test Restores**: Regularly test restore procedures in staging
-4. **Monitor Warnings**: Even if compatible, review warnings before proceeding
-5. **Keep Backups Organized**: Label backups with version info in filename
-
-## Migration Instructions
-
-1. Run the new migration:
-```bash
-cd backend
-npm run migrate
-```
-
-2. Existing backups will show "unknown" for version fields
-3. New backups will automatically include version information
-4. The system remains backward compatible with old backups
-
-## Troubleshooting
-
-### Version Mismatch Errors
-- Check current app version: `cat backend/package.json | grep version`
-- Check Node version: `node --version`
-- Check latest migration: `SELECT name FROM knex_migrations ORDER BY id DESC LIMIT 1`
-
-### Restore Failures
-- Review `restore_history` table for detailed error messages
-- Check version compatibility warnings
-- Consider using same version environment for critical restores
-
-## Future Enhancements
-
-1. **Automated Version Matching**: Docker containers with specific versions
-2. **Migration Rollback**: Support for downgrading schema safely
-3. **Version Matrix**: Compatibility matrix for different version combinations
-4. **Restore Wizard**: UI for guided restore with compatibility checks
-
----
-
-**Implementation Date**: January 2025
-**Current Version**: 1.0.77
-**Status**: Production Ready

CLAUDE.md

@@ -1,365 +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
-```bash
-docker-compose -f docker-compose.prod.yml up -d  # Production deployment
-pm2 start ecosystem.config.js                     # Alternative: PM2 deployment
-```
-
-**⚠️ 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
-
-## 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

CODE_OF_CONDUCT.md

@@ -20,7 +20,7 @@ We are committed to providing a welcoming and inspiring community for all photog
 
 ## Enforcement
 
-Instances of unacceptable behavior may be reported to the project team at conduct@example.com. All complaints will be reviewed and investigated promptly and fairly.
+Instances of unacceptable behavior may be reported by [opening an issue](https://github.com/the-luap/picpeak/issues/new?labels=conduct) on GitHub. All complaints will be reviewed and investigated promptly and fairly.
 
 ## Attribution
 

CONTRIBUTING.md

@@ -153,8 +153,8 @@ picpeak/
 
 ## 📮 Contact
 
-- Create an issue for bugs or features
-- Join discussions for questions
-- Email: picpeak@example.com for security issues
+- Create an [issue](https://github.com/the-luap/picpeak/issues) for bugs or features
+- Join [discussions](https://github.com/the-luap/picpeak/discussions) for questions
+- Security issues: Open a [security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
 
 Thank you for contributing! 🎉

DEPLOYMENT.md

@@ -1,220 +0,0 @@
-# 🚀 PicPeak Deployment Guide
-
-This guide will help you deploy PicPeak in production. The entire process takes about 10-15 minutes.
-
-## 📋 Prerequisites
-
-- A server with Docker and Docker Compose installed
-- A domain name (for SSL certificates)
-- SMTP credentials for sending emails
-- Basic command line knowledge
-
-## 🏃 Quick Deploy (Recommended)
-
-### 1. Clone and Configure
-
-```bash
-# Clone the repository
-git clone https://github.com/the-luap/picpeak.git
-cd picpeak
-
-# Copy environment template
-cp .env.production.example .env
-
-# Generate a secure JWT secret
-echo "JWT_SECRET=$(openssl rand -base64 32)" >> .env
-
-# Edit configuration
-nano .env
-```
-
-### 2. Required Environment Variables
-
-Edit your `.env` file with these essential settings:
-
-```env
-# Application URLs
-FRONTEND_URL=https://your-domain.com
-BACKEND_URL=https://your-domain.com
-
-# Email Configuration (Required for notifications)
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_USER=your-email@gmail.com
-SMTP_PASS=your-app-password
-SMTP_FROM=your-email@gmail.com
-
-# Admin Configuration
-ADMIN_EMAIL=admin@your-domain.com
-ADMIN_PASSWORD=your-secure-password
-
-# Database (PostgreSQL for production)
-DATABASE_CLIENT=pg
-DB_HOST=postgres
-DB_NAME=picpeak
-DB_USER=picpeak
-DB_PASSWORD=secure-db-password
-```
-
-### 3. Deploy with Docker Compose
-
-```bash
-# Start all services
-docker-compose -f docker-compose.prod.yml up -d
-
-# Check logs
-docker-compose logs -f
-
-# Access your site at https://your-domain.com
-```
-
-## 🔧 Configuration Options
-
-### Storage Settings
-
-```env
-# Storage paths (default: ./storage)
-STORAGE_PATH=./storage
-ARCHIVE_PATH=./storage/archives
-
-# Gallery expiration (days)
-DEFAULT_EXPIRATION_DAYS=30
-WARNING_DAYS_BEFORE_EXPIRY=7
-```
-
-### Security Settings
-
-```env
-# Session timeout (minutes)
-SESSION_TIMEOUT=60
-
-# Rate limiting
-RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
-RATE_LIMIT_MAX_REQUESTS=100
-```
-
-### Analytics (Optional)
-
-```env
-# Umami Analytics
-VITE_UMAMI_URL=https://analytics.your-domain.com
-VITE_UMAMI_WEBSITE_ID=your-website-id
-```
-
-## 🔒 SSL/TLS Setup
-
-The production Docker Compose includes automatic SSL via Let's Encrypt:
-
-1. **Ensure your domain points to your server**
-2. **Update nginx configuration**:
-   ```bash
-   nano nginx/nginx.conf
-   # Replace your-domain.com with your actual domain
-   ```
-3. **Start services** - Certbot will automatically obtain certificates
-
-## 📁 Directory Structure
-
-After deployment, your directory structure will be:
-
-```
-picpeak/
-├── backend/          # API server
-├── frontend/         # React app
-├── storage/          # Photo storage
-│   ├── events/       # Active galleries
-│   │   ├── active/   # Current photos
-│   │   └── archived/ # Expired galleries
-│   ├── thumbnails/   # Generated thumbnails
-│   └── uploads/      # User uploads
-├── data/            # Database files
-└── logs/            # Application logs
-```
-
-## 🔄 Maintenance
-
-### Backup
-
-```bash
-# Backup database and photos
-./scripts/backup.sh
-
-# Backups are stored in ./backups/
-```
-
-### Update
-
-```bash
-# Pull latest changes
-git pull
-
-# Rebuild and restart
-docker-compose -f docker-compose.prod.yml up -d --build
-```
-
-### Logs
-
-```bash
-# View all logs
-docker-compose logs
-
-# View specific service
-docker-compose logs backend
-docker-compose logs frontend
-```
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-**Photos not appearing:**
-- Check storage permissions: `chmod -R 755 storage/`
-- Verify file watcher is running: `docker-compose logs backend | grep watcher`
-
-**Email not sending:**
-- Test SMTP settings: Admin Panel → Settings → Email → Send Test
-- Check email queue: Admin Panel → System → Email Queue
-
-**Can't access admin panel:**
-- Default login: Use email/password from `.env`
-- Reset password: `docker exec picpeak-backend npm run reset-admin`
-
-### Health Check
-
-```bash
-# Check service status
-docker-compose ps
-
-# Test backend API
-curl https://your-domain.com/api/health
-
-# Check disk space
-df -h storage/
-```
-
-## 🐳 Alternative Deployment Methods
-
-### Using Docker Swarm
-
-For high availability deployments, see [Docker Swarm Setup](deploy/README.md).
-
-### Manual Installation
-
-If you prefer not to use Docker:
-
-1. Install Node.js 18+
-2. Install PostgreSQL
-3. Clone repository
-4. Install dependencies: `npm install` in both `/backend` and `/frontend`
-5. Build frontend: `cd frontend && npm run build`
-6. Start services with PM2
-
-## 📞 Support
-
-- 📘 [Documentation](https://github.com/the-luap/picpeak)
-- 🐛 [Report Issues](https://github.com/the-luap/picpeak/issues)
-- 💬 [Discussions](https://github.com/the-luap/picpeak/discussions)
-
----
-
-**Need help?** Open an issue on GitHub and we'll assist you!

PRODUCTION_DEPLOYMENT_GUIDE.md

@@ -1,378 +0,0 @@
-# Production Deployment Guide
-
-This comprehensive guide addresses all production deployment scenarios and common issues.
-
-## Pre-Deployment Checklist
-
-### 1. Environment Variables
-Create a `.env` file with ALL required variables:
-
-```bash
-# CRITICAL - Must change these!
-JWT_SECRET=<generate-with-openssl-rand-base64-32>
-DB_PASSWORD=<strong-password>
-
-# Application URLs (your actual domain)
-ADMIN_URL=https://yourdomain.com
-FRONTEND_URL=https://yourdomain.com
-BACKEND_URL=https://yourdomain.com
-
-# Database (PostgreSQL)
-DATABASE_CLIENT=pg
-DB_HOST=postgres  # or external host
-DB_PORT=5432
-DB_USER=picpeak
-DB_NAME=picpeak
-
-# Email Configuration (required for notifications)
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=your-email@gmail.com
-SMTP_PASS=your-app-password  # Use app-specific password
-EMAIL_FROM=PicPeak <noreply@yourdomain.com>
-
-# Port Configuration
-PORT=3001
-
-# Performance Tuning
-DB_POOL_MIN=5
-DB_POOL_MAX=25
-NODE_ENV=production
-LOG_LEVEL=info
-
-# Optional: Umami Analytics (configured via Admin UI)
-# UMAMI_URL=https://analytics.yourdomain.com
-# UMAMI_WEBSITE_ID=your-website-id
-```
-
-### 2. Generate Secrets
-
-```bash
-# Generate JWT Secret (REQUIRED)
-openssl rand -base64 32
-
-# Generate Database Password
-openssl rand -base64 24
-```
-
-## Frontend Configuration
-
-For production deployment behind a reverse proxy:
-
-### Frontend Environment
-```bash
-# frontend/.env.production
-VITE_API_URL=/api  # Uses relative path for reverse proxy
-
-# Optional: Umami fallback (primary config via Admin UI)
-# VITE_UMAMI_URL=https://analytics.yourdomain.com
-# VITE_UMAMI_WEBSITE_ID=your-website-id
-```
-
-This ensures all API calls use the same domain/protocol as the frontend.
-
-### Nginx Proxy Configuration
-
-The frontend nginx configuration already includes proper proxy settings for:
-- `/api` → Backend API
-- `/photos` → Protected photo access
-- `/thumbnails` → Thumbnail images
-- `/uploads` → Public uploads (logos, favicons)
-
-All static assets are served through the nginx proxy, inheriting authentication headers.
-
-## Deployment Steps
-
-### 1. Initial Setup
-
-```bash
-# Clone repository
-git clone https://github.com/the-luap/wedding-photo-sharing.git
-cd wedding-photo-sharing
-
-# Create required directories
-mkdir -p storage/events/active storage/events/archived storage/thumbnails storage/uploads
-mkdir -p data logs
-mkdir -p certbot/conf certbot/www
-
-# Set permissions (important!)
-chmod -R 755 storage data logs
-```
-
-### 2. Fix Docker Volume Permissions
-
-Create `docker-compose.override.yml` for local volume configuration:
-
-```yaml
-version: '3.8'
-
-services:
-  backend:
-    volumes:
-      - ./storage:/app/storage:delegated
-      - ./data:/app/data:delegated
-      - ./logs:/app/logs:delegated
-    user: "1001:1001"  # nodejs user
-
-  db:
-    volumes:
-      - ./postgres-data:/var/lib/postgresql/data
-```
-
-### 3. Build and Deploy
-
-```bash
-# Build images
-docker-compose -f docker-compose.prod.yml build
-
-# Start services
-docker-compose -f docker-compose.prod.yml up -d
-
-# Check logs
-docker-compose -f docker-compose.prod.yml logs -f backend
-```
-
-### 4. Initial Admin Setup
-
-The admin user is automatically created during database migration:
-
-```bash
-# Run migrations (this creates admin user)
-docker-compose -f docker-compose.prod.yml exec backend npm run migrate
-
-# Admin credentials will be displayed in console and saved to ADMIN_CREDENTIALS.txt
-# Example output:
-# ========================================
-# ✅ Admin user created successfully!
-# ========================================
-# Username: admin
-# Password: SwiftEagle3847!
-# 
-# ⚠️  IMPORTANT: Change password on first login
-# ========================================
-
-# Retrieve credentials if needed
-docker-compose -f docker-compose.prod.yml exec backend cat ADMIN_CREDENTIALS.txt
-```
-
-**Important**: You MUST change the auto-generated password on first login.
-
-### 5. Configure Email (if using database config)
-
-1. Login to admin panel: https://yourdomain.com/admin
-2. Go to Settings > Email Configuration
-3. Enter SMTP details
-4. Test email sending
-
-## Common Issues and Solutions
-
-### Issue 1: Migration Failures
-
-**Error**: "relation already exists"
-
-**Solution**: The safe migration runner handles this automatically. If issues persist:
-
-```bash
-# Reset migrations tracking
-docker-compose -f docker-compose.prod.yml exec db psql -U picpeak -d picpeak
-
-# In PostgreSQL:
-DROP TABLE IF EXISTS migrations;
-\q
-
-# Re-run migrations
-docker-compose -f docker-compose.prod.yml exec backend npm run migrate:safe
-```
-
-### Issue 2: Permission Denied Errors
-
-**Error**: "EACCES: permission denied"
-
-**Solution**: Fix container permissions:
-
-```bash
-# Stop containers
-docker-compose -f docker-compose.prod.yml down
-
-# Fix permissions on host
-sudo chown -R 1001:1001 storage data logs
-
-# Restart
-docker-compose -f docker-compose.prod.yml up -d
-```
-
-### Issue 3: Database Connection Failed
-
-**Error**: "no pg_hba.conf entry"
-
-**Solution**: Already fixed in docker-compose.prod.yml with:
-- SSL disabled for internal Docker network
-- Proper authentication method (scram-sha-256)
-
-### Issue 4: Frontend Can't Connect to Backend
-
-**Error**: CORS errors or connection refused
-
-**Solution**: Ensure environment variables match:
-- Backend: `FRONTEND_URL` must match your frontend URL
-- Frontend: `VITE_API_URL` must be set during build
-
-### Issue 5: Email Not Sending
-
-**Solution**: Check email configuration:
-
-```bash
-# Check backend logs
-docker-compose -f docker-compose.prod.yml logs backend | grep email
-
-# Verify SMTP settings
-# Gmail users: Use app password, not regular password
-# Enable "Less secure app access" or use OAuth2
-```
-
-## SSL/HTTPS Setup
-
-### Option 1: Using Traefik (Recommended)
-
-Add these labels to your docker-compose override:
-
-```yaml
-services:
-  frontend:
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.picpeak.rule=Host(`yourdomain.com`)"
-      - "traefik.http.routers.picpeak.entrypoints=websecure"
-      - "traefik.http.routers.picpeak.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak.loadbalancer.server.port=80"
-```
-
-### Option 2: Using Certbot
-
-1. Update `nginx/sites-enabled/default` with your domain
-2. Run certbot:
-
-```bash
-# Initial certificate
-docker-compose -f docker-compose.prod.yml run --rm certbot certonly \
-  --webroot --webroot-path=/var/www/certbot \
-  -d yourdomain.com -d www.yourdomain.com
-
-# Auto-renewal is handled by the certbot container
-```
-
-## Monitoring
-
-### Health Checks
-
-```bash
-# Backend health
-curl http://localhost/api/health
-
-# Database connection
-docker-compose -f docker-compose.prod.yml exec backend \
-  psql -U picpeak -d picpeak -c "SELECT 1"
-```
-
-### Logs
-
-```bash
-# All services
-docker-compose -f docker-compose.prod.yml logs -f
-
-# Specific service
-docker-compose -f docker-compose.prod.yml logs -f backend
-```
-
-## Backup and Restore
-
-### Backup
-
-```bash
-#!/bin/bash
-# backup.sh
-DATE=$(date +%Y%m%d_%H%M%S)
-BACKUP_DIR="./backups/$DATE"
-
-mkdir -p $BACKUP_DIR
-
-# Database
-docker-compose -f docker-compose.prod.yml exec -T db \
-  pg_dump -U picpeak picpeak > $BACKUP_DIR/database.sql
-
-# Files
-tar -czf $BACKUP_DIR/storage.tar.gz storage/
-
-echo "Backup completed: $BACKUP_DIR"
-```
-
-### Restore
-
-```bash
-# Database
-docker-compose -f docker-compose.prod.yml exec -T db \
-  psql -U picpeak picpeak < ./backups/20240713_120000/database.sql
-
-# Files
-tar -xzf ./backups/20240713_120000/storage.tar.gz
-```
-
-## Production Best Practices
-
-1. **Always use named volumes** in production for better data persistence
-2. **Set up monitoring** with Prometheus/Grafana
-3. **Enable backups** with automated scripts
-4. **Use a reverse proxy** (Nginx) for SSL termination
-5. **Implement rate limiting** at the Nginx level
-6. **Regular updates** - Keep Docker images updated
-7. **Log rotation** - Configure log rotation for application logs
-
-## Troubleshooting Commands
-
-```bash
-# Check running containers
-docker-compose -f docker-compose.prod.yml ps
-
-# Restart a service
-docker-compose -f docker-compose.prod.yml restart backend
-
-# View real-time logs
-docker-compose -f docker-compose.prod.yml logs -f --tail=100
-
-# Execute commands in container
-docker-compose -f docker-compose.prod.yml exec backend sh
-
-# Database shell
-docker-compose -f docker-compose.prod.yml exec db psql -U picpeak
-
-# Clean restart
-docker-compose -f docker-compose.prod.yml down
-docker-compose -f docker-compose.prod.yml up -d
-```
-
-## Security Checklist
-
-- [ ] Strong JWT_SECRET (min 32 chars)
-- [ ] Strong database password
-- [ ] Admin password changed from auto-generated one
-- [ ] SSL/HTTPS enabled
-- [ ] Firewall configured (only 80/443 open)
-- [ ] Regular security updates
-- [ ] Backup encryption
-- [ ] Access logs monitored
-- [ ] Rate limiting enabled (built-in)
-- [ ] File upload restrictions configured
-- [ ] Password complexity requirements configured (Admin > Settings)
-- [ ] Session timeout configured (default 60 min)
-- [ ] Umami analytics configured (if using)
-- [ ] SMTP credentials secured with app-specific password
-
-## Support
-
-For issues not covered here:
-1. Check application logs
-2. Review error messages carefully
-3. Ensure all environment variables are set
-4. Verify file permissions
-5. Check Docker daemon logs

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:
@@ -28,11 +44,13 @@ Unlike expensive SaaS solutions, PicPeak gives you:
 
 ### For Photographers
 - 📁 **Drag & Drop Upload** - Simply drop photos into folders
+- 🔗 **External Media (Reference Mode)** - Browse and import from a read‑only external folder library without copying originals
 - ⏰ **Auto-Expiring Galleries** - Set expiration dates (default: 30 days)
 - 🔐 **Password Protection** - Secure client galleries
 - 📧 **Automated Emails** - Creation confirmations and expiration warnings
 - 📊 **Analytics Dashboard** - Track views, downloads, and engagement
 - 🎨 **Custom Themes** - Match your brand perfectly
+- 🌐 **Public Landing Page** - Publish a curated marketing page when guests visit your root URL
 
 ### For Clients
 - 🖼️ **Beautiful Galleries** - Clean, modern interface
@@ -40,10 +58,12 @@ Unlike expensive SaaS solutions, PicPeak gives you:
 - ⬇️ **Bulk Downloads** - Download all photos with one click
 - 🔍 **Smart Search** - Find photos quickly
 - 📤 **Guest Uploads** - Optional client photo uploads
+- 🛡️ **Download Protection** - Advanced image protection with watermarking and right-click prevention
 
 ### Technical Excellence
 - 🐳 **Docker Ready** - Deploy in minutes
 - 🔄 **Auto-Processing** - Automatic thumbnail generation
+- 🗂️ **Reference Library Support** - Point PicPeak at `EXTERNAL_MEDIA_ROOT` to reference existing originals, index quickly, and generate thumbnails on demand
 - 💾 **Smart Storage** - Automatic archiving of expired galleries
 - 🛡️ **Security First** - JWT auth, rate limiting, CORS protection
 - 📈 **Scalable** - From small studios to large agencies
@@ -64,19 +84,95 @@ 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)
+- When using bind mounts (e.g., `./storage`, `./data`, `./logs`, `./events`), ensure the container user can write to these host folders. The backend runs as a non‑root user by default.
+- Set `PUID` and `PGID` in your `.env` to match your host user’s UID/GID (run `id -u` and `id -g` on the host). Compose maps the container user to these values.
+- Example in `.env`:
+  - `PUID=1000`
+  - `PGID=1000`
+- 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.md) - Detailed installation instructions
+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
 - 📋 [**Code of Conduct**](CODE_OF_CONDUCT.md) - Community guidelines
 
+## 🌐 Public Landing Page
+
+Spotlight your studio with a customizable marketing page at `/`:
+
+- Head to **Admin → CMS Pages** to enable the public landing page toggle.
+- Edit the provided HTML template (rich sections, hero, testimonials) and optional CSS overrides.
+- The preview renders in a sandboxed iframe so you can iterate safely before publishing.
+- PicPeak sanitizes stored HTML and CSS server-side—scripts, iframes, and unsafe attributes are stripped automatically.
+- Use **Reset to default** anytime to restore the bundled template.
+- The backend caches the rendered landing page for 60 seconds by default; override with `PUBLIC_SITE_CACHE_TTL_MS` if you need a different TTL.
+- When the landing page is disabled PicPeak continues to serve the admin SPA/login exactly as before.
+
 ## 🎯 Use Cases
 
 Perfect for:
@@ -90,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
@@ -108,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.
@@ -138,7 +360,7 @@ PicPeak takes security seriously:
 - 📝 Activity logging
 - 🔒 Secure file access
 
-Found a security issue? Please email security@example.com
+Found a security issue? Please open a [security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
 
 ## 📸 Screenshots
 
@@ -177,20 +399,65 @@ Organize and manage your photo galleries with intuitive event management tools.
 
 We're constantly improving PicPeak and welcome contributions from our community! If you have ideas for new features or want to help implement existing ones, please open an issue or submit a pull request. Your contributions help make PicPeak better for everyone.
 
+### 🚧 Beta Features (Use at your own risk)
+
+These features are currently in beta testing and may have limited functionality or stability:
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Simple Deployment Script** | One-click deployment script for quick server setup with automated configuration and dependency installation | 🧪 Beta |
+
+### 📋 Future Enhancements
+
 | Feature | Description | Priority | Status |
 |---------|-------------|----------|---------|
 | **Backup & Restore** | Comprehensive backup system with S3/MinIO support, automated scheduling, and safe restore functionality | High | ✅ Implemented |
-| **Gallery Templates** | Additional gallery layouts and themes (masonry, slideshow, story-style) for different event types | Medium | 🔄 Open |
+| **External Media Library (Reference Mode)** | Use an external folder library as a read‑only source with import and on‑demand thumbnail generation | High | ✅ Implemented |
+| **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 | 🔄 Open |
-| **Video Support** | Upload and display videos alongside photos in galleries with streaming support | 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 | ✅ 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.
 
+### 👥 Contributors
+
+A huge thank you to the people whose code, reports, and feedback have shaped PicPeak:
+
+- [**@Luca-Timo**](https://github.com/Luca-Timo) — native Apple Silicon multi-arch images, external-URL toggle for legal CMS pages, the lazy-loaded folder tree picker, the admin-email picker on event creation, the data-driven self-hosted webfont system, the gallery header/banner decoupling, and several typed-API refactors. Consistently raises the bar with thoughtful PRs.
+- [**@Rekoo-PS**](https://github.com/Rekoo-PS) — sharp-eyed bug reporter and product feedback. Filed the issues that drove the login-loop fix, the gallery-loading skeleton work, the redirection cleanup, the mobile-lightbox overhaul, the admin-events search-counter fix, the photo-count column, and the bulk-delete workflow. Also a [BuyMeACoffee](https://buymeacoffee.com/theluap) supporter — the kind of feedback loop that keeps the project useful for real deployments.
+
+If you've contributed and aren't listed here, please open a PR — this list is meant to grow.
+
+### 🤖 AI-Assisted Development
+
+This project was generated with the assistance of AI technology, but has been:
+- ✅ **Fully tested end-to-end** by human developers
+- 🔒 **Security audited** with comprehensive security checks
+- 👨‍💻 **Human-reviewed** for code quality and best practices
+- 🧪 **Production-tested** in real-world scenarios
+
+We believe in transparent development practices and the responsible use of AI as a tool to accelerate development while maintaining high standards of quality and security.
+
 ## 📄 License
 
 PicPeak is released under the [MIT License](LICENSE). Use it freely for personal or commercial projects.
@@ -198,7 +465,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.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!
 
@@ -207,7 +474,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.md">Documentation</a> •
+  <a href="https://docs.picpeak.app">Documentation</a> •
   <a href="https://github.com/the-luap/picpeak/issues">Support</a>
-</p>
+</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,11 +15,14 @@ We take the security of PicPeak seriously. If you have discovered a security vul
 
 ### 1. **Do NOT create a public GitHub issue**
 
-### 2. Email us at security@example.com with:
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact
-- Suggested fix (if any)
+### 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
+  - Potential impact
+  - Suggested fix (if any)
 
 ### 3. You can expect:
 - Acknowledgment within 48 hours
@@ -79,7 +82,7 @@ We believe in responsible disclosure. Once a vulnerability is fixed:
 
 ## Contact
 
-- Security issues: security@example.com
-- General support: https://github.com/the-luap/picpeak/issues
+- 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

@@ -0,0 +1,553 @@
+# 🚀 PicPeak Simple Setup Guide
+
+This guide provides easy installation instructions for PicPeak on Linux servers with both Docker and non-Docker options.
+
+## 📋 Quick Start
+
+### One-Line Installation
+
+```bash
+# Download and run the unified setup script
+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.
+
+## 🎯 Installation Methods
+
+### Method 1: Docker Installation (Recommended)
+Best for: Most users, easy updates, isolated environment
+
+```bash
+sudo ./picpeak-setup.sh --docker
+```
+
+**Pros:**
+- ✅ Easier installation and updates
+- ✅ Better isolation from system
+- ✅ Consistent environment across platforms
+- ✅ Built-in PostgreSQL and Redis
+
+**Cons:**
+- ❌ Requires more resources (~4GB RAM recommended)
+- ❌ Additional Docker overhead
+
+### Method 2: Native Installation
+Best for: Resource-constrained systems, Raspberry Pi, direct control
+
+```bash
+sudo ./picpeak-setup.sh --native
+```
+
+**Pros:**
+- ✅ Lower resource usage (~1GB RAM minimum)
+- ✅ Direct system control
+- ✅ No Docker overhead
+- ✅ Better for ARM devices
+
+**Cons:**
+- ❌ More complex setup
+- ❌ System dependencies required
+- ❌ Manual update process
+
+## 📋 System Requirements
+
+### Minimum Requirements
+- **OS**: Ubuntu 20.04+, Debian 11+, Fedora 38+, RHEL/CentOS 8+, Raspberry Pi OS
+- **RAM**: 
+  - Docker: 2GB minimum (4GB recommended)
+  - Native: 1GB minimum (2GB recommended)
+- **Storage**: 2GB for application + space for photos
+- **Network**: Port 3001 (or 80/443 with proxy)
+
+### Supported Platforms
+- ✅ Ubuntu 20.04, 22.04, 24.04
+- ✅ Debian 11, 12
+- ✅ Raspberry Pi OS (32-bit and 64-bit)
+- ✅ Fedora 38, 39, 40
+- ✅ RHEL/CentOS/Rocky/AlmaLinux 8, 9
+
+## 🛠️ Installation Options
+
+### Interactive Mode (Default)
+```bash
+sudo ./picpeak-setup.sh
+```
+
+The script will prompt you to choose:
+1. Installation method (Docker or Native)
+2. Admin email and password
+3. Domain configuration (optional)
+4. Email server settings (optional)
+5. SSL/HTTPS setup (optional)
+
+### Unattended Installation
+
+#### Docker with full configuration:
+```bash
+sudo ./picpeak-setup.sh --docker --unattended \
+  --domain photos.example.com \
+  --email admin@example.com \
+  --admin-password SecurePass123 \
+  --smtp-host smtp.gmail.com \
+  --smtp-port 587 \
+  --smtp-user your-email@gmail.com \
+  --smtp-pass your-app-password \
+  --enable-ssl
+```
+
+#### Native with minimal configuration:
+```bash
+sudo ./picpeak-setup.sh --native --unattended \
+  --email admin@example.com \
+  --admin-password SecurePass123
+```
+
+### Command Line Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--docker` | Use Docker installation | `--docker` |
+| `--native` | Use native installation | `--native` |
+| `--unattended` | Run without prompts | `--unattended` |
+| `--domain` | Domain for HTTPS setup | `--domain photos.example.com` |
+| `--email` | Admin email address | `--email admin@example.com` |
+| `--admin-password` | Set admin password | `--admin-password MySecurePass` |
+| `--smtp-host` | SMTP server hostname | `--smtp-host smtp.gmail.com` |
+| `--smtp-port` | SMTP server port | `--smtp-port 587` |
+| `--smtp-user` | SMTP username | `--smtp-user user@gmail.com` |
+| `--smtp-pass` | SMTP password | `--smtp-pass app-password` |
+| `--enable-ssl` | Enable HTTPS with Let's Encrypt | `--enable-ssl` |
+| `--port` | Custom port (native only) | `--port 8080` |
+| `--update` | Update existing installation | `--update` |
+| `--uninstall` | Remove installation | `--uninstall` |
+| `--help` | Show help message | `--help` |
+
+## 🏗️ What Gets Installed
+
+### Docker Installation
+```
+~/picpeak/                    # Or custom directory
+├── docker-compose.yml        # Service definitions
+├── .env                      # Configuration
+├── storage/
+│   └── events/              # Photo storage
+│       ├── active/          # Current galleries
+│       └── archived/        # Expired galleries
+├── logs/                    # Application logs
+└── backup/                  # Backup directory
+```
+
+**Services:**
+- PicPeak Backend (Node.js application)
+- PostgreSQL Database
+- Redis Cache
+- Nginx Reverse Proxy (optional)
+- Background Workers
+
+### Native Installation
+```
+/opt/picpeak/                # Installation directory
+├── backend/                 # Application code
+├── events/                  # Photo storage
+│   ├── active/             # Current galleries
+│   └── archived/           # Expired galleries
+├── logs/                   # Application logs
+└── config/                 # Configuration files
+```
+
+**Services (systemd):**
+- `picpeak-backend` - Main application
+- `picpeak-workers` - Background workers
+- `caddy` - Web server (optional)
+
+## 🌐 Access Methods
+
+### Direct Access (Simplest)
+- Docker: `http://your-server:3000` (frontend and admin at `/admin`)
+- Backend/API: `http://your-server:3001` (API only; no UI routes)
+  
+For native installs, serve the built frontend (e.g., with nginx or Caddy) and access the admin at `/admin` on the frontend domain.
+
+### With Domain & HTTPS
+If configured during setup:
+- `https://your-domain.com` - Gallery frontend
+- `https://your-domain.com/admin` - Admin panel
+
+### Behind Existing Proxy
+Add to your Nginx/Apache configuration (split frontend vs backend):
+```nginx
+# Frontend (UI + /admin/*)
+location / {
+    proxy_pass http://localhost:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection 'upgrade';
+    proxy_set_header Host $host;
+    proxy_cache_bypass $http_upgrade;
+    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_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection 'upgrade';
+    proxy_set_header Host $host;
+    proxy_cache_bypass $http_upgrade;
+    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;
+    client_max_body_size 100M;
+}
+location ~ ^/(photos|thumbnails|uploads) {
+    proxy_pass http://localhost:3001;
+    proxy_http_version 1.1;
+    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;
+}
+```
+
+## 📁 Managing Galleries
+
+### Creating a Gallery
+
+#### Via Admin Panel
+1. Login to admin panel at `/admin`
+2. Click "Create New Event"
+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.
+
+```bash
+# Docker installation — copy photos into an existing event's folder
+cp /path/to/photos/*.jpg ~/picpeak/storage/events/active/<event-slug>/
+
+# Native installation
+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
+```
+<event-slug>/
+├── collages/        # Group photos (optional subfolder)
+├── individual/      # Individual photos (optional subfolder)
+└── photo.jpg        # Photos at root level also work
+```
+
+## 🔧 Service Management
+
+### Docker Installation
+
+```bash
+cd ~/picpeak
+
+# Check status
+docker compose ps
+
+# View logs
+docker compose logs -f
+
+# Stop services
+docker compose down
+
+# Start services
+docker compose up -d
+
+# Restart services
+docker compose restart
+
+# Update PicPeak
+docker compose pull
+docker compose up -d
+```
+
+### Native Installation
+
+```bash
+# Check status
+sudo systemctl status picpeak-backend
+sudo systemctl status picpeak-workers
+
+# View logs
+sudo journalctl -u picpeak-backend -f
+sudo journalctl -u picpeak-workers -f
+
+# Start services
+sudo systemctl start picpeak-backend picpeak-workers
+
+# Stop services
+sudo systemctl stop picpeak-backend picpeak-workers
+
+# Restart services
+sudo systemctl restart picpeak-backend picpeak-workers
+
+# Update PicPeak
+# (reruns migrations to pick up schema fixes for native installs)
+sudo ./picpeak-setup.sh --update
+```
+
+## ⚙️ Configuration
+
+### Docker Configuration
+Edit `~/picpeak/.env`:
+```bash
+nano ~/picpeak/.env
+docker compose restart
+```
+
+### Native Configuration
+Edit `/opt/picpeak/app/backend/.env`:
+```bash
+sudo nano /opt/picpeak/app/backend/.env
+sudo systemctl restart picpeak-backend
+```
+
+### Key Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `JWT_SECRET` | Token signing secret | Auto-generated |
+| `ADMIN_EMAIL` | Admin email | admin@example.com |
+| `ADMIN_PASSWORD` | Admin password | Auto-generated |
+| `PHOTOS_DIR` | Photo storage path | Varies by method |
+| `SMTP_ENABLED` | Email notifications | false |
+| `DEFAULT_EXPIRY_DAYS` | Gallery expiration | 30 |
+
+## 📧 Email Configuration
+
+### Gmail Setup
+1. Enable 2-Factor Authentication
+2. Generate App Password
+3. Configure:
+```env
+SMTP_ENABLED=true
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=your-email@gmail.com
+SMTP_PASS=your-app-password
+SMTP_FROM=noreply@yourdomain.com
+```
+
+### SendGrid Setup
+1. Sign up at sendgrid.com (100 emails/day free)
+2. Create API key
+3. Configure:
+```env
+SMTP_ENABLED=true
+SMTP_HOST=smtp.sendgrid.net
+SMTP_PORT=587
+SMTP_USER=apikey
+SMTP_PASS=your-sendgrid-api-key
+SMTP_FROM=verified-sender@yourdomain.com
+```
+
+## 🔄 Maintenance
+
+### Backups
+
+#### Docker:
+```bash
+# Backup script included
+cd ~/picpeak
+./backup.sh
+
+# Manual backup
+docker exec picpeak-postgres pg_dump -U picpeak picpeak > backup.sql
+tar -czf photos-backup.tar.gz storage/events/
+```
+
+#### Native:
+```bash
+# Database backup
+sudo cp /opt/picpeak/app/backend/data/photo_sharing.db /backup/database-$(date +%Y%m%d).sqlite
+
+# Photos backup
+sudo tar -czf /backup/photos-$(date +%Y%m%d).tar.gz /opt/picpeak/events/
+```
+
+### Updates
+
+```bash
+# Docker
+cd ~/picpeak
+docker compose pull
+docker compose up -d
+
+# Native
+sudo ./picpeak-setup.sh --update
+```
+
+### Uninstall
+
+```bash
+# Will prompt for confirmation and data removal options
+sudo ./picpeak-setup.sh --uninstall
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### Service Won't Start
+```bash
+# Docker
+docker compose logs backend
+docker compose down && docker compose up -d
+
+# Native
+sudo journalctl -u picpeak-backend -n 50
+sudo systemctl restart picpeak-backend
+```
+
+#### Can't Access Admin Panel
+1. Check firewall:
+```bash
+# Ubuntu/Debian
+sudo ufw allow 3001
+
+# RHEL/CentOS
+sudo firewall-cmd --add-port=3001/tcp --permanent
+sudo firewall-cmd --reload
+```
+
+2. Verify service:
+```bash
+# Docker
+curl http://localhost:3001/api/health
+
+# Native
+sudo systemctl is-active picpeak-backend
+```
+
+#### Photos Not Showing
+```bash
+# Check permissions (Native)
+sudo chown -R picpeak:picpeak /opt/picpeak/events/
+sudo chmod -R 755 /opt/picpeak/events/
+
+# Check permissions (Docker)
+ls -la ~/picpeak/storage/events/
+```
+
+#### Reset Admin Password
+
+```bash
+# Docker
+docker exec picpeak-backend node scripts/reset-admin-password.js
+
+# Native
+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:**
+   - Docker: `docker compose logs -f`
+   - Native: `sudo journalctl -u picpeak-backend -f`
+   - Installation: `/tmp/picpeak-setup-*.log`
+
+2. **Documentation:**
+   - [Full Documentation](https://docs.picpeak.app)
+   - [Deployment Guide](https://docs.picpeak.app/deployment)
+
+3. **Support:**
+   - [GitHub Issues](https://github.com/the-luap/picpeak/issues)
+   - Include: Error messages, system info (`uname -a`), installation method
+
+## 🔒 Security Best Practices
+
+### Essential Security
+1. **Change default admin password immediately**
+2. **Use HTTPS for production** (Let's Encrypt included)
+3. **Configure firewall** (only open necessary ports)
+4. **Regular updates** (system and PicPeak)
+5. **Automated backups** (configure in admin panel)
+
+### Advanced Security
+- Use VPN for admin panel access
+- Configure fail2ban for brute force protection
+- Enable audit logging
+- Regular security scans
+- Implement IP whitelisting
+
+## 📊 Performance Optimization
+
+### Docker Optimization
+```yaml
+# Adjust in docker-compose.yml
+services:
+  backend:
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 2G
+```
+
+### Native Optimization
+```bash
+# Increase Node.js memory
+echo "NODE_OPTIONS=--max-old-space-size=2048" >> /opt/picpeak/app/backend/.env
+sudo systemctl restart picpeak-backend
+```
+
+## 🎯 Quick Setup Examples
+
+### Home/Office Network
+```bash
+# Simple local setup without domain
+sudo ./picpeak-setup.sh --native --email admin@local.com
+```
+
+### Public Website with HTTPS
+```bash
+# Full production setup
+sudo ./picpeak-setup.sh --docker \
+  --domain photos.company.com \
+  --email admin@company.com \
+  --enable-ssl
+```
+
+### Raspberry Pi Setup
+```bash
+# Optimized for ARM devices
+sudo ./picpeak-setup.sh --native \
+  --port 8080 \
+  --email pi@local.com
+```
+
+## ✅ Post-Installation Checklist
+
+- [ ] Admin password changed
+- [ ] Email configuration tested
+- [ ] First test gallery created
+- [ ] Backup schedule configured
+- [ ] Firewall rules applied
+- [ ] SSL certificate working (if applicable)
+- [ ] Monitoring setup
+- [ ] Documentation bookmarked
+
+---
+
+**PicPeak Setup v1.0** | [Documentation](https://github.com/the-luap/picpeak) | [Support](https://github.com/the-luap/picpeak/issues)

backend/.env.example

@@ -9,9 +9,43 @@ 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
@@ -38,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,26 +1,46 @@
-FROM node:18-alpine AS builder
+FROM node:22-alpine AS builder
 
-# Add build argument for cache busting
+# Add build arguments
 ARG CACHEBUST=1
+ARG BUILD_DATE
+ARG VCS_REF
+ARG VERSION
+
+# Add labels for GitHub Container Registry
+LABEL org.opencontainers.image.source="https://github.com/the-luap/picpeak"
+LABEL org.opencontainers.image.description="PicPeak Backend Service"
+LABEL org.opencontainers.image.licenses="MIT"
 
 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:18-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
@@ -29,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__/adminSettings.logo.test.js

@@ -0,0 +1,184 @@
+const fs = require('fs');
+const fsPromises = fs.promises;
+const os = require('os');
+const path = require('path');
+const express = require('express');
+const request = require('supertest');
+
+describe('Admin settings logo upload flow', () => {
+  let tmpDir;
+  let router;
+  let app;
+  let settingsStore;
+
+  const resetModules = () => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  };
+
+  beforeEach(async () => {
+    resetModules();
+
+    tmpDir = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'picpeak-logo-'));
+    process.env.STORAGE_PATH = tmpDir;
+
+    settingsStore = new Map();
+
+    const buildQuery = (table) => {
+      const filters = [];
+      const applyFilters = (rows) => {
+        if (filters.length === 0) {
+          return rows;
+        }
+        return rows.filter((row) =>
+          filters.every(({ column, value }) => row[column] === value)
+        );
+      };
+
+      const makeRow = (row) => ({ ...row });
+
+      return {
+        where(column, value) {
+          filters.push({ column, value });
+          return this;
+        },
+        first() {
+          if (table === 'app_settings') {
+            const rows = applyFilters(Array.from(settingsStore.values()).map(makeRow));
+            return Promise.resolve(rows[0]);
+          }
+          return Promise.resolve(undefined);
+        },
+        select() {
+          return Promise.resolve([]);
+        },
+        sum() {
+          return Promise.resolve({ total: 0 });
+        },
+        join() {
+          return this;
+        },
+        groupBy() {
+          return this;
+        },
+        orderBy() {
+          return this;
+        },
+        limit() {
+          return this;
+        },
+        insert(payload) {
+          const rows = Array.isArray(payload) ? payload : [payload];
+          const upsert = (row, overrides = {}) => {
+            if (table === 'app_settings') {
+              const key = row.setting_key;
+              const existing = settingsStore.get(key) || {};
+              settingsStore.set(key, { ...existing, ...row, ...overrides });
+            }
+            return Promise.resolve();
+          };
+
+          return {
+            onConflict() {
+              return {
+                merge(overrides) {
+                  return Promise.all(rows.map((row) => upsert(row, overrides))).then(() => undefined);
+                }
+              };
+            }
+          };
+        }
+      };
+    };
+
+    const dbMock = jest.fn((table) => buildQuery(table));
+    dbMock.raw = jest.fn();
+    dbMock.transaction = async (handler) => handler({
+      commit: async () => {},
+      rollback: async () => {}
+    });
+
+    jest.doMock('../src/database/db', () => ({
+      db: dbMock,
+      logActivity: jest.fn()
+    }));
+
+    jest.doMock('../src/middleware/auth', () => ({
+      adminAuth: (req, res, next) => {
+        req.admin = { id: 1, username: 'tester' };
+        next();
+      }
+    }));
+
+    jest.doMock('../src/services/publicSiteService', () => ({
+      clearPublicSiteCache: jest.fn(),
+      getDefaultPublicSitePayload: jest.fn(),
+      getRawPublicSiteSettings: jest.fn().mockResolvedValue({})
+    }));
+
+    jest.doMock('../src/services/rateLimitService', () => ({
+      clearSettingsCache: jest.fn()
+    }));
+
+    jest.doMock('../src/middleware/maintenance', () => ({
+      maintenanceMiddleware: (req, res, next) => next(),
+      clearMaintenanceCache: jest.fn()
+    }));
+
+    router = require('../src/routes/adminSettings');
+
+    app = express();
+    app.use(express.json());
+    app.use('/api/admin/settings', router);
+  });
+
+  afterEach(async () => {
+    resetModules();
+    if (tmpDir) {
+      await fsPromises.rm(tmpDir, { recursive: true, force: true });
+      tmpDir = null;
+    }
+    delete process.env.STORAGE_PATH;
+  });
+
+  it('stores logo uploads under STORAGE_PATH and deletes on branding reset', async () => {
+    const fileBuffer = Buffer.from('fake image data');
+
+    const uploadResponse = await request(app)
+      .post('/api/admin/settings/logo')
+      .attach('logo', fileBuffer, 'logo.png');
+
+    expect(uploadResponse.status).toBe(200);
+    expect(uploadResponse.body).toHaveProperty('logoUrl');
+    const logoUrl = uploadResponse.body.logoUrl;
+    expect(logoUrl.startsWith('/uploads/logos/')).toBe(true);
+
+    const storedPath = path.join(tmpDir, logoUrl.replace('/uploads/', 'uploads/'));
+    await expect(fsPromises.access(storedPath)).resolves.toBeUndefined();
+
+    await request(app)
+      .put('/api/admin/settings/branding')
+      .send({
+        company_name: 'Test Co',
+        company_tagline: 'Tagline',
+        support_email: 'test@example.com',
+        footer_text: 'Footer',
+        watermark_enabled: false,
+        watermark_position: 'bottom-right',
+        watermark_opacity: 0.5,
+        watermark_size: 'medium',
+        favicon_url: null,
+        logo_url: '',
+        watermark_logo_url: null,
+        logo_size: 'medium',
+        logo_max_height: 120,
+        logo_position: 'left',
+        logo_display_header: true,
+        logo_display_hero: false,
+        logo_display_mode: 'default'
+      })
+      .expect(200);
+
+    await expect(fsPromises.access(storedPath)).rejects.toThrow();
+  });
+});

backend/__tests__/integration/adminPhotos.reference.test.js

@@ -0,0 +1,207 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const express = require('express');
+const request = require('supertest');
+
+describe('Admin photos in reference mode', () => {
+  let tmpDir;
+  let storagePath;
+  let db;
+  let app;
+  let categoryId;
+
+  const resetModules = () => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  };
+
+  beforeAll(async () => {
+    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-admin-photos-'));
+    storagePath = path.join(tmpDir, 'storage');
+    await fs.promises.mkdir(storagePath, { recursive: true });
+
+    process.env.NODE_ENV = 'test';
+    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'photo_sharing_test.db');
+    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
+    try {
+      await fs.promises.unlink(process.env.TEST_DATABASE_PATH);
+    } catch (_) {
+      /* ignore */
+    }
+    process.env.STORAGE_PATH = storagePath;
+
+    resetModules();
+
+    jest.doMock('../../src/middleware/auth', () => ({
+      adminAuth: (req, _res, next) => {
+        req.admin = { id: 1, username: 'tester' };
+        next();
+      }
+    }));
+
+    jest.doMock('../../src/services/imageProcessor', () => ({
+      generateThumbnail: jest.fn().mockResolvedValue('thumbnails/mock-thumb.jpg'),
+      ensureThumbnail: jest.fn()
+    }));
+
+    jest.doMock('../../src/middleware/uploadValidation', () => ({
+      validateUploadedFiles: (_req, _res, next) => next()
+    }));
+
+    jest.doMock('../../src/utils/fileSecurityUtils', () => {
+      const actual = jest.requireActual('../../src/utils/fileSecurityUtils');
+      return {
+        ...actual,
+        validateFileType: () => true,
+        createFileUploadValidator: () => (_req, _res, next) => next()
+      };
+    });
+
+    jest.doMock('../../src/utils/logger', () => ({
+      debug: jest.fn(),
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn()
+    }));
+
+    const dbModule = require('../../src/database/db');
+    db = dbModule.db;
+
+    await db.schema.dropTableIfExists('photo_feedback');
+    await db.schema.dropTableIfExists('photos');
+    await db.schema.dropTableIfExists('photo_categories');
+    await db.schema.dropTableIfExists('events');
+
+    await db.schema.createTable('events', (table) => {
+      table.increments('id').primary();
+      table.string('slug').notNullable();
+      table.string('event_name').notNullable();
+      table.string('source_mode').notNullable();
+      table.string('external_path');
+    });
+
+    await db.schema.createTable('photo_categories', (table) => {
+      table.increments('id').primary();
+      table.string('name').notNullable();
+      table.string('slug').notNullable();
+      table.boolean('is_global').defaultTo(true);
+      table.integer('event_id');
+    });
+
+    await db.schema.createTable('photos', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').notNullable();
+      table.string('filename').notNullable();
+      table.string('path').notNullable();
+      table.string('thumbnail_path');
+      table.string('type').notNullable();
+      table.integer('size_bytes');
+      table.integer('category_id');
+      table.string('source_origin');
+      table.string('external_relpath');
+      table.datetime('uploaded_at').defaultTo(db.fn.now());
+      table.float('average_rating').defaultTo(0);
+      table.integer('like_count').defaultTo(0);
+      table.integer('favorite_count').defaultTo(0);
+    });
+
+    await db.schema.createTable('photo_feedback', (table) => {
+      table.increments('id');
+      table.integer('photo_id');
+      table.string('feedback_type');
+      table.boolean('is_approved');
+      table.boolean('is_hidden');
+    });
+
+    await db('events').insert({
+      id: 1,
+      slug: 'test-event',
+      event_name: 'Test Event',
+      source_mode: 'reference',
+      external_path: 'external/library'
+    });
+
+    const insertedCategory = await db('photo_categories').insert({
+      name: 'Highlights',
+      slug: 'highlights',
+      is_global: true
+    });
+    categoryId = Array.isArray(insertedCategory) ? insertedCategory[0] : insertedCategory;
+
+    const router = require('../../src/routes/adminPhotos');
+    app = express();
+    app.use(express.json());
+    app.use('/api/admin/events', router);
+  });
+
+  afterAll(async () => {
+    if (db) {
+      await db.destroy();
+    }
+    resetModules();
+    delete process.env.TEST_DATABASE_PATH;
+    delete process.env.STORAGE_PATH;
+    if (tmpDir) {
+      await fs.promises.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('stores managed uploads with category information and managed origin', async () => {
+    const uploadResponse = await request(app)
+      .post(`/api/admin/events/1/upload`)
+      .field('category_id', String(categoryId))
+      .attach('photos', Buffer.from('fake image data'), 'photo.jpg');
+
+    expect(uploadResponse.status).toBe(200);
+    expect(uploadResponse.body).toHaveProperty('photos');
+    expect(Array.isArray(uploadResponse.body.photos)).toBe(true);
+
+    const photo = await db('photos').first();
+    expect(photo).toBeTruthy();
+    expect(photo.category_id).toBe(categoryId);
+    expect(photo.source_origin).toBe('managed');
+    expect(photo.external_relpath).toBeNull();
+  });
+
+  it('returns numeric category metadata when listing photos', async () => {
+    await db('photos').insert({
+      event_id: 1,
+      filename: 'external.jpg',
+      path: 'test-event/external.jpg',
+      thumbnail_path: null,
+      type: 'individual',
+      size_bytes: 123,
+      source_origin: 'external',
+      external_relpath: 'individual/external.jpg'
+    });
+
+    const response = await request(app)
+      .get(`/api/admin/events/1/photos`)
+      .expect(200);
+
+    expect(Array.isArray(response.body.photos)).toBe(true);
+    const managedPhoto = response.body.photos.find((p) => p.category_id === categoryId);
+    expect(managedPhoto).toBeTruthy();
+    expect(managedPhoto.category_name).toBe('Highlights');
+
+    const filtered = await request(app)
+      .get(`/api/admin/events/1/photos`)
+      .query({ category_id: String(categoryId) })
+      .expect(200);
+
+    expect(filtered.body.photos.every((p) => p.category_id === categoryId)).toBe(true);
+  });
+
+  it('normalizes category updates', async () => {
+    const photo = await db('photos').first();
+
+    await request(app)
+      .patch(`/api/admin/events/1/photos/${photo.id}`)
+      .send({ category_id: '0' })
+      .expect(200);
+
+    const updated = await db('photos').where({ id: photo.id }).first();
+    expect(updated.category_id).toBeNull();
+  });
+});

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

@@ -1,4 +1,4 @@
-const { describe, it, expect, jest, beforeAll, afterAll, beforeEach, afterEach } = require('@jest/globals');
+const { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } = require('@jest/globals');
 const { S3Client, CreateBucketCommand, DeleteBucketCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
 const path = require('path');
 const fs = require('fs').promises;
@@ -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();
     }
   }
@@ -503,4 +521,4 @@ describe('S3 Backup Integration Tests', () => {
       console.error('Failed to cleanup S3 objects:', error);
     }
   }
-});
+});

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__/middleware/sessionTimeout.isSessionExpired.test.js

@@ -0,0 +1,112 @@
+/**
+ * Unit test for the non-mutating isSessionExpired() helper added to
+ * middleware/sessionTimeout.js. Used by GET /auth/session to mirror the
+ * timeout enforcement that sessionTimeoutMiddleware applies to /api/admin
+ * endpoints — closing the asymmetry that surfaced as the redirect-loop
+ * recurrence on v3.39.1-beta.0 (issue #350).
+ *
+ * The helper has two branches:
+ *   1. In-memory `lastActivity` exists for this token  → expired iff
+ *      now - lastActivity > timeout.
+ *   2. No in-memory entry (post-restart, or first request)  → expired
+ *      iff token's iat is older than the timeout (post-restart guard
+ *      that the existing middleware already implements at line ~101).
+ *
+ * Both branches must NOT mutate the in-memory `sessions` Map — the
+ * middleware is the only place that tracks activity. We assert that.
+ */
+
+jest.mock('../../src/database/db', () => ({
+  db: () => ({
+    where: () => ({
+      first: () => ({
+        timeout: () => Promise.resolve(null),
+      }),
+    }),
+  }),
+}));
+
+// Speed up the cached-timeout reads. The module reads
+// `security_session_timeout_minutes` from app_settings and falls back to
+// DEFAULT_SESSION_TIMEOUT (60 min) when the row is null.
+const SIXTY_MINUTES_MS = 60 * 60 * 1000;
+
+const sessionTimeout = require('../../src/middleware/sessionTimeout');
+const { isSessionExpired } = sessionTimeout;
+
+function makeDecodedToken({ id = 1, iatSecondsAgo = 0 } = {}) {
+  return { id, iat: Math.floor((Date.now() - iatSecondsAgo * 1000) / 1000) };
+}
+
+describe('isSessionExpired (sessionTimeout helper)', () => {
+  it('returns false for a freshly-issued token with no in-memory record', async () => {
+    const decoded = makeDecodedToken({ id: 1, iatSecondsAgo: 60 });
+    expect(await isSessionExpired('fresh-token-1', decoded)).toBe(false);
+  });
+
+  it('returns true when iat is older than the timeout (post-restart guard)', async () => {
+    const decoded = makeDecodedToken({
+      id: 2,
+      // 90 minutes > 60 minute default timeout
+      iatSecondsAgo: 90 * 60,
+    });
+    expect(await isSessionExpired('stale-token-2', decoded)).toBe(true);
+  });
+
+  it('returns false / true based on lastActivity when one exists', async () => {
+    // Drive the in-memory map by running the actual middleware once to
+    // record activity for the token, then check the helper.
+    const decoded = makeDecodedToken({ id: 3 });
+
+    // Drive the actual middleware once with a real signed token so it
+    // records this token in the in-memory `sessions` Map. Then check the
+    // helper sees that recent activity and reports "not expired".
+    const res = { status: jest.fn(() => res), json: jest.fn() };
+    const jwt = require('jsonwebtoken');
+    process.env.JWT_SECRET = 'session-timeout-helper-test-secret';
+    const realToken = jwt.sign(decoded, process.env.JWT_SECRET, {
+      issuer: 'picpeak-auth',
+    });
+    const realReq = {
+      headers: { authorization: `Bearer ${realToken}` },
+      cookies: {},
+    };
+    await sessionTimeout.sessionTimeoutMiddleware(realReq, res, () => {});
+
+    const decodedReal = jwt.decode(realToken);
+    // Just-recorded → not expired
+    expect(await isSessionExpired(realToken, decodedReal)).toBe(false);
+  });
+
+  it('returns false when token / decoded is missing (defensive)', async () => {
+    expect(await isSessionExpired(null, { id: 1 })).toBe(false);
+    expect(await isSessionExpired('tok', null)).toBe(false);
+    expect(await isSessionExpired('tok', {})).toBe(false);
+  });
+
+  // Sanity: the helper must not poke the `sessions` Map. Indirectly check
+  // by counting active sessions before/after a call with a never-seen
+  // token — should not change.
+  it('does not mutate the in-memory sessions map', async () => {
+    const before = sessionTimeout.getActiveSessions();
+    await isSessionExpired('never-seen-token-99', makeDecodedToken({ id: 99 }));
+    const after = sessionTimeout.getActiveSessions();
+    expect(after).toBe(before);
+  });
+
+  it('uses the default 60-minute timeout when no DB setting exists', async () => {
+    // 59 minutes → not expired
+    const fresh = makeDecodedToken({ id: 4, iatSecondsAgo: 59 * 60 });
+    expect(await isSessionExpired('fresh-4', fresh)).toBe(false);
+
+    // 61 minutes → expired (just past the default)
+    const stale = makeDecodedToken({ id: 5, iatSecondsAgo: 61 * 60 });
+    expect(await isSessionExpired('stale-5', stale)).toBe(true);
+  });
+
+  // Document the constant the test relies on so a future timeout change
+  // makes this assertion explicit rather than mysterious.
+  it('default timeout is 60 minutes (constant under test)', () => {
+    expect(SIXTY_MINUTES_MS).toBe(60 * 60 * 1000);
+  });
+});

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

@@ -0,0 +1,395 @@
+/**
+ * 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) }));
+// Mock sessionTimeout's isSessionExpired so each test controls the return.
+// Default: not expired (so existing tests keep passing without setup).
+jest.mock('../../src/middleware/sessionTimeout', () => ({
+  endSession: jest.fn(),
+  isSessionExpired: jest.fn(() => Promise.resolve(false)),
+}));
+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);
+  });
+
+  // Session-timeout symmetry — issue #350 recurrence on v3.39.1-beta.0.
+  // sessionTimeoutMiddleware (mounted on /api/admin) rejects idle/old-iat
+  // tokens with 401 SESSION_TIMEOUT, but /auth/session previously didn't.
+  // The new isSessionExpired helper closes that asymmetry.
+  describe('session-timeout symmetry', () => {
+    const { isSessionExpired } = require('../../src/middleware/sessionTimeout');
+
+    beforeEach(() => {
+      isSessionExpired.mockReset();
+      // Default to "active session" so the other admin checks above also
+      // pass when this branch runs.
+      isSessionExpired.mockResolvedValue(false);
+    });
+
+    it('returns valid:false when isSessionExpired reports the token has timed out', async () => {
+      fakeDb.adminUsers.push({
+        id: 1,
+        username: 'admin',
+        is_active: true,
+        password_changed_at: null,
+      });
+      isSessionExpired.mockResolvedValue(true);
+      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);
+      expect(res.body.error).toBe('Session expired');
+    });
+
+    it('returns valid:true for an active admin token (helper says not expired)', async () => {
+      fakeDb.adminUsers.push({
+        id: 1,
+        username: 'admin',
+        is_active: true,
+        password_changed_at: null,
+      });
+      isSessionExpired.mockResolvedValue(false);
+      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(isSessionExpired).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not call isSessionExpired for gallery tokens', 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);
+      expect(isSessionExpired).not.toHaveBeenCalled();
+    });
+
+    it('falls through (treats as valid) if the helper itself throws', async () => {
+      // Defensive: the require() in auth.js is wrapped in try/catch so a
+      // missing/broken helper doesn't fail-closed during early bootstrap.
+      fakeDb.adminUsers.push({
+        id: 1,
+        username: 'admin',
+        is_active: true,
+        password_changed_at: null,
+      });
+      isSessionExpired.mockRejectedValue(new Error('boom'));
+      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);
+    });
+  });
+});

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/backupService.enhanced.test.js

@@ -1,4 +1,4 @@
-const { describe, it, expect, jest, beforeEach, afterEach } = require('@jest/globals');
+const { describe, it, expect, beforeEach, afterEach } = require('@jest/globals');
 const mockFs = require('mock-fs');
 const path = require('path');
 const crypto = require('crypto');
@@ -748,4 +748,4 @@ describe('Enhanced Backup Service Tests', () => {
       );
     });
   });
-});
+});

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/fontsService.test.js

@@ -0,0 +1,320 @@
+const fs = require('fs');
+const fsPromises = fs.promises;
+const os = require('os');
+const path = require('path');
+
+// Silence the logger so test output stays clean. Capture calls so the
+// "warning logged" assertions can still verify behaviour.
+jest.mock('../../src/utils/logger', () => ({
+  warn: jest.fn(),
+  info: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn()
+}));
+
+const logger = require('../../src/utils/logger');
+// Required ONCE at module top so the jest.mock factory above applies to
+// the logger reference that fontsService captures. A previous version
+// re-required it inside beforeEach() with jest.resetModules() — that
+// silently bypassed the mock (logger calls went to the real logger),
+// so the "warning logged" assertions would resolve as 0 calls and
+// silently pass-as-noop. Module-level state in fontsService is just
+// the cache, which clearFontsCache() resets between tests.
+const fontsService = require('../../src/services/fontsService');
+
+// Probe at load time: is the host filesystem case-sensitive?
+// macOS APFS and Windows NTFS treat "Inter" and "INTER" as the same
+// directory entry, which means the "two folders, same lowercase key"
+// dedup test below can't be set up via real folders on those platforms —
+// the second mkdir is a no-op. Skip that one test conditionally.
+const FS_IS_CASE_SENSITIVE = (() => {
+  const probeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-fs-probe-'));
+  fs.writeFileSync(path.join(probeDir, 'casetest'), '');
+  let sensitive = true;
+  try {
+    fs.accessSync(path.join(probeDir, 'CASETEST'));
+    sensitive = false;
+  } catch { /* file not found → case-sensitive FS */ }
+  fs.rmSync(probeDir, { recursive: true, force: true });
+  return sensitive;
+})();
+const testCaseSensitiveFS = FS_IS_CASE_SENSITIVE ? test : test.skip;
+
+let bundledRoot;
+let userRoot;
+
+/**
+ * Create a font family folder with the given weights (and optional meta.json).
+ * @param {string} root absolute path to the bundled or user root
+ * @param {string} folderName e.g. "Inter" or "Playfair-Display"
+ * @param {Array<number>|Array<string>} weights numeric weights (creates `<w>.woff2`)
+ *                                              or filenames to create directly
+ * @param {Object|null} meta optional meta.json contents (object) or null
+ */
+async function makeFamily(root, folderName, weights, meta = null) {
+  const dir = path.join(root, folderName);
+  await fsPromises.mkdir(dir, { recursive: true });
+  for (const w of weights) {
+    const fname = typeof w === 'number' ? `${w}.woff2` : w;
+    await fsPromises.writeFile(path.join(dir, fname), Buffer.from([]));
+  }
+  if (meta !== null) {
+    await fsPromises.writeFile(
+      path.join(dir, 'meta.json'),
+      typeof meta === 'string' ? meta : JSON.stringify(meta)
+    );
+  }
+  return dir;
+}
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+
+  bundledRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'picpeak-fonts-bundled-'));
+  userRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'picpeak-fonts-user-'));
+
+  process.env.PICPEAK_BUNDLED_FONTS_ROOT = bundledRoot;
+  // The user root resolves under STORAGE_PATH/fonts, so STORAGE_PATH must
+  // point at the parent of userRoot — we name the leaf "fonts" ourselves.
+  const storageParent = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'picpeak-fonts-storage-'));
+  await fsPromises.rename(userRoot, path.join(storageParent, 'fonts'));
+  userRoot = path.join(storageParent, 'fonts');
+  process.env.STORAGE_PATH = storageParent;
+
+  // Reset the module-level cache so each test sees a fresh scan.
+  // (Both getBundledFontsRoot and getUserFontsRoot read process.env at
+  // call-time, so the env vars set above are picked up without needing
+  // to re-require the module — see fontsService.js getBundledFontsRoot /
+  // getUserFontsRoot.)
+  fontsService.clearFontsCache();
+});
+
+afterEach(async () => {
+  fontsService.clearFontsCache();
+  await fsPromises.rm(bundledRoot, { recursive: true, force: true }).catch(() => {});
+  // userRoot's parent is the actual mkdtemp; remove it.
+  await fsPromises.rm(path.dirname(userRoot), { recursive: true, force: true }).catch(() => {});
+  delete process.env.PICPEAK_BUNDLED_FONTS_ROOT;
+  delete process.env.STORAGE_PATH;
+});
+
+describe('fontsService.listFonts', () => {
+  describe('roots', () => {
+    test('empty bundled root + missing user root → []', async () => {
+      // delete user root so it triggers ENOENT
+      await fsPromises.rm(path.dirname(userRoot), { recursive: true, force: true });
+      const fonts = await fontsService.listFonts();
+      expect(fonts).toEqual([]);
+    });
+
+    test('missing bundled root (ENOENT) → [], does not throw', async () => {
+      await fsPromises.rm(bundledRoot, { recursive: true, force: true });
+      const fonts = await fontsService.listFonts();
+      expect(fonts).toEqual([]);
+    });
+
+    test('non-directory entries at the root are skipped', async () => {
+      await fsPromises.writeFile(path.join(bundledRoot, 'README.md'), 'hi');
+      await makeFamily(bundledRoot, 'Inter', [400, 700]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Inter']);
+    });
+
+    test('hidden folders are skipped', async () => {
+      await makeFamily(bundledRoot, '.git', [400]);
+      await makeFamily(bundledRoot, '.DS_Store', [400]);
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Inter']);
+    });
+  });
+
+  describe('weight parsing', () => {
+    test('three weight files → sorted ascending', async () => {
+      await makeFamily(bundledRoot, 'Inter', [700, 400, 600]);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 600, 700]);
+    });
+
+    test('non-numeric filenames are ignored', async () => {
+      await makeFamily(bundledRoot, 'Inter', ['bold.woff2', 'regular.woff2', '400.woff2', '700.woff2']);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 700]);
+    });
+
+    test('non-.woff2 files are ignored', async () => {
+      await makeFamily(bundledRoot, 'Inter', ['400.ttf', '400.woff', '400.woff2', '700.otf']);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400]);
+    });
+
+    test('weight values out of range (sub-1 / over-1000) are ignored', async () => {
+      await makeFamily(bundledRoot, 'Inter', [0, 400, 1001, 700]);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 700]);
+    });
+
+    test('family folder with no usable .woff2 files is silently skipped', async () => {
+      await makeFamily(bundledRoot, 'NoWeights', ['readme.txt', 'bold.ttf']);
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Inter']);
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Skipping NoWeights')
+      );
+    });
+  });
+
+  describe('folder name → display family', () => {
+    test('hyphens become spaces', async () => {
+      await makeFamily(bundledRoot, 'Playfair-Display', [400]);
+      const [pd] = await fontsService.listFonts();
+      expect(pd.family).toBe('Playfair Display');
+    });
+
+    test('case is preserved', async () => {
+      await makeFamily(bundledRoot, 'IBM-Plex-Sans', [400]);
+      const [ibm] = await fontsService.listFonts();
+      expect(ibm.family).toBe('IBM Plex Sans');
+    });
+  });
+
+  describe('user-overrides-bundled', () => {
+    test('user folder of the same family wins; weights come from user', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400, 600, 700]);
+      await makeFamily(userRoot, 'Inter', [400, 900]); // different weights
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 900]);
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('overrides bundled default')
+      );
+    });
+
+    test('user-only family is included', async () => {
+      await makeFamily(userRoot, 'Lobster', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Lobster']);
+    });
+
+    testCaseSensitiveFS('case-insensitive duplicate within the same root → second skipped, warning', async () => {
+      // Two folder names whose lowercase keys collide. On a case-sensitive
+      // FS (Linux ext4) we can create both `Inter/` and `INTER/`; on a
+      // case-insensitive FS (macOS APFS, Windows NTFS) the second mkdir
+      // resolves to the same directory as the first and the dedup branch
+      // is unreachable from this test setup — see testCaseSensitiveFS above.
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      await makeFamily(bundledRoot, 'INTER', [700]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts).toHaveLength(1);
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Duplicate family')
+      );
+    });
+  });
+
+  describe('meta.json — generic fallback', () => {
+    test('valid generic="serif"', async () => {
+      await makeFamily(bundledRoot, 'Playfair-Display', [400], { generic: 'serif' });
+      const [pd] = await fontsService.listFonts();
+      expect(pd.generic).toBe('serif');
+    });
+
+    test('valid generic="cursive"', async () => {
+      await makeFamily(bundledRoot, 'Comic-Neue', [400], { generic: 'cursive' });
+      const [cn] = await fontsService.listFonts();
+      expect(cn.generic).toBe('cursive');
+    });
+
+    test('valid generic="monospace"', async () => {
+      await makeFamily(bundledRoot, 'Fira-Mono', [400], { generic: 'monospace' });
+      const [fm] = await fontsService.listFonts();
+      expect(fm.generic).toBe('monospace');
+    });
+
+    test('missing meta.json → defaults to sans-serif (no warning)', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.generic).toBe('sans-serif');
+      // No warning for the missing-file case (it's the normal path).
+      const noisy = (logger.warn.mock.calls || []).filter((c) =>
+        String(c[0]).includes('meta.json')
+      );
+      expect(noisy).toEqual([]);
+    });
+
+    test('invalid generic value → defaults to sans-serif, warning logged', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400], { generic: 'bogus' });
+      const [inter] = await fontsService.listFonts();
+      expect(inter.generic).toBe('sans-serif');
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('invalid generic "bogus"')
+      );
+    });
+
+    test('malformed JSON → defaults to sans-serif, warning logged', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400], '{ this is not json');
+      const [inter] = await fontsService.listFonts();
+      expect(inter.generic).toBe('sans-serif');
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('not valid JSON')
+      );
+    });
+  });
+
+  describe('result shape', () => {
+    test('every family is { family, weights, generic }', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400, 700]);
+      await makeFamily(bundledRoot, 'Playfair-Display', [400], { generic: 'serif' });
+      const fonts = await fontsService.listFonts();
+      for (const f of fonts) {
+        expect(f).toEqual({
+          family: expect.any(String),
+          weights: expect.any(Array),
+          generic: expect.stringMatching(/^(sans-serif|serif|cursive|monospace)$/)
+        });
+        expect(f.weights.length).toBeGreaterThan(0);
+      }
+    });
+
+    test('output sorted alphabetically by family', async () => {
+      await makeFamily(bundledRoot, 'Zilla-Slab', [400]);
+      await makeFamily(bundledRoot, 'Alpha-Sans', [400]);
+      await makeFamily(bundledRoot, 'Mid-Pack', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual([
+        'Alpha Sans',
+        'Mid Pack',
+        'Zilla Slab'
+      ]);
+    });
+  });
+
+  describe('cache', () => {
+    test('cache hit: second call within TTL does not re-readdir', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const spy = jest.spyOn(fsPromises, 'readdir');
+      await fontsService.listFonts();
+      const callsAfterFirst = spy.mock.calls.length;
+      await fontsService.listFonts();
+      expect(spy.mock.calls.length).toBe(callsAfterFirst);
+      spy.mockRestore();
+    });
+
+    test('clearFontsCache forces a fresh scan on the next call', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      await fontsService.listFonts();
+
+      // Add a new family AFTER the cache was populated.
+      await makeFamily(bundledRoot, 'Roboto', [400]);
+
+      // Without clearing, listFonts returns the stale cache.
+      const stale = await fontsService.listFonts();
+      expect(stale.map((f) => f.family)).toEqual(['Inter']);
+
+      // After clear, the new family appears.
+      fontsService.clearFontsCache();
+      const fresh = await fontsService.listFonts();
+      expect(fresh.map((f) => f.family)).toEqual(['Inter', 'Roboto']);
+    });
+  });
+});

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__/services/photoResolver.test.js

@@ -0,0 +1,85 @@
+const path = require('path');
+const mockPath = path;
+
+jest.mock('../../src/services/externalMediaService', () => ({
+  resolveExternalPath: jest.fn((event, relPath) => mockPath.join('/mock/external', event.external_path || '', relPath || '')),
+}));
+
+const { resolveExternalPath } = require('../../src/services/externalMediaService');
+const { resolvePhotoFilePath } = require('../../src/services/photoResolver');
+
+describe('resolvePhotoFilePath', () => {
+  const backendRoot = path.resolve(__dirname, '../../');
+  const originalStoragePath = process.env.STORAGE_PATH;
+
+  beforeEach(() => {
+    process.env.STORAGE_PATH = path.join(backendRoot, 'storage');
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterAll(() => {
+    if (typeof originalStoragePath === 'string') {
+      process.env.STORAGE_PATH = originalStoragePath;
+    } else {
+      delete process.env.STORAGE_PATH;
+    }
+  });
+
+  it('returns absolute path for managed photos with legacy slug paths', () => {
+    const event = { slug: 'wedding-party', source_mode: 'managed' };
+    const photo = { path: 'wedding-party/hero.jpg' };
+
+    const result = resolvePhotoFilePath(event, photo);
+
+    expect(result).toBe(path.join(backendRoot, 'storage', 'events/active', 'wedding-party', 'hero.jpg'));
+  });
+
+  it('normalizes prefixed managed paths without duplicating segments', () => {
+    const event = { slug: 'wedding-party', source_mode: 'managed' };
+    const photo = { path: 'events/active/wedding-party/hero.jpg' };
+
+    const result = resolvePhotoFilePath(event, photo);
+
+    expect(result).toBe(path.join(backendRoot, 'storage', 'events/active', 'wedding-party', 'hero.jpg'));
+  });
+
+  it('delegates external photos to external media resolver', () => {
+    const event = { slug: 'fashion-show', source_mode: 'reference', external_path: 'picsum-demo' };
+    const photo = { source_origin: 'external', external_relpath: 'individual/look-01.jpg' };
+
+    const result = resolvePhotoFilePath(event, photo);
+
+    expect(resolveExternalPath).toHaveBeenCalledWith(event, 'individual/look-01.jpg');
+    expect(result).toBe(path.join('/mock/external', 'picsum-demo', 'individual', 'look-01.jpg'));
+  });
+
+  it('deduplicates folder names when event external path already ends with segment', () => {
+    const event = { slug: 'fashion-show', source_mode: 'reference', external_path: 'picsum-demo/individual' };
+    const photo = { source_origin: 'external', external_relpath: 'individual/look-02.jpg' };
+
+    const result = resolvePhotoFilePath(event, photo);
+
+    expect(resolveExternalPath).toHaveBeenCalledWith(event, 'look-02.jpg');
+    expect(result).toBe(path.join('/mock/external', 'picsum-demo/individual', 'look-02.jpg'));
+  });
+
+  it('falls back to managed storage when external metadata is missing', () => {
+    const event = { slug: 'fashion-show', source_mode: 'reference', external_path: 'picsum-demo' };
+    const photo = { path: 'fashion-show/new-upload.jpg' };
+
+    const result = resolvePhotoFilePath(event, photo);
+
+    expect(resolveExternalPath).not.toHaveBeenCalled();
+    expect(result).toBe(path.join(backendRoot, 'storage', 'events/active', 'fashion-show', 'new-upload.jpg'));
+  });
+
+  it('throws when external photo is missing relative path data', () => {
+    const event = { slug: 'fashion-show', source_mode: 'reference', external_path: 'picsum-demo' };
+    const photo = { source_origin: 'external' };
+
+    expect(() => resolvePhotoFilePath(event, photo)).toThrow('Missing external_relpath for external photo');
+  });
+});

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/assets/fonts/Comic-Neue/meta.json

@@ -0,0 +1,3 @@
+{
+  "generic": "cursive"
+}

backend/assets/fonts/LICENSE-OFL.txt

@@ -0,0 +1,114 @@
+This directory bundles the following typefaces, each licensed under the
+SIL Open Font License v1.1.
+------------------------------------------------------------
+Per-font copyright notices
+------------------------------------------------------------
+Inter
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+Noto Sans
+Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)
+Poppins
+Copyright 2020 The Poppins Project Authors (https://github.com/itfoundry/Poppins)
+Jost
+Copyright 2020 The Jost Project Authors (https://github.com/indestructible-type/Jost)
+Montserrat
+Copyright 2011 The Montserrat Project Authors (https://github.com/JulietaUla/Montserrat)
+Playfair Display
+Copyright 2017 The Playfair Display Project Authors (https://github.com/clauseggers/Playfair)
+IBM Plex Sans
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+Comic Neue
+Copyright (c) 2014 by Craig Rozynski. All rights reserved.
+
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

backend/assets/fonts/Playfair-Display/meta.json

@@ -0,0 +1,3 @@
+{
+  "generic": "serif"
+}

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/jest.setup.js

@@ -1,4 +1,10 @@
 beforeAll(() => {
   process.env.NODE_ENV = 'test';
   process.env.JWT_SECRET = 'test-secret';
+  if (!process.env.SKIP_S3_TESTS) {
+    process.env.SKIP_S3_TESTS = 'true';
+  }
+  if (!process.env.STORAGE_PATH) {
+    process.env.STORAGE_PATH = '/storage';
+  }
 });

backend/knexfile.js

@@ -3,6 +3,54 @@ require('dotenv').config();
 const path = require('path');
 
 // Database configuration for different environments
+const resolveSqliteFilename = (filenameEnv) => {
+  const fallback = path.join(__dirname, './data/photo_sharing.db');
+
+  if (!filenameEnv) {
+    return fallback;
+  }
+
+  const trimmed = String(filenameEnv).trim();
+  if (!trimmed) {
+    return fallback;
+  }
+
+  let resolved;
+  if (path.isAbsolute(trimmed)) {
+    resolved = trimmed;
+  } else if (trimmed.startsWith('./') || trimmed.startsWith('../')) {
+    resolved = path.resolve(__dirname, trimmed);
+  } else {
+    resolved = path.join(__dirname, trimmed);
+  }
+
+  const normalized = path.normalize(resolved);
+  const baseSuffix = path.relative(path.parse(__dirname).root, path.normalize(__dirname));
+  const duplicatePattern = `${path.sep}${baseSuffix}${path.sep}${baseSuffix}`;
+
+  if (normalized.includes(duplicatePattern)) {
+    return normalized.replace(duplicatePattern, `${path.sep}${baseSuffix}`);
+  }
+
+  return normalized;
+};
+
+const sqliteConnection = (filenameEnv) => ({
+  filename: resolveSqliteFilename(filenameEnv)
+});
+
+const baseSqliteConfig = {
+  client: 'sqlite3',
+  connection: sqliteConnection(),
+  useNullAsDefault: true,
+  migrations: {
+    directory: './migrations'
+  },
+  seeds: {
+    directory: './seeds'
+  }
+};
+
 const config = {
   development: {
     client: process.env.DATABASE_CLIENT || 'sqlite3',
@@ -13,7 +61,7 @@ const config = {
       password: process.env.DB_PASSWORD || 'postgres',
       database: process.env.DB_NAME || 'photo_sharing'
     } : {
-      filename: path.join(__dirname, process.env.DATABASE_PATH || './data/photo_sharing.db')
+      filename: resolveSqliteFilename(process.env.DATABASE_PATH || './data/photo_sharing.db')
     },
     useNullAsDefault: process.env.DATABASE_CLIENT !== 'pg',
     migrations: {
@@ -24,36 +72,65 @@ const config = {
     }
   },
 
+  test: (() => {
+    const client = process.env.DATABASE_CLIENT || 'sqlite3';
+    const isPostgres = client === 'pg';
+
+    return {
+      ...baseSqliteConfig,
+      client,
+      useNullAsDefault: !isPostgres,
+      connection: isPostgres
+        ? {
+            host: process.env.DB_HOST || 'localhost',
+            port: process.env.DB_PORT || 5432,
+            user: process.env.DB_USER || 'postgres',
+            password: process.env.DB_PASSWORD || 'postgres',
+            database: process.env.DB_NAME || 'photo_sharing_test'
+          }
+        : sqliteConnection(process.env.TEST_DATABASE_PATH || './data/photo_sharing_test.db')
+    };
+  })(),
+
   production: {
     client: process.env.DATABASE_CLIENT || 'pg',
-    connection: {
-      host: process.env.DB_HOST || 'db',
-      port: process.env.DB_PORT || 5432,
-      user: process.env.DB_USER || 'picpeak',
-      password: process.env.DB_PASSWORD,
-      database: process.env.DB_NAME || 'picpeak',
-      ssl: process.env.DB_SSL === 'true' ? { rejectUnauthorized: false } : false,
-      // Connection stability settings
-      connectionTimeoutMillis: 30000,
-      idleTimeoutMillis: 30000,
-      keepAlive: true,
-      keepAliveInitialDelayMillis: 0
-    },
-    pool: {
-      min: 5,
-      max: 25,
-      acquireTimeoutMillis: 60000,
-      createTimeoutMillis: 60000,
-      idleTimeoutMillis: 30000,
-      reapIntervalMillis: 1000,
-      createRetryIntervalMillis: 200,
-      propagateCreateError: false
-    },
+    // Support both Postgres and SQLite in production based on DATABASE_CLIENT
+    connection: (process.env.DATABASE_CLIENT || 'pg') === 'pg'
+      ? {
+          host: process.env.DB_HOST || 'db',
+          port: process.env.DB_PORT || 5432,
+          user: process.env.DB_USER || 'picpeak',
+          password: process.env.DB_PASSWORD,
+          database: process.env.DB_NAME || 'picpeak',
+          ssl: process.env.DB_SSL === 'true' ? { rejectUnauthorized: false } : false,
+          // Connection stability settings
+          connectionTimeoutMillis: 30000,
+          idleTimeoutMillis: 30000,
+          keepAlive: true,
+          keepAliveInitialDelayMillis: 0
+        }
+      : {
+          filename: resolveSqliteFilename(process.env.DATABASE_PATH || './data/photo_sharing.db')
+        },
+    useNullAsDefault: (process.env.DATABASE_CLIENT || 'pg') !== 'pg',
+    pool: (process.env.DATABASE_CLIENT || 'pg') === 'pg'
+      ? {
+          min: 5,
+          max: 25,
+          acquireTimeoutMillis: 60000,
+          createTimeoutMillis: 60000,
+          idleTimeoutMillis: 30000,
+          reapIntervalMillis: 1000,
+          createRetryIntervalMillis: 200,
+          propagateCreateError: false
+        }
+      : undefined,
     migrations: {
       directory: './migrations'
     },
     acquireConnectionTimeout: 60000
   }
 };
+const env = process.env.NODE_ENV || 'development';
 
-module.exports = config[process.env.NODE_ENV || 'development'];
+module.exports = config[env] || config.development;

backend/migrations/004_add_categories_and_cms.js

@@ -1,101 +0,0 @@
-const { db } = require('../src/database/db');
-
-async function up() {
-  console.log('Adding photo categories and CMS tables...');
-  
-  // Create photo_categories table
-  await db.schema.createTable('photo_categories', (table) => {
-    table.increments('id').primary();
-    table.string('name', 100).notNullable();
-    table.string('slug', 100).notNullable();
-    table.boolean('is_global').defaultTo(true);
-    table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
-    table.timestamp('created_at').defaultTo(db.fn.now());
-    
-    // Unique constraint for slug within event scope
-    table.unique(['slug', 'event_id']);
-  });
-
-  // Create cms_pages table
-  await db.schema.createTable('cms_pages', (table) => {
-    table.increments('id').primary();
-    table.string('slug', 100).unique().notNullable();
-    table.text('title_en');
-    table.text('title_de');
-    table.text('content_en');
-    table.text('content_de');
-    table.timestamp('updated_at').defaultTo(db.fn.now());
-  });
-
-  // Add category_id to photos table
-  await db.schema.alterTable('photos', (table) => {
-    table.integer('category_id').references('id').inTable('photo_categories');
-  });
-
-  // Add language preference to admin_users
-  await db.schema.alterTable('admin_users', (table) => {
-    table.string('language', 2).defaultTo('en');
-  });
-
-  // Add language preference to app_settings for global default
-  await db('app_settings').insert({
-    setting_key: 'default_language',
-    setting_value: 'en',
-    setting_type: 'general',
-    updated_at: new Date()
-  });
-
-  // Insert default global categories
-  const defaultCategories = [
-    { name: 'Ceremony', slug: 'ceremony', is_global: true },
-    { name: 'Reception', slug: 'reception', is_global: true },
-    { name: 'Portraits', slug: 'portraits', is_global: true },
-    { name: 'Group Photos', slug: 'group-photos', is_global: true },
-    { name: 'Details', slug: 'details', is_global: true },
-    { name: 'Party', slug: 'party', is_global: true }
-  ];
-
-  await db('photo_categories').insert(defaultCategories);
-
-  // Insert default legal pages
-  await db('cms_pages').insert([
-    {
-      slug: 'impressum',
-      title_en: 'Legal Notice',
-      title_de: 'Impressum',
-      content_en: '<h2>Legal Notice</h2><p>Please edit this content in the admin panel.</p>',
-      content_de: '<h2>Impressum</h2><p>Bitte bearbeiten Sie diesen Inhalt im Admin-Panel.</p>',
-      updated_at: new Date()
-    },
-    {
-      slug: 'datenschutz',
-      title_en: 'Privacy Policy',
-      title_de: 'Datenschutzerklärung',
-      content_en: '<h2>Privacy Policy</h2><p>Please edit this content in the admin panel.</p>',
-      content_de: '<h2>Datenschutzerklärung</h2><p>Bitte bearbeiten Sie diesen Inhalt im Admin-Panel.</p>',
-      updated_at: new Date()
-    }
-  ]);
-
-  console.log('Photo categories and CMS tables created successfully');
-}
-
-async function down() {
-  // Remove language from app_settings
-  await db('app_settings').where('setting_key', 'default_language').delete();
-  
-  // Drop columns
-  await db.schema.alterTable('admin_users', (table) => {
-    table.dropColumn('language');
-  });
-  
-  await db.schema.alterTable('photos', (table) => {
-    table.dropColumn('category_id');
-  });
-  
-  // Drop tables
-  await db.schema.dropTableIfExists('cms_pages');
-  await db.schema.dropTableIfExists('photo_categories');
-}
-
-module.exports = { up, down };

backend/migrations/006_add_photo_counter_to_categories.js

@@ -1,28 +0,0 @@
-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();
-  });
-
-  // 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 });
-    }
-  }
-};
-
-exports.down = async function(knex) {
-  await knex.schema.alterTable('photo_categories', function(table) {
-    table.dropColumn('photo_counter');
-  });
-};

backend/migrations/008_add_language_support_to_email_templates.js

@@ -1,35 +0,0 @@
-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');
-  });
-
-  // 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) {
-  await knex.schema.alterTable('email_templates', function(table) {
-    // Remove German columns
-    table.dropColumn('subject_de');
-    table.dropColumn('body_html_de');
-    table.dropColumn('body_text_de');
-    
-    // Rename columns back
-    table.renameColumn('subject_en', 'subject');
-    table.renameColumn('body_html_en', 'body_html');
-    table.renameColumn('body_text_en', 'body_text');
-  });
-};

backend/migrations/011_add_user_upload_settings.js

@@ -1,23 +0,0 @@
-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 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
-  });
-};
-
-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');
-  });
-};

backend/migrations/015_add_login_attempts_table.js

@@ -1,19 +0,0 @@
-exports.up = function(knex) {
-  return knex.schema.createTable('login_attempts', table => {
-    table.increments('id').primary();
-    table.string('identifier').notNullable(); // username or email
-    table.string('ip_address', 45).notNullable(); // IPv4 or IPv6
-    table.text('user_agent');
-    table.timestamp('attempt_time').defaultTo(knex.fn.now());
-    table.boolean('success').defaultTo(false);
-    
-    // Indexes for performance
-    table.index('identifier');
-    table.index('attempt_time');
-    table.index(['identifier', 'success', 'attempt_time']);
-  });
-};
-
-exports.down = function(knex) {
-  return knex.schema.dropTableIfExists('login_attempts');
-};

backend/migrations/016_add_auth_security_columns.js

@@ -1,25 +0,0 @@
-exports.up = function(knex) {
-  return knex.schema.table('admin_users', table => {
-    // Add password change tracking
-    table.timestamp('password_changed_at').nullable();
-    
-    // Add last login IP for security monitoring
-    table.string('last_login_ip', 45).nullable();
-    
-    // Add account security flags
-    table.boolean('two_factor_enabled').defaultTo(false);
-    table.string('two_factor_secret').nullable();
-    
-    // Add index for performance
-    table.index('password_changed_at');
-  });
-};
-
-exports.down = function(knex) {
-  return knex.schema.table('admin_users', table => {
-    table.dropColumn('password_changed_at');
-    table.dropColumn('last_login_ip');
-    table.dropColumn('two_factor_enabled');
-    table.dropColumn('two_factor_secret');
-  });
-};

backend/migrations/017_add_token_revocation_tables.js

@@ -1,34 +0,0 @@
-exports.up = function(knex) {
-  return knex.schema
-    // Table for individual token revocations
-    .createTable('revoked_tokens', table => {
-      table.increments('id').primary();
-      table.string('token_id').notNullable().unique(); // JWT ID or generated ID
-      table.integer('user_id').nullable(); // User who owned the token
-      table.string('token_type', 20); // admin, gallery, etc.
-      table.timestamp('revoked_at').defaultTo(knex.fn.now());
-      table.timestamp('expires_at').notNullable(); // When token would have expired
-      table.string('reason', 100); // password_change, logout, compromised, etc.
-      table.text('metadata'); // Additional JSON data
-      
-      // Indexes for performance
-      table.index('token_id');
-      table.index('user_id');
-      table.index('expires_at'); // For cleanup
-    })
-    // Table for user-level revocations (revoke all tokens before a certain time)
-    .createTable('user_token_revocations', table => {
-      table.integer('user_id').primary();
-      table.timestamp('revoked_at').notNullable();
-      table.string('reason', 100);
-      
-      // Index for quick lookups
-      table.index('revoked_at');
-    });
-};
-
-exports.down = function(knex) {
-  return knex.schema
-    .dropTableIfExists('user_token_revocations')
-    .dropTableIfExists('revoked_tokens');
-};

backend/migrations/033_add_gallery_feedback.js

@@ -1,129 +0,0 @@
-// No helpers needed for boolean values
-
-exports.up = async function(knex) {
-  console.log('Adding gallery feedback tables...');
-  
-  // Create event_feedback_settings table
-  await knex.schema.createTable('event_feedback_settings', (table) => {
-    table.increments('id').primary();
-    table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
-    table.boolean('feedback_enabled').defaultTo(false);
-    table.boolean('allow_ratings').defaultTo(true);
-    table.boolean('allow_likes').defaultTo(true);
-    table.boolean('allow_comments').defaultTo(false);
-    table.boolean('allow_favorites').defaultTo(true);
-    table.boolean('require_name_email').defaultTo(false);
-    table.boolean('moderate_comments').defaultTo(true);
-    table.boolean('show_feedback_to_guests').defaultTo(true);
-    table.timestamp('created_at').defaultTo(knex.fn.now());
-    table.timestamp('updated_at').defaultTo(knex.fn.now());
-    table.unique(['event_id']);
-  });
-
-  // Create photo_feedback table
-  await knex.schema.createTable('photo_feedback', (table) => {
-    table.increments('id').primary();
-    table.integer('photo_id').references('id').inTable('photos').onDelete('CASCADE');
-    table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
-    table.string('feedback_type', 20).notNullable();
-    table.integer('rating');
-    table.text('comment_text');
-    table.string('guest_name', 100);
-    table.string('guest_email', 255);
-    table.string('guest_identifier', 64);
-    table.string('ip_address', 45);
-    table.text('user_agent');
-    table.boolean('is_approved').defaultTo(true);
-    table.boolean('is_hidden').defaultTo(false);
-    table.timestamp('created_at').defaultTo(knex.fn.now());
-    table.timestamp('updated_at').defaultTo(knex.fn.now());
-    
-    // Add indexes
-    table.index(['photo_id']);
-    table.index(['event_id']);
-    table.index(['feedback_type']);
-    table.index(['guest_identifier']);
-    
-    // Add check constraint for rating (PostgreSQL)
-    if (knex.client.config.client === 'pg') {
-      table.check('?? >= 1 AND ?? <= 5', ['rating', 'rating']);
-    }
-  });
-
-  // Create feedback_rate_limits table
-  await knex.schema.createTable('feedback_rate_limits', (table) => {
-    table.increments('id').primary();
-    table.string('identifier', 64).notNullable();
-    table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
-    table.string('action_type', 20).notNullable();
-    table.integer('action_count').defaultTo(1);
-    table.timestamp('window_start').defaultTo(knex.fn.now());
-    
-    // Add indexes
-    table.index(['identifier', 'event_id', 'action_type']);
-    table.index(['window_start']);
-  });
-
-  // Create feedback_word_filters table
-  await knex.schema.createTable('feedback_word_filters', (table) => {
-    table.increments('id').primary();
-    table.string('word', 100).notNullable();
-    table.string('severity', 20).defaultTo('moderate');
-    table.boolean('is_active').defaultTo(true);
-    table.timestamp('created_at').defaultTo(knex.fn.now());
-    table.unique(['word']);
-  });
-
-  // Add feedback summary columns to photos table
-  await knex.schema.alterTable('photos', (table) => {
-    table.integer('feedback_count').defaultTo(0);
-    table.integer('like_count').defaultTo(0);
-    table.decimal('average_rating', 3, 2).defaultTo(0);
-    table.integer('favorite_count').defaultTo(0);
-  });
-
-  // Add feedback notification settings to app_settings
-  await knex('app_settings').insert([
-    {
-      setting_key: 'feedback_notification_email',
-      setting_value: JSON.stringify(''),
-      setting_type: 'feedback'
-    },
-    {
-      setting_key: 'feedback_rate_limits',
-      setting_value: JSON.stringify({
-        rating: { max: 100, window: 3600 }, // 100 ratings per hour
-        comment: { max: 20, window: 3600 }, // 20 comments per hour
-        like: { max: 200, window: 3600 } // 200 likes per hour
-      }),
-      setting_type: 'feedback'
-    }
-  ]);
-  
-  console.log('Gallery feedback tables created successfully');
-};
-
-exports.down = async function(knex) {
-  console.log('Removing gallery feedback tables...');
-  
-  // Remove feedback settings from app_settings
-  await knex('app_settings')
-    .whereIn('setting_key', ['feedback_notification_email', 'feedback_rate_limits'])
-    .delete();
-
-  // Remove feedback columns from photos table
-  await knex.schema.alterTable('photos', (table) => {
-    table.dropColumn('feedback_count');
-    table.dropColumn('like_count');
-    table.dropColumn('average_rating');
-    table.dropColumn('favorite_count');
-  });
-
-  // Drop tables in reverse order
-  await knex.schema.dropTableIfExists('feedback_word_filters');
-  await knex.schema.dropTableIfExists('feedback_rate_limits');
-  await knex.schema.dropTableIfExists('photo_feedback');
-  await knex.schema.dropTableIfExists('event_feedback_settings');
-  
-  console.log('Gallery feedback tables removed');
-};

backend/migrations/041_add_logo_customization_settings.js

@@ -0,0 +1,89 @@
+exports.up = async function(knex) {
+  console.log('Running migration: 041_add_logo_customization_settings');
+  
+  // Add default logo customization settings
+  const logoSettings = [
+    {
+      setting_key: 'branding_logo_size',
+      setting_value: JSON.stringify('medium'),
+      setting_type: 'branding',
+      description: 'Logo size: small, medium, large, xlarge, or custom',
+      created_at: new Date(),
+      updated_at: new Date()
+    },
+    {
+      setting_key: 'branding_logo_max_height',
+      setting_value: JSON.stringify(48),
+      setting_type: 'branding', 
+      description: 'Maximum logo height in pixels (used when size is custom)',
+      created_at: new Date(),
+      updated_at: new Date()
+    },
+    {
+      setting_key: 'branding_logo_position',
+      setting_value: JSON.stringify('left'),
+      setting_type: 'branding',
+      description: 'Logo position in header: left, center, right',
+      created_at: new Date(),
+      updated_at: new Date()
+    },
+    {
+      setting_key: 'branding_logo_display_header',
+      setting_value: JSON.stringify(true),
+      setting_type: 'branding',
+      description: 'Show logo in gallery header',
+      created_at: new Date(),
+      updated_at: new Date()
+    },
+    {
+      setting_key: 'branding_logo_display_hero',
+      setting_value: JSON.stringify(true),
+      setting_type: 'branding',
+      description: 'Show logo in hero section (for non-grid layouts)',
+      created_at: new Date(),
+      updated_at: new Date()
+    },
+    {
+      setting_key: 'branding_logo_display_mode',
+      setting_value: JSON.stringify('logo_and_text'),
+      setting_type: 'branding',
+      description: 'Display mode: logo_only, text_only, logo_and_text',
+      created_at: new Date(),
+      updated_at: new Date()
+    }
+  ];
+
+  // Insert settings that don't already exist
+  for (const setting of logoSettings) {
+    const exists = await knex('app_settings')
+      .where('setting_key', setting.setting_key)
+      .first();
+    
+    if (!exists) {
+      await knex('app_settings').insert(setting);
+      console.log(`Added setting: ${setting.setting_key}`);
+    } else {
+      console.log(`Setting already exists: ${setting.setting_key}`);
+    }
+  }
+
+  console.log('Migration 041_add_logo_customization_settings completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rolling back migration: 041_add_logo_customization_settings');
+  
+  // Remove the logo customization settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'branding_logo_size',
+      'branding_logo_max_height',
+      'branding_logo_position',
+      'branding_logo_display_header',
+      'branding_logo_display_hero',
+      'branding_logo_display_mode'
+    ])
+    .del();
+  
+  console.log('Rollback of 041_add_logo_customization_settings completed');
+};

backend/migrations/README.md

@@ -0,0 +1,47 @@
+# Database Migrations
+
+This directory contains database migrations for the PicPeak photo sharing platform.
+
+## Directory Structure
+
+### `/core`
+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.
+
+## For New Deployments
+
+If you're deploying this application for the first time:
+1. The `initializeDatabase()` function in `src/database/db.js` will create all necessary tables
+2. Only migrations in the `/core` directory will be run
+3. This ensures a clean, optimized database schema
+
+## For Existing Deployments
+
+If you're upgrading from an older version:
+1. All migrations (both core and legacy) will be run in sequence
+2. The migration system tracks which migrations have been applied
+3. Only new migrations will be executed
+
+## Running Migrations
+
+```bash
+# Development
+npm run migrate
+
+# Production
+npm run migrate:prod
+```
+
+## Note on Duplicate Migration Numbers
+
+The legacy directory contains renamed duplicates:
+- `014_add_host_name_to_events_duplicate.js` (was duplicate of 014)
+- `027_add_rate_limit_settings_duplicate.js` (was duplicate of 027)
+
+These have been renamed to avoid conflicts while preserving the migration history.

backend/migrations/core/001_init.js

@@ -1,33 +1,39 @@
 const bcrypt = require('bcrypt');
-const { db, initializeDatabase } = require('../src/database/db');
-const { generateReadablePassword } = require('../src/utils/passwordGenerator');
+const { initializeDatabase } = require('../../src/database/db');
+const { generateReadablePassword } = require('../../src/utils/passwordGenerator');
 const fs = require('fs').promises;
 const path = require('path');
 
-async function runMigrations() {
-  console.log('Running database migrations...');
+exports.up = async function(knex) {
+  console.log('Initializing database schema...');
   
   try {
     // Initialize tables
     await initializeDatabase();
     
     // Create default admin user if none exists
-    const adminExists = await db('admin_users').first();
+    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
       
-      await db('admin_users').insert({
-        username: 'admin',
-        email: 'admin@example.com',
+      // Get admin credentials from environment or use defaults
+      const adminUsername = process.env.ADMIN_USERNAME || 'admin';
+      const adminEmail = process.env.ADMIN_EMAIL || 'admin@example.com';
+      
+      await knex('admin_users').insert({
+        username: adminUsername,
+        email: adminEmail,
         password_hash: passwordHash,
-        must_change_password: true, // Flag for forcing password change
+        must_change_password: true,
         created_at: new Date()
       });
       
-      // Save the generated password to a file for the user to retrieve
-      const setupInfoPath = path.join(__dirname, '..', '..', 'ADMIN_CREDENTIALS.txt');
+      // Try to save credentials to file, but don't fail if we can't
+      const dataDir = path.join(__dirname, '..', '..', 'data');
+      const setupInfoPath = path.join(dataDir, 'ADMIN_CREDENTIALS.txt');
+      
       const setupInfo = `
 ========================================
 PicPeak Admin Credentials
@@ -35,39 +41,49 @@ PicPeak Admin Credentials
 
 Your admin account has been created with these credentials:
 
-Username: admin
+Email: ${adminEmail}
 Password: ${generatedPassword}
 
 IMPORTANT SECURITY NOTES:
-1. You MUST change this password on first login
+1. Please change this password after first login
 2. This file will be created only once
 3. Store these credentials securely
 4. Delete this file after noting the password
 
 Login URL: ${process.env.ADMIN_URL || 'http://localhost:3001'}/admin
 
+Login with the email address shown above
+
 Generated on: ${new Date().toISOString()}
 ========================================
 `;
       
-      await fs.writeFile(setupInfoPath, setupInfo, 'utf8');
+      try {
+        // Try to create directory and write file
+        await fs.mkdir(dataDir, { recursive: true });
+        await fs.writeFile(setupInfoPath, setupInfo, 'utf8');
+        console.log(`📁 Credentials also saved to: data/ADMIN_CREDENTIALS.txt`);
+      } catch (error) {
+        // If we can't write the file, that's okay - credentials are shown in console
+        console.log('⚠️  Could not save credentials to file (permission denied)');
+        console.log('   Please copy the credentials shown above');
+      }
       
       console.log('\n========================================');
       console.log('✅ Admin user created successfully!');
       console.log('========================================');
-      console.log('Username: admin');
+      console.log(`Email: ${adminEmail}`);
       console.log(`Password: ${generatedPassword}`);
       console.log('\n⚠️  IMPORTANT:');
       console.log('1. Save these credentials securely');
-      console.log('2. You will be required to change the password on first login');
-      console.log('3. Credentials are also saved in: ADMIN_CREDENTIALS.txt');
+      console.log('2. Please change the password after first login');
       console.log('========================================\n');
     }
     
     // Create default email templates if none exist
-    const templateExists = await db('email_templates').first();
+    const templateExists = await knex('email_templates').first();
     if (!templateExists) {
-      await db('email_templates').insert([
+      await knex('email_templates').insert([
         {
           template_key: 'gallery_created',
           subject: 'Your Photo Gallery is Ready!',
@@ -101,9 +117,9 @@ Generated on: ${new Date().toISOString()}
     }
 
     // Create default email config if none exists
-    const emailConfig = await db('email_configs').first();
+    const emailConfig = await knex('email_configs').first();
     if (!emailConfig) {
-      await db('email_configs').insert({
+      await knex('email_configs').insert({
         smtp_host: process.env.SMTP_HOST || 'mailhog',
         smtp_port: process.env.SMTP_PORT || 1025,
         smtp_secure: process.env.SMTP_SECURE === 'true',
@@ -116,11 +132,13 @@ Generated on: ${new Date().toISOString()}
     }
 
     console.log('Migrations completed successfully');
-    process.exit(0);
   } catch (error) {
-    console.error('Migration failed:', error);
-    process.exit(1);
+    console.error('Initial setup failed:', error);
+    throw error;
   }
-}
+};
 
-runMigrations();
+exports.down = async function(knex) {
+  // This migration cannot be rolled back as it creates the initial schema
+  console.log('Initial setup cannot be rolled back');
+};

backend/migrations/core/029_add_backup_service_tables.js

@@ -1,4 +1,4 @@
-const { db } = require('../src/database/db');
+const { db } = require('../../src/database/db');
 
 async function up() {
   console.log('Adding backup service tables and settings...');
@@ -156,9 +156,8 @@ async function up() {
   const backupEmailTemplates = [
     {
       template_key: 'backup_failed',
-      subject_en: 'Backup Failed - Immediate Attention Required',
-      subject_de: 'Backup fehlgeschlagen - Sofortige Aufmerksamkeit erforderlich',
-      body_html_en: `<h2>Backup Failed</h2>
+      subject: 'Backup Failed - Immediate Attention Required',
+      body_html: `<h2>Backup Failed</h2>
 <p>The scheduled backup has failed and requires immediate attention.</p>
 <p><strong>Error Details:</strong></p>
 <ul>
@@ -167,24 +166,13 @@ async function up() {
   <li>Error: {{error_message}}</li>
 </ul>
 <p>Please check the system logs for more details and resolve the issue as soon as possible.</p>`,
-      body_html_de: `<h2>Backup fehlgeschlagen</h2>
-<p>Das geplante Backup ist fehlgeschlagen und erfordert sofortige Aufmerksamkeit.</p>
-<p><strong>Fehlerdetails:</strong></p>
-<ul>
-  <li>Startzeit: {{start_time}}</li>
-  <li>Backup-Typ: {{backup_type}}</li>
-  <li>Fehler: {{error_message}}</li>
-</ul>
-<p>Bitte überprüfen Sie die Systemprotokolle für weitere Details und beheben Sie das Problem so schnell wie möglich.</p>`,
-      body_text_en: 'Backup Failed\n\nThe scheduled backup has failed and requires immediate attention.\n\nStart Time: {{start_time}}\nBackup Type: {{backup_type}}\nError: {{error_message}}\n\nPlease check the system logs for more details.',
-      body_text_de: 'Backup fehlgeschlagen\n\nDas geplante Backup ist fehlgeschlagen und erfordert sofortige Aufmerksamkeit.\n\nStartzeit: {{start_time}}\nBackup-Typ: {{backup_type}}\nFehler: {{error_message}}\n\nBitte überprüfen Sie die Systemprotokolle für weitere Details.',
+      body_text: 'Backup Failed\n\nThe scheduled backup has failed and requires immediate attention.\n\nStart Time: {{start_time}}\nBackup Type: {{backup_type}}\nError: {{error_message}}\n\nPlease check the system logs for more details.',
       variables: JSON.stringify(['start_time', 'backup_type', 'error_message'])
     },
     {
       template_key: 'backup_completed',
-      subject_en: 'Backup Completed Successfully',
-      subject_de: 'Backup erfolgreich abgeschlossen',
-      body_html_en: `<h2>Backup Completed</h2>
+      subject: 'Backup Completed Successfully',
+      body_html: `<h2>Backup Completed</h2>
 <p>The scheduled backup has been completed successfully.</p>
 <p><strong>Backup Summary:</strong></p>
 <ul>
@@ -194,18 +182,7 @@ async function up() {
   <li>Total Size: {{total_size}}</li>
   <li>Backup Type: {{backup_type}}</li>
 </ul>`,
-      body_html_de: `<h2>Backup abgeschlossen</h2>
-<p>Das geplante Backup wurde erfolgreich abgeschlossen.</p>
-<p><strong>Backup-Zusammenfassung:</strong></p>
-<ul>
-  <li>Startzeit: {{start_time}}</li>
-  <li>Dauer: {{duration}}</li>
-  <li>Gesicherte Dateien: {{files_count}}</li>
-  <li>Gesamtgröße: {{total_size}}</li>
-  <li>Backup-Typ: {{backup_type}}</li>
-</ul>`,
-      body_text_en: 'Backup Completed\n\nThe scheduled backup has been completed successfully.\n\nStart Time: {{start_time}}\nDuration: {{duration}}\nFiles Backed Up: {{files_count}}\nTotal Size: {{total_size}}\nBackup Type: {{backup_type}}',
-      body_text_de: 'Backup abgeschlossen\n\nDas geplante Backup wurde erfolgreich abgeschlossen.\n\nStartzeit: {{start_time}}\nDauer: {{duration}}\nGesicherte Dateien: {{files_count}}\nGesamtgröße: {{total_size}}\nBackup-Typ: {{backup_type}}',
+      body_text: 'Backup Completed\n\nThe scheduled backup has been completed successfully.\n\nStart Time: {{start_time}}\nDuration: {{duration}}\nFiles Backed Up: {{files_count}}\nTotal Size: {{total_size}}\nBackup Type: {{backup_type}}',
       variables: JSON.stringify(['start_time', 'duration', 'files_count', 'total_size', 'backup_type'])
     }
   ];

backend/migrations/core/030_add_database_backup_tables.js

@@ -1,4 +1,4 @@
-const { db } = require('../src/database/db');
+const { db } = require('../../src/database/db');
 
 async function up() {
   console.log('Adding database backup tables and settings...');
@@ -96,9 +96,8 @@ async function up() {
   const databaseBackupEmailTemplates = [
     {
       template_key: 'database_backup_failed',
-      subject_en: 'Database Backup Failed - Critical Alert',
-      subject_de: 'Datenbank-Backup fehlgeschlagen - Kritische Warnung',
-      body_html_en: `<h2>Database Backup Failed</h2>
+      subject: 'Database Backup Failed - Critical Alert',
+      body_html: `<h2>Database Backup Failed</h2>
 <p>The scheduled database backup has failed and requires immediate attention.</p>
 <p><strong>Error Details:</strong></p>
 <ul>
@@ -107,24 +106,13 @@ async function up() {
   <li>Error: {{error_message}}</li>
 </ul>
 <p>This is a critical issue that could affect disaster recovery. Please investigate immediately.</p>`,
-      body_html_de: `<h2>Datenbank-Backup fehlgeschlagen</h2>
-<p>Das geplante Datenbank-Backup ist fehlgeschlagen und erfordert sofortige Aufmerksamkeit.</p>
-<p><strong>Fehlerdetails:</strong></p>
-<ul>
-  <li>Backup-Typ: {{backup_type}}</li>
-  <li>Zeitstempel: {{timestamp}}</li>
-  <li>Fehler: {{error_message}}</li>
-</ul>
-<p>Dies ist ein kritisches Problem, das die Disaster-Recovery beeinträchtigen könnte. Bitte untersuchen Sie es sofort.</p>`,
-      body_text_en: 'Database Backup Failed\n\nThe scheduled database backup has failed.\n\nBackup Type: {{backup_type}}\nTimestamp: {{timestamp}}\nError: {{error_message}}\n\nThis is critical - please investigate immediately.',
-      body_text_de: 'Datenbank-Backup fehlgeschlagen\n\nDas geplante Datenbank-Backup ist fehlgeschlagen.\n\nBackup-Typ: {{backup_type}}\nZeitstempel: {{timestamp}}\nFehler: {{error_message}}\n\nDies ist kritisch - bitte sofort untersuchen.',
+      body_text: 'Database Backup Failed\n\nThe scheduled database backup has failed.\n\nBackup Type: {{backup_type}}\nTimestamp: {{timestamp}}\nError: {{error_message}}\n\nThis is critical - please investigate immediately.',
       variables: JSON.stringify(['backup_type', 'timestamp', 'error_message'])
     },
     {
       template_key: 'database_backup_completed',
-      subject_en: 'Database Backup Completed Successfully',
-      subject_de: 'Datenbank-Backup erfolgreich abgeschlossen',
-      body_html_en: `<h2>Database Backup Completed</h2>
+      subject: 'Database Backup Completed Successfully',
+      body_html: `<h2>Database Backup Completed</h2>
 <p>The scheduled database backup has been completed successfully.</p>
 <p><strong>Backup Summary:</strong></p>
 <ul>
@@ -134,18 +122,7 @@ async function up() {
   <li>Compression Ratio: {{compression_ratio}}</li>
   <li>File Path: {{file_path}}</li>
 </ul>`,
-      body_html_de: `<h2>Datenbank-Backup abgeschlossen</h2>
-<p>Das geplante Datenbank-Backup wurde erfolgreich abgeschlossen.</p>
-<p><strong>Backup-Zusammenfassung:</strong></p>
-<ul>
-  <li>Backup-Typ: {{backup_type}}</li>
-  <li>Dauer: {{duration}}</li>
-  <li>Dateigröße: {{file_size}}</li>
-  <li>Komprimierungsverhältnis: {{compression_ratio}}</li>
-  <li>Dateipfad: {{file_path}}</li>
-</ul>`,
-      body_text_en: 'Database Backup Completed\n\nThe scheduled database backup has been completed successfully.\n\nBackup Type: {{backup_type}}\nDuration: {{duration}}\nFile Size: {{file_size}}\nCompression Ratio: {{compression_ratio}}\nFile Path: {{file_path}}',
-      body_text_de: 'Datenbank-Backup abgeschlossen\n\nDas geplante Datenbank-Backup wurde erfolgreich abgeschlossen.\n\nBackup-Typ: {{backup_type}}\nDauer: {{duration}}\nDateigröße: {{file_size}}\nKomprimierungsverhältnis: {{compression_ratio}}\nDateipfad: {{file_path}}',
+      body_text: 'Database Backup Completed\n\nThe scheduled database backup has been completed successfully.\n\nBackup Type: {{backup_type}}\nDuration: {{duration}}\nFile Size: {{file_size}}\nCompression Ratio: {{compression_ratio}}\nFile Path: {{file_path}}',
       variables: JSON.stringify(['backup_type', 'duration', 'file_size', 'compression_ratio', 'file_path'])
     }
   ];

backend/migrations/core/031_add_backup_manifest_columns.js

@@ -1,5 +1,5 @@
-const { db } = require('../src/database/db');
-const logger = require('../src/utils/logger');
+const { db } = require('../../src/database/db');
+const logger = require('../../src/utils/logger');
 
 async function up() {
   console.log('Adding backup manifest columns...');

backend/migrations/core/032_add_restore_runs_table.js

@@ -5,7 +5,9 @@
  */
 exports.up = async function(knex) {
   // Create restore_runs table
-  await knex.schema.createTable('restore_runs', table => {
+  const hasRestoreRunsTable = await knex.schema.hasTable('restore_runs');
+  if (!hasRestoreRunsTable) {
+    await knex.schema.createTable('restore_runs', table => {
     table.increments('id').primary();
     
     // Timing
@@ -44,10 +46,13 @@ exports.up = async function(knex) {
     
     table.index(['status', 'started_at']);
     table.index(['restore_type', 'started_at']);
-  });
+    });
+  }
   
   // Create restore_file_operations table for tracking individual file operations
-  await knex.schema.createTable('restore_file_operations', table => {
+  const hasRestoreFileOperationsTable = await knex.schema.hasTable('restore_file_operations');
+  if (!hasRestoreFileOperationsTable) {
+    await knex.schema.createTable('restore_file_operations', table => {
     table.increments('id').primary();
     
     table.integer('restore_run_id').notNullable()
@@ -67,10 +72,13 @@ exports.up = async function(knex) {
     
     table.index(['restore_run_id', 'status']);
     table.index(['file_path']);
-  });
+    });
+  }
   
   // Create restore_validation_results table
-  await knex.schema.createTable('restore_validation_results', table => {
+  const hasRestoreValidationResultsTable = await knex.schema.hasTable('restore_validation_results');
+  if (!hasRestoreValidationResultsTable) {
+    await knex.schema.createTable('restore_validation_results', table => {
     table.increments('id').primary();
     
     table.integer('restore_run_id').notNullable()
@@ -86,10 +94,11 @@ exports.up = async function(knex) {
     table.timestamp('validated_at').notNullable().defaultTo(knex.fn.now());
     
     table.index(['restore_run_id', 'validation_type']);
-  });
+    });
+  }
   
   // Add restore-related settings to app_settings
-  await knex('app_settings').insert([
+  const restoreSettings = [
     {
       setting_key: 'restore_allow_force',
       setting_value: JSON.stringify(false),
@@ -120,15 +129,24 @@ exports.up = async function(knex) {
       setting_value: '30',
       setting_type: 'restore'
     }
-  ]);
+  ];
+
+  for (const setting of restoreSettings) {
+    const exists = await knex('app_settings')
+      .where('setting_key', setting.setting_key)
+      .first();
+    
+    if (!exists) {
+      await knex('app_settings').insert(setting);
+    }
+  }
   
   // Add new email templates for restore notifications
   const emailTemplates = [
     {
       template_key: 'restore_completed',
-      subject_en: '✅ Restore Completed Successfully',
-      subject_de: '✅ Wiederherstellung erfolgreich abgeschlossen',
-      body_html_en: `<h2>Restore Operation Completed</h2>
+      subject: '✅ Restore Completed Successfully',
+      body_html: `<h2>Restore Operation Completed</h2>
 <p>A restore operation has completed successfully.</p>
 
 <h3>Details:</h3>
@@ -141,20 +159,7 @@ exports.up = async function(knex) {
 </ul>
 
 <p>Please verify that all systems are functioning correctly after the restore.</p>`,
-      body_html_de: `<h2>Wiederherstellungsvorgang abgeschlossen</h2>
-<p>Ein Wiederherstellungsvorgang wurde erfolgreich abgeschlossen.</p>
-
-<h3>Details:</h3>
-<ul>
-  <li><strong>Wiederherstellungstyp:</strong> {{restore_type}}</li>
-  <li><strong>Dauer:</strong> {{duration}}</li>
-  <li><strong>Wiederhergestellte Dateien:</strong> {{files_restored}}</li>
-  <li><strong>Backup-ID:</strong> {{backup_id}}</li>
-  <li><strong>Zeitstempel:</strong> {{timestamp}}</li>
-</ul>
-
-<p>Bitte überprüfen Sie, ob alle Systeme nach der Wiederherstellung ordnungsgemäß funktionieren.</p>`,
-      body_text_en: `Restore Operation Completed
+      body_text: `Restore Operation Completed
 
 A restore operation has completed successfully.
 
@@ -166,25 +171,12 @@ Details:
 - Timestamp: {{timestamp}}
 
 Please verify that all systems are functioning correctly after the restore.`,
-      body_text_de: `Wiederherstellungsvorgang abgeschlossen
-
-Ein Wiederherstellungsvorgang wurde erfolgreich abgeschlossen.
-
-Details:
-- Wiederherstellungstyp: {{restore_type}}
-- Dauer: {{duration}}
-- Wiederhergestellte Dateien: {{files_restored}}
-- Backup-ID: {{backup_id}}
-- Zeitstempel: {{timestamp}}
-
-Bitte überprüfen Sie, ob alle Systeme nach der Wiederherstellung ordnungsgemäß funktionieren.`,
       variables: JSON.stringify(['restore_type', 'duration', 'files_restored', 'backup_id', 'timestamp'])
     },
     {
       template_key: 'restore_failed',
-      subject_en: '❌ Restore Operation Failed',
-      subject_de: '❌ Wiederherstellungsvorgang fehlgeschlagen',
-      body_html_en: `<h2>Restore Operation Failed</h2>
+      subject: '❌ Restore Operation Failed',
+      body_html: `<h2>Restore Operation Failed</h2>
 <p>A restore operation has failed and requires attention.</p>
 
 <h3>Details:</h3>
@@ -197,20 +189,7 @@ Bitte überprüfen Sie, ob alle Systeme nach der Wiederherstellung ordnungsgemä
 <p>Please check the system logs for more details and take appropriate action.</p>
 
 <p><strong>Important:</strong> If a pre-restore backup was created, it may be used for recovery.</p>`,
-      body_html_de: `<h2>Wiederherstellungsvorgang fehlgeschlagen</h2>
-<p>Ein Wiederherstellungsvorgang ist fehlgeschlagen und erfordert Ihre Aufmerksamkeit.</p>
-
-<h3>Details:</h3>
-<ul>
-  <li><strong>Wiederherstellungstyp:</strong> {{restore_type}}</li>
-  <li><strong>Fehler:</strong> {{error_message}}</li>
-  <li><strong>Zeitstempel:</strong> {{timestamp}}</li>
-</ul>
-
-<p>Bitte überprüfen Sie die Systemprotokolle für weitere Details und ergreifen Sie entsprechende Maßnahmen.</p>
-
-<p><strong>Wichtig:</strong> Falls ein Backup vor der Wiederherstellung erstellt wurde, kann es zur Wiederherstellung verwendet werden.</p>`,
-      body_text_en: `Restore Operation Failed
+      body_text: `Restore Operation Failed
 
 A restore operation has failed and requires attention.
 
@@ -222,23 +201,19 @@ Details:
 Please check the system logs for more details and take appropriate action.
 
 Important: If a pre-restore backup was created, it may be used for recovery.`,
-      body_text_de: `Wiederherstellungsvorgang fehlgeschlagen
-
-Ein Wiederherstellungsvorgang ist fehlgeschlagen und erfordert Ihre Aufmerksamkeit.
-
-Details:
-- Wiederherstellungstyp: {{restore_type}}
-- Fehler: {{error_message}}
-- Zeitstempel: {{timestamp}}
-
-Bitte überprüfen Sie die Systemprotokolle für weitere Details und ergreifen Sie entsprechende Maßnahmen.
-
-Wichtig: Falls ein Backup vor der Wiederherstellung erstellt wurde, kann es zur Wiederherstellung verwendet werden.`,
       variables: JSON.stringify(['restore_type', 'error_message', 'timestamp'])
     }
   ];
   
-  await knex('email_templates').insert(emailTemplates);
+  for (const template of emailTemplates) {
+    const exists = await knex('email_templates')
+      .where('template_key', template.template_key)
+      .first();
+    
+    if (!exists) {
+      await knex('email_templates').insert(template);
+    }
+  }
 };
 
 exports.down = async function(knex) {

backend/migrations/core/033_add_gallery_feedback.js

@@ -0,0 +1,152 @@
+// No helpers needed for boolean values
+
+exports.up = async function(knex) {
+  console.log('Adding gallery feedback tables...');
+  
+  // Check if tables and columns already exist
+  const hasEventFeedbackSettingsTable = await knex.schema.hasTable('event_feedback_settings');
+  const hasPhotoFeedbackTable = await knex.schema.hasTable('photo_feedback');
+  const hasFeedbackRateLimitsTable = await knex.schema.hasTable('feedback_rate_limits');
+  const hasFeedbackWordFiltersTable = await knex.schema.hasTable('feedback_word_filters');
+  const hasFeedbackCountColumn = await knex.schema.hasColumn('photos', 'feedback_count');
+  
+  // Create event_feedback_settings table
+  if (!hasEventFeedbackSettingsTable) {
+    await knex.schema.createTable('event_feedback_settings', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
+      table.boolean('feedback_enabled').defaultTo(false);
+      table.boolean('allow_ratings').defaultTo(true);
+      table.boolean('allow_likes').defaultTo(true);
+      table.boolean('allow_comments').defaultTo(false);
+      table.boolean('allow_favorites').defaultTo(true);
+      table.boolean('require_name_email').defaultTo(false);
+      table.boolean('moderate_comments').defaultTo(true);
+      table.boolean('show_feedback_to_guests').defaultTo(true);
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+      table.unique(['event_id']);
+    });
+  }
+
+  // Create photo_feedback table
+  if (!hasPhotoFeedbackTable) {
+    await knex.schema.createTable('photo_feedback', (table) => {
+      table.increments('id').primary();
+      table.integer('photo_id').references('id').inTable('photos').onDelete('CASCADE');
+      table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
+      table.string('feedback_type', 20).notNullable();
+      table.integer('rating');
+      table.text('comment_text');
+      table.string('guest_name', 100);
+      table.string('guest_email', 255);
+      table.string('guest_identifier', 64);
+      table.string('ip_address', 45);
+      table.text('user_agent');
+      table.boolean('is_approved').defaultTo(true);
+      table.boolean('is_hidden').defaultTo(false);
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+      
+      // Add indexes
+      table.index(['photo_id']);
+      table.index(['event_id']);
+      table.index(['feedback_type']);
+      table.index(['guest_identifier']);
+      
+      // Add check constraint for rating (PostgreSQL)
+      if (knex.client.config.client === 'pg') {
+        table.check('?? >= 1 AND ?? <= 5', ['rating', 'rating']);
+      }
+    });
+  }
+
+  // Create feedback_rate_limits table
+  if (!hasFeedbackRateLimitsTable) {
+    await knex.schema.createTable('feedback_rate_limits', (table) => {
+      table.increments('id').primary();
+      table.string('identifier', 64).notNullable();
+      table.integer('event_id').references('id').inTable('events').onDelete('CASCADE');
+      table.string('action_type', 20).notNullable();
+      table.integer('action_count').defaultTo(1);
+      table.timestamp('window_start').defaultTo(knex.fn.now());
+      
+      // Add indexes
+      table.index(['identifier', 'event_id', 'action_type']);
+      table.index(['window_start']);
+    });
+  }
+
+  // Create feedback_word_filters table
+  if (!hasFeedbackWordFiltersTable) {
+    await knex.schema.createTable('feedback_word_filters', (table) => {
+      table.increments('id').primary();
+      table.string('word', 100).notNullable();
+      table.string('severity', 20).defaultTo('moderate');
+      table.boolean('is_active').defaultTo(true);
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.unique(['word']);
+    });
+  }
+
+  // Add feedback summary columns to photos table
+  if (!hasFeedbackCountColumn) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.integer('feedback_count').defaultTo(0);
+      table.integer('like_count').defaultTo(0);
+      table.decimal('average_rating', 3, 2).defaultTo(0);
+      table.integer('favorite_count').defaultTo(0);
+    });
+  }
+
+  // Add feedback notification settings to app_settings
+  const hasFeedbackNotificationEmail = await knex('app_settings')
+    .where('setting_key', 'feedback_notification_email')
+    .first();
+    
+  if (!hasFeedbackNotificationEmail) {
+    await knex('app_settings').insert([
+      {
+        setting_key: 'feedback_notification_email',
+        setting_value: JSON.stringify(''),
+        setting_type: 'feedback'
+      },
+      {
+        setting_key: 'feedback_rate_limits',
+        setting_value: JSON.stringify({
+          rating: { max: 100, window: 3600 }, // 100 ratings per hour
+          comment: { max: 20, window: 3600 }, // 20 comments per hour
+          like: { max: 200, window: 3600 } // 200 likes per hour
+        }),
+        setting_type: 'feedback'
+      }
+    ]);
+  }
+  
+  console.log('Gallery feedback tables created successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing gallery feedback tables...');
+  
+  // Remove feedback settings from app_settings
+  await knex('app_settings')
+    .whereIn('setting_key', ['feedback_notification_email', 'feedback_rate_limits'])
+    .delete();
+
+  // Remove feedback columns from photos table
+  await knex.schema.alterTable('photos', (table) => {
+    table.dropColumn('feedback_count');
+    table.dropColumn('like_count');
+    table.dropColumn('average_rating');
+    table.dropColumn('favorite_count');
+  });
+
+  // Drop tables in reverse order
+  await knex.schema.dropTableIfExists('feedback_word_filters');
+  await knex.schema.dropTableIfExists('feedback_rate_limits');
+  await knex.schema.dropTableIfExists('photo_feedback');
+  await knex.schema.dropTableIfExists('event_feedback_settings');
+  
+  console.log('Gallery feedback tables removed');
+};

backend/migrations/core/034_add_version_to_backups.js

@@ -1,4 +1,4 @@
-const { db } = require('../src/database/db');
+const { db } = require('../../src/database/db');
 
 async function up() {
   console.log('Adding version tracking to backup tables...');

backend/migrations/core/035_enhance_backup_system.js

@@ -1,4 +1,4 @@
-const { db } = require('../src/database/db');
+const { db } = require('../../src/database/db');
 
 async function up() {
   console.log('Enhancing backup system...');

backend/migrations/core/036_fix_missing_columns.js

@@ -0,0 +1,87 @@
+// Fix missing columns identified in GitHub issues
+
+exports.up = async function(knex) {
+  console.log('Adding missing columns to database tables...');
+  
+  // Add must_change_password column to admin_users table
+  const hasMustChangePassword = await knex.schema.hasColumn('admin_users', 'must_change_password');
+  if (!hasMustChangePassword) {
+    console.log('Adding must_change_password column to admin_users table...');
+    await knex.schema.table('admin_users', (table) => {
+      table.boolean('must_change_password').defaultTo(false);
+    });
+  }
+  
+  // Add password_changed_at column to admin_users table
+  const hasPasswordChangedAt = await knex.schema.hasColumn('admin_users', 'password_changed_at');
+  if (!hasPasswordChangedAt) {
+    console.log('Adding password_changed_at column to admin_users table...');
+    await knex.schema.table('admin_users', (table) => {
+      table.datetime('password_changed_at');
+    });
+  }
+  
+  // Add require_moderation column to event_feedback_settings table
+  const hasEventFeedbackSettings = await knex.schema.hasTable('event_feedback_settings');
+  if (hasEventFeedbackSettings) {
+    const hasRequireModeration = await knex.schema.hasColumn('event_feedback_settings', 'require_moderation');
+    if (!hasRequireModeration) {
+      console.log('Adding require_moderation column to event_feedback_settings table...');
+      await knex.schema.table('event_feedback_settings', (table) => {
+        table.boolean('require_moderation').defaultTo(true);
+      });
+    }
+  }
+  
+  // Add host_name column to events table if missing
+  const hasHostName = await knex.schema.hasColumn('events', 'host_name');
+  if (!hasHostName) {
+    console.log('Adding host_name column to events table...');
+    await knex.schema.table('events', (table) => {
+      table.string('host_name');
+    });
+  }
+  
+  console.log('Missing columns have been added successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing added columns...');
+  
+  // Remove must_change_password column from admin_users table
+  const hasMustChangePassword = await knex.schema.hasColumn('admin_users', 'must_change_password');
+  if (hasMustChangePassword) {
+    await knex.schema.table('admin_users', (table) => {
+      table.dropColumn('must_change_password');
+    });
+  }
+  
+  // Remove password_changed_at column from admin_users table
+  const hasPasswordChangedAt = await knex.schema.hasColumn('admin_users', 'password_changed_at');
+  if (hasPasswordChangedAt) {
+    await knex.schema.table('admin_users', (table) => {
+      table.dropColumn('password_changed_at');
+    });
+  }
+  
+  // Remove require_moderation column from event_feedback_settings table
+  const hasEventFeedbackSettings = await knex.schema.hasTable('event_feedback_settings');
+  if (hasEventFeedbackSettings) {
+    const hasRequireModeration = await knex.schema.hasColumn('event_feedback_settings', 'require_moderation');
+    if (hasRequireModeration) {
+      await knex.schema.table('event_feedback_settings', (table) => {
+        table.dropColumn('require_moderation');
+      });
+    }
+  }
+  
+  // Remove host_name column from events table
+  const hasHostName = await knex.schema.hasColumn('events', 'host_name');
+  if (hasHostName) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('host_name');
+    });
+  }
+  
+  console.log('Columns removed');
+};

backend/migrations/core/037_add_download_controls.js

@@ -0,0 +1,69 @@
+// Add download control features to events table
+
+exports.up = async function(knex) {
+  console.log('Adding download control columns to events table...');
+  
+  // Add download control columns to events table
+  const hasAllowDownloads = await knex.schema.hasColumn('events', 'allow_downloads');
+  if (!hasAllowDownloads) {
+    await knex.schema.table('events', (table) => {
+      table.boolean('allow_downloads').defaultTo(true);
+      table.boolean('disable_right_click').defaultTo(false);
+      table.boolean('watermark_downloads').defaultTo(false);
+      table.text('watermark_text');
+    });
+  }
+  
+  // Add download control settings to app_settings
+  const downloadSettingExists = await knex('app_settings')
+    .where('setting_key', 'default_allow_downloads')
+    .first();
+    
+  if (!downloadSettingExists) {
+    await knex('app_settings').insert([
+      {
+        setting_key: 'default_allow_downloads',
+        setting_value: JSON.stringify(true),
+        setting_type: 'gallery'
+      },
+      {
+        setting_key: 'default_disable_right_click',
+        setting_value: JSON.stringify(false),
+        setting_type: 'gallery'
+      },
+      {
+        setting_key: 'default_watermark_downloads',
+        setting_value: JSON.stringify(false),
+        setting_type: 'gallery'
+      }
+    ]);
+  }
+  
+  console.log('Download control features added successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing download control columns...');
+  
+  // Remove app settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'default_allow_downloads',
+      'default_disable_right_click', 
+      'default_watermark_downloads'
+    ])
+    .delete();
+  
+  // Remove columns from events table
+  const hasAllowDownloads = await knex.schema.hasColumn('events', 'allow_downloads');
+  if (hasAllowDownloads) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('allow_downloads');
+      table.dropColumn('disable_right_click');
+      table.dropColumn('watermark_downloads');
+      table.dropColumn('watermark_text');
+    });
+  }
+  
+  console.log('Download control columns removed');
+};

backend/migrations/core/038_add_enhanced_image_protection.js

@@ -0,0 +1,128 @@
+// Add enhanced image protection features
+
+exports.up = async function(knex) {
+  console.log('Adding enhanced image protection features...');
+  
+  // Add protection columns to events table
+  const hasProtectionLevel = await knex.schema.hasColumn('events', 'protection_level');
+  if (!hasProtectionLevel) {
+    await knex.schema.table('events', (table) => {
+      table.enum('protection_level', ['basic', 'standard', 'enhanced', 'maximum']).defaultTo('standard');
+      table.integer('image_quality').defaultTo(85);
+      table.boolean('add_fingerprint').defaultTo(true);
+      table.boolean('enable_devtools_protection').defaultTo(true);
+      table.boolean('use_canvas_rendering').defaultTo(false);
+      table.integer('fragmentation_level').defaultTo(3);
+      table.boolean('overlay_protection').defaultTo(true);
+    });
+  }
+  
+  // Create image access logs table
+  const hasImageAccessLogs = await knex.schema.hasTable('image_access_logs');
+  if (!hasImageAccessLogs) {
+    await knex.schema.createTable('image_access_logs', (table) => {
+      table.increments('id').primary();
+      table.integer('photo_id').unsigned().notNullable();
+      table.integer('event_id').unsigned().notNullable();
+      table.string('client_ip', 45).notNullable();
+      table.text('user_agent');
+      table.string('access_type', 20).defaultTo('view'); // view, download, suspicious
+      table.string('client_fingerprint', 32).notNullable();
+      table.timestamp('accessed_at').defaultTo(knex.fn.now());
+      table.json('metadata'); // Additional security metadata
+      
+      table.foreign('photo_id').references('id').inTable('photos').onDelete('CASCADE');
+      table.foreign('event_id').references('id').inTable('events').onDelete('CASCADE');
+      
+      table.index(['photo_id', 'accessed_at']);
+      table.index(['client_fingerprint', 'accessed_at']);
+      table.index(['client_ip', 'accessed_at']);
+    });
+  }
+  
+  // Add protection settings to app_settings
+  const protectionSettingExists = await knex('app_settings')
+    .where('setting_key', 'default_protection_level')
+    .first();
+    
+  if (!protectionSettingExists) {
+    await knex('app_settings').insert([
+      {
+        setting_key: 'default_protection_level',
+        setting_value: JSON.stringify('standard'),
+        setting_type: 'security'
+      },
+      {
+        setting_key: 'default_image_quality',
+        setting_value: JSON.stringify(85),
+        setting_type: 'security'
+      },
+      {
+        setting_key: 'enable_devtools_protection',
+        setting_value: JSON.stringify(true),
+        setting_type: 'security'
+      },
+      {
+        setting_key: 'max_image_requests_per_minute',
+        setting_value: JSON.stringify(30),
+        setting_type: 'security'
+      },
+      {
+        setting_key: 'suspicious_activity_threshold',
+        setting_value: JSON.stringify(10),
+        setting_type: 'security'
+      },
+      {
+        setting_key: 'enable_canvas_rendering',
+        setting_value: JSON.stringify(false),
+        setting_type: 'security'
+      },
+      {
+        setting_key: 'default_fragmentation_level',
+        setting_value: JSON.stringify(3),
+        setting_type: 'security'
+      }
+    ]);
+  }
+  
+  console.log('Enhanced image protection features added successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing enhanced image protection features...');
+  
+  // Remove app settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'default_protection_level',
+      'default_image_quality',
+      'enable_devtools_protection',
+      'max_image_requests_per_minute',
+      'suspicious_activity_threshold',
+      'enable_canvas_rendering',
+      'default_fragmentation_level'
+    ])
+    .delete();
+  
+  // Drop image access logs table
+  const hasImageAccessLogs = await knex.schema.hasTable('image_access_logs');
+  if (hasImageAccessLogs) {
+    await knex.schema.dropTable('image_access_logs');
+  }
+  
+  // Remove protection columns from events table
+  const hasProtectionLevel = await knex.schema.hasColumn('events', 'protection_level');
+  if (hasProtectionLevel) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('protection_level');
+      table.dropColumn('image_quality');
+      table.dropColumn('add_fingerprint');
+      table.dropColumn('enable_devtools_protection');
+      table.dropColumn('use_canvas_rendering');
+      table.dropColumn('fragmentation_level');
+      table.dropColumn('overlay_protection');
+    });
+  }
+  
+  console.log('Enhanced image protection features removed');
+};

backend/migrations/core/039_add_security_logging.js

@@ -0,0 +1,117 @@
+// Add security logging and monitoring tables
+
+exports.up = async function(knex) {
+  console.log('Adding security logging and monitoring tables...');
+  
+  // Create security logs table for general security events
+  const hasSecurityLogs = await knex.schema.hasTable('security_logs');
+  if (!hasSecurityLogs) {
+    await knex.schema.createTable('security_logs', (table) => {
+      table.increments('id').primary();
+      table.string('event_type', 50).notNullable(); // rate_limit_exceeded, suspicious_activity, etc.
+      table.string('client_ip', 45).notNullable();
+      table.string('client_fingerprint', 32);
+      table.text('user_agent');
+      table.string('request_path');
+      table.string('request_method', 10);
+      table.json('details'); // Additional event details
+      table.timestamp('timestamp').defaultTo(knex.fn.now());
+      
+      // Indexes for performance
+      table.index(['event_type', 'timestamp']);
+      table.index(['client_ip', 'timestamp']);
+      table.index(['client_fingerprint', 'timestamp']);
+    });
+  }
+  
+  // Add security monitoring settings to app_settings
+  const securitySettings = [
+    {
+      setting_key: 'security_monitoring_enabled',
+      setting_value: JSON.stringify(true),
+      setting_type: 'security'
+    },
+    {
+      setting_key: 'max_image_requests_per_5_minutes',
+      setting_value: JSON.stringify(100),
+      setting_type: 'security'
+    },
+    {
+      setting_key: 'max_image_requests_per_hour',
+      setting_value: JSON.stringify(500),
+      setting_type: 'security'
+    },
+    {
+      setting_key: 'block_suspicious_ips',
+      setting_value: JSON.stringify(true),
+      setting_type: 'security'
+    },
+    {
+      setting_key: 'log_security_events_to_db',
+      setting_value: JSON.stringify(true),
+      setting_type: 'security'
+    },
+    {
+      setting_key: 'auto_block_threshold',
+      setting_value: JSON.stringify(5),
+      setting_type: 'security'
+    }
+  ];
+
+  for (const setting of securitySettings) {
+    const exists = await knex('app_settings')
+      .where('setting_key', setting.setting_key)
+      .first();
+      
+    if (!exists) {
+      await knex('app_settings').insert(setting);
+    }
+  }
+  
+  // Add mime_type column to photos table if it doesn't exist
+  const hasMimeType = await knex.schema.hasColumn('photos', 'mime_type');
+  if (!hasMimeType) {
+    await knex.schema.table('photos', (table) => {
+      table.string('mime_type', 100);
+    });
+    
+    // Update existing photos with default mime type
+    await knex('photos')
+      .whereNull('mime_type')
+      .update({ mime_type: 'image/jpeg' });
+  }
+  
+  console.log('Security logging and monitoring tables added successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Removing security logging and monitoring tables...');
+  
+  // Remove security settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'security_monitoring_enabled',
+      'max_image_requests_per_5_minutes', 
+      'max_image_requests_per_hour',
+      'block_suspicious_ips',
+      'log_security_events_to_db',
+      'auto_block_threshold'
+    ])
+    .delete();
+  
+  // Drop security logs table
+  const hasSecurityLogs = await knex.schema.hasTable('security_logs');
+  if (hasSecurityLogs) {
+    await knex.schema.dropTable('security_logs');
+  }
+  
+  // Remove mime_type column from photos table
+  const hasMimeType = await knex.schema.hasColumn('photos', 'mime_type');
+  if (hasMimeType) {
+    await knex.schema.table('photos', (table) => {
+      table.dropColumn('mime_type');
+    });
+  }
+  
+  console.log('Security logging and monitoring tables removed');
+};

backend/migrations/core/040_add_thumbnail_settings.js

@@ -0,0 +1,33 @@
+exports.up = async function(knex) {
+  // Add thumbnail settings to app_settings table
+  const thumbnailSettings = [
+    { setting_key: 'thumbnail_width', setting_value: 300, setting_type: 'number' },
+    { setting_key: 'thumbnail_height', setting_value: 300, setting_type: 'number' },
+    { setting_key: 'thumbnail_fit', setting_value: JSON.stringify('cover'), setting_type: 'string' },
+    { setting_key: 'thumbnail_quality', setting_value: 85, setting_type: 'number' },
+    { setting_key: 'thumbnail_format', setting_value: JSON.stringify('jpeg'), setting_type: 'string' }
+  ];
+
+  for (const setting of thumbnailSettings) {
+    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) {
+  // Remove thumbnail settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'thumbnail_width',
+      'thumbnail_height', 
+      'thumbnail_fit',
+      'thumbnail_quality',
+      'thumbnail_format'
+    ])
+    .del();
+};

backend/migrations/core/041_add_external_media.js

@@ -0,0 +1,54 @@
+/**
+ * Migration 041: Add external media reference support
+ * - events.source_mode: 'managed' | 'reference'
+ * - events.external_path: relative path under external media root
+ * - photos.source_origin: 'managed' | 'external'
+ * - photos.external_relpath: relative path within event.external_path
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 041_add_external_media');
+
+  // events.source_mode (default 'managed')
+  await addColumnIfNotExists(knex, 'events', 'source_mode', (table) => {
+    table.string('source_mode').notNullable().defaultTo('managed');
+  });
+
+  // events.external_path (nullable)
+  await addColumnIfNotExists(knex, 'events', 'external_path', (table) => {
+    table.text('external_path');
+  });
+
+  // photos.source_origin (default 'managed')
+  await addColumnIfNotExists(knex, 'photos', 'source_origin', (table) => {
+    table.string('source_origin').notNullable().defaultTo('managed');
+  });
+
+  // photos.external_relpath (nullable)
+  await addColumnIfNotExists(knex, 'photos', 'external_relpath', (table) => {
+    table.text('external_relpath');
+  });
+
+  // Helpful index for queries
+  try {
+    if (knex.client.config.client === 'pg') {
+      await knex.raw("CREATE INDEX IF NOT EXISTS photos_event_source_idx ON photos (event_id, source_origin)");
+    } else {
+      await knex.schema.alterTable('photos', (table) => {
+        table.index(['event_id', 'source_origin'], 'photos_event_source_idx');
+      });
+    }
+  } catch (e) {
+    console.log('Index creation skipped or failed (may already exist):', e.message);
+  }
+
+  console.log('Migration 041_add_external_media completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 041_add_external_media');
+  // Keep columns (safe rollback not removing data). Intentionally no-op.
+};
+