theme-song-booth/README.md

# Theme Song Booth

A Flask web app for a convention booth where visitors request a custom AI-generated theme song, the operator manages the queue, and the final MP3(s) are delivered by email after payment.

## Features

### Customer-facing

- **Request form** (`/request`) — visitors enter name, email, hobbies, notable facts, preferred style/genre, vocal gender preference, and extra requests. A branded banner image is shown. The email field is validated to reduce delivery problems. If the operator marks the booth as closed, this page shows a closed banner and message instead.
- **Closed page** (`/request`) — when the booth is marked closed from `/admin/settings`, visitors see the closed banner and a friendly "goblin engineers are on a break" message.
- **Order status lookup** (`/status`) — customers enter their email to see all their requests, current status, and the private player link once songs are uploaded.
- **Confirmation page** (`/thanks/<id>`) — shows the request number after submission.
- **FAQ page** (`/faq`) — answers common customer questions.
- **Private player page** (`/play/<token>`) — customer receives an email with a unique link. They can stream Version A and Version B, pick one (or both), or request a limited number of revisions.
- **Revision workflow** — when a customer asks for changes, the current MP3s are archived and the operator sees the request as "Revisions Requested" in the dashboard.
- **Rate limiting** — the public request form is capped at 5 submissions per minute per IP.

### Operator/admin

- **Admin login** (`/admin/login`) — simple session-based login protected by `ADMIN_PASSWORD`.
- **Dashboard queue** (`/admin`) — filter by status (All, Pending, Needs Upload, Awaiting Payment, Delivered) and auto-refresh at a configurable interval.
- **Per-request detail page** (`/admin/request/<id>`):
  - Generate and save a Suno prompt from customer info.
  - Edit the customer's email address if they mistyped it.
  - Upload Version A and Version B MP3s (with automatic ID3 metadata tagging).
  - Send a preview email with a private player link.
  - Mark paid, enter a Square payment reference, and deliver selected MP3 attachments.
- **Settings / maintenance page** (`/admin/settings`):
  - Database health check with optional schema repair.
  - Database statistics, size, upload counts.
  - Configure customer revision limit.
  - Configure dashboard auto-refresh interval.
  - Configure SMTP host/port/user/from; store the SMTP password encrypted.
  - Configure default MP3 metadata tags (artist, album, year, comment).
  - Send a test email.
  - Download or restore the SQLite database backup.
  - Reset the entire system for a new event.
- **Per-request delete** and **system reset** — remove requests and uploaded files; reset auto-increment back to 1.

## Status flow

```
pending → prompt_ready → songs_uploaded → awaiting_payment → paid → delivered
```

| Status | Meaning |
|---|---|
| `pending` | Customer submitted a request; operator has not saved a prompt yet. |
| `prompt_ready` | Operator saved Title/Style/Lyrics. |
| `songs_uploaded` | Both MP3s uploaded; preview link can be sent. Dashboard filter label: **Needs Upload** (shown for this state when filtering). |
| `revisions_requested` | Customer asked for changes; current files were archived. |
| `awaiting_payment` | Customer approved a version; waiting for operator to collect payment and deliver. |
| `paid` | Payment recorded (used internally). |
| `delivered` | MP3 attachment(s) emailed to the customer. |

## File layout

| File | Purpose |
|---|---|
| `app.py` | Flask routes, helpers, email layer, runtime settings, MP3 tagging, rate limiting, and DB maintenance helpers. |
| `config.py` | Environment-variable based configuration; defines defaults for DB, uploads, SMTP, and secrets. |
| `models.py` | SQLite schema and CRUD helpers. |
| `init_db.py` | Standalone script to create the database tables. |
| `templates/closed.html` | Message shown on `/request` when the booth is marked closed. |
| `templates/request.html` | Customer request form. |
| `templates/thanks.html` | Post-submission confirmation. |
| `templates/status.html` | Customer order status lookup. |
| `templates/faq.html` | Customer FAQ page. |
| `templates/player.html` | Customer audio player, approval, and revision form. |
| `templates/admin/login.html` | Admin login page. |
| `templates/admin/dashboard.html` | Operator queue with filters and auto-refresh. |
| `templates/admin/request.html` | Single-request detail / prompt / upload / delivery page. Customer email is editable here. |
| `templates/admin/settings.html` | Maintenance, settings, backup/restore, and reset page. |
| `static/Trollgorithm_booth.jpg` | Banner image on the request page. |
| `static/DM-Logo_email.png` | Inline Dionysis Media logo attached to emails. |
| `static/Booth_closed.png` | Banner shown when the booth is marked closed. |
| `Dockerfile` | Production container image. |
| `docker-compose.yml` | Portainer stack definition. |
| `requirements.txt` | Python dependencies. |
| `.env.example` | Template for local environment variables. |
| `REVIEW.md` | Quick-reference for returning to this project. |

## Local development

```bash
cd /home/jess/workspace/theme-song-booth
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# Edit .env and set APP_SECRET_KEY, ADMIN_PASSWORD, SMTP_PASS, PUBLIC_BASE_URL
.venv/bin/python init_db.py
.venv/bin/python -m flask --app app run --host=0.0.0.0
```

Visit:
- Customer form: http://127.0.0.1:5000/request
- Admin login: http://127.0.0.1:5000/admin

## Deployment with Portainer

1. Log in to Portainer.
2. Go to **Stacks** → **Add stack**.
3. Choose **Repository**:
   - URL: `https://gitlab.hallsworth.ca/yrtria/theme-song-booth.git`
   - Branch: `main`
   - Compose path: `docker-compose.yml`
4. Add environment variables:

| Variable | Required | Purpose |
|---|---|---|
| `APP_SECRET_KEY` | Yes | Long random string for Flask sessions and to encrypt stored SMTP password. Generate with `python3 -c "import secrets; print(secrets.token_hex(32))"`. |
| `ADMIN_PASSWORD` | Yes | Password for `/admin`. |
| `SMTP_PASS` | Yes | Password for the SMTP account. |
| `PUBLIC_BASE_URL` | Yes | Public HTTPS URL, e.g. `https://booth.dionysismedia.ca`. |
| `HOST_PORT` | No | Host-side port mapping, default `127.0.0.1:8000`. |
| `INTERNAL_PORT` | No | Port gunicorn binds inside container, default `8000`. |
| `BOOTH_NAME` | No | Name used in emails, default `Trollgorithm Theme Songs`. |
| `PRICE_PER_VERSION` | No | Shown to the operator/customer, default `10.00`. |
| `CURRENCY` | No | Currency label, default `CAD`. |
| `MAX_REVISIONS` | No | Default customer revision limit if not changed in settings, default `2`. |

5. Deploy the stack.
6. Open a console in the `theme-song-booth` container and run once:

```bash
python init_db.py
```

7. Point your reverse proxy at the `HOST_PORT` you chose.
8. Print or display a QR code pointing to `https://your-domain/request`.

### Updating the deployment

After each push to GitLab, go to Portainer → **Stacks** → `theme-song-booth` → **Pull and redeploy** to rebuild from the repo.

## Important notes

- **No `.env` file in production.** `docker-compose.yml` passes variables directly from Portainer. This avoids Portainer's `env_file not found` error.
- **Runtime settings persist.** SMTP config, revision limit, auto-refresh interval, booth open/closed state, and MP3 metadata defaults are stored in `booth_settings.json` inside the persistent uploads volume. They survive redeploys.
- **Booth open/closed switch.** Operators can flip the booth status from `/admin/settings`. When closed, `/request` shows a closed banner and message instead of the form.
- **Payments are manual.** The app records a Square payment reference but does not integrate with Square's API. Use a Square Terminal/Reader at the booth.
- **Operator queue is the dashboard.** No operator email alerts are sent; approvals and revision notes appear as status changes in `/admin`.
- **MP3 metadata.** Uploaded files are tagged with title (from the saved prompt), plus configured artist/album/year/comment values.
- **Email logo.** `static/DM-Logo_email.png` is attached inline to all customer emails as the Dionysis Media signature.
- **Security:** the repo is public on GitLab. No secrets are committed. Admin password is plain text in the Portainer environment.

## Common troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| "Send Preview Link" does nothing | Form tags were unbalanced (now fixed). | Redeploy the latest commit. |
| Emails not arriving | SMTP settings wrong or messages in spam. | Use **Send Test Email** on `/admin/settings`; verify host/port/password. |
| Can't reach app through domain | Reverse proxy points to wrong host port. | Match `HOST_PORT` to your proxy upstream. |
| Static banner not showing | Browser cached old image. | Hard-refresh or redeploy stack. |
| Logo missing from email | Logo file missing from `static/`. | Ensure `static/DM-Logo_email.png` is in the container. |
| Database schema mismatch | New column added but old DB not migrated. | Go to `/admin/settings` and click **Fix Missing Columns**, or run `python init_db.py`. |

## License / ownership

Built for Jess's Trollgorithm theme-song booth. All code and assets are private to that project.