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

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.
config.py	Env vars. ADMIN_PASSWORD is plain text.
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 extraction JS lives here.
templates/admin/dashboard.html	Queue table + topbar Reset System button.
docker-compose.yml	No env_file; variables come from Portainer.

Status meanings

pending → prompt_ready → songs_uploaded → awaiting_payment → paid → delivered

Operator workflow

1. Customer fills /request.
2. Open /admin, click request row.
3. Click Copy customer info for Hermes, paste result to Hermes.
4. Paste Hermes response (Title/Style/Lyrics format), click Extract, click Save Prompt.
5. Copy Style/Lyrics into Suno Custom Mode, generate two versions.
6. Upload Version A and B MP3s.
7. Click Send Preview Link.
8. Customer receives email, visits player, picks version.
9. Operator collects Square payment, enters reference, clicks Mark Paid & Deliver.
10. 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

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.

Things that could be improved later

• Move customer info copy/paste to a direct Hermes API/webhook call.
• Add operator email alerts as an opt-in config instead of hard-disabled.
• Store admin password hashed.
• Add a receipt/pricing page for the customer.
• Upload progress indicator for large MP3s.
• Back up SQLite and uploads to S3 or similar before reset.

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.

Last major changes

• Added banner image and styling to request page.
• Moved Reset System button to topbar next to Log out.
• Added file/email status badges on admin request page.
• Added per-request Delete and full-system Reset.
• Switched Hermes prompt workflow to plain-text Title/Style/Lyrics blocks.