Document photo galleries, payment providers, and updated deploy topology in README

Cover features added since the last README update: the standalone photo-api Go service, the central payment provider registry (Lightning + manual TPago/bank/card/cash), stable /next and /featured URLs, dashboard overview, and the three-service dev/deploy setup (photo-api on 3003 dev / 3020 prod). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a thumbnail filmstrip to the photo lightbox.
2026-07-26 05:57:30 +00:00 · 2026-07-26 05:53:37 +00:00
4 changed files with 148 additions and 58 deletions
@@ -4,17 +4,24 @@ A full-stack web app for organizing and managing language exchange events (Asunc

 ## Features

- **Public site**: events, booking, contact, community, legal pages, bilingual (EN/ES)
- **User dashboard**: profile, tickets, payments, sessions/security
- **Admin** (`/admin`): events, tickets/check-in, users/roles, payments, email templates, media uploads
+- **Public site**: events, booking, contact, community, **photo galleries**, legal pages, bilingual (EN/ES)
+  - Stable `/next` and `/featured` URLs that redirect to the current event
+  - Human-readable event URL slugs (with legacy-ID redirect support)
+- **User dashboard**: overview tab, profile, tickets, payments, sessions/security
+  - Lightning invoice reuse and re-payment straight from the dashboard
+- **Admin** (`/admin`): events, tickets/check-in, users/roles, payments, email templates, media uploads, **photo galleries**
+  - One unified ticket-creation modal with first-class payment status
+- **Payments**: one automatic provider (**Lightning** via LNbits) plus manual providers (**TPago link**, bank transfer, card, cash), all defined in a central provider registry. Manual payments stay pending until an admin reconciles them (they are not auto-failed after the pending TTL).
+- **Photo galleries** (standalone `photo-api` Go service): admins upload event photos, group them into galleries, and share them by visibility mode (public / private / share-link / ticket-holders). See [`photo-api/`](photo-api/README.md).
 - **API**: Swagger UI at `/api-docs`, OpenAPI JSON at `/openapi.json`, health check at `/health`

 ## Tech stack

 - **Backend**: Node.js + TypeScript, Hono, Drizzle ORM, SQLite (default) or PostgreSQL
+- **Photo service**: standalone Go module (`photo-api/`), its own binary/deploy unit, sharing the backend database and `JWT_SECRET`
 - **Auth**: JWT (via `jose`), **Argon2id** password hashing (with legacy bcrypt verification for older hashes)
 - **Email**: `nodemailer` (SMTP) with optional provider config
- **Frontend**: Next.js 14 (App Router), Tailwind CSS, Heroicons
+- **Frontend**: Next.js (App Router), Tailwind CSS, Heroicons, skeleton loading states, custom error / global-error pages

 ## Local development

@@ -22,6 +29,8 @@ A full-stack web app for organizing and managing language exchange events (Asunc

 - Node.js 18+
 - npm
+- Go 1.26+ (for the `photo-api` service)
+- Optional: `libvips-tools` (or `libheif-examples`) on the host to accept HEIC photo uploads

 ### Setup

@@ -29,12 +38,14 @@ A full-stack web app for organizing and managing language exchange events (Asunc
 npm install
 cp backend/.env.example backend/.env
 cp frontend/.env.example frontend/.env
+cp photo-api/.env.example photo-api/.env   # set JWT_SECRET + DATABASE_URL to match backend/.env
 ```

 ### Initialize database (SQLite by default)

 ```bash
-npm run db:migrate
+npm run db:migrate      # backend (Drizzle) tables
+npm run migrate:photos  # photo-api owns only the photos_* tables via its own migrations
 ```

 ### Run
@@ -43,10 +54,13 @@ npm run db:migrate
 npm run dev
 ```

+`npm run dev` starts the backend, frontend, and photo-api together (via `concurrently`).
+
 Default URLs:

 - Frontend: `http://localhost:3002`
 - Backend API: `http://localhost:3001`
+- Photo API: `http://localhost:3003` (the Next dev server rewrites `/api/photos/*` to it)
 - API docs: `http://localhost:3001/api-docs`

 ### First user becomes admin
@@ -58,14 +72,20 @@ The first user to register becomes the **admin**. Register at `/register`.
 Run these from the repo root:

 ```bash
-npm run dev
-npm run build
+npm run dev             # backend + frontend + photo-api
+npm run build           # build all workspaces
 npm run start
 npm run db:generate
 npm run db:migrate
 npm run db:studio
-npm run db:export   # Backup database
-npm run db:import   # Restore from backup
+npm run db:export       # Backup database
+npm run db:import       # Restore from backup
+
+# Photo service (Go)
+npm run dev:photos      # go run ./cmd/photo-api
+npm run build:photos    # go build -o bin/photo-api
+npm run migrate:photos  # apply photos_* migrations
+npm run test:photos     # go test ./...
 ```

 You can also run per workspace:
@@ -85,9 +105,19 @@ Key settings (see `backend/.env.example` for the full list):
 - **Auth**: `JWT_SECRET` (change in production)
 - **URLs/ports**: `PORT`, `API_URL`, `FRONTEND_URL`
 - **Email**: `EMAIL_PROVIDER` (`console|smtp|resend`) and corresponding credentials
- **Payments (optional)**: Stripe/MercadoPago/LNbits configuration
+- **Payments (optional)**: LNbits (Lightning) configuration for the automatic provider. Manual providers (TPago link, bank transfer, card, cash) need no API keys — the TPago pay link is configured and sent via an email template.
 - **Scaling (optional)**: `REDIS_URL`, `DB_POOL_MAX`, and `S3_*` (see "Horizontal scaling" below)

+### Photo service (`photo-api/.env`)
+
+Key settings (see `photo-api/.env.example`):
+
+- **Port**: `PORT=3003` (dev)
+- **DB**: `DB_TYPE` and `DATABASE_URL` — point at the **same** database as the backend
+- **Auth**: `JWT_SECRET` — must match `backend/.env` (the service validates the backend's JWTs)
+- **Storage**: `STORAGE_PATH` (local disk) or `S3_ENDPOINT` + `S3_BUCKET` (S3/Garage/MinIO); S3 downloads use short-lived presigned URLs
+- **Uploads/worker**: `MAX_UPLOAD_MB`, `WORKER_CONCURRENCY` (a worker generates thumb/preview JPEG variants with EXIF stripped)
+
 ### Frontend (`frontend/.env`)

 Key settings (see `frontend/.env.example`):
@@ -143,12 +173,13 @@ npm run db:import -- --yes ./data/backups/spanglish-2025-03-07.sql   # Skip conf

 This repo includes example configs in `deploy/`:

- **systemd**: `deploy/spanglish-backend.service`, `deploy/spanglish-frontend.service`
-  - Backend runs on **3018**, frontend on **3019** by default (see the unit files)
+- **systemd**: `deploy/spanglish-backend.service`, `deploy/spanglish-frontend.service`, `deploy/spanglish-photos.service`
+  - Backend runs on **3018**, frontend on **3019**, photo-api on **3020** by default (see the unit files)
  - Backend needs write access to `backend/data` and `backend/uploads`
+  - The photo service runs its own migrations on start (`photo-api migrate`) and needs write access to its `STORAGE_PATH` (or S3 config)
 - **nginx**:
-  - `deploy/spanglish_upstreams.conf` defines upstreams for ports 3018/3019
-  - `deploy/front-end_nginx.conf` proxies `/api` and `/uploads` to the backend and everything else to the frontend
+  - `deploy/spanglish_upstreams.conf` defines upstreams for ports 3018/3019/3020
+  - `deploy/front-end_nginx.conf` proxies `/api/photos` to the photo service, `/api` and `/uploads` to the backend, and everything else to the frontend
  - `deploy/back-end_nginx.conf` is a dedicated API vhost example with CORS handling

 Typical production flow:
@@ -156,7 +187,9 @@ Typical production flow:
 ```bash
 npm ci
 npm run build
+npm run build:photos
 npm run db:migrate
+npm run migrate:photos
 ```

 Then install/enable the systemd services and nginx configs for your server.
@@ -149,6 +149,7 @@ export default function GalleryClient({ slug, eventSlug, initial }: GalleryClien
    previewUrl: p.urls.preview || p.urls.original,
    downloadUrl: p.urls.original,
    filename: p.originalFilename,
+    thumbUrl: p.urls.thumb,
  }));

  const title = es && gallery.titleEs ? gallery.titleEs : gallery.title;
@@ -266,6 +266,7 @@ export default function AdminGalleryDetailPage() {
    previewUrl: p.urls.preview || p.urls.original,
    downloadUrl: p.urls.original,
    filename: p.originalFilename,
+    thumbUrl: p.urls.thumb,
  }));
  const openLightboxFor = (photoId: string) => {
    const idx = readyPhotos.findIndex((p) => p.id === photoId);
@@ -1,6 +1,6 @@
 'use client';

-import { useEffect, useCallback, useState } from 'react';
+import { useEffect, useCallback, useRef, useState } from 'react';
 import {
  XMarkIcon,
  ChevronLeftIcon,
@@ -13,6 +13,8 @@ export interface LightboxItem {
  previewUrl: string;
  downloadUrl: string;
  filename?: string;
+  /** Small thumbnail for the filmstrip; falls back to previewUrl. */
+  thumbUrl?: string;
 }

 interface LightboxProps {
@@ -29,8 +31,10 @@ interface LightboxProps {
 * style of the admin gallery preview modal (fixed inset-0 bg-black/90).
 */
 export default function Lightbox({ items, index, onClose, onNavigate, renderActions }: LightboxProps) {
-  const [touchStartX, setTouchStartX] = useState<number | null>(null);
+  const touchStart = useRef<{ x: number; y: number } | null>(null);
+  const activeThumbRef = useRef<HTMLButtonElement | null>(null);
  const item = items[index];
+  const hasMultiple = items.length > 1;

  const prev = useCallback(() => {
    onNavigate(index > 0 ? index - 1 : items.length - 1);
@@ -53,19 +57,33 @@ export default function Lightbox({ items, index, onClose, onNavigate, renderActi
    };
  }, [onClose, prev, next]);

+  // Keep the active thumbnail centred in the filmstrip as you navigate.
+  useEffect(() => {
+    activeThumbRef.current?.scrollIntoView({
+      behavior: 'smooth',
+      inline: 'center',
+      block: 'nearest',
+    });
+  }, [index]);
+
  if (!item) return null;

  return (
    <div
-      className="fixed inset-0 bg-black/90 z-50 flex items-center justify-center"
+      className="fixed inset-0 bg-black/90 z-50 flex flex-col"
      onClick={onClose}
-      onTouchStart={(e) => setTouchStartX(e.touches[0].clientX)}
+      onTouchStart={(e) => {
+        touchStart.current = { x: e.touches[0].clientX, y: e.touches[0].clientY };
+      }}
      onTouchEnd={(e) => {
-        if (touchStartX === null) return;
-        const dx = e.changedTouches[0].clientX - touchStartX;
-        if (dx > 60) prev();
-        if (dx < -60) next();
-        setTouchStartX(null);
+        if (touchStart.current === null) return;
+        const dx = e.changedTouches[0].clientX - touchStart.current.x;
+        const dy = e.changedTouches[0].clientY - touchStart.current.y;
+        touchStart.current = null;
+        // Only treat as a swipe when it's clearly horizontal.
+        if (Math.abs(dx) < 50 || Math.abs(dx) < Math.abs(dy)) return;
+        if (dx > 0) prev();
+        else next();
      }}
    >
      <button
@@ -91,47 +109,84 @@ export default function Lightbox({ items, index, onClose, onNavigate, renderActi
        {renderActions?.(item, index)}
      </div>

-      {items.length > 1 && (
-        <>
-          <button
-            className="absolute left-2 md:left-4 text-white/80 hover:text-white z-10 p-2"
-            onClick={(e) => {
-              e.stopPropagation();
-              prev();
-            }}
-            aria-label="Previous"
-          >
-            <ChevronLeftIcon className="w-9 h-9" />
-          </button>
-          <button
-            className="absolute right-2 md:right-4 text-white/80 hover:text-white z-10 p-2"
-            onClick={(e) => {
-              e.stopPropagation();
-              next();
-            }}
-            aria-label="Next"
-          >
-            <ChevronRightIcon className="w-9 h-9" />
-          </button>
-        </>
-      )}
+      {/* Main image area */}
+      <div className="relative flex-1 min-h-0 flex items-center justify-center">
+        {hasMultiple && (
+          <>
+            <button
+              className="absolute left-2 md:left-4 top-1/2 -translate-y-1/2 text-white/80 hover:text-white z-10 p-2"
+              onClick={(e) => {
+                e.stopPropagation();
+                prev();
+              }}
+              aria-label="Previous"
+            >
+              <ChevronLeftIcon className="w-9 h-9" />
+            </button>
+            <button
+              className="absolute right-2 md:right-4 top-1/2 -translate-y-1/2 text-white/80 hover:text-white z-10 p-2"
+              onClick={(e) => {
+                e.stopPropagation();
+                next();
+              }}
+              aria-label="Next"
+            >
+              <ChevronRightIcon className="w-9 h-9" />
+            </button>
+          </>
+        )}

-      {/* eslint-disable-next-line @next/next/no-img-element */}
-      <img
-        src={item.previewUrl}
-        alt=""
-        className="max-w-[95vw] max-h-[90vh] object-contain select-none"
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img
+          src={item.previewUrl}
+          alt=""
+          className="max-w-[95vw] max-h-full object-contain select-none"
+          onClick={(e) => e.stopPropagation()}
+          draggable={false}
+        />
+      </div>
+
+      {/* Counter + thumbnail filmstrip you can skip through. */}
+      <div
+        className="shrink-0 pb-3 pt-2"
        onClick={(e) => e.stopPropagation()}
-        draggable={false}
-      />
-
-      <div className="absolute bottom-3 inset-x-0 text-center text-white/70 text-sm">
-        {index + 1} / {items.length}
+        onTouchStart={(e) => e.stopPropagation()}
+        onTouchEnd={(e) => e.stopPropagation()}
+      >
+        <div className="text-center text-white/70 text-sm mb-2">
+          {index + 1} / {items.length}
+        </div>
+        {hasMultiple && (
+          <div className="flex gap-2 overflow-x-auto px-4 pb-1 justify-start sm:justify-center [scrollbar-width:thin]">
+            {items.map((it, i) => (
+              <button
+                key={it.id}
+                ref={i === index ? activeThumbRef : null}
+                onClick={() => onNavigate(i)}
+                aria-label={`Photo ${i + 1}`}
+                aria-current={i === index}
+                className={`relative shrink-0 overflow-hidden rounded transition ${
+                  i === index
+                    ? 'ring-2 ring-white opacity-100'
+                    : 'opacity-50 hover:opacity-90'
+                }`}
+              >
+                {/* eslint-disable-next-line @next/next/no-img-element */}
+                <img
+                  src={it.thumbUrl || it.previewUrl}
+                  alt=""
+                  className="h-14 w-14 sm:h-16 sm:w-16 object-cover"
+                  draggable={false}
+                />
+              </button>
+            ))}
+          </div>
+        )}
      </div>

      {/* Preload neighbours so prev/next feels instant. */}
      <div className="hidden" aria-hidden>
-        {items.length > 1 && (
+        {hasMultiple && (
          <>
            {/* eslint-disable-next-line @next/next/no-img-element */}
            <img src={items[(index + 1) % items.length].previewUrl} alt="" />