2026-07-31 22:23:40 +00:00 · 2026-07-31 22:23:40 +00:00 · b4f0222bd5
commit b4f0222bd5
parent 9e532a1920
16 changed files with 1230 additions and 552 deletions
--- a/REVIEW.md
+++ b/REVIEW.md
@ -0,0 +1,94 @@
+# 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.