fediversion/docs/AUDIT_AND_PLAN.md

Elmeg Platform Audit & Implementation Plan

Date: December 22, 2024

---

Executive Summary

This audit examines the Elmeg platform against spec'd features, user stories, and interaction gaps. The platform has strong core functionality but has several incomplete areas that impact user experience.

---

🔴 Critical Gaps (High Priority)

1. Email System Not Functional

Status: Backend model ready, email sending not implemented

Impact: Users cannot:

• Verify their email addresses
• Reset passwords
• Receive notification emails

User Stories Affected:

• ❌ "As a new user, I want to receive a verification email"
• ❌ "As a user, I want to reset my password if I forgot it"

Fix Required:

• Implement backend/services/email_service.py
• Integrate with AWS SES (docs exist at AWS_SES_SETUP.md)
• Connect auth endpoints to email service

---

2. XP Not Actually Awarded

Status: Models and endpoints exist, but XP isn't awarded on actions

Impact: Gamification system is purely cosmetic - actions don't increase XP

User Stories Affected:

• ❌ "As a user, I want to earn XP when I rate a performance"
• ❌ "As a user, I want to earn XP when I mark attendance"

Fix Required:

• Hook award_xp() into attendance, rating, review endpoints
• Call check_and_award_badges() after XP-earning actions

---

3. Frontend Not Using Slug URLs

Status: API supports slugs, frontend still uses numeric IDs

Impact: URLs are non-memorable (e.g., /songs/69 instead of /songs/tweezer)

Fix Required:

• Update all <Link> components to use slug
• Add slug to API response schemas
• Update frontend routing to accept slug params

---

🟡 Important Gaps (Medium Priority)

4. Onboarding Flow Incomplete

Status: /welcome page exists but is minimal

Gaps:

• No guided tour for new users
• No prompt to set up profile
• No progressive disclosure of features

User Stories Affected:

• ❌ "As a new user, I want a guided introduction to the platform"

---

5. Chase Song "Mark as Caught" Not Wired

Status: Backend endpoint exists, no frontend UI

Impact: Users can add chase songs but can't mark them as caught at shows

Fix Required:

• Add "Mark Caught" button on show detail page
• Connect to POST /chase/songs/{id}/caught

---

6. Performance Rating Disconnected

Status: RatingInput component exists, not connected to performances

Impact: Users can see ratings but can't submit their own on performance pages

Fix Required:

• Wire up POST /ratings endpoint on performance detail page
• Award XP when rating is submitted

---

7. Notification Center Empty

Status: Backend + frontend components exist, no triggers

Impact: Bell icon in header shows nothing useful

Fix Required:

• Create notifications on: ratings received, badge earned, reply to comment
• Add notification sound/toast for new notifications

---

8. Groups Feature Skeletal

Status: CRUD exists, no member activity

Gaps:

• Can't see what members are doing
• No group leaderboards
• No group chat/discussions

---

🟢 Working Features (Verified)

Feature	Status	Notes
User registration/login	✅	Works
Show/Song/Venue browsing	✅	Working
Performance detail pages	✅	With navigation
Slug-based API lookups	✅	All entities
Comment sections	✅	Threaded
Review system	✅	With ratings
Chase song list	✅	Add/remove works
Attendance tracking	✅	Basic
Profile page	✅	With stats
Activity feed	✅	Global
Heady Version display	✅	Top performances
Admin panel	✅	User/content management
Mod panel	✅	Reports/nicknames
Theme toggle	✅	Light/dark
Settings/preferences	✅	Wiki mode

---

📋 Implementation Plan

Sprint 1: Critical Infrastructure (Est. 4-6 hours)

1.1 Email Service Integration

- [ ] Create EmailService class with AWS SES
- [ ] Implement send_verification_email()
- [ ] Implement send_password_reset_email()
- [ ] Wire up auth endpoints
- [ ] Test email flow end-to-end

1.2 XP Award Hooks

- [ ] Hook award_xp() into attendance.py
- [ ] Hook award_xp() into reviews.py
- [ ] Hook award_xp() into ratings endpoint
- [ ] Call check_and_award_badges() automatically
- [ ] Add "XP earned" toast feedback on frontend

---

Sprint 2: URL & UX Polish (Est. 3-4 hours)

2.1 Slug URLs on Frontend

- [ ] Add slug to Song, Show, Venue, Performance response schemas
- [ ] Update Link components to use slug
- [ ] Verify all routes work with slugs
- [ ] Update internal links in ActivityFeed
- [ ] Update search results to use slugs

2.2 Performance Rating Widget

- [ ] Add RatingInput to performance detail page
- [ ] Connect to POST /ratings endpoint
- [ ] Show user's existing rating if any
- [ ] Animate rating confirmation
- [ ] Award XP on rating

---

Sprint 3: Feature Completion (Est. 4-5 hours)

3.1 Chase Song Completion

- [ ] Add "Mark Caught" button on show detail page
- [ ] Show user's chase songs that match show setlist
- [ ] Animate "caught" celebration
- [ ] Award badge for catching 5 songs

3.2 Notification Triggers

- [ ] Create notification on badge earned
- [ ] Create notification on comment reply
- [ ] Create notification on review reaction
- [ ] Add toast/sound for new notifications

3.3 Onboarding Experience

- [ ] Create multi-step welcome wizard
- [ ] Prompt profile setup (bio, avatar)
- [ ] Highlight key features
- [ ] Set first badge on completion

---

Sprint 4: Social Enhancement (Est. 3-4 hours)

4.1 XP Leaderboard Integration

- [ ] Add XP leaderboard to home page
- [ ] Add leaderboard to /leaderboards page
- [ ] Add "Your Rank" indicator
- [ ] Weekly/monthly/all-time views

4.2 Groups Upgrade

- [ ] Show member activity in group
- [ ] Group XP leaderboard
- [ ] Group attendance stats

---

📊 Priority Matrix

Item	Impact	Effort	Priority
Email service	High	Medium	P1
XP award hooks	High	Low	P1
Slug URLs on frontend	Medium	Low	P2
Performance rating widget	High	Low	P2
Chase "Mark Caught"	Medium	Low	P2
Notification triggers	Medium	Medium	P3
Onboarding wizard	Medium	Medium	P3
Groups enhancement	Low	High	P4

---

Recommended Execution Order

1. Now: XP award hooks (quick win, high impact)
2. Today: Performance rating widget
3. Today: Slug URLs on frontend
4. Next: Email service (requires AWS config)
5. Next: Chase song completion
6. Later: Notifications, onboarding, groups

---

Quick Wins (Can Do in 30 min each)

1. ✨ Wire XP awards to attendance/review endpoints
2. 🎯 Add performance rating widget
3. 🔗 Update frontend links to use slugs
4. 🏆 Add XP leaderboard to home page
5. 🎵 Add "Mark Caught" button to show pages