Files

T

paul 6c82958c79 Add complete frontend implementation and Docker deployment setup

- Implement React frontend with TypeScript and Tailwind CSS
- Add scrappbook.de-inspired UI design with photo galleries
- Implement authentication, photo viewing, and download features
- Add Docker Swarm configuration with Traefik reverse proxy
- Set up Drone CI/CD pipeline for automated deployments
- Add monitoring stack with Prometheus and Grafana
- Create comprehensive deployment documentation
- Add simple local development setup with docker-compose.local.yml

Features:
- Password-protected galleries with expiration warnings
- Responsive photo grid with lightbox viewer
- Bulk download functionality
- Hot reload development environment
- Email testing with Mailhog
- Production-ready deployment scripts

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-07-06 20:23:13 +02:00

5.5 KiB

Raw Blame History

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

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

cd backend
npm test -- path/to/test.test.js
npm test -- --testNamePattern="test name"

Production

docker-compose -f docker-compose.prod.yml up -d  # Production deployment
pm2 start ecosystem.config.js                     # Alternative: PM2 deployment

Key Product Requirements (from PRD)

Core Features

File-Based System: Drop photos in folders → automatic gallery creation
Automatic Expiration: Default 30 days, with 7-day warning emails
Password Protection: Secure access with customizable passwords
Automatic Archiving: ZIP compression and storage after expiration
Email Notifications: Creation, warning, and expiration notifications
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

Landing Page: Password entry with event preview
Gallery View:
- Responsive photo grid with lazy loading
- Toggle between collages/individual photos
- Prominent expiration banner
- Download urgency indicators
Photo Lightbox: Full-screen viewing with zoom
Mobile-First: Responsive design with touch gestures
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

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

Security: All gallery access requires valid JWT with event-specific claims
Expiration: Events auto-expire based on expires_at, with 7-day email warnings
Email Queue: Async processing with retry logic, check email_queue table
File Processing: Sharp library for thumbnail generation (300x300)
Frontend Status: Only skeleton exists - requires full implementation based on PRD
Umami Analytics: Track password entries, downloads, views, expiration warnings

Environment Variables

Required in .env:

JWT_SECRET - Token signing
ADMIN_URL, FRONTEND_URL - CORS origins
SMTP_* - Email configuration
DB_* - PostgreSQL credentials (production)
UMAMI_* - Analytics configuration

Testing Approach

Jest with Supertest for API testing
Test files in __tests__ directories
Database migrations run before tests
Mock email sending in tests

Success Metrics (from PRD)

Time to generate gallery: <2 minutes
Guest satisfaction: >90%
System uptime: 99.9%
Email delivery rate: >98%
Successful archiving: 100%

5.5 KiB Raw Blame History