IHNYC RC Gallery Worker

• Service Name: ihnyc-rc-gallery
• Live Site: https://moments.ihnyc-rc.org
• Repository: https://github.com/dghauri0/ihnyc-rc-gallery.git

🧭 Overview

• Cloudflare Worker serving public gallery and admin UI from single entrypoint
• Stores media in R2 and metadata/indexes in Workers KV
• Uses Cloudflare Image Resizing for derived variants
• Scheduled repair jobs run every 30 minutes
• Admin routes protected via Cloudflare Access

Sources: ihnyc-rc-gallery/wrangler.toml, ihnyc-rc-gallery/src/index.ts, ihnyc-rc-gallery/README.md

👥 Key User Flows

Public Gallery

• Browse published media at /gallery
• View permalinks at /gallery/:id
• List published items via /api/gallery
• Fetch media with on-the-fly resizing at /media/*

Admin Media Management

• Upload originals and thumbs via /api/admin/media
• List all media (published and unpublished)
• Update KV indexes automatically
• Run orphan cleanup jobs

Media Delivery

• Serve originals or resized variants from R2
• Cloudflare Image Resizing generates variants on-demand
• Requires PUBLIC_MEDIA_BASE_URL for resizing fetches

Sources: ihnyc-rc-gallery/src/index.ts, ihnyc-rc-gallery/README.md

🔗 Key Routes and Endpoints

🖼️ Media variants and parameters

• variant=original (default): raw bytes
• variant=thumb: resized, default width ~480
• variant=display: resized, default width ~1600
• Optional query params:
  • w=<number>: custom max width (clamped 16–4096)
  • format=webp|jpeg|png: output format override

🔐 Admin upload constraints

• Max file size: 10MB
• Accepted types: JPEG, PNG, WebP
• Upload field name: files (multipart)

🗄️ Data and Storage

Sources: ihnyc-rc-gallery/wrangler.toml, ihnyc-rc-gallery/src/index.ts

Data Flow Diagram (Mermaid)

flowchart LR
  subgraph Users
    U_RES["USER: Visitor"]
    U_ADMIN["USER: Admin"]
  end

  subgraph Services
    S_GALLERY["SVC: ihnyc-rc-gallery"]
  end

  subgraph Storage
    STORE_R2["STORE: R2 (GALLERY_MEDIA)"]
    STORE_KV["STORE: KV (GALLERY_META)"]
  end

  subgraph External_Systems
    EXT_IMG["EXT: Cloudflare Image Resizing"]
  end

  U_RES -->|browse| S_GALLERY
  U_ADMIN -->|manage media| S_GALLERY

  S_GALLERY -->|store originals/thumbs| STORE_R2
  S_GALLERY -->|index metadata| STORE_KV
  S_GALLERY -->|resize variants| EXT_IMG

Sources: ihnyc-rc-gallery/wrangler.toml, ihnyc-rc-gallery/src/index.ts

🔄 Automations and Integrations

Image Resizing

• Cloudflare Image Resizing: On-demand variant generation via cf.image
• Requires PUBLIC_MEDIA_BASE_URL configured

Scheduled Jobs

• Orphan Repair: Runs every 30 minutes
• Cleans up dangling KV entries with missing R2 objects

Access Protection

• Admin routes are not protected in code; enforce Cloudflare Access at the edge
• Configure Access for /admin/* and /api/admin/*

Sources: ihnyc-rc-gallery/src/index.ts, ihnyc-rc-gallery/README.md, ihnyc-rc-gallery/wrangler.toml

📚 Detailed Guides

• architecture: Worker layout and routing
• data: KV + R2 data model and indexes
• api: Public and admin API reference
• media-pipeline: Uploads, thumbnails, variants
• ops: Runbooks and operational notes

🗺️ Service Flow Diagram

Gallery service architecture and integrations

flowchart LR
  subgraph Users
    U_RES["USER: Visitor"]
    U_ADMIN["USER: Admin"]
  end

  subgraph Services
    S_GALLERY["SVC: ihnyc-rc-gallery"]
  end

  subgraph External_Systems
    EXT_IMG["EXT: Cloudflare Image Resizing"]
  end

  subgraph Storage
    STORE_R2["STORE: R2"]
    STORE_KV["STORE: KV"]
  end

  U_RES -->|view| S_GALLERY
  U_ADMIN -->|admin| S_GALLERY

  S_GALLERY -->|media| STORE_R2
  S_GALLERY -->|metadata| STORE_KV
  S_GALLERY -->|resize| EXT_IMG

Sources: ihnyc-rc-gallery/wrangler.toml, ihnyc-rc-gallery/src/index.ts

🛠️ Common Ops

Local Development

npm run dev

Deployment

npm run deploy

Create R2 Bucket

wrangler r2 bucket create <bucket-name>

Create KV Namespace

wrangler kv:namespace create GALLERY_META

Sources: ihnyc-rc-gallery/README.md

🔐 Environment Variables

Sources: ihnyc-rc-gallery/wrangler.toml, ihnyc-rc-gallery/src/index.ts

❓ Open Questions

Production Configuration

• Are /admin* and /api/admin* protected by Cloudflare Access in production?

Sources: ihnyc-rc-gallery/README.md

🎨 UI/UX Features

Gallery Interface (2026-01-16 Update)

Skeleton Loading States

• Animated placeholder cards during initial load
• 8 skeleton cards with shimmer animation
• Respects prefers-reduced-motion accessibility setting
• Improves perceived performance and user engagement

Enhanced Lightbox Experience

• Rich metadata overlay showing event date, tags, and dimensions
• Glass-morphism styled badge design for metadata tags
• Emoji-prefixed information for quick visual scanning
• Progressive image quality upgrade on zoom

Tag Filter UX

• Gradient fade indicators on scroll edges
• Visual cues for discoverability of overflow content
• Smooth scrollbar styling (webkit/firefox)
• Dynamic visibility based on scroll position

Custom Form Controls

• Replaced system-default dropdowns with custom-styled selects
• Inline SVG chevron icons matching design language
• Consistent styling across all interactive elements
• Smooth hover transitions with primary color accents

Mobile Responsiveness

• Responsive grid gaps (12px→16px→20px→24px across breakpoints)
• Touch target optimization (44px+ buttons/selects, 36px+ chips)
• Meets WCAG 2.1 Level AAA touch target requirements
• Enhanced mobile viewport handling (48px touch targets <480px)

Accessibility Enhancements

• Skip-to-content link for keyboard navigation
• Enhanced focus indicators (3px solid outline)
• Proper ARIA labels on all interactive controls
• aria-pressed states on filter buttons
• Region landmarks for screen reader navigation

Sources: ihnyc-rc-gallery/src/templates/gallery.ts, ihnyc-rc-gallery/src/templates/layout.ts

🔗 Related

• system-overview
• api-contracts
• security-model
• ihnyc-rc-landing
• ihnyc-rc-cal-landing
• ihnyc-rc-vote