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 Gitea 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

• Gitea: 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 7 days.
• 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.
• __pycache__ and local .env files are already ignored by .gitignore; make sure they never get committed.

How to redeploy

1. Push changes to Gitea 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

• Structured style dropdowns — customer form now uses Decade / Basic / Additional style dropdowns instead of a free-text genre field. Values are stored as a comma-separated string in style_genre.
• Pronouns field — required pronouns dropdown on the customer request form; stored in the pronouns column.
• Lyrics in delivery email — final delivery email includes the generated lyrics in the same format as the player page.
• Delete uploaded songs — admin request page can delete selected Version A / B uploads and reset the request to prompt_ready.
• Live queue kiosk slide — /kiosk can cycle through QR, pricing, and active-queue slides based on kiosk_cycle_seconds.
• 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.

Project state notes

• No .gitlab-ci.yml is currently in the repo; old pipeline records from an earlier CI config are still visible in Gitea but are not actionable because no runners are attached. Add a CI skeleton (see below) if you want automated checks back.
• No automated tests exist yet.

CI skeleton (optional)

A CI skeleton is the smallest Gitea CI config that gives you useful automated checks on every push without needing a heavy test suite. For this project it would be a .gitlab-ci.yml with one or two jobs:

1. Syntax check job — install Python dependencies and run python -m py_compile app.py models.py config.py init_db.py to catch SyntaxErrors before they reach Portainer.
2. (Optional) Test job — run a minimal pytest suite once tests are written. Right now this would be a placeholder that skips if no tests exist, so the pipeline stays green while you decide whether to add tests.

It needs a Gitea runner to execute. Your Gitea instance has no runners attached, which is why the old pipelines are stuck/canceled. The skeleton just defines what to run; a runner is still required for it to actually execute.

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