elmeg-demo/docs/PLATFORM_ENHANCEMENT_SPEC.md

Platform Enhancement Spec v2.0

Sprint Goal: Complete user lifecycle management, robust admin tools, and enhanced content features.

---

Phase 1: User Account Lifecycle

1.1 Email Verification

Goal: Ensure valid email addresses and reduce spam accounts.

User Stories

• As a new user, I want to receive a verification email so I can confirm my account.
• As a user, I want to resend verification if I didn't receive it.
• As an unverified user, I see limited functionality until verified.

Implementation

1. Model Changes - Add to User:

   • email_verified: bool = Field(default=False)
   • verification_token: Optional[str]
   • verification_token_expires: Optional[datetime]

2. API Endpoints:

   Method	Endpoint	Description
   POST	/auth/register	Creates user + sends verification email
   POST	/auth/verify-email	Verifies token, sets email_verified=True
   POST	/auth/resend-verification	Generates new token, sends email

3. Frontend Pages:

   • /verify-email?token=xxx - Handles verification link
   • Registration success page prompts to check email

4. Email Template: HTML email with verification link (48hr expiry)

---

1.2 Password Reset

Goal: Self-service password recovery without admin intervention.

User Stories

• As a user, I want to reset my password if I forgot it.
• As a user, I want a secure, time-limited reset link.

Implementation

1. Model Changes - Add to User:

   • reset_token: Optional[str]
   • reset_token_expires: Optional[datetime]

2. API Endpoints:

   Method	Endpoint	Description
   POST	/auth/forgot-password	Sends reset email (rate limited)
   POST	/auth/reset-password	Validates token + sets new password

3. Frontend Pages:

   • /forgot-password - Email input form
   • /reset-password?token=xxx - New password form

4. Security:

   • Tokens expire in 1 hour
   • Single-use tokens (invalidated after use)
   • Rate limiting on forgot-password endpoint

---

1.3 Email Service Abstraction

Goal: Provider-agnostic email sending.

Implementation

Create backend/email_service.py:

class EmailService:
    async def send_verification_email(user, token)
    async def send_password_reset_email(user, token)
    async def send_notification_email(user, subject, body)

Environment Variables

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=<secret>
EMAIL_FROM=noreply@elmeg.xyz

---

Phase 2: Admin Panel (/admin)

2.1 Overview

Goal: Full content management for administrators.

User Stories

• As an admin, I want to manage all users (roles, bans, verification status).
• As an admin, I want to CRUD shows, songs, venues, and tours.
• As an admin, I want to see platform statistics.

---

2.2 Features

Users Tab

• DataTable with search/filter
• Columns: Email, Username, Role, Verified, Active, Joined
• Actions: Edit role, Toggle ban, Force verify, View activity

Content Tabs (Shows, Songs, Venues, Tours)

• DataTable with CRUD actions
• Create/Edit modals with form validation
• YouTube link fields for Shows/Songs/Performances
• Bulk delete with confirmation

Stats Dashboard

• Total users, verified users
• Total shows, songs, venues
• Recent signups chart
• Activity heatmap

---

2.3 Access Control

# backend/routers/admin.py
allow_admin = RoleChecker(["admin"])

@router.get("/users")
def list_users(user: User = Depends(allow_admin), ...):

---

Phase 3: Enhanced Mod Panel (/mod)

3.1 Current Features

• ✅ Nickname approval queue
• ✅ Report queue (comments, reviews)

3.2 New Features

User Lookup

• Search user by email/username
• View user's full activity history:
  • Comments, reviews, ratings
  • Attendance history
  • Reports submitted/received

Temp Bans

• Ban duration selector (1hr, 24hr, 7d, 30d, permanent)
• Ban reason (required)
• Auto-unban via scheduled job

Bulk Actions

• Select multiple reports → Dismiss All / Resolve All
• Select multiple nicknames → Approve All / Reject All

Audit Log

• Recent moderation actions by all mods
• Who did what, when

---

Phase 4: YouTube Integration

4.1 Current State

• ✅ youtube_link field on Show, Song, Performance
• ✅ YouTubeEmbed component
• ✅ Show detail page displays embed

4.2 Enhancements

Song Page YouTube

• Display YouTube embed of #1 Heady Version
• Performance list shows YouTube icon if link exists

Admin Integration

• YouTube URL field in Show/Song/Performance edit forms
• URL validation (must be valid YouTube URL)

---

Phase 5: Song Page Enhancement ("Heady Version")

5.1 Concept

A Song is the abstract composition (e.g., "Hungersite"). A Performance is a specific rendition (e.g., "Hungersite @ Red Rocks 2023").

The "Heady Version" is the highest-rated performance of that song.

---

5.2 Song Page Layout

┌─────────────────────────────────────────────────────┐
│ 🎵 HUNGERSITE                                       │
│ Original: Goose │ Times Played: 127                 │
├─────────────────────────────────────────────────────┤
│ ▶ HEADY VERSION                                     │
│ [YouTube Embed of #1 Performance]                   │
│ 2023-07-21 @ Red Rocks ★ 9.4 (47 ratings)          │
├─────────────────────────────────────────────────────┤
│ 📊 HEADY LEADERBOARD                                │
│ 🥇 Red Rocks 2023-07-21      9.4★ (47)             │
│ 🥈 MSG 2024-03-15            9.1★ (32)             │
│ 🥉 Legend Valley 2022-09-10  8.9★ (28)             │
│ 4. Dillon 2023-08-15         8.7★ (19)             │
│ 5. The Capitol 2024-01-20    8.5★ (22)             │
├─────────────────────────────────────────────────────┤
│ 📈 RATING TREND                                     │
│ [Line chart: avg rating over time]                  │
├─────────────────────────────────────────────────────┤
│ 📅 ALL PERFORMANCES                                 │
│ [Sortable by: Date | Rating]                        │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 2024-11-15 @ Orpheum     8.2★  ▶ [YouTube]     │ │
│ │ 2024-10-20 @ Red Rocks   9.4★  ▶ [YouTube]     │ │
│ │ ...                                             │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

---

5.3 API Endpoints

Endpoint	Returns
GET /songs/{id}	Song + stats (times_played, avg_rating, heady_version)
GET /songs/{id}/performances	All performances with ratings, sorted
GET /songs/{id}/heady-version	Top-rated performance with YouTube link

---

Migration

Database Changes

ALTER TABLE "user" ADD COLUMN email_verified BOOLEAN DEFAULT FALSE;
ALTER TABLE "user" ADD COLUMN verification_token VARCHAR;
ALTER TABLE "user" ADD COLUMN verification_token_expires TIMESTAMP;
ALTER TABLE "user" ADD COLUMN reset_token VARCHAR;
ALTER TABLE "user" ADD COLUMN reset_token_expires TIMESTAMP;

---

Environment Requirements

# Required for email
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=<your-sendgrid-key>
EMAIL_FROM=noreply@elmeg.xyz

---

Acceptance Criteria

Phase 1

• User registers → receives verification email
• User clicks link → account verified
• Unverified user sees "verify email" banner
• User requests password reset → receives email
• User resets password → can login with new password

Phase 2

• Admin can list/search all users
• Admin can change user roles
• Admin can CRUD shows/songs/venues/tours
• Admin can add YouTube links via UI

Phase 3

• Mod can lookup user activity
• Mod can temp ban users
• Mod can bulk approve/reject

Phase 4

• YouTube embeds on song pages
• YouTube icons on performance lists

Phase 5

• Song page shows Heady Version embed
• Song page shows Heady Leaderboard
• Song page shows rating trend chart
• Performance list sortable by date/rating