Server (AWS EC2):

🔹 Instance: t3.large (2 vCPU, 8GB RAM) — ~$60/month

🔹 Elastic IP: 3.131.5.193

🔹 OS: Ubuntu 22.04 / PHP 8.1 / MySQL / Nginx

🔹 SSL: Let's Encrypt auto-renew via certbot

🔹 ffmpeg: Installed for re-judge video merging

🔹 Web root: /var/www/starz/public/

🔹 Config: /var/www/starz/config.php

🔹 DB: turnt_arena (shared with TURNT Arena, starz_ prefix tables)

Storage — S3:

🔹 Bucket: starz-media-vault (us-east-2)

🔹 CloudFront CDN: d1udxlxsuq202.cloudfront.net (backup only — NAS is primary)

🔹 All viewing AND downloads go through NAS. Uploads go direct to S3. PDFs use presigned S3 URLs.

🔹 S3 egress: near zero — only PDFs, uploads, admin QA checks

Storage — NAS (Synology DS925+):

🔹 Hardware: 4×4TB WD Red Plus (SHR ~12TB usable) + 32GB RAM + 1TB WD Black NVMe

🔹 NIC: 2.5GbE (confirmed 2500Mb/s via ethtool)

🔹 Location: Home with T-Mobile 2Gbps fiber (static IP)

🔹 DSM: 7.3.2 — Web Station (PHP 8.1 enabled, nginx backend)

🔹 Public IP: 66.33.15.170 (T-Mobile static — confirmed not CGNAT)

🔹 Local IP: 192.168.1.134 (DHCP reservation)

🔹 Domain: files.turnthat.com → 66.33.15.170

🔹 SSL: Let's Encrypt on NAS (renewed April 3, 2026)

🔹 CloudSync: S3 → NAS (download only, syncs automatically)

🔹 Port forwards: 22, 80, 443, 5001 TCP → 192.168.1.134

🔹 Router: T-Mobile gateway at 192.168.1.1 (admin/a1b5c1ae, SSID CXNK01D2ADBE)

🔹 SSH: ssh Twisted701@66.33.15.170

🔹 QuickConnect: quickconnect.to/twisted701

🔹 Web Station service: "files" (native script language, PHP 8.1, nginx)

🔹 Web Station portal: 740033ca-0448-4243-9c33-4c7a8510d68b

🔹 Web Station PHP service: 28b01abb-817b-4d4d-9e83-79253fe9d701

🔹 CORS config: /usr/local/etc/nginx/conf.d/28b01abb-817b-4d4d-9e83-79253fe9d701/user.conf

🔹 ZIP script: /volume1/media/zip.php — builds ZIPs from local disk, streams directly to browser

🔹 Document root: /volume1/media

🔹 Timeouts: connection 60s, send 3600s, read 3600s (for large ZIP downloads)

🔹 Benchmark: EC2→NAS 155MB video in 1.4s = ~920 Mbps (limited by EC2 network, NAS can do 2.5Gbps)

🔹 Purpose: Serve ALL media viewing + downloads + ZIP downloads. Zero EC2 media bandwidth.

🔹 ⚠️ CORS note: When Web Station service changes, CORS user.conf path changes. Check /var/tmp/nginx/test/plugin_config/ for current service ID.

DNS (GoDaddy):

🔹 media.turnthat.com → 3.131.5.193 (EC2)

🔹 files.turnthat.com → 66.33.15.170 (NAS)

🔹 play.turnthat.com → 3.131.5.193 (TURNT Arena)

🔹 book.turnthat.com → 3.131.5.193

⚠️ Costs (after NAS migration):

🔹 EC2 t3.large: ~$60/month

🔹 S3 Storage (~863GB): ~$20/month

🔹 EC2 EBS: ~$15/month

🔹 S3 egress: ~$0-2/month (PDFs + admin QA only)

🔹 Total: ~$95-100/month (was $150+ with CloudFront + S3 egress)

Pre-Setup:

📋 Admin → Generate Emails → save Studio.txt

📋 Program by Competition for Printer → save schedule PDF

In Admin:

1️⃣ Import Studios → upload Studio.txt, set event label & year

2️⃣ Event Setup → upload schedule PDF → configure livestream → set media visibility

3️⃣ Set event status to Active (enables overlay auto-detect)

4️⃣ Upload Media → desktop app uploads to S3

5️⃣ QA Inspector → Daily Media Report + Critique Validator + Temp Cleanup

6️⃣ Notify Studios → sends login email via SendGrid

During Event:

🎤 Scorer Station records critiques → uploads to S3

📡 Backstage advances routines → Now Performing overlay updates

📺 Production staff manages livestream embed URLs

Post-Event:

🔍 Run QA report → fix misfiled videos, missing photos, timestamp mismatches

🎤 Custom Judge Critiques → upload video, generate judge link

📧 Resend studio emails individually from Studio Activity

starz-media-vault/

  _Deleted/ ← soft-deleted files (auto-cleaned after 7 days)

  2026/

    Des Moines/

      Studio Name(#1)/

        Media/

          0041/ ← routine photos folder

            IMG_101528.JPG

          1-041 - 07 March 2026 - 05-18-36 PM.mp4 ← video

        Critiques/

          Judge_1_RoutineName.mp3 ← audio

          Judge_1_RoutineName.mp4 ← merged video (480p, 15% original audio)

          scoring.pdf

          Custom/ ← custom judge critiques

            StudioNum/

              RoutineName.mp4 ← uploaded HD video

        _Deleted/

Daily Media Report:

🔹 Missing videos, missing photos, misfiled videos (wrong studio folder)

🔹 Timestamp mismatch detection (±60min window) with rename/keep options

🔹 Duplicate JPG detection across studios with overlap delete button

🔹 Wrong-date video detection (outside event dates ±1 day)

🔹 Photo/video preview, delete buttons per issue

🔹 Confirmed scratches from starz_scratches table (gold) vs likely scratched (gray)

🔹 Ignore system saved to audit log

🔹 "✅ This IS #X — Keep It Here" button for false positives

🔹 folderByRoutine prefers correct studio per schedule when duplicates exist

Critique Validator:

🔹 5-pass name matching + saved pairings

🔹 Skips confirmed scratches (loads from starz_scratches)

🔹 Per-routine list per judge with video-ready status

🔹 "⚠️ Upload video to enable rejudge" warnings

🔹 Generate rejudge links per judge with all missing routines

Video Checker:

🔹 Finds duplicate videos (original + -001 retry from ffmpeg)

🔹 Compare sizes, preview both, delete corrupt one

🔹 "Delete All Corrupt" bulk button

Temp File Cleanup:

🔹 Scan for .tmp files (including .tmp.mp4 from interrupted recordings)

🔹 Manual delete button + automatic hourly cron cleanup

Custom Judge Critique:

🔹 Select event → studio → type routine name → pick judge → upload HD video

🔹 Video uploads to S3: Year/EventLabel/Critiques/Custom/StudioNum/RoutineName.ext

🔹 Generates rejudge link (/rejudge/TOKEN)

🔹 Judge watches video, records critique → server merges via ffmpeg

🔹 Saves Judge_X_RoutineName.mp3 + .mp4 to studio's Critiques/ folder

🔹 Email notification via SendGrid when judge finishes

How It Works:

1️⃣ Admin runs Critique Validator → sees missing critiques per judge

2️⃣ Clicks "Generate Link for Judge X" → creates rejudge session in DB

3️⃣ Session contains: judge label, list of routines with videoKey references

4️⃣ Judge opens /rejudge/TOKEN on any device (phone, laptop, tablet)

Judge Flow:

🔹 Welcome screen → shows routine count, judge name

🔹 Mic Check → records 3 seconds, plays back for verification

🔹 Judging screen → video plays at FULL volume, mic records simultaneously

🔹 Review → listen to recording, redo or submit

🔹 Auto-advances to next routine

Server Processing (on submit):

🔹 Receives audio as WebM blob

🔹 Converts to MP3 via ffmpeg

🔹 Downloads video from S3 (uses precache — video downloaded while judge watches)

🔹 ffmpeg merges: original video (15% audio) + judge recording (100% audio) → 480p MP4

🔹 Uploads Judge_X_RoutineName.mp3 and .mp4 to Critiques/ folder on S3

🔹 Marks routine as completed in session

Custom Critique (single routine):

🔹 Admin uploads HD video via QA → Custom Judge Critique tool

🔹 Stored in starz_custom_critiques table (token, video key, studio, routine name)

🔹 Same judge flow — /rejudge/TOKEN works for both regular and custom

🔹 Info endpoint checks custom_critiques table first, then rejudge_sessions

🔹 Submit endpoint handles both — custom saves to studio's Critiques/ folder

🔹 Sends email via SendGrid when complete

Key Tables:

🔹 starz_rejudge_sessions: token, judge_label, routines (JSON), completed (JSON), status

🔹 starz_custom_critiques: token, event_id, studio_num, studio_name, routine_name, judge_num, video_s3_key, critique_mp3_key, critique_mp4_key, notify_email, status

Key Endpoints:

🔹 rejudge/TOKEN/info → session data (checks custom first, then regular)

🔹 rejudge/TOKEN/video-url → presigned S3 URL for video playback

🔹 rejudge/TOKEN/precache → downloads video to server cache while judge watches

🔹 rejudge/TOKEN/submit → receives audio, ffmpeg merge, upload to S3

Components:

🔹 /live/overlay.php — standalone overlay for vMix/OBS (1920×1080, transparent bg)

🔹 /live/embed.php — embeddable player with overlay for WordPress/external sites

🔹 /live page — overlay built into livestream viewer

Overlay Shows:

🔹 Now Performing: routine #, name, studio, division

🔹 Ahead/behind schedule timing

🔹 Up Next: next 2-3 routines

🔹 Custom text from backstage (e.g. "IMPROV")

🔹 Polls /api/public/now-performing every 3 seconds

Embed Page (embed.php):

🔹 Loads stream URL from event config (supports Rumble, YouTube)

🔹 Overlay sits below video (not on top — avoids blocking player controls)

🔹 Custom fullscreen button (top-right) → fullscreens video + overlay together

🔹 Hidden on mobile (mobile uses native Rumble fullscreen)

🔹 Auto-detects active event if no event_id specified

URLs:

🔹 /live/overlay.php?stage=A — vMix/OBS browser source

🔹 /live/embed.php?event_id=X&stage=A — WordPress embed

🔹 /live/embed.php?stage=A — auto-detect active event

Production Staff Login:

🔹 Username: production / Password: starz1 (desktop_role='production' in starz_staff)

🔹 Sees ONLY the livestream setup page — no admin, no QA, no files

🔹 Workflow: select event → paste Rumble/YouTube URL → save → copy embed code

🔹 Auto-converts Rumble page URLs and embed scripts to iframe URLs

🔹 WordPress instructions + copy button for iframe embed code

Event Status:

🔹 Events tab has status dropdown: Active / Upcoming / Completed / Cancelled

🔹 Active events show overlay links and embed code copy buttons

🔹 public/active-event endpoint returns the active event for auto-detect

Modes:

🔹 Upload Machine: uploads photos/videos/critiques from local folders to S3

🔹 Scorer Station: monitors judge critique recordings in real-time

🔹 Monitor: remote view of scorer status + scratch management

Upload Machine:

🔹 Select event → pick folder → scans files → S3 verification runs in BACKGROUND

🔹 UI is usable immediately — no blocking scan overlay

🔹 Status shows: "15,200 pending — verified 5,000/20,458"

🔹 Deleted files (via QA) return -1 from check-exists → skipped, not re-uploaded

🔹 Temp files (.tmp), files <5 seconds old, files with .tmp companion are skipped

🔹 Quarantine for small files: audio <500KB, video <2MB → play/upload/skip buttons

Scorer Station:

🔹 Maps 3 judge folders → monitors for new MP3/MP4 files every 10 seconds

🔹 Grid: Routine | Judge 1 | Judge 2 | Judge 3 (✅/❌/⚠️ per file type)

🔹 Smart alerts: 30-second timer before alerting missing judge files

🔹 Live activity ticker: color-coded per judge

🔹 Progress bar: "47 / 497 (499 scheduled, 2 scratched)"

🔹 Scratch system: dropdown from schedule, syncs to starz_scratches table

Build:

🔹 Electron app — npm start to run, npm run build for .exe

🔹 Source: src/index.html (UI), src/main.js (Node backend), src/preload.js (bridge)

/studio — Studio Portal:

🔹 Login with email/password → see events → media/critiques/codes

🔹 Photos grouped by routine with dancer names from schedule

🔹 Delete moves to _Deleted/ on S3, download via CloudFront/NAS

🔹 Access codes for parents with media/critiques/both filter

/gallery/CODE — Parent Access:

🔹 Same UI as studio but view/download only — no delete, no codes

🔹 Respects code expiration, use count, category filter

/live — Public Event Page:

🔹 QR code landing page: Photos, Videos, Livestream, Schedule, Find Routine, Notify Me

🔹 Livestream: single room goes straight to stream, multi-room shows picker

🔹 Only rooms with URLs configured are shown (empty URLs filtered out)

🔹 Now Performing overlay on livestream viewer

🔹 Stream iframe killed when navigating back (stops background audio)

🔹 Schedule PDF loaded on demand (presigned URL generated per-request)

🔹 Push notifications via web-push + SendGrid email

🔹 Browse S3 bucket with folder tree navigation

🔹 Search: search all S3 files by name (scans entire bucket, 30s timeout)

🔹 Move, rename, delete files (audit logged)

🔹 Bulk select + delete with progress

🔹 Delete moves to _Deleted/ (soft delete) — uploader skips deleted files

Hourly Cron (api/cron/cleanup?key=starz-cleanup-2026):

🔹 Deletes expired sessions (30-day lifetime)

🔹 Cleans rejudge video cache (/tmp/rejudge_cache/) older than 24 hours

🔹 Permanently deletes S3 _Deleted/ files older than 7 days

🔹 Deletes .tmp and .tmp.mp4 files from S3

🔹 Cleans old scorer status data (7+ days)

Server Crontab (root):

🔹 0 * * * * curl -s "https://media.turnthat.com/api/cron/cleanup?key=starz-cleanup-2026"

Email: SendGrid

🔹 API key in config.php (SMV_SENDGRID_KEY)

🔹 Used for: studio notifications, custom critique completion, push notification emails

🔹 From: [email protected] / Starz Dance Competition

Tables:

🔹 starz_events, starz_studios, starz_event_studios, starz_event_studio_numbers

🔹 starz_sessions, starz_staff, starz_staff_events

🔹 starz_access_codes, starz_schedule_entries

🔹 starz_file_audit, starz_media (legacy)

🔹 starz_rejudge_sessions, starz_custom_critiques

🔹 starz_scratches (event_id, routine_num, routine_name)

🔹 starz_scorer_status (event_id, status_json)

🔹 starz_stage_queue, starz_notify_*, starz_room_chat

New Endpoints (this session):

🔹 public/active-event — returns current active event (for overlay auto-detect)

🔹 public/schedule-url — generates presigned URL for single event's schedule PDF

🔹 admin/set-event-status — change event status (active/upcoming/completed/cancelled)

🔹 admin/create-custom-critique — upload video + create rejudge link

🔹 admin/resend-studio-welcome — resend login email to single studio (test_mode param)

🔹 admin/files/search — search entire S3 bucket by filename

🔹 admin/presign-upload — alias for admin/upload-url (web admin bulk upload)

🔹 cron/cleanup — maintenance endpoint (key=starz-cleanup-2026)

Overview:

🔹 4th button on /build home page — "📧 Email Studios"

🔹 Upload schedule PDF → pdfplumber parses all routines → groups by studio

🔹 Pulls studio emails from event-studio-map

🔹 Draft/Final version toggle, custom subject + message

🔹 Select all/none studios, send one at a time with progress bar

🔹 Test email sends to [email protected] with [TEST] prefix

🔹 Preview button opens popup with print-friendly styles

🔹 Session caching — remembers last parse on refresh

Per-Studio Email HTML:

🔹 Event header, studio name, routine count, version label

🔹 Routines grouped by Day/Room, sorted by time

🔹 Color-coded levels (S=gold, RS=green, NS=gray in email)

🔹 Award ceremony markers inline in schedule

🔹 TITLE badge (purple) for routines with + in category

🔹 Dancer names listed under each routine

🔹 Print styles: white bg, alternating gray rows, ink-friendly

Backend:

🔹 send_schedule_email action in /build backend (not /api/admin/)

🔹 SendGrid HTML email — no attachments, renders in inbox

🔹 Logs to starz_schedule_emails table

Category Parsing Fix:

🔹 COL_CATEGORY boundary set from "Grp" header right edge + 5px

🔹 Fixed "Contemporary" at x=268.6 being skipped by hard-coded x>270

🔹 cat_full field added as fallback — raw "Contemporary S 15-18" text

Overview:

🔹 Phone-based awards tracker for audience members during ceremonies

🔹 All data stored in localStorage — zero server load

🔹 Gold-bordered button on /live hub (only shows when schedule entries exist)

Selection Modes:

🔹 All Routines — track everything

🔹 Your Studio — pick studio from dropdown

🔹 Choose Routines — search/select specific routines

Two Tabs (matching award ceremony flow):

🔹 🏅 Adjudication — Judges Award, G/HG/P/DE buttons, Category placement X/total

🔹 🏆 High Points — routines grouped by HP pool in read order (youngest→oldest, Solo→Prod, NS→RS→S)

🔹 HP tab has level filter: All / New Starz / Rising Starz / Starz

Per-Routine Tracking:

🔹 Judges Award — themed modal prompt, "JA" badge on header

🔹 Adjudication — G/HG/P (+ DE for Starz only), badge on header

🔹 Category Placement — X / total (auto-filled from block count, level-separated)

🔹 High Point Placement — X / top-N (5/10/15/20 from /build thresholds: 24+=10, 49+=15, 75+=20)

🔹 Overall Placement — X / total (RS and S only, not NS)

UX:

🔹 Cards collapsed by default — tap to expand, auto-closes others

🔹 Badges update in real-time on collapsed headers

🔹 atSave() merges with existing data (doesn't wipe other tab's data)

🔹 Themed modals replace native prompt()/confirm()

🔹 Sorting: R# Order or By Room/Day. Filters: Day + Room

Share Results:

🔹 📤 Share button generates trophy-case HTML with medal chips

🔹 html2canvas renders to PNG image at 2x resolution

🔹 Mobile: native share sheet with image file (Instagram/text/email)

🔹 Desktop: downloads PNG file

🔹 Responsive: single column on phone, 2-col tablet, 3-col print/desktop

🔹 Light theme for share (white cards, dark header, color chips)

Level Colors (brand):

🔹 New Starz: pink #d94b7a

🔹 Rising Starz: yellow #f5d623

🔹 Starz: blue #2196F3

Level Column:

🔹 starz_schedule_entries.level — VARCHAR(10), stores NS/RS/S

🔹 pdf.js parser (admin) can't reliably extract level from text items

🔹 Solution: after pdf.js save, /build pdfplumber parser runs on same PDF

🔹 Pdfplumber extracts level reliably → admin/update-schedule-levels UPDATEs the DB

🔹 This happens automatically in setupUploadSchedule() step 4

Division String Format (from pdf.js):

🔹 "Solo 1 Contemporary S 15-18" or "D/T 2 Jazz T 12-14"

🔹 "Producti" — pdf.js splits "Production" across text items

🔹 All regex patterns must handle: Producti(?:on)?|Prod|Production

HP Key Format:

🔹 AGE-DIVISION-LEVEL (e.g. "T-Solo-RS", "S-D/T-S")

🔹 Category block key: division string + "|" + level (separates NS/RS/S)