From 93476ac72ab2c866712df30b9374dc929fd0af28 Mon Sep 17 00:00:00 2001 From: Michilis Date: Sun, 26 Jul 2026 05:57:30 +0000 Subject: [PATCH] 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 --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index f768805..ce5feda 100644 --- a/README.md +++ b/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) -- **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.