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, 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.
init_db.py	Run once after deploy: python init_db.py.
templates/admin/request.html	Biggest template; prompt copy helpers and JS live here. Customer email and operator notes are editable here.
templates/admin/dashboard.html	Queue table + filters + auto-refresh + topbar Reset System button.
templates/admin/settings.html	SMTP config, MP3 metadata defaults, DB backup/restore, health check, reset, and Hermes API key management.
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.
docker-compose.yml	No env_file; variables come from Portainer.

Status meanings

pending → prompt_ready → songs_uploaded → awaiting_payment → paid → delivered

revisions_requested is a branch used when the customer asks for changes.

Operator workflow

1. Customer fills /request.
2. Open /admin, click request row (or filter by status).
3. On /admin/request/<id>, fix the customer's email 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 Style/Lyrics into Suno Custom Mode, 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.

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 shows the form or the closed banner.
• Container cannot read host paths; all static assets used at runtime (logo, banner, favicons, closed banner) must be in the repo 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.

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 Missing Columns.