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>

README.md

@@ -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)
+- **Public site**: events, booking, contact, community, **photo galleries**, legal pages, bilingual (EN/ES)
-- **User dashboard**: profile, tickets, payments, sessions/security
+  - Stable `/next` and `/featured` URLs that redirect to the current event
-- **Admin** (`/admin`): events, tickets/check-in, users/roles, payments, email templates, media uploads
+  - 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 dev             # backend + frontend + photo-api
-npm run build
+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:export       # Backup database
-npm run db:import   # Restore from backup
+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`
+- **systemd**: `deploy/spanglish-backend.service`, `deploy/spanglish-frontend.service`, `deploy/spanglish-photos.service`
-  - Backend runs on **3018**, frontend on **3019** by default (see the unit files)
+  - 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/spanglish_upstreams.conf` defines upstreams for ports 3018/3019/3020
-  - `deploy/front-end_nginx.conf` proxies `/api` and `/uploads` to the backend and everything else to the frontend
+  - `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.