94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# 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.
|