# 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.