# 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`: ```python 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 ```env SMTP_HOST=smtp.sendgrid.net SMTP_PORT=587 SMTP_USER=apikey SMTP_PASSWORD= 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 ```python # 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 ```sql 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 ```env # Required for email SMTP_HOST=smtp.sendgrid.net SMTP_PORT=587 SMTP_USER=apikey SMTP_PASSWORD= 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