theme-song-booth/README.md

Theme Song Booth

Prototype web app for a convention booth where attendees request custom AI-generated theme songs.

Flow

1. Customer fills out the public request form at /request.
2. Operator generates a Suno Custom Mode prompt via Hermes and saves it in the admin detail page.
3. Operator generates two song versions in Suno and uploads the MP3s in admin.
4. Operator clicks Send Preview Link. Customer receives an email with a private player page.
5. Customer listens to Version A and Version B, then approves one/both or requests changes.
6. Operator sees the approval alert, collects payment via Square reader, then clicks Mark Paid & Deliver.
7. Customer receives the approved MP3(s) as email attachments.

Local Development

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_HASH, SMTP_PASS, PUBLIC_BASE_URL
.venv/bin/python init_db.py
.venv/bin/python -m flask --app app run --host=0.0.0.0

Generate an admin password hash with:

.venv/bin/python -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('yourpassword'))"

Deployment on Unraid

1. Copy the project directory to your Unraid server or build it via git.
2. Create /mnt/user/appdata/theme-song-booth/data and /mnt/user/appdata/theme-song-booth/uploads.
3. Copy .env.example to .env, fill in real values, and place it next to docker-compose.yml.
4. Run docker compose up -d --build.
5. Initialize the database once: docker compose exec booth python init_db.py.
6. Point your chosen domain at the Unraid server's public IP and route it through your reverse proxy to http://127.0.0.1:8000.
7. Print the booth QR code pointing to https://your-domain.example.com/request.

Files

• app.py — Flask application with public/admin routes and email logic.
• models.py — SQLite schema and helper functions.
• config.py — Configuration loaded from environment.
• templates/ — Jinja2 HTML templates.
• init_db.py — Standalone script to create the SQLite database.
• Dockerfile / docker-compose.yml — Container packaging for Unraid.