theme-song-booth/REVIEW.md

REVIEW.md — Theme Song Booth

Quick reference for future work on this project.

One-sentence summary

Flask app that lets convention attendees request custom AI-generated theme songs, lets an operator manage the queue, and emails MP3s after payment.

Stack

• Python 3.12 + Flask
• SQLite (file-based, request-scoped connection via g)
• Gunicorn in Docker
• Portainer stack deployed from GitLab repo
• SMTP (SSL port 465) for customer emails
• Square Terminal/Reader for manual payment
• mutagen for MP3 metadata tagging
• flask-limiter for public form rate limiting
• cryptography to encrypt the stored SMTP password

Repository

• GitLab: https://gitlab.hallsworth.ca/yrtria/theme-song-booth (public)
• Deployed at: https://booth.dionysismedia.ca

Key files and what they hold

File	Notes
app.py	All routes, helpers, email function, status labels, runtime settings, MP3 tagging, rate limiting, DB health, kiosk route, pricing route, sales report, ZIP backup, and the /api/prompt/<id> Hermes callback endpoint.
config.py	Env vars. ADMIN_PASSWORD is plain text. HERMES_API_KEY can be overridden at runtime.
models.py	SQLite schema + CRUD. player_token is a secret URL-safe token. revision_history table tracks each customer revision.
init_db.py	Run once after deploy: python init_db.py.
templates/admin/request.html	Biggest template. Customer info editing, revision history, operator notes, Suno prompt fields, upload/delivery, cancel request button.
templates/admin/dashboard.html	Queue table + filters + auto-refresh + topbar links to Kiosk, Pricing, Sales, Settings.
templates/admin/settings.html	SMTP config, MP3 metadata defaults, DB backup/restore/health, reset, kiosk mode, Hermes API key display.
templates/admin/pricing.html	Fixed and custom pricing configuration.
templates/admin/sales.html	Sales report of delivered requests.
templates/faq.html	Customer FAQ page.
templates/status.html	Customer order status lookup.
templates/closed.html	Message shown on /request when the booth is marked closed.
templates/kiosk.html	Public full-screen display: open/closed banner, QR code, price list, auto-refresh.
docker-compose.yml	No env_file; variables come from Portainer.

Status meanings

pending → prompt_ready → songs_uploaded → awaiting_payment → paid → delivered

Branch states:

• revisions_requested — customer asked for changes; current files are archived and a note is logged.
• cancelled — operator cancelled the request.

Operator workflow

1. Customer fills /request.
2. Open /admin, click request row (or filter by status).
3. On /admin/request/<id>, fix customer info if needed, then click Copy customer info for Hermes, paste result to Hermes.
4. Hermes POSTs Title/Style/Lyrics back to the signed callback URL; the request becomes Prompt Ready.
5. If the callback fails, paste Hermes' response into the Title/Style/Lyrics fields and click Save Prompt.
6. Copy Lyrics, Style, Title into Suno Custom Mode in that order, generate two versions.
7. Upload Version A and B MP3s.
8. Click Send Preview Link.
9. Customer receives email, visits player, picks version.
10. Operator collects Square payment, enters reference, clicks Mark Paid & Deliver.
11. Customer receives MP3 attachment(s) by email.

Environment variables that matter

APP_SECRET_KEY
ADMIN_PASSWORD
SMTP_PASS
PUBLIC_BASE_URL
BOOTH_NAME
HOST_PORT
INTERNAL_PORT
MAX_REVISIONS
HERMES_API_KEY

Most can be overridden at runtime from /admin/settings and stored in booth_settings.json.

Runtime settings stored in booth_settings.json

• SMTP host/port/user/from and encrypted password
• Dashboard auto-refresh interval
• Max revisions allowed per customer
• Booth open/closed state
• Default MP3 metadata tags (artist, album, year, comment)
• Hermes API key
• Pricing: fixed items (One Song, Both Songs, WAV per song, STEMs per song) and up to 5 custom named items
• Kiosk cycle mode (QR only, pricing only, or N seconds per slide)

These survive redeploys because booth_settings.json lives in the persistent uploads volume.

Gotchas

• Multiple forms on admin/request.html must stay properly closed; nested forms break buttons.
• upload_songs form needs enctype="multipart/form-data" and a matching </form>.
• The dashboard uses basename() as a function, not a Jinja filter.
• Reset System deletes DB rows and all files under UPLOAD_FOLDER, then resets sqlite_sequence.
• Runtime settings are stored in the persistent uploads volume (booth_settings.json).
• The booth_open setting controls whether /request and /kiosk show the open banner or the closed banner.
• Container cannot read host paths; all static assets used at runtime (logo, banners, QR code) must be in static/ or a mounted volume.
• The Hermes callback URL is signed with APP_SECRET_KEY and expires after 1 hour.
• If you regenerate the Hermes API key, update the Hermes skill/config immediately; old key requests will 401.
• New columns/tables are added via models.py. Use /admin/settings → Fix Database Schema after redeploying a schema change.

How to redeploy

1. Push changes to GitLab main.
2. In Portainer: Stacks → theme-song-booth → Pull and redeploy.
3. If schema changed, open container console and run python init_db.py, or use /admin/settings → Fix Database Schema.

Recent major additions

• Cancelled status — operators can mark any request as cancelled from the top of /admin/request/<id>.
• Revision history log — each customer revision is recorded with revision count, note, and archived file names.
• Stems / Extras link — operators paste a file-share link on the request page; customers see a download button after delivery.
• Sales report — /admin/sales lists all delivered requests with payment references.
• Pricing page — /admin/pricing configures fixed prices plus up to 5 custom items; used by /kiosk.
• Public kiosk — /kiosk is a full-screen tablet display with QR code and price list cycling.
• Music ZIP backup — /admin/settings can download all uploaded MP3s as a ZIP.
• Database schema repair — health check detects missing columns and tables and can repair them.

Static assets to keep in the repo

• static/Trollgorithm_booth.jpg — open banner (request page and kiosk)
• static/Booth_closed.png — closed banner
• static/DM-Logo_email.png — email signature logo
• static/qr-code.png — kiosk QR code pointing to /request